Skip to content

Commit 45d5fcc

Browse files
committed
doxy: split out a faq about disabling things
Taken out of the "why" and "slow lstopo" entries. Signed-off-by: Brice Goglin <Brice.Goglin@inria.fr>
1 parent ee17dab commit 45d5fcc

File tree

1 file changed

+22
-14
lines changed

1 file changed

+22
-14
lines changed

doc/hwloc.doxy

Lines changed: 22 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -3457,7 +3457,7 @@ than any system-provided copy of hwloc.
34573457
\section faq1 Concepts
34583458

34593459

3460-
\subsection faq_why I only need binding, why should I use hwloc ?
3460+
\subsection faq_why I only need binding, or the number of cores, why should I use hwloc ?
34613461

34623462
hwloc is its portable API that works on a variety of operating
34633463
systems.
@@ -3478,11 +3478,27 @@ multiple tasks are in the same physical core.
34783478
However, using hwloc comes with an overhead since a topology must
34793479
be loaded before gathering information and binding tasks or memory.
34803480
Fortunately this overhead may be significantly reduced by filtering
3481-
non-interesting information out of the topology.
3481+
non-interesting information out of the topology,
3482+
see \ref faq_disable_faster below.
3483+
3484+
3485+
\subsection faq_disable_faster What may I disable to make hwloc faster?
3486+
3487+
Building a hwloc topology on a large machine may be slow because
3488+
the discovery of hundreds of hardware cores or threads takes time
3489+
(especially when reading thousands of sysfs files on Linux).
3490+
Ignoring some objects (for instance caches) that aren't useful
3491+
to the current application may improve this overhead.
3492+
One should also consider using XML (see \ref faq_xml) to work
3493+
around such issues.
3494+
3495+
Contrary to lstopo which enables most features (see \ref faq_slow_lstopo),
3496+
the default hwloc configuration is to keep all objects enabled
3497+
except I/Os and instruction caches.
3498+
This usually builds a very precise view of the CPU and memory subsystems,
3499+
which may be reduced if some information is unneeded.
34823500

34833501
<br/>
3484-
For instance, the default configuration is to keep all objects enabled
3485-
(except I/Os and instruction caches).
34863502
The following code tells hwloc to build a much smaller topology that
34873503
only contains Cores (explicitly filtered-in below),
34883504
hardware threads (PUs, cannot be filtered-out),
@@ -4005,17 +4021,9 @@ an I/O subtree.
40054021

40064022

40074023

4008-
\subsection faq_slow_lstopo Why is hwloc slow?
4009-
4010-
Building a hwloc topology on a large machine may be slow because
4011-
the discovery of hundreds of hardware cores or threads takes time
4012-
(especially when reading thousands of sysfs files on Linux).
4013-
Ignoring some objects (for instance caches) that aren't useful
4014-
to the current application may improve this overhead (see \ref faq_why).
4015-
One should also consider using XML (see \ref faq_xml) to work
4016-
around such issues.
4024+
\subsection faq_slow_lstopo Why is lstopo slow?
40174025

4018-
Additionally, lstopo enables most hwloc objects and discovery flags
4026+
lstopo enables most hwloc objects and discovery flags
40194027
by default so that the output topology is as precise as possible
40204028
(while hwloc disables many of them by default).
40214029
This includes I/O device discovery through PCI libraries as well as external

0 commit comments

Comments
 (0)