| blob | 17ce8e35ffd60e2c2a56e101a87d52320df9af68 |
1 '\" te
2 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH LGRPINFO 1 "April 9, 2016"
7 .SH NAME
8 lgrpinfo \- display information about locality groups
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBlgrpinfo\fR [\fB-aceGlLmrt\fR] [\fB-u \fR\fIunit\fR] [\fB-C\fR | \fB-P\fR] \fIlgrp\fR ...
13 .fi
15 .LP
16 .nf
17 \fBlgrpinfo\fR \fB-h\fR
18 .fi
20 .LP
21 .nf
22 \fBlgrpinfo\fR \fB-I\fR [\fB-c\fR] [\fB-G\fR] [\fB-C\fR | \fB-P\fR] \fIlgrp\fR ...
23 .fi
25 .LP
26 .nf
27 \fBlgrpinfo\fR [\fB-T\fR] [\fB-aceGlLmr\fR] [\fB-u \fR\fIunit\fR]
28 .fi
30 .SH DESCRIPTION
31 .LP
32 \fBlgrpinfo\fR prints information about the locality group (\fBlgroup\fR)
33 hierarchy and its contents.
34 .sp
35 .LP
36 An lgroup represents the set of CPU and memory-like hardware devices that are
37 at most some distance (latency) apart from each other. All lgroups in the
38 system are identified by a unique integer called an \fBlgroup ID\fR.
39 .sp
40 .LP
41 lgroups are organized into a hierarchy to facilitate finding the nearest
42 resources. Leaf lgroups each contain a set of resources that are closest
43 (local) to each other. Each parent lgroup in the hierarchy contains the
44 resources of its child lgroups plus their next nearest resources. Finally, the
45 \fBroot\fR lgroup contains all the resources in the domain within the largest
46 latency.
47 .sp
48 .LP
49 A Uniform Memory Access (UMA) machine is simply represented by the root lgroup.
50 A Non Uniform Memory Access (NUMA) machine is represented by a hierarchy of
51 lgroups to show the corresponding levels of locality. For example, a NUMA
52 machine with two latencies (local and remote) has an \fBlgroup\fR hierarchy
53 consisting of two levels with its leaves and the root.
54 .sp
55 .LP
56 Every application thread is assigned a \fBhome\fR lgroup. When the system needs
57 to allocate a CPU or memory resource for a thread, it searches lgroup hierarchy
58 from the thread's home lgroup for the closest available resources to the
59 thread's home. See \fBplgrp\fR(1) for details.
60 .sp
61 .LP
62 Without arguments, \fBlgrpinfo\fR prints general information about all lgroups
63 in the system. If any lgroup IDs are specified on the command line, the command
64 only prints information about the specified lgroups. Various options control
65 which lgroups are displayed and the exact information that is printed for each
66 lgroup.
67 .sp
68 .LP
69 lgroups can be specified on the command line as lgroup IDs or by using specific
70 keywords. See \fBOPERANDS\fR.
71 .SH OPTIONS
72 .LP
73 You can combine options together and the order in which options are specified
74 is not important. Lowercase options select what information should be printed
75 about lgroups.
76 .sp
77 .LP
78 Invoking \fBlgrpinfo\fR without arguments is equivalent to:
79 .sp
80 .in +2
81 .nf
82 lgrpinfo -c -e -l -m -r -t all
83 .fi
84 .in -2
85 .sp
87 .sp
88 .LP
89 The following options are supported:
90 .sp
91 .ne 2
92 .na
93 \fB\fB-a\fR\fR
94 .ad
95 .RS 12n
96 Print topology, CPU, memory, load and latency information.
97 .sp
98 This option is a shorthand for
99 .sp
100 .in +2
101 .nf
102 lgrpinfo -t -c -e -m -r -l -L
103 .fi
104 .in -2
105 .sp
107 unless \fB-T\fR is specified as well. When \fB-T\fR is specified, the \fB-t\fR
108 option is not included.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fB-c\fR\fR
115 .ad
116 .RS 12n
117 Print CPU information.
118 .sp
119 This is the default.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fB-C\fR\fR
126 .ad
127 .RS 12n
128 Replace each lgroup in the list with its children.
129 .sp
130 This option cannot be used with the \fB-P\fR or the \fB-T\fR option. When no
131 arguments are specified, this option is applied to the lgroups displayed by
132 default.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fB-e\fR\fR
139 .ad
140 .RS 12n
141 Print lgroup load average. The lgroup load averages are only displayed for leaf
142 lgroups.
143 .sp
144 This is the default.
145 .RE
147 .sp
148 .ne 2
149 .na
150 \fB\fB-G\fR\fR
151 .ad
152 .RS 12n
153 Print OS view of lgroup hierarchy.
154 .sp
155 By default, the caller's view of the lgroup hierarchy is displayed which only
156 includes what the caller can use, for example, only the CPUs in the caller's
157 processor set is displayed. See \fBlgrp_init\fR(3LGRP) on the operating system
158 and the caller's view.
159 .RE
161 .sp
162 .ne 2
163 .na
164 \fB\fB-h\fR\fR
165 .ad
166 .RS 12n
167 Print short help message and exit.
168 .RE
170 .sp
171 .ne 2
172 .na
173 \fB\fB-I\fR\fR
174 .ad
175 .RS 12n
176 Print matching IDs only.
177 .sp
178 This option is intended for scripts and can be used with \fB-c\fR, \fB-G\fR,
179 and \fB-C\fR or \fB-P\fR. If \fB-c\fR is specified, print list of CPUs
180 contained in all matching lgroups. Otherwise, the IDs for the matching lgroups
181 is displayed. See \fBEXAMPLES\fR.
182 .sp
183 When no arguments are specified, this option is applied to the lgroups
184 displayed, which, by default is all lgroups.
185 .RE
187 .sp
188 .ne 2
189 .na
190 \fB\fB-l\fR\fR
191 .ad
192 .RS 12n
193 Print information about lgroup latencies.
194 .sp
195 The latency value specified for each lgroup is defined by the operating system
196 and is platform-specific. It can only be used for relative comparison of
197 lgroups on the running system. It does not necessarily represent the actual
198 latency between hardware devices and might not be applicable across platforms.
199 .RE
201 .sp
202 .ne 2
203 .na
204 \fB\fB-L\fR\fR
205 .ad
206 .RS 12n
207 Print the lgroup latency table. The lgroup latency table displays the relative
208 latency from each lgroup to each of the other lgroups including itself.
209 .RE
211 .sp
212 .ne 2
213 .na
214 \fB\fB-m\fR\fR
215 .ad
216 .RS 12n
217 Print memory information.
218 .sp
219 Memory sizes are scaled to the unit of measure that yields an integer from
220 \fB0\fR to \fB1023\fR unless the \fB-u\fR option is specified as well. The
221 fractional part of the number is only displayed for values less than \fB10\fR.
222 This behavior is similar to using the \fB-h\fR option of \fBls\fR(1) or
223 \fBdf\fR(1M) to display a human readable format.
224 .sp
225 This is the default.
226 .RE
228 .sp
229 .ne 2
230 .na
231 \fB\fB-P\fR\fR
232 .ad
233 .RS 12n
234 Replace each lgroup in the list with its parents.
235 .sp
236 This option cannot be used with the \fB-C\fR or \fB-T\fR option. When no
237 arguments are specified, this option is applied to the lgroups displayed,
238 which, by default is all lgroups.
239 .RE
241 .sp
242 .ne 2
243 .na
244 \fB\fB-r\fR\fR
245 .ad
246 .RS 12n
247 Print information about lgroup resources.
248 .sp
249 The resources are represented by a set of lgroups in which each member lgroup
250 directly contains CPU and memory resources. If \fB-T\fR is specified as well,
251 only information about resources of the intermediate lgroups is displayed.
252 .RE
254 .sp
255 .ne 2
256 .na
257 \fB\fB-t\fR\fR
258 .ad
259 .RS 12n
260 Print information about lgroup topology.
261 .sp
262 This is the default.
263 .RE
265 .sp
266 .ne 2
267 .na
268 \fB\fB-T\fR\fR
269 .ad
270 .RS 12n
271 Print the lgroup topology of a system graphically as a tree. This option can
272 only be used with the \fB-a\fR, \fB-c\fR, \fB-e\fR, \fB-G\fR,
273 \fB-l\fR,\fB-L\fR, \fB-m\fR, \fB-r\fR, and \fB-u\fR options. It only prints
274 lgroup resources for intermediate lgroups when used with the \fB-r\fR. The
275 \fB-t\fR option is omitted when \fB-T\fR is used with \fB-a\fR. No information
276 is printed for the \fBroot\fR lgroup unless it is the only lgroup.
277 .RE
279 .sp
280 .ne 2
281 .na
282 \fB\fB-u\fR \fIunits\fR\fR
283 .ad
284 .RS 12n
285 Specify memory units. Units should be b, k, m, g, t, p, or e for bytes,
286 kilobytes, megabytes, gigabytes, terabytes, petabytes, or exabytes
287 respectively. The fractional part of the number is only displayed for values
288 less than 10. This behavior is similar to using the \fB-h\fR option of
289 \fBls\fR(1) or \fBdf\fR(1M) to display a human readable format.
290 .RE
292 .SH OPERANDS
293 .LP
294 The following operands are supported:
295 .sp
296 .ne 2
297 .na
298 \fB\fIlgrp\fR\fR
299 .ad
300 .RS 8n
301 lgroups can be specified on the command line as lgroup ID, by using one of the
302 following keywords:
303 .sp
304 .ne 2
305 .na
306 \fBall\fR
307 .ad
308 .RS 16n
309 All lgroups.
310 .sp
311 This is the default.
312 .RE
314 .sp
315 .ne 2
316 .na
317 \fBintermediate\fR
318 .ad
319 .RS 16n
320 All intermediate lgroups. An intermediate lgroup is an lgroup that has a parent
321 and children.
322 .RE
324 .sp
325 .ne 2
326 .na
327 \fBleaves\fR
328 .ad
329 .RS 16n
330 All leaf lgroups. A leaf lgroup is an lgroup that has no children in the lgroup
331 hierarchy.
332 .RE
334 .sp
335 .ne 2
336 .na
337 \fBroot\fR
338 .ad
339 .RS 16n
340 Root lgroup. Root lgroup contains all the resources in the domain within the
341 largest latency and has no parent lgroup.
342 .RE
344 .RE
346 .sp
347 .LP
348 If an invalid lgroup is specified, the lgrpinfo command prints a message on
349 standard error showing the invalid ID and continues processing other lgroups
350 specified on the command line. When none of the specified lgroups are valid,
351 \fBlgrpinfo\fR exits with an exit status of \fB2\fR.
352 .SH EXAMPLES
353 .LP
354 \fBExample 1 \fRPrinting Information about lgroups
355 .sp
356 .LP
357 The following example prints general information about lgroups in the system.
359 .sp
360 .LP
361 In this example, the system is a 2 CPU AMD Opteron machine with two nodes, each
362 having one CPU and 2 gigabytes of memory. Each of these nodes is represented by
363 a leaf lgroup. The root lgroup contains all the resources in the machine:
365 .sp
366 .in +2
367 .nf
368 $ lgrpinfo
369 lgroup 0 (root):
370 Children: 1 2
371 CPUs: 0 1
372 Memory: installed 4.0G, allocated 2.2G, free 1.8G
373 Lgroup resources: 1 2 (CPU); 1 2 (memory)
374 Latency: 83
375 lgroup 1 (leaf):
376 Children: none, Parent: 0
377 CPU: 0
378 Memory: installed 2.0G, allocated 1.2G, free 788M
379 Lgroup resources: 1 (CPU); 1 (memory)
380 Load: 0.793
381 Latency: 56
382 lgroup 2 (leaf):
383 Children: none, Parent: 0
384 CPU: 1
385 Memory: installed 2.0G, allocated 1017M, free 1.0G
386 Lgroup resources: 2 (CPU); 2 (memory)
387 Load: 0.817
388 Latency: 56
389 .fi
390 .in -2
391 .sp
393 .LP
394 \fBExample 2 \fRPrinting lgroup Topology
395 .sp
396 .LP
397 The following example prints the lgroup topology tree on a 4 CPU AMD Opteron
398 machine:
400 .sp
401 .in +2
402 .nf
403 $ lgrpinfo -T
404 0
405 |-- 5
406 | `-- 1
407 |-- 6
408 | `-- 2
409 |-- 7
410 | `-- 3
411 `-- 8
412 `-- 4
413 .fi
414 .in -2
415 .sp
417 .LP
418 \fBExample 3 \fRPrinting lgroup Topology
419 .sp
420 .LP
421 The following example prints the lgroup topology tree, resources, memory and
422 CPU information on a 2 CPU AMD Opteron machine:
424 .sp
425 .in +2
426 .nf
427 $ lgrpinfo -Ta
428 0
429 |-- 1
430 | CPU: 0
431 | Memory: installed 2.0G, allocated 1.2G, free 790M
432 | Load: 0.274
433 | Latency: 56
434 `-- 2
435 CPU: 1
436 Memory: installed 2.0G, allocated 1019M, free 1.0G
437 Load: 0.937
438 Latency: 56
440 Lgroup latencies:
442 ------------
443 | 0 1 2
444 ------------
445 0 | 83 83 83
446 1 | 83 56 83
447 2 | 83 83 56
448 ------------
449 .fi
450 .in -2
451 .sp
453 .LP
454 \fBExample 4 \fRPrinting lgroup IDs
455 .sp
456 .LP
457 The following example prints lgroup IDs for children of the root lgroup:
459 .sp
460 .in +2
461 .nf
462 $ lgrpinfo -I -C root
463 1 2
464 .fi
465 .in -2
466 .sp
468 .LP
469 \fBExample 5 \fRPrinting CPU IDs
470 .sp
471 .LP
472 The following example prints CPU IDs for all CPUs in lgroup 1:
474 .sp
475 .in +2
476 .nf
477 $ lgrpinfo -c -I 1
478 0
479 .fi
480 .in -2
481 .sp
483 .LP
484 \fBExample 6 \fRPrinting Information about lgropu Latencies
485 .sp
486 .LP
487 The following example prints information about lgroup latencies:
489 .sp
490 .in +2
491 .nf
492 $ lgrpinfo -l
493 lgroup 0 (root):
494 Latency: 83
495 lgroup 1 (leaf):
496 Latency: 56
497 lgroup 2 (leaf):
498 Latency: 5
499 .fi
500 .in -2
501 .sp
503 .SH EXIT STATUS
504 .LP
505 The following exit values are returned:
506 .sp
507 .ne 2
508 .na
509 \fB\fB0\fR\fR
510 .ad
511 .RS 5n
512 Successful completion.
513 .RE
515 .sp
516 .ne 2
517 .na
518 \fB\fB1\fR\fR
519 .ad
520 .RS 5n
521 Unable to get lgroup information from the system.
522 .RE
524 .sp
525 .ne 2
526 .na
527 \fB\fB2\fR\fR
528 .ad
529 .RS 5n
530 All lgroups specified are invalid.
531 .RE
533 .sp
534 .ne 2
535 .na
536 \fB\fB3\fR\fR
537 .ad
538 .RS 5n
539 Invalid syntax.
540 .RE
542 .SH ATTRIBUTES
543 .LP
544 See \fBattributes\fR(5) for descriptions of the following attributes:
545 .sp
547 .sp
548 .TS
549 box;
550 c | c
551 l | l .
552 ATTRIBUTE TYPE ATTRIBUTE VALUE
553 _
554 Interface Stability See below.
555 .TE
557 .sp
558 .LP
559 The human readable output is Unstable.
560 .SH SEE ALSO
561 .LP
562 \fBls\fR(1), \fBplgrp\fR(1), \fBpmap\fR(1), \fBproc\fR(1), \fBps\fR(1),
563 \fBdf\fR(1M), \fBprstat\fR(1M), \fBlgrp_init\fR(3LGRP), \fBliblgrp\fR(3LIB),
564 \fBproc\fR(4), \fBattributes\fR(5)