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

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

NAME
----
ipmctl-show-device - Shows information about one or more DCPMMs

SYNOPSIS
--------
[verse]
ipmctl show [OPTIONS] -dimm [TARGETS]

DESCRIPTION
-----------
Shows information about one or more DCPMMs.

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.

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
-------
-dimm [DimmIDs]::
  Restricts output to specific DCPMMs by supplying the DIMM target and one or
  more comma-separated DCPMM identifiers. The default is to display all DCPMMs.

-socket [SocketIDs]::
  Restricts output to the DCPMMs installed on specific sockets by supplying the
  socket target and one or more comma-separated socket identifiers. The default
  is to display all sockets.

NOTE: If ACPI PMTT table is not present, then DDR4 memory will not be displayed
in the filtered socket list.

EXAMPLES
--------
Lists a few key fields for each DCPMM.
[verse]
ipmctl show -dimm

Lists all properties for DCPMM 0x0001.
[verse]
ipmctl show -a -dimm 0x0001

Retrieves specific properties for each DCPMM.
[verse]
ipmctl show -d HealthState,LockState -dimm

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. Limited
information (noted in the table below) is applicable if the DCPMM is not
manageable by the software as indicated by the "ManageabilityState" property.

NOTE: Some data is endian-swapped for human readability.

DimmID::
  (Default)  The DCPMM identifier.

Capacity::
  (Default) The usable capacity of the DCPMM as reported by the
  firmware.

HealthState::
  (Default) Overall DCPMM health. One of:
  - Healthy
  - Noncritical: Maintenance is required.
  - Critical: Features or performance are degraded due to failure.
  - Fatal: Critical internal state failure (DPA Failure, Internal Buffer Failure,
    AIT Failure, etc) is non-recoverable and data loss has occurred or is imminent.
	In this case, the firmware will disable the media and access to user data and
	operations that require use of the media will fail.
  - Non-functional: The DCPMM is present but failed to initialize and is
	non-responsive via the DDRT communication path. It may be possible to
	communicate with this DCPMM via SMBus for a subset of commands.
  - Unmanageable: The DCPMM is not supported by this version of
    the software
  - Unknown: Unable to determine the DCPMM health state.
  Refer to _HealthStateReason_ for _HealthState_ details.

HealthStateReason::
  Indicates why the DCPMM is in the current Health State.
  One or more of:
  - None
  - Percentage Remaining less than 1%
  - Package Sparing occurred
  - CAP Self-Test warning
  - Percentage Remaining is 0
  - Die Failure
  - AIT DRAM disabled
  - CAP Self-Test failure
  - Critical internal state failure
  - Performance degraded
  - CAP Self-Test communication failure
   +
  Refer to the _Intel® Optane™ DC Persistent Memory Firmware
  Interface Specification_, document number 556488, Section 4.8
  SMART and Health.

InterfaceFormatCode::
  A comma-delimited list of the JEDEC standard format
  interface code(s) for the DCPMM where each code is formatted as: code
  (JEDEC Description or "Unknown").

ManageabilityState::
  Ability of the DCPMM host software to manage the DCPMM.
  Manageability is determined by the interface format code, the vendor
  identifier, device identifier and the firmware API version. One of:
  - Manageable: The DCPMM is manageable by the software.
  - Unmanageable: The DCPMM is not supported by this version of
    the software.

PopulationViolation::
  Memory populations are evaluated based on the "Enforce Population POR" setup option in UEFI Firmware.
  If enforcement of POR populations is selected, then some DCPMM memory may be in population
  violation. See <<DCPMMs in non-POR configuration>> for details. One of:
  - Yes: The DCPMM is in population violation.
  - No: The DCPMM is not in population violation.

PhysicalID::
  The DCPMM physical identifier (i.e., SMBIOS Type 17 handle).

DimmHandle::
  The DCPMM handle formatted as 0xABCD.
  - A = Socket
  - B = Memory Controller
  - C = Channel
  - D = Slot

DimmUID::
  The unique identifier of the DCPMM formatted as VVVV-ML-MMYYSNSNSNSN or
  VVVV-SNSNSNSN (if the manufacturing information is not available) where:
  - VVVV = VendorID
  - ML = ManufacturingLocation
  - MMYY = ManufacturingDate
  - SNSNSNSN = SerialNumber

SocketID::
  The processor socket identifier (i.e., NUMA node) where the DCPMM is
  installed.

MemControllerID::
  The associated memory controller identifier.

ChannelID::
  The associated channel.

ChannelPos::
  The DCPMM position in the channel.

MemoryType::
  The memory type. One of:
  - Unknown
  - DDR4
  - Logical Non-Volatile Device

VendorID::
  The vendor identifier of the DCPMM.
  This value is presented in big endian format.

DeviceID::
  The device identifier of the DCPMM.
  This value is presented in big endian format.

RevisionID::
  The revision identifier of the DCPMM.

SubsystemVendorID::
  The vendor identifier of the non-volatile memory subsystem controller.
  This value is presented in big endian format.

SubsystemDeviceID::
  The device identifier of the non-volatile memory subsystem controller.

SubsystemRevisionID::
  The revision identifier of the non-volatile memory subsystem controller
  retrieved from NFIT. This field uses a different encoding than
  ControllerRevisionID.

ManufacturingInfoValid::
  If the manufacturing location and date are valid. One of:
  - 0: Not valid
  - 1: Valid

ManufacturingLocation::
  The manufacturing location assigned by the vendor or "N/A" if ManufacturingInfoValid
  is 0.

ManufacturingDate::
  The manufacturing date assigned by the vendor or "N/A" if ManufacturingInfoValid
  is 0.

SerialNumber::
  The serial number assigned by the vendor.
  This value is presented in big endian format.

PartNumber::
  The part number assigned by the vendor

DeviceLocator::
  A string describing the physically-labeled socket or board position where the
  memory device is located from the SMBIOS Type 17 Memory Device table.

BankLabel::
  A string that identifies the physically labeled bank where the memory device
  is located from the SMBIOS Type 17 Memory Device table.

DataWidth::
  The width in bits used to store user data from the SMBIOS Type 17 Memory
  Device table.

TotalWidth::
  The width in bits for data and error correction and/or data redundancy from
  the SMBIOS Type 17 Memory Device table.

Speed::
  The maximum capable speed of the device in megatransfers per second (MT/s)
  from the SMBIOS Type 17 Memory Device table.

FormFactor::
  The DCPMM form factor (i.e., SMBIOS Type 17 Memory Device Form Factor). One
  of:
  - Unknown
  - DIMM
  - SODIMM

LockState::
  (Default) The current security state of the persistent memory on the DCPMM.
  One ore more of:
  - Unknown - The security state cannot be determined (e.g., when the
    DCPMM is not manageable by the software).
  - Disabled - Security is not enabled.
  - Unlocked - Security is enabled and unlocked.
  - Locked - Security is enabled and locked.
  - Frozen - A reboot is required to change the security state.
  - Exceeded - The passphrase limit has been reached. A power cycle is
    required to change the security state.
  - MP Exceeded - The master passphrase limit has been reached. A power cycle
    is required to change the security state.
  - Not Supported - Security is not supported on the DCPMM.

SVNDowngrade::
  (Default) The Opt-in value of SVN Downgrade security opt-in feature for DCPMM.
  One of :
  - Unknown
  - Disabled
  - Enabled

SecureErasePolicy::
  (Default) The Opt-in value of Secure erase policy opt-in feature for DCPMM.
  One of :
  - Unknown
  - No Master Passphrase
  - Master Passphrase Enabled

S3ResumeOptIn::
  (Default) The Opt-in value of S3 Resume security opt-in feature for DCPMM.
  One of :
  - Unknown
  - UnsecureS3
  - SecureS3

FwActivateOptIn::
  (Default) The Opt-in value of Fw Activate security opt-in feature for DCPMM.
  One of :
  - Unknown
  - Disabled
  - Enabled

FWVersion::
  (Default) The BCD-formatted revision of the active firmware in the format
  PN.RN.SV.bbbb where:
  * PN = 2-digit product number
  * RN = 2-digit revision number
  * SN = 2-digit security revision number
  * bbbb = 4-digit build version

  Value may be N/A if the DCPMM is not manageable by the software.

FWAPIVersion::
  The firmware supported interface revision in the format aa.bb where:
  - aa = 2-digit major version
  - bb = 2-digit minor version
   +
  The firmware interface is intended to be backwards compatible. Therefore,
  the host software allows management of DCPMMs where this version is less than
  or equal to the version stored in the host software. Value may be N/A if the
  DCPMM is not manageable by the software.

*The following information is only applicable when the DCPMM is manageable by the
software as indicated by the "ManageabilityState".*

ManufacturerID::
  The manufacturer identifier of the DCPMM.
  This value is presented in big endian format.

ControllerRevisionID::
  The controller stepping and revision ID retrieved from the controller FW. This
  field uses a different encoding than SubsystemRevisionID.

IsNew::
  Whether or not the DCPMM is incorporated with the rest of the DCPMM in the
  system. One of:
  - 0: Configured
  - 1: The DCPMM requires configuration.

MemoryCapacity::
  Usable DCPMM Memory Mode capacity.

AppDirectCapacity::
  Usable DCPMM App Direct capacity.

UnconfiguredCapacity::
  DCPMM capacity that is inaccessible because it is not mapped into the system
  physical address space.

InaccessibleCapacity::
  DCPMM capacity that is inaccessible due to:
  - licensing issue
  - platform configuration prevents accessing this capacity. For example,
  MemoryCapacity is configured and available on a DCPMM but MemoryMode is not
  enabled by BIOS.

ReservedCapacity::
  DCPMM capacity reserved for proper alignment.

AvgPowerLimit::
  If the DCPMM firmware power management policy is enabled, the power limit in
  mW used for average power. Refer to FIS for allowable range and default value.

MemoryBandwidthBoostFeature::
  Returns if the Memory Bandwidth Boost Feature is currently enabled or not. One of:
  - 0x0: Disabled
  - 0x1: Enabled

MemoryBandwidthBoostMaxPowerLimit::
  The power limit used for limiting the Memory Bandwidth Boost Feature's power consumption [mW].

MemoryBandwidthBoostAveragePowerTimeConstant::
  The value used as a base time window for average power throttle [ms]. This range can be checked in the Max Memory Bandwidth Boost Average Time Constant and Average Power Time Constant Step from the Get Device Characteristics command.
  - Default: 15000 ms

MaxAveragePowerLimit::
   Maximum average power limit [mW] supported by the DCPMM.

MaxTurboModePowerConsumption::
   Maximum Turbo Power value [mW] that can be set for the DCPMM. Will return 0 if unsupported by current FIS.

MaxAveragePowerTimeConstant::
   This field returns the maximum supported value of the Average Power Time Constant and Average Power Reporting Time constant [ms] that can be set via the Set Power Management Policy and the Optional Configuration Data Policy Commands.

AveragePowerTimeConstantStep::
   Thie field returns the increments in milliseconds allowed by the firmware when setting the Average Power Time Constant and Average Power Reporting Time Constant via the Set Power Management Policy and the Optional Configuration Data Policy Commands.

PackageSparingCapable::
  Whether or not the DCPMM supports package sparing. One of:
  - 0: False
  - 1: True

PackageSparingEnabled::
  Whether or not the DCPMM package sparing policy is enabled. One of:
 - 0: Disabled
 - 1: Enabled

PackageSparesAvailable::
  The number of spare devices available for package sparing.

LatchedLastShutdownStatus::
  The status of the last shutdown of the DCPMM. One or more of:
  - Unknown: The last shutdown status cannot be determined.
  - PM ADR Command Received: Power management ADR command received.
  - PM S3 Received: Power management S3 command received.
  - PM S5 Received: Power management S5 command received.
  - DDRT Power Fail Command Received: DDR power fail command received.
  - PMIC 12V/DDRT 1.2V Power Loss (PLI)
  - PM Warm Reset Received: Power management warm reset received.
  - Thermal Shutdown Received: Thermal shutdown triggered.
  - Controller’s FW State Flush Complete: Flush Completed.
  - Viral Interrupt Received: Viral interrupt received.
  - Surprise Clock Stop Received: Surprise clock stop received.
  - Write Data Flush Complete: Write data flush completed.
  - PM S4 Received: Power management S4 command received.
  - PM Idle Received: Power management idle received.
  - DDRT Surprise Reset Received: Surprise reset received.
  - Extended Flush Complete.

UnlatchedLastShutdownStatus::
  The status of the last shutdown status of the DCPMM. Same fields as the
  Latched Last Shutdown Status with the only difference that LLS details
  on a dirty shutdown is logged, even if the Latch System Shutdown Status
  was not enabled. One or more of:
  - Unknown: The last shutdown status cannot be determined.
  - PM ADR Command: Power management ADR command received.
  - PM S3: Power management S3 command received.
  - PM S5: Power management S5 command received.
  - DDRT Power Fail Command: DDR power fail command received.
  - PMIC 12V/DDRT 1.2V Power Loss (PLI)
  - PM Warm Reset: Power management warm reset received.
  - Thermal Shutdown: Thermal shutdown triggered.
  - Controller’s FW State Flush Complete: Flush Completed.
  - Viral Interrupt: Viral interrupt received.
  - Surprise Clock Stop: Surprise clock stop received.
  - Write Data Flush Complete: Write data flush completed.
  - PM S4: Power management S4 command received.
  - DDRT Surprise Reset: Surprise reset received
  - PM Idle Received: Power management idle received.
  - Extended Flush Complete.

ThermalThrottleLossPercent::
  The average performance loss percentage due to thermal throttling
  in current boot of the DCPMM.

LastShutdownTime::
  The time the system was last shutdown.

ModesSupported::
  A list of the modes supported by the DCPMM. Refer to the command
  Show System Capabilities to determine the modes supported by the
  platform. One or more of:
  - Memory Mode: DCPMMs act as system memory under the control of the operating
    system. In Memory Mode, any DDR in the platform will act as a cache working
    in conjunction with the DCPMM.
  - App Direct: DCPMMs and DDR act as independent memory resources under direct
    load/store control of the application.

SecurityCapabilities::
  The security features supported by the DCPMM. Zero or more of:
  - Encryption: The DCPMM supports persistent memory encryption by
    setting a passphrase.
  - Erase: The DCPMM is erasable.

MasterPassphraseEnabled::
  This property indicates if master passphrase is enabled. If it is disabled,
  then it cannot be enabled. One of:
  - 0: Disabled - Cannot be enabled
  - 1: Enabled - Master passphrase can be changed. Cannot be disabled.

ConfigurationStatus::
  The status of the DCPMM memory configuration. One of:
  - Valid: The configuration is valid.
  - Not Configured: The DCPMM has not been configured.
  - Failed - Bad configuration: The configuration is corrupt.
  - Failed - Broken interleave: This DCPMM is part of an interleave
    set that is not complete.
  - Failed - Reverted: The configuration failed and was reverted to the last
    known good configuration.
  - Failed - Unsupported: The configuration is not compatible with the
    installed BIOS.
  - Unknown: The configuration cannot be determined.

SKUViolation::
  The configuration of the DCPMM is unsupported due to a license issue. One of:
  - 0: False
  - 1: True

ARSStatus::
  The address range scrub (ARS) operation status for the DCPMM. The status is a
  reflection of the last requested ARS, but not necessarily within the current
  platform power cycle. One of:
  - Unknown - The ARS operation status cannot be determined.
  - Not started - An ARS operation has not started.
  - In progress - An ARS operation is currently in progress.
  - Completed - The last ARS operation has completed.
  - Aborted - The last ARS operation was aborted.

OverwriteStatus::
  The overwrite DIMM operation status for the DCPMM. One of:
  - Unknown - The overwrite DIMM operation status cannot be determined. This may
    occur if the status gets overwritten due to a different long operation
    running on this DCPMM.
  - Not started - An overwrite DIMM operation was not started on the last
    boot.
  - In progress - An overwrite DIMM operation is currently in progress.
  - Completed - An overwrite DIMM operation completed and a reboot is
    required to use the DCPMM.

AveragePowerReportingTimeConstantMultiplier::
  The value that is used to multiply the base time value used for average power
  consumption measurements. Can be set to a value between 0 and 32. The default
  value is 0.

AveragePowerReportingTimeConstant::
  The value, in milliseconds, used to determine the time constant for reporting
  the average power consumption measurements. Can be set to a value between 100
  and 12000, by increments of 100. The default value is 1000.

ViralPolicy::
  Whether viral policies are enabled on the DCPMM. One of:
  - 0: Disabled - This is the default.
  - 1: Enabled - The persistent memory on the DCPMM will be put into read-only
    mode if the host operating system software detects an uncorrectable error
    situation and indicates a viral state in order to prevent the spread of
    damage.

ViralState::
  Whether the DCPMM is currently viral. One of:
  - 0: Not Viral
  - 1: Viral - The viral policies of the DCPMM have switched the
    persistent memory to read-only mode due to the host operating system
    software detecting an uncorrectable error situation and indicating a viral
    state.

AitDramEnabled::
  If the DCPMM AIT DRAM is enabled. One of:
  - 0: Disabled - The device will suffer performance degradation if the AIT
    DRAM becomes disabled.
  - 1: Enabled

BootStatus::
  The initialization status of the DCPMM as reported by the firmware in the boot
  status register. One or more of:
  - Unknown - The boot status register cannot be read.
  - Success - No errors were reported during initialization.
   +
  *The following statuses indicate that the media is not functional and
  therefore access to user data and operations that require use of the media
  will fail.*
  - Media Not Ready - The firmware did not complete media training.
  - Media Error - The firmware detected an error during media training.
  - Media Disabled - The firmware disabled the media due to a critical issue.
   +
  *The following statuses indicate that communication with the firmware is not
  functional.*
  - FW Assert - The firmware reported an assert during initialization.

BootStatusRegister::
  The raw hex value of the DCPMM Boot Status Register of the DCPMM

LatchSystemShutdownState::
  Status of the latch. Specifies whether the DCPMM will latch the SMART Last Shutdown Status and SMART
  Dirty Shutdown Count.
  - 0: Disabled - This is the default.
  - 1: Enabled

PreviousPowerCycleLatchSystemShutdownState::
  The status of the latch during the previous power cycle.
  - 0: Disabled - This is the default.
  - 1: Enabled

ExtendedAdrEnabled::
  Specifies whether extended ADR flow is enabled in the FW.
  - 0: Disabled
  - 1: Enabled

PpcExtendedAdrEnabled::
  Specifies whether extended ADR flow was enabled in the FW during the last power cycle.
  - 0: Disabled
  - 1: Enabled

ErrorInjectionEnabled::
  Error injection status.
  - 0: Disabled - This is the default.
  - 1: Enabled
MediaTemperatureInjectionEnabled::
  Media temperature injection status.
  - 0: Disabled - This is the default.
  - 1: Enabled

SoftwareTriggersEnabled::
  Software trigger status.
  - 0: Disabled - This is the default.
  - 1: At least one software trigger enabled.

SoftwareTriggersEnabledDetail::
  Comma separated list of software triggers currently enabled. One or more of:
  - None
  - Package Sparing
  - Fatal Error
  - Percentage Remaining
  - Dirty Shutdown

PoisonErrorInjectionsCounter::
  This counter is incremented each time the set poison error is successfully
  executed.

PoisonErrorClearCounter::
  This counter is incremented each time the clear poison error is successfully
  executed.
MediaTemperatureInjectionsCounter::
  This counter is incremented each time the media temperature is injected.

SoftwareTriggersCounter::
  This counter is incremented each time a software trigger is enabled.

MaxMediaTemperature::
  The highest die temperature reported in degrees Celsius.
  This value is persistent through Power Loss as well as not effected by Overwrite Dimm or Media Temperature Error Injection.

MaxControllerTemperature::
  The highest controller temperature reported in degrees Celsius.
  This value is persistent through Power Loss as well as not effected by Overwrite Dimm.
  
MixedSKU::
  One or more DCPMMs in the system have different SKUs. One of:
  - 0: False
  - 1: True - In this case, the host software operates in a read-only mode and
  does not allow changes to the DCPMMs and their associated capacity.