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)