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

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

NAME
----
ipmctl-show-sensor - Shows sensor data for one or more PMem modules

SYNOPSIS
--------
[listing]
ipmctl show [OPTIONS] -sensor [SENSORS] [TARGETS]

DESCRIPTION
-----------
Shows sensor data for one or more PMem modules. This data includes PMem module health, temperatures,
percentage remaining, up-time and more.

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[]

SENSORS
-------
Health::
  (Default) The current PMem module health as reported in the SMART log. Attributes include:
  - DimmID
  - Type
  - CurrentValue

MediaTemperature::
  (Default) The current PMem module media temperature in Celsius. Attributes include:
  - DimmID
  - Type
  - CurrentValue
  - AlarmThreshold
  - AlarmEnabled
  - ThrottlingStopThreshold
  - ThrottlingStartThreshold
  - ShutdownThreshold
  - MaxTemperature

ControllerTemperature::
  (Default) The current PMem module controller temperature in Celsius. Attributes include:
  - DimmID
  - Type
  - CurrentValue
  - AlarmThreshold
  - AlarmEnabled
  - ThrottlingStopThreshold
  - ThrottlingStartThreshold
  - ShutdownThreshold
  - MaxTemperature

PercentageRemaining::
  (Default) Remaining PMem module’s life as a percentage value of factory expected
  life span. Attributes include:
  - DimmID
  - Type
  - CurrentValue
  - AlarmThreshold
  - AlarmEnabled

LatchedDirtyShutdownCount::
  (Default) The number of shutdowns without notification over the lifetime of
  the PMem module. Attributes include:
  - DimmID
  - Type
  - CurrentValue

UnlatchedDirtyShutdownCount::
  (Default) The number of shutdowns without notification over the lifetime of
  the PMem module. This counter is the same as LatchedDirtyShutdownCount except it will
  always be incremented on a dirty shutdown, even if Latch System Shutdown Status
  was not enabled. Attributes include:
  - DimmID
  - Type
  - CurrentValue

PowerOnTime::
  (Default) The total power-on time over the lifetime of the PMem module. Attributes include:
  - DimmID
  - Type
  - CurrentValue

UpTime::
  (Default) The total power-on time since the last power cycle of the PMem module. Attributes include:
  - DimmID
  - Type
  - CurrentValue

PowerCycles::
  (Default) The number of power cycles over the lifetime of the PMem module. Attributes include:
  - DimmID
  - Type
  - CurrentValue

FwErrorCount::
  (Default) The total number of firmware error log entries. Attributes include:
  - DimmID
  - Type
  - CurrentValue

TARGETS
-------
-dimm [DimmIDs]::
  Restricts output to the sensors on specific PMem modules by supplying the DIMM
  target and one or more comma-separated PMem module identifiers. The default is to
  display sensors for all manageable PMem modules.

EXAMPLES
--------
Gets all sensor information for all PMem modules.
[listing]
ipmctl show -sensor

Shows the media temperature sensor for the specified PMem module.
[listing]
ipmctl show -sensor MediaTemperature -dimm 0x0001

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

- The caller must have the appropriate privileges.

- The specified PMem modules must be manageable by the host software.

RETURN DATA
-----------
This command displays a table with a row for each sensor on each PMem module. Applying
a specific PMem module or sensor type target limits the number of rows. Applying
options can be used to expand or restrict the output.

NOTE: Supported thresholds for a given sensor are listed as a part of the return data when using the -all or -display flag. Only the alarm threshold is settable.

DimmID::
  (Default) The PMem module identifier

Type::
  (Default) The sensor type. Refer to the sensor table above.

CurrentValue::
  (Default) The current reading followed by the units of measurement
  (e.g., 57 °C or 25%)

AlarmThreshold::
  The threshold value at which an alarm for the respective sensor will be triggered.

AlarmEnabled::
  Current state of the alarm threshold, where applicable.
  One of:
  - 0: Disabled
  - 1: Enabled
  - N/A

ThrottlingStopThreshold::
  The threshold value at which firmware will stop throttling to reduce overall thermals and keep the PMem module within safe operating temperatures.

ThrottlingStartThreshold::
  The threshold value at which firmware will start throttling to reduce overall thermals and keep the PMem module within safe operating temperatures.

ShutdownThreshold::
  The threshold value at which device shutdown will occur.

MaxTemperature::
  The highest temperature reported in degrees Celsius for a given media or controller sensor.
  This value is persistent through Power Loss and is read-only.
