1 LGRPINFO(1) User Commands LGRPINFO(1) 2 3 4 5 NAME 6 lgrpinfo - display information about locality groups 7 8 SYNOPSIS 9 lgrpinfo [-aceGlLmrt] [-u unit] [-C | -P] lgrp ... 10 11 12 lgrpinfo -h 13 14 15 lgrpinfo -I [-c] [-G] [-C | -P] lgrp ... 16 17 18 lgrpinfo [-T] [-aceGlLmr] [-u unit] 19 20 21 DESCRIPTION 22 lgrpinfo prints information about the locality group (lgroup) hierarchy 23 and its contents. 24 25 26 An lgroup represents the set of CPU and memory-like hardware devices 27 that are at most some distance (latency) apart from each other. All 28 lgroups in the system are identified by a unique integer called an 29 lgroup ID. 30 31 32 lgroups are organized into a hierarchy to facilitate finding the 33 nearest resources. Leaf lgroups each contain a set of resources that 34 are closest (local) to each other. Each parent lgroup in the hierarchy 35 contains the resources of its child lgroups plus their next nearest 36 resources. Finally, the root lgroup contains all the resources in the 37 domain within the largest latency. 38 39 40 A Uniform Memory Access (UMA) machine is simply represented by the root 41 lgroup. A Non Uniform Memory Access (NUMA) machine is represented by a 42 hierarchy of lgroups to show the corresponding levels of locality. For 43 example, a NUMA machine with two latencies (local and remote) has an 44 lgroup hierarchy consisting of two levels with its leaves and the root. 45 46 47 Every application thread is assigned a home lgroup. When the system 48 needs to allocate a CPU or memory resource for a thread, it searches 49 lgroup hierarchy from the thread's home lgroup for the closest 50 available resources to the thread's home. See plgrp(1) for details. 51 52 53 Without arguments, lgrpinfo prints general information about all 54 lgroups in the system. If any lgroup IDs are specified on the command 55 line, the command only prints information about the specified lgroups. 56 Various options control which lgroups are displayed and the exact 57 information that is printed for each lgroup. 58 59 60 lgroups can be specified on the command line as lgroup IDs or by using 61 specific keywords. See OPERANDS. 62 63 OPTIONS 64 You can combine options together and the order in which options are 65 specified is not important. Lowercase options select what information 66 should be printed about lgroups. 67 68 69 Invoking lgrpinfo without arguments is equivalent to: 70 71 lgrpinfo -c -e -l -m -r -t all 72 73 74 75 76 The following options are supported: 77 78 -a 79 Print topology, CPU, memory, load and latency information. 80 81 This option is a shorthand for 82 83 lgrpinfo -t -c -e -m -r -l -L 84 85 86 unless -T is specified as well. When -T is specified, the 87 -t option is not included. 88 89 90 -c 91 Print CPU information. 92 93 This is the default. 94 95 96 -C 97 Replace each lgroup in the list with its children. 98 99 This option cannot be used with the -P or the -T option. 100 When no arguments are specified, this option is applied to 101 the lgroups displayed by default. 102 103 104 -e 105 Print lgroup load average. The lgroup load averages are 106 only displayed for leaf lgroups. 107 108 This is the default. 109 110 111 -G 112 Print OS view of lgroup hierarchy. 113 114 By default, the caller's view of the lgroup hierarchy is 115 displayed which only includes what the caller can use, for 116 example, only the CPUs in the caller's processor set is 117 displayed. See lgrp_init(3LGRP) on the operating system and 118 the caller's view. 119 120 121 -h 122 Print short help message and exit. 123 124 125 -I 126 Print matching IDs only. 127 128 This option is intended for scripts and can be used with 129 -c, -G, and -C or -P. If -c is specified, print list of 130 CPUs contained in all matching lgroups. Otherwise, the IDs 131 for the matching lgroups is displayed. See EXAMPLES. 132 133 When no arguments are specified, this option is applied to 134 the lgroups displayed, which, by default is all lgroups. 135 136 137 -l 138 Print information about lgroup latencies. 139 140 The latency value specified for each lgroup is defined by 141 the operating system and is platform-specific. It can only 142 be used for relative comparison of lgroups on the running 143 system. It does not necessarily represent the actual 144 latency between hardware devices and might not be 145 applicable across platforms. 146 147 148 -L 149 Print the lgroup latency table. The lgroup latency table 150 displays the relative latency from each lgroup to each of 151 the other lgroups including itself. 152 153 154 -m 155 Print memory information. 156 157 Memory sizes are scaled to the unit of measure that yields 158 an integer from 0 to 1023 unless the -u option is specified 159 as well. The fractional part of the number is only 160 displayed for values less than 10. This behavior is 161 similar to using the -h option of ls(1) or df(1M) to 162 display a human readable format. 163 164 This is the default. 165 166 167 -P 168 Replace each lgroup in the list with its parents. 169 170 This option cannot be used with the -C or -T option. When 171 no arguments are specified, this option is applied to the 172 lgroups displayed, which, by default is all lgroups. 173 174 175 -r 176 Print information about lgroup resources. 177 178 The resources are represented by a set of lgroups in which 179 each member lgroup directly contains CPU and memory 180 resources. If -T is specified as well, only information 181 about resources of the intermediate lgroups is displayed. 182 183 184 -t 185 Print information about lgroup topology. 186 187 This is the default. 188 189 190 -T 191 Print the lgroup topology of a system graphically as a 192 tree. This option can only be used with the -a, -c, -e, -G, 193 -l,-L, -m, -r, and -u options. It only prints lgroup 194 resources for intermediate lgroups when used with the -r. 195 The -t option is omitted when -T is used with -a. No 196 information is printed for the root lgroup unless it is the 197 only lgroup. 198 199 200 -u units 201 Specify memory units. Units should be b, k, m, g, t, p, or 202 e for bytes, kilobytes, megabytes, gigabytes, terabytes, 203 petabytes, or exabytes respectively. The fractional part of 204 the number is only displayed for values less than 10. This 205 behavior is similar to using the -h option of ls(1) or 206 df(1M) to display a human readable format. 207 208 209 OPERANDS 210 The following operands are supported: 211 212 lgrp 213 lgroups can be specified on the command line as lgroup ID, by 214 using one of the following keywords: 215 216 all 217 All lgroups. 218 219 This is the default. 220 221 222 intermediate 223 All intermediate lgroups. An intermediate 224 lgroup is an lgroup that has a parent and 225 children. 226 227 228 leaves 229 All leaf lgroups. A leaf lgroup is an lgroup 230 that has no children in the lgroup hierarchy. 231 232 233 root 234 Root lgroup. Root lgroup contains all the 235 resources in the domain within the largest 236 latency and has no parent lgroup. 237 238 239 240 241 If an invalid lgroup is specified, the lgrpinfo command prints a 242 message on standard error showing the invalid ID and continues 243 processing other lgroups specified on the command line. When none of 244 the specified lgroups are valid, lgrpinfo exits with an exit status of 245 2. 246 247 EXAMPLES 248 Example 1 Printing Information about lgroups 249 250 251 The following example prints general information about lgroups in the 252 system. 253 254 255 256 In this example, the system is a 2 CPU AMD Opteron machine with two 257 nodes, each having one CPU and 2 gigabytes of memory. Each of these 258 nodes is represented by a leaf lgroup. The root lgroup contains all the 259 resources in the machine: 260 261 262 $ lgrpinfo 263 lgroup 0 (root): 264 Children: 1 2 265 CPUs: 0 1 266 Memory: installed 4.0G, allocated 2.2G, free 1.8G 267 Lgroup resources: 1 2 (CPU); 1 2 (memory) 268 Latency: 83 269 lgroup 1 (leaf): 270 Children: none, Parent: 0 271 CPU: 0 272 Memory: installed 2.0G, allocated 1.2G, free 788M 273 Lgroup resources: 1 (CPU); 1 (memory) 274 Load: 0.793 275 Latency: 56 276 lgroup 2 (leaf): 277 Children: none, Parent: 0 278 CPU: 1 279 Memory: installed 2.0G, allocated 1017M, free 1.0G 280 Lgroup resources: 2 (CPU); 2 (memory) 281 Load: 0.817 282 Latency: 56 283 284 285 286 Example 2 Printing lgroup Topology 287 288 289 The following example prints the lgroup topology tree on a 4 CPU AMD 290 Opteron machine: 291 292 293 $ lgrpinfo -T 294 0 295 |-- 5 296 | `-- 1 297 |-- 6 298 | `-- 2 299 |-- 7 300 | `-- 3 301 `-- 8 302 `-- 4 303 304 305 306 Example 3 Printing lgroup Topology 307 308 309 The following example prints the lgroup topology tree, resources, 310 memory and CPU information on a 2 CPU AMD Opteron machine: 311 312 313 $ lgrpinfo -Ta 314 0 315 |-- 1 316 | CPU: 0 317 | Memory: installed 2.0G, allocated 1.2G, free 790M 318 | Load: 0.274 319 | Latency: 56 320 `-- 2 321 CPU: 1 322 Memory: installed 2.0G, allocated 1019M, free 1.0G 323 Load: 0.937 324 Latency: 56 325 326 Lgroup latencies: 327 328 ------------ 329 | 0 1 2 330 ------------ 331 0 | 83 83 83 332 1 | 83 56 83 333 2 | 83 83 56 334 ------------ 335 336 337 338 Example 4 Printing lgroup IDs 339 340 341 The following example prints lgroup IDs for children of the root 342 lgroup: 343 344 345 $ lgrpinfo -I -C root 346 1 2 347 348 349 350 Example 5 Printing CPU IDs 351 352 353 The following example prints CPU IDs for all CPUs in lgroup 1: 354 355 356 $ lgrpinfo -c -I 1 357 0 358 359 360 361 Example 6 Printing Information about lgroup Latencies 362 363 364 The following example prints information about lgroup latencies: 365 366 367 $ lgrpinfo -l 368 lgroup 0 (root): 369 Latency: 83 370 lgroup 1 (leaf): 371 Latency: 56 372 lgroup 2 (leaf): 373 Latency: 5 374 375 376 377 EXIT STATUS 378 The following exit values are returned: 379 380 0 381 Successful completion. 382 383 384 1 385 Unable to get lgroup information from the system. 386 387 388 2 389 All lgroups specified are invalid. 390 391 392 3 393 Invalid syntax. 394 395 396 ATTRIBUTES 397 See attributes(5) for descriptions of the following attributes: 398 399 400 401 402 +--------------------+-----------------+ 403 | ATTRIBUTE TYPE | ATTRIBUTE VALUE | 404 +--------------------+-----------------+ 405 |Interface Stability | See below. | 406 +--------------------+-----------------+ 407 408 409 The human readable output is Unstable. 410 411 SEE ALSO 412 ls(1), plgrp(1), pmap(1), proc(1), ps(1), df(1M), prstat(1M), 413 lgrp_init(3LGRP), liblgrp(3LIB), proc(4), attributes(5) 414 415 416 417 April 9, 2016 LGRPINFO(1)