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
  14 
  15 .LP
  16 .nf
  17 \fBlgrpinfo\fR \fB-h\fR
  18 .fi
  19 
  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
  24 
  25 .LP
  26 .nf
  27 \fBlgrpinfo\fR [\fB-T\fR] [\fB-aceGlLmr\fR] [\fB-u \fR\fIunit\fR]
  28 .fi
  29 
  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
  86 
  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
 106 
 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
 110 
 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
 121 
 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
 134 
 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
 146 
 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
 160 
 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
 169 
 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
 186 
 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
 200 
 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
 210 
 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
 227 
 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
 240 
 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
 253 
 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
 264 
 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
 278 
 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
 291 
 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
 313 
 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
 323 
 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
 333 
 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
 343 
 344 .RE
 345 
 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.
 358 
 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:
 364 
 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
 392 
 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:
 399 
 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
 416 
 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:
 423 
 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
 439 
 440 Lgroup latencies:
 441 
 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
 452 
 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:
 458 
 459 .sp
 460 .in +2
 461 .nf
 462 $ lgrpinfo -I -C root
 463   1 2
 464 .fi
 465 .in -2
 466 .sp
 467 
 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:
 473 
 474 .sp
 475 .in +2
 476 .nf
 477 $ lgrpinfo -c -I 1
 478   0
 479 .fi
 480 .in -2
 481 .sp
 482 
 483 .LP
 484 \fBExample 6 \fRPrinting Information about lgroup Latencies
 485 .sp
 486 .LP
 487 The following example prints information about lgroup latencies:
 488 
 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
 502 
 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
 514 
 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
 523 
 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
 532 
 533 .sp
 534 .ne 2
 535 .na
 536 \fB\fB3\fR\fR
 537 .ad
 538 .RS 5n
 539 Invalid syntax.
 540 .RE
 541 
 542 .SH ATTRIBUTES
 543 .LP
 544 See \fBattributes\fR(5) for descriptions of the following attributes:
 545 .sp
 546 
 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
 556 
 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)