| lgrpinfo - display information about locality groups |
NAME
lgrpinfo - display information about locality groups
SYNOPSYS
lgrpinfo [-aceGlLmrt] [-u unit] [-C|-P] [lgrp ...] lgrpinfo -h lgrpinfo -I [-c] [-G] [-C|-P] [lgrp ...] lgrpinfo -T [-aceGlLmr] [-u unit]
DESCRIPTION
The lgrpinfo command prints information about the locality group (lgroup) hierarchy and its contents.
An lgroup represents the set of CPU and memory-like hardware devices that areat most some distance (latency) apart from each other. All lgroups in the system are identified by a unique integer called an ``lgroup ID''.
The lgroups are organized into a hierarchy to facilitate finding the nearest resources. Leaf lgroups each contain a set of resources that are closest (local) to each other. Each parent lgroup in the hierarchy contains the resources of its child lgroups plus their next nearest resources. Finally, the root lgroup contains all the resources in the domain within the largest latency.
A Uniform Memory Access (UMA) machine will simply be represented by the root lgroup. A Non Uniform Memory Access (NUMA) machine is represented by a hierarchy of lgroups to show the corresponding levels of locality. For example, a NUMA machine with two latencies (local and remote) will have an lgroup hierarchy consisting of two levels with its leaves and the root.
Every application thread is assigned a ``home'' lgroup. When the system needs to allocate a CPU or memory resource for a thread, it searches lgroup hierarchy from the thread's home lgroup for the closest available resources to the thread's home. Please see plgrp(1) for more details.
When called without any arguments, lgrpinfo(1) prints general information about all lgroups in the system. If any lgroup IDs are given in the command line, the command will only print information about the specified lgroups.
The lgroup(s) may be specified on the command line as lgroup IDs or by using one of the following keywords:
- all
- All lgroups (default)
- root
- Root lgroup (which contains all the resources in the domain within the largest latency and has no parent lgroup)
- leaves
- All leaf lgroups (where a leaf lgroup is an lgroup that has no children in the lgroup hierarchy)
- intermediate
- All intermediate lgroups (where an intermediate lgroup is an lgroup that has a parent and children)
If an invalid lgroup is specified, the lgrpinfo command prints a message on standard error showing the invalid ID and continues processing other lgroups given in the command line. When none of the specified lgroups are valid, lgrpinfo(1) will exit with 2 as its exit status.
OPTIONS
Various options control which lgroups are displayed and the exact informationthat is printed for each lgroup. Options may be combined together and the order given is not important. Lowercase options select what information should be printed about lgroup(s).
Calling the program without any arguments is equivalent to
lgrpinfo -c -e -l -m -r -t all
Valid options are:
- -a
- Print topology, CPU, memory, load and latency information. This option is a shorthand for -t -c -e -m -r -l -L unless -T is specified as well. When -T is specified, the -t option is not included.
- -c
- Print CPU information (default)
- -C
- Replace each lgroup in the list with its children(s). This option cannot be used with the -P or -T option. When no arguments are given, this option will be applied to the lgroups displayed by default which is all of them.
- -e
- Print lgroup load average (default). Currently, the lgroup load averages are only displayed for leaf lgroups.
- -G
- Print OS view of lgroup hierarchy. By default, the caller's view of the lgroup hierarchy is displayed which only includes what the caller can use (eg. only the CPUs in the caller's processor set will be displayed, etc.). Please see lgrp_init(3LGRP) for more details on the OS and caller's view.
- -h
- Print short help message and exit.
- -I
- Only print matching IDs. This option is mostly intended for scripts and may be used with -c, -G, and -C or -P. If -c is specified, print list of CPUs contained in all matching lgroups. Otherwise, the IDs for the matching lgroups will be displayed (see examples). When no arguments are given, this option will be applied to the lgroups displayed by default which is all of them.
- -l
- Print information about lgroup latencies. The latency value given for each lgroup is defined by the operating system and is platform-specific. It can only be used for relative comparison of lgroups on the running system. It does not necessarily represent the actual latency between hardware devices and may not be applicable across platforms.
- -L
- Print the lgroup latency table which is a table that shows the relative latency from each lgroup to each of the other lgroups including itself.
- -m
- Print memory information (default). Memory sizes are scaled to the unit of measure that yields an integer from 0 to 1023 unless the -u option is specified as well. The fractional part of the number is only displayed for values less than 10. This behavior is similiar to what the -h option does for ls(1) and df(1M) to display a human readable format.
- -P
- Replace each lgroup in the list with its parent(s). This option cannot be used with the -C or -T option. When no arguments are given, this option will be applied to the lgroups displayed by default which is all of them.
- -r
- Print information about lgroup resources. The resources are represented by a set of lgroups in which each member lgroup directly contains CPU and/or memory resources. If -T is specified as well, only information about resources of the intermediate lgroups is displayed.
- -t
- Print information about lgroup topology (default).
- -T
- Print the lgroup topology of a system graphically as a tree. This option may only be used with the -a, -c, -e, -G, -l, -L, -m, -r, and -u options. It will only print lgroup resources for intermediate lgroups when used with the -r. The -t option is omitted when -T is used with -a. No information is printed for the root lgroup unless it is the only lgroup.
- -u units
- Specify memory units. Units should be b, k, m, g, t, p, or e for bytes, kilobytes, megabytes, gigabytes, terabytes, petabytes, or exabytes respectively. The fractional part of the number is only displayed for values less than 10. This behavior is similiar to what the -h option does for ls(1) and df(1M) to display a human readable format.
EXAMPLES
1.
$ lgrpinfo
lgroup 0 (root):
Children: 1 2
CPUs: 0 1
Memory: installed 4.0G, allocated 2.2G, free 1.8G
Lgroup resources: 1 2 (CPU); 1 2 (memory)
Latency: 83
lgroup 1 (leaf):
Children: none, Parent: 0
CPU: 0
Memory: installed 2.0G, allocated 1.2G, free 788M
Lgroup resources: 1 (CPU); 1 (memory)
Load: 0.793
Latency: 56
lgroup 2 (leaf):
Children: none, Parent: 0
CPU: 1
Memory: installed 2.0G, allocated 1017M, free 1.0G
Lgroup resources: 2 (CPU); 2 (memory)
Load: 0.817
Latency: 56
1.
$ lgrpinfo -T
0
|~-- 5
| `~-- 1
|~-- 6
| `~-- 2
|~-- 7
| `~-- 3
`~-- 8
`~-- 4
1.
$ lgrpinfo -Ta
0
|~-- 1
| CPU: 0
| Memory: installed 2.0G, allocated 1.2G, free 790M
| Load: 0.274
| Latency: 56
`~-- 2
CPU: 1
Memory: installed 2.0G, allocated 1019M, free 1.0G
Load: 0.937
Latency: 56
Lgroup latencies:
~------------
| 0 1 2
~------------
0 | 83 83 83
1 | 83 56 83
2 | 83 83 56
~------------
1.
$ lgrpinfo -I -C root 1 2
1.
$ lgrpinfo -c -I 1 0
1.
$ lgrpinfo -l
lgroup 0 (root):
Latency: 83
lgroup 1 (leaf):
Latency: 56
lgroup 2 (leaf):
Latency: 56
EXIT STATUS
The following exit values are returned:
0 Successful operation.
1 Unable to get lgroup information from the system.
2 All lgroups specified are invalid
3 Invalid syntax
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
{{{___________________________________________________________}}}
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|{{{_____________________________}}}|{{{_____________________________}}}|
| Availability | SUNWesu |
|{{{_____________________________}}}|{{{_____________________________}}}|
| Interface Stability | Unstable |
|{{{_____________________________}}}|{{{_____________________________}}}|
Human readable output is unstable.
SEE ALSO
the Sun::Solaris::Lgrp(1) manpage, plgrp(1), pmap(1), ps(1), prstat(1M), liblgrp(3LIB), lgrp_init(3LGRP), attributes(5).
| lgrpinfo - display information about locality groups |