illumos: manual page: lgrpinfo.1

LGRPINFO(1) 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.

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 children.

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.

-e
Print lgroup load average. The lgroup load averages 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 lgrp_init(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 specified, print list of CPUs
contained in all matching 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 relative comparison of lgroups on the running
system. 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 including itself.

-m
Print memory information.

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 similar to using the
-h option of ls(1) or df(8) 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 graphically 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 similar to using the -h option of ls(1) or df(8)
to display a human readable format.

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 intermediate 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 command 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):
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
|-- 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 lgroup Latencies

The following example prints information about lgroup latencies:

$ 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.

ATTRIBUTES