'\" t
.\"     Title: ipmctl-show-region
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 1.5.8
.\"      Date: 2021-02-28
.\"    Manual: ipmctl
.\"    Source: ipmctl
.\"  Language: English
.\"
.TH "IPMCTL\-SHOW\-REGION" "1" "2021-02-28" "ipmctl" "ipmctl"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
ipmctl\-show\-region \- Retrieves a list of persistent memory regions.
.SH "SYNOPSIS"
.sp
.if n .RS 4
.nf
ipmctl show [OPTIONS] \-region [TARGETS]
.fi
.if n .RE
.SH "DESCRIPTION"
.sp
Retrieves a list of persistent memory regions of PMem module capacity.
.SH "OPTIONS"
.sp
\-a, \-all
.RS 4
Shows all attributes.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
The all and display options are exclusive and may not be used together.
.sp .5v
.RE
.sp
\-d (attributes), \-display (attributes)
.RS 4
Filters the returned attributes by explicitly specifying a comma separated
list of any of the attributes defined in the Return Data section.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
The all and display options are exclusive and may not be used together.
.sp .5v
.RE
.sp
\-h, \-help
.RS 4
Displays help for the command.
.RE
.sp
\-ddrt
.RS 4
Used to specify DDRT as the desired transport protocol for the current invocation of ipmctl.
.RE
.sp
\-smbus
.RS 4
Used to specify SMBUS as the desired transport protocol for the current invocation of ipmctl.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
The \-ddrt and \-smbus options are mutually exclusive and may not be used together.
.sp .5v
.RE
.sp
\-lpmb
.RS 4
Used to specify large transport payload size for the current invocation of ipmctl.
.RE
.sp
\-spmb
.RS 4
Used to specify small transport payload size for the current invocation of ipmctl.
.RE
.if n .sp
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
.B Note
.ps -1
.br
.sp
The \-lpmb and \-spmb options are mutually exclusive and may not be used together.
.sp .5v
.RE
.sp
\-nfit
.RS 4
Used to specify NFIT table as the source instead of PCD (default) for the current invocation of ipmctl.
.RE
.sp
\-o (text|nvmxml), \-output (text|nvmxml)
.RS 4
Changes the output format. One of: "text" (default) or "nvmxml".
.RE
.sp
\-u (B|MB|MiB|GB|GiB|TB| TiB), \-units (B|MB|MiB|GB|GiB|TB| TiB)
.RS 4
Changes the units that capacities are displayed in for this command. One of:
bytes (B), megabytes (MB), mebibytes (MiB), gigabytes (GB), gibibytes (GiB),
terabytes (TB) or tebibytes (TiB).
.RE
.SH "TARGETS"
.sp
\-socket [SocketIDs]
.RS 4
Restricts output to the persistent memory regions on specific sockets by
supplying the socket target and one or more comma separated socket
identifiers. The default is to display all sockets.
.RE
.SH "EXAMPLES"
.sp
Shows all attributes of all persistent memory regions in the server.
.sp
.if n .RS 4
.nf
ipmctl show \-a \-region
.fi
.if n .RE
.SH "LIMITATIONS"
.sp
In order to successfully execute this command:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
The caller must have the appropriate privileges.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
All the underlying PMem modules should be unlocked to accurately reflect the available
capacities. The specified PMem modules must be manageable by the host software.
.RE
.SH "RETURN DATA"
.sp
The default behavior is to display a table with the default attributes listed below;
applying options changes the output to a more detailed format.
.sp
ISetID
.RS 4
(Default) The region unique identifier. Also known as interleave set cookie.
.RE
.sp
PersistentMemoryType
.RS 4
(Default) A comma separated list of the underlying types of persistent
memory capacity in the region. One or more of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
AppDirect: App Direct capacity interleaved across two or more PMem modules that is
fully mapped into the system physical address space.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
AppDirectNotInterleaved: App Direct capacity wholly contained on a single
PMem modules that is fully mapped into the system physical address space.
.RE
.RE
.sp
Capacity
.RS 4
(Default) Total usable capacity, both allocated and unallocated
.RE
.sp
FreeCapacity
.RS 4
(Default) Remaining usable capacity
.RE
.sp
SocketID
.RS 4
(Default) Socket ID to which the region belongs
.RE
.sp
HealthState
.RS 4
The rolled up health of the underlying PMem modules. One of:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Unknown: The region health cannot be determined.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Healthy: All underlying PMem module persistent memory capacity is available.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Pending: A new memory allocation goal has been created but not applied.
Reboot or delete any existing memory allocation goals before creating
namespaces on the region.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Error: There is an issue with some or all of the underlying PMem module capacity
because the interleave set has failed. One of:
+ PMem module missing (serial number of PMem module from the Platform Config Data not found in the PMem module list)
+ PMem module not configured
+ Failure to retrieve AppDirect I/O structures from NFIT (system physical address missing)
+ Interleave set or PMem module region initialization failure (out of memory)
+ Locked: One or more of the of the underlying Pmem modules are locked.
.RE
.RE
.sp
DimmID
.RS 4
A list of all the PMem modules that are part of this reg.
.RE