// Copyright (c) 2018, Intel Corporation.
// SPDX-License-Identifier: BSD-3-Clause

ifdef::manpage[]
ipmctl-show-region(1)
=====================
endif::manpage[]

NAME
----
ipmctl-show-region - Retrieves a list of persistent memory regions.

SYNOPSIS
--------
[listing]
ipmctl show [OPTIONS] -region [TARGETS]

DESCRIPTION
-----------
Retrieves a list of persistent memory regions of PMem module capacity.

OPTIONS
-------
-a::
-all::
  Shows all attributes.

NOTE: The all and display options are exclusive and may not be used together.

-d (attributes)::
-display (attributes)::
  Filters the returned attributes by explicitly specifying a comma-separated
  list of any of the attributes defined in the Return Data section.

NOTE: The all and display options are exclusive and may not be used together.

-h::
-help::
  Displays help for the command.

-ddrt::
  Used to specify DDRT as the desired transport protocol for the current invocation of ipmctl.

-smbus::
  Used to specify SMBUS as the desired transport protocol for the current invocation of ipmctl.

NOTE: The -ddrt and -smbus options are mutually exclusive and may not be used together.

-lpmb::
  Used to specify large transport payload size for the current invocation of ipmctl.

-spmb::
  Used to specify small transport payload size for the current invocation of ipmctl.

NOTE: The -lpmb and -spmb options are mutually exclusive and may not be used together.

-nfit::
  Used to specify NFIT table as the source instead of PCD (default) for the current invocation of ipmctl.

ifdef::os_build[]
-o (text|nvmxml)::
-output (text|nvmxml)::
  Changes the output format. One of: "text" (default) or "nvmxml".
endif::os_build[]

-u (B|MB|MiB|GB|GiB|TB| TiB)::
-units (B|MB|MiB|GB|GiB|TB| TiB)::
  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).

TARGETS
-------
-region [RegionIDs]::
  Restricts output to specific persistent memory regions by providing one or
  more comma separated region identifiers. The default is to display the
  persistent memory regions across all manageable PMem modules.

-socket [SocketIDs]::
  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.

EXAMPLES
--------
Shows all attributes of all persistent memory regions in the server.
[listing]
ipmctl show -a -region

Shows all attributes for the specified persistent memory region.
[listing]
ipmctl show -a -region 1

LIMITATIONS
-----------
In order to successfully execute this command:

- The caller must have the appropriate privileges.

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

RETURN DATA
-----------
The default behavior is to display a table with the default attributes listed below;
applying options changes the output to a more detailed format.

ifndef::os_build[]
RegionID::
  (Default) The unique region identifier
endif::os_build[]

ifdef::os_build[]
ISetID::
  (Default) The region unique identifier. Also known as interleave set cookie.
endif::os_build[]

PersistentMemoryType::
  (Default) A comma-separated list of the underlying types of persistent
  memory capacity in the region. One or more of:
  - AppDirect: App Direct capacity interleaved across two or more PMem modules that is
    fully mapped into the system physical address space.
  - AppDirectNotInterleaved: App Direct capacity wholly contained on a single
    PMem modules that is fully mapped into the system physical address space.

Capacity::
  (Default) Total usable capacity, both allocated and unallocated

FreeCapacity::
  (Default) Remaining usable capacity

SocketID::
  (Default) Socket ID to which the region belongs

HealthState::
  The rolled up health of the underlying PMem modules. One of:
  - Unknown: The region health cannot be determined.
  - Healthy: All underlying PMem module persistent memory capacity is available.
  - 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.
  - 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 moduless are locked.

ifndef::os_build[]
ISetID::
  The region unique identifier. Also known as interleave set cookie.
endif::os_build[]

DimmID::
  A list of all the PMem modules that are part of this reg.
