User Commands lgrpinfo(1)
NAME
lgrpinfo - display information about locality groups
SYNOPSIS
lgrpinfo [-aceGlLmrt] [-u unit] [-C -P] lgrp ...
lgrpinfo -h
lgrpinfo -I [-c] [-G] [-C -P] lgrp ...
lgrpinfo [-T] [-aceGlLmr] [-u unit]
DESCRIPTION
lgrpinfo prints information about the locality group
(lgroup) hierarchy and its contents.
An lgroup represents the set of CPU and memory-like hardware
devices that are at most some distance (latency) apart from
each other. All lgroups in the system are identified by a
unique integer called an lgroup ID.
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 is simply 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) has 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. See plgrp(1) for details.
SunOS 5.11 Last change: 11 Sep 2006 1
User Commands lgrpinfo(1)
Without arguments, lgrpinfo prints general information about
all lgroups in the system. If any lgroup IDs are specified
on the command line, the command only prints information
about the specified lgroups. Various options control which
lgroups are displayed and the exact information that is
printed for each lgroup.
lgroups can be specified on the command line as lgroup IDs
or by using specific keywords. See OPERANDS.
OPTIONS
You can combine options together and the order in which
options are specified is not important. Lowercase options
select what information should be printed about lgroups.
Invoking lgrpinfo without arguments is equivalent to:
lgrpinfo -c -e -l -m -r -t all
The following options are supported:
-a Print topology, CPU, memory, load and latency
information.
This option is a shorthand for
lgrpinfo -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.
This is the default.
-C Replace each lgroup in the list with its chil-
dren.
This option cannot be used with the -P or the -T
option. When no arguments are specified, this
option is applied to the lgroups displayed by
default.
SunOS 5.11 Last change: 11 Sep 2006 2
User Commands lgrpinfo(1)
-e Print lgroup load average. The lgroup load aver-
ages are only displayed for leaf lgroups.
This is the default.
-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, for example, only the CPUs
in the caller's processor set is displayed. See
lgrpinit(3LGRP) on the operating system and the
caller's view.
-h Print short help message and exit.
-I Print matching IDs only.
This option is intended for scripts and can be
used with -c, -G, and -C or -P. If -c is speci-
fied, print list of CPUs contained in all match-
ing lgroups. Otherwise, the IDs for the matching
lgroups is displayed. See EXAMPLES.
When no arguments are specified, this option is
applied to the lgroups displayed, which, by
default is all lgroups.
-l Print information about lgroup latencies.
The latency value specified for each lgroup is
defined by the operating system and is
platform-specific. It can only be used for rela-
tive comparison of lgroups on the running sys-
tem. It does not necessarily represent the
actual latency between hardware devices and
might not be applicable across platforms.
-L Print the lgroup latency table. The lgroup
latency table displays the relative latency from
each lgroup to each of the other lgroups includ-
ing itself.
-m Print memory information.
Memory sizes are scaled to the unit of measure
SunOS 5.11 Last change: 11 Sep 2006 3
User Commands lgrpinfo(1)
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 using
the -h option of ls(1) or df(1M) to display a
human readable format.
This is the default.
-P Replace each lgroup in the list with its
parents.
This option cannot be used with the -C or -T
option. When no arguments are specified, this
option is applied to the lgroups displayed,
which, by default is all lgroups.
-r Print information about lgroup resources.
The resources are represented by a set of
lgroups in which each member lgroup directly
contains CPU and memory resources. If -T is
specified as well, only information about
resources of the intermediate lgroups is
displayed.
-t Print information about lgroup topology.
This is the default.
-T Print the lgroup topology of a system graphi-
cally as a tree. This option can only be used
with the -a, -c, -e, -G, -l,-L, -m, -r, and -u
options. It only prints 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 using the -h option of
ls(1) or df(1M) to display a human readable for-
mat.
SunOS 5.11 Last change: 11 Sep 2006 4
User Commands lgrpinfo(1)
OPERANDS
The following operands are supported:
lgrp lgroups can be specified on the command line as
lgroup ID, by using one of the following keywords:
all All lgroups.
This is the default.
intermediate All intermediate lgroups. An inter-
mediate lgroup is an lgroup that has
a parent and children.
leaves All leaf lgroups. A leaf lgroup is
an lgroup that has no children in
the lgroup hierarchy.
root Root lgroup. Root lgroup contains
all the resources in the domain
within the largest latency and has
no parent lgroup.
If an invalid lgroup is specified, the lgrpinfo command
prints a message on standard error showing the invalid ID
and continues processing other lgroups specified on the com-
mand line. When none of the specified lgroups are valid,
lgrpinfo exits with an exit status of 2.
EXAMPLES
Example 1 Printing Information about lgroups
The following example prints general information about
lgroups in the system.
In this example, the system is a 2 CPU AMD Opteron machine
with two nodes, each having one CPU and 2 gigabytes of
memory. Each of these nodes is represented by a leaf lgroup.
The root lgroup contains all the resources in the machine:
$ lgrpinfo
lgroup 0 (root):
SunOS 5.11 Last change: 11 Sep 2006 5
User Commands lgrpinfo(1)
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
Example 2 Printing lgroup Topology
The following example prints the lgroup topology tree on a 4
CPU AMD Opteron machine:
$ lgrpinfo -T
0
-- 5
`-- 1
-- 6
`-- 2
-- 7
`-- 3
`-- 8
`-- 4
Example 3 Printing lgroup Topology
The following example prints the lgroup topology tree,
resources, memory and CPU information on a 2 CPU AMD Opteron
machine:
$ lgrpinfo -Ta
0
SunOS 5.11 Last change: 11 Sep 2006 6
User Commands lgrpinfo(1)
-- 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
------------
Example 4 Printing lgroup IDs
The following example prints lgroup IDs for children of the
root lgroup:
$ lgrpinfo -I -C root
1 2
Example 5 Printing CPU IDs
The following example prints CPU IDs for all CPUs in lgroup
1:
$ lgrpinfo -c -I 1
0
Example 6 Printing Information about lgropu Latencies
The following example prints information about lgroup laten-
cies:
SunOS 5.11 Last change: 11 Sep 2006 7
User Commands lgrpinfo(1)
$ lgrpinfo -l
lgroup 0 (root):
Latency: 83
lgroup 1 (leaf):
Latency: 56
lgroup 2 (leaf):
Latency: 5
EXIT STATUS
The following exit values are returned:
0 Successful completion.
1 Unable to get lgroup information from the system.
2 All lgroups specified are invalid.
3 Invalid syntax.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Availability SUNWesu
Interface Stability See below.
The human readable output is Unstable.
SEE ALSO
ls(1), plgrp(1), pmap(1), proc(1), ps(1), df(1M),
prstat(1M), lgrpinit(3LGRP), liblgrp(3LIB), proc(4), attri-
butes(5)
SunOS 5.11 Last change: 11 Sep 2006 8
|
