1LSTOPO(1) hwloc LSTOPO(1)
2
6 lstopo, lstopo-no-graphics - Show the topology of the system (note that
7 hwloc-bind(1) provides a detailed explanation of the hwloc system; it
8 should be read before reading this man page).
9
11 lstopo [ options ]... [ filename ]
12 lstopo-no-graphics [ options ]... [ filename ]
14
16 --of <format>, --output-format <format>
17 Enforce the output in the given format. See the OUTPUT FORMATS
18 section below.
19 -i <file>, --input <file>
21 Read topology from XML file <file> (instead of discovering the
22 topology on the local machine). If <file> is "-", the standard
23 input is used. XML support must have been compiled in to hwloc
24 for this option to be usable.
25 -i <directory>, --input <directory>
27 Read topology from the chroot specified by <directory> (instead
28 of discovering the topology on the local machine). This option
29 is generally only available on Linux. The chroot was usually
30 created by gathering another machine topology with hwloc-gather-
31 topology.
32 -i <specification>, --input <specification>
34 Simulate a fake hierarchy (instead of discovering the topology
35 on the local machine). If <specification> is "node:2 pu:3", the
36 topology will contain two NUMA nodes with 3 processing units in
37 each of them. The <specification> string must end with a number
38 of PUs.
39 --if <format>, --input-format <format>
41 Enforce the input in the given format, among xml, fsroot and
42 synthetic.
43 -v --verbose
45 Include additional detail.
46 -s --silent
48 Reduce the amount of details to show.
49 -l --logical
51 Display hwloc logical indexes instead of physical/OS indexes
52 (default for console output). These indexes are prefixed with
53 "L#". The physical indexes of some objects (PU and Node by
54 default, all objects if verbose) will appear as object attribute
55 "P#...".
56 -p --physical
58 Display OS/physical indexes instead of hwloc logical indexes
59 (default for graphical output). These indexes are prefixed with
60 "P#" instead of "L#" in the console output.
61 -c --cpuset
63 Display the cpuset of each object.
64 -C --cpuset-only
66 Only display the cpuset of each object; do not display anything
67 else about the object.
68 --taskset
70 Show CPU set strings in the format recognized by the taskset
71 command-line program instead of hwloc-specific CPU set string
72 format. This option should be combined with --cpuset or
73 --cpuset-only, otherwise it will imply --cpuset.
74 --only <type>
76 Only show objects of the given type in the textual output.
77 --ignore <type>
79 Ignore all objects of type <type> in the topology.
80 --no-caches
82 Do not show caches.
83 --no-useless-caches
85 Do not show caches which do not have a hierarchical impact.
86 --no-icaches
88 Do not show Instruction caches, only Data and Unified caches are
89 displayed.
90 --whole-system
92 Do not consider administration limitations.
93 --merge
95 Do not show levels that do not have a hierarchical impact.
96 --restrict <cpuset>
98 Restrict the topology to the given cpuset.
99 --restrict binding
101 Restrict the topology to the current process binding. This
102 option requires the use of the actual current machine topology
103 (or any other topology with --thissystem or with HWLOC_THISSYS‐
104 TEM set to 1 in the environment).
105 --no-io
107 Do not show any I/O device or bridge. By default, common
108 devices (GPUs, NICs, block devices, ...) and interesting bridges
109 are shown.
110 --no-bridges
112 Do not show any I/O bridge except hostbridges. By default, com‐
113 mon devices (GPUs, NICs, block devices, ...) and interesting
114 bridges are shown.
115 --whole-io
117 Show all I/O devices and bridges. By default, only common
118 devices (GPUs, NICs, block devices, ...) and interesting bridges
119 are shown.
120 --thissystem
122 Assume that the selected backend provides the topology for the
123 system on which we are running. This is useful when using
124 --restrict binding and loading a custom topology such as an XML
125 file.
126 --pid <pid>
128 Detect topology as seen by process <pid>, i.e. as if process
129 <pid> did the discovery itself. Note that this can for instance
130 change the set of allowed processors. Also show this process
131 current CPU binding in the graphical output (in Green, see the
132 COLORS section below). If 0 is given as pid, the current bind‐
133 ing for the lstopo process will be shown.
134 --ps --top
136 Show existing processes as misc objects in the output. To avoid
137 uselessly cluttering the output, only processes that are
138 restricted to some part of the machine are shown. On Linux,
139 kernel threads are not shown. If many processes appear, the
140 output may become hard to read anyway, making the hwloc-ps pro‐
141 gram more practical.
142 --fontsize <size>
144 Set size of text font.
145 --gridsize <size>
147 Set size of margin between elements.
148 --horiz, --horiz=<type1,...>
150 Horizontal graphical layout instead of nearly 4/3 ratio. If a
151 comma-separated list of types is given, the layout only applies
152 to the corresponding containers.
153 --vert, --vert=<type1,...>
155 Vertical graphical layout instead of nearly 4/3 ratio. If a
156 comma-separated list of types is given, the layout only applies
157 to the corresponding containers.
158 --no-legend
160 Remove the text legend at the bottom.
161 --version
163 Report version and exit.
164
166 lstopo and lstopo-no-graphics are capable of displaying a topological
167 map of the system in a variety of different output formats. The only
168 difference between lstopo and lstopo-no-graphics is that graphical out‐
169 puts are only supported by lstopo, to reduce dependencies on external
170 libraries.
171 If no filename is specified and the DISPLAY environment variable is
173 set, lstopo displays the map in a graphical window. If no filename is
174 specified and the DISPLAY environment variable is not set, a text sum‐
175 mary is displayed.
176 The filename specified directly implies the output format that will be
178 used; see the OUTPUT FORMATS section, below. Output formats that sup‐
179 port color will indicate specific characteristics about individual CPUs
180 by their color; see the COLORS section, below.
181
183 The filename on the command line usually determines the format of the
184 output. There are a few filenames that indicate specific output for‐
185 mats and devices (e.g., a filename of "-" will output a text summary to
186 stdout), but most filenames indicate the desired output format by their
187 suffix (e.g., "topo.png" will output a PNG-format file).
188 The format of the output may also be changed with "--of". For
190 instance, "--of pdf" will generate a PDF-format file on the standard
191 output, while "--of fig toto" will output a Xfig-format file named
192 "toto".
193 The list of currently supported formats is given below. Any of them may
196 be used with "--of" or as a filename suffix.
197 default
199 Send the output to a window or to the console depending on the
200 environment.
201 console
203 Send a text summary to stdout. No color annotation for binding,
204 unallowed or offline processors is shown in this mode; see the
205 COLORS section, below.
206 txt Output an ASCII art representation of the map. If outputting to
208 stdout and if colors are supported on the terminal, the output
209 will be colorized.
210 fig Output a representation of the map that can be loaded in Xfig.
212 pdf If lstopo was compiled with the proper support, lstopo outputs a
214 PDF representation of the map.
215 ps If lstopo was compiled with the proper support, lstopo outputs a
217 Postscript representation of the map.
218 png If lstopo was compiled with the proper support, lstopo outputs a
220 PNG representation of the map.
221 svg If lstopo was compiled with the proper support, lstopo outputs
223 an SVG representation of the map.
224 synthetic
226 If the topology is symmetric, lstopo outputs a synthetic
227 description string. This output may be reused as an input syn‐
228 thetic topology description later.
229 xml If lstopo was compiled with the proper support, lstopo outputs
231 an XML representation of the map. It may be reused later, even
232 on another machine, with lstopo --input, the HWLOC_XMLFILE envi‐
233 ronment variable, or the hwloc_topology_set_xml() function.
234 The following special names may be used:
237 - Send a text summary to stdout.
239 /dev/stdout
241 Send a text summary to stdout. It is effectively the same as
242 specifying "-".
243 -.<format>
245 If the entire filename is "-.<format>", lstopo behaves as if
246 "--of <format> -" was given, which means a file of the given
247 format is sent to the standard output.
248 See the output of "lstopo --help" for a specific list of what graphical
251 output formats are supported in your hwloc installation.
252
254 Individual CPUs are colored in the semi-graphical and graphical output
255 formats to indicate different characteristics:
256 Green The topology is reported as seen by a specific process (see
258 --pid), and the given CPU is in this process CPU binding mask.
259 White The CPU is in the allowed set (see below). If the topology is
261 reported as seen by a specific process (see --pid), the given
262 CPU is also not in this process CPU binding mask.
263 Red The CPU is not in the allowed set (see below).
265 Black The CPU is offline (not all OS's support displaying offline
267 CPUs).
268 The "allowed set" is the set of CPUs to which the current process is
270 allowed to bind. The allowed set is usually either inherited from the
271 parent process or set by administrative qpolicies on the system. Linux
272 cpusets are one example of limiting the allowed set for a process and
273 its children to be less than the full set of CPUs on the system.
274 Different processes may therefore have different CPUs in the allowed
276 set. Hence, invoking lstopo in different contexts and/or as different
277 users may display different colors for the same individual CPUs (e.g.,
278 running lstopo in one context may show a specific CPU as red, but run‐
279 ning lstopo in a different context may show the same CPU as white).
280 Some lstopo output modes, e.g. the console mode (default non-graphical
282 output), do not support colors at all. The above characteristics are
283 not shown in this case.
284
286 In its graphical output, lstopo uses simple rectangular heuristics to
287 try to achieve a 4/3 ratio between width and height. However, in the
288 particular case of NUMA nodes, the layout is always a flat rectangle,
289 to avoid letting the user believe any particular NUMA topology (lstopo
290 is not able to render that yet).
291
293 To display the machine topology in textual mode:
294 lstopo-no-graphics
296 To display the machine topology in pseudo-graphical mode:
298 lstopo-no-graphics -.txt
300 To display in graphical mode (assuming that the DISPLAY environment
302 variable is set to a relevant value):
303 lstopo
305 To export the topology to a PNG file:
307 lstopo file.png
309 To export an XML file on a machine and later display the corresponding
311 graphical output on another machine:
312 machine1$ lstopo file.xml
314 <transfer file.xml from machine1 to machine2>
315 machine2$ lstopo --input file.xml
316 To save the current machine topology to XML and later reload it faster
318 while still considering it as the current machine:
319 $ lstopo file.xml
321 <...>
322 $ lstopo --input file.xml --thissystem
323 To restrict an XML topology to only physical processors 0, 1, 4 and 5:
325 lstopo --input file.xml --restrict 0x33 newfile.xml
327 To restrict an XML topology to only numa node whose logical index is 1:
329 lstopo --input file.xml --restrict $(hwloc-calc --input file.xml
331 node:1) newfile.xml
332 To display a summary of the topology:
334 lstopo -s
336 To get more details about the topology:
338 lstopo -v
340 To only show cores:
342 lstopo --only core
344 To show cpusets:
346 lstopo --cpuset
348 To only show the cpusets of sockets:
350 lstopo --only socket --cpuset-only
352 Simulate a fake hierarchy; this example shows with 2 NUMA nodes of 2
354 processor units:
355 lstopo --input "n:2 2"
357 To count the number of logical processors in the system
359 lstopo --only pu | wc -l
361
363 hwloc-bind(1), hwloc-ps(1), hwloc-gather-topology(1)
3641.5 Jul 30, 2012 LSTOPO(1)