1# pmbus_read_sensor
2
3## Description
4Reads one sensor for a PMBus regulator rail.  Communicates with the device
5directly using the [I2C interface](i2c_interface.md).
6
7This action should be executed during [sensor_monitoring](sensor_monitoring.md)
8for the rail.
9
10### Sensor Value Type
11Currently the following sensor value types are supported:
12
13| Type | Description |
14| :--- | :---------- |
15| iout | Output current |
16| iout_peak | Highest output current |
17| iout_valley | Lowest output current |
18| pout | Output power |
19| temperature | Temperature |
20| temperature_peak | Highest temperature |
21| vout | Output voltage |
22| vout_peak | Highest output voltage |
23| vout_valley | Lowest output voltage |
24
25Notes:
26* Some regulators only support a subset of these sensor value types.
27* Some of these sensor value types are not part of the PMBus specification and
28  must be obtained by reading from manufacturer-specific commands.
29
30### Data Format
31Currently the following PMBus data formats are supported:
32
33| Format | Description |
34| :----- | :---------- |
35| linear_11 | Linear data format used for values not related to voltage output, such as output current, input voltage, and temperature.  Two byte value with an 11-bit, two's complement mantissa and a 5-bit, two's complement exponent. |
36| linear_16 | Linear data format used for values related to voltage output.  Two byte (16-bit), unsigned integer that is raised to the power of an exponent.  The exponent is not stored within the two bytes. |
37
38### Exponent For "linear_16" Data Format
39The "linear_16" data format requires an exponent value.
40
41If the device supports the PMBus VOUT_MODE command, the exponent value can be
42read from the device.
43
44If VOUT_MODE is not supported by the device, the exponent value must be
45specified using the "exponent" property.  The exponent value can normally be
46found in the device documentation (data sheet).
47
48### D-Bus Sensor
49A [D-Bus sensor
50object](https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md)
51will be created on the BMC to store the sensor value.  This makes the sensor
52available to external interfaces like Redfish.
53
54D-Bus sensors have an object path with the following format:
55```
56/xyz/openbmc_project/sensors/<type>/<label>
57```
58
59The D-Bus `<type>` is the hwmon class name.  The following table shows how the
60sensor value type is mapped to a D-Bus `<type>`.
61
62| Sensor Value Type | D-Bus `<type>` |
63| :---------------- | :------------- |
64| iout | current |
65| iout_peak | current |
66| iout_valley | current |
67| pout | power |
68| temperature | temperature |
69| temperature_peak | temperature |
70| vout | voltage |
71| vout_peak | voltage |
72| vout_valley | voltage |
73
74The D-Bus `<label>` is the sensor name.  It must be unique within the entire
75system.  The `<label>` will be set to the following:
76```
77<rail_id>_<sensor_value_type>
78```
79For example, if sensor monitoring for rail "vdd0" reads a "vout_peak" sensor,
80the resulting D-Bus `<label>` will be "vdd0_vout_peak".
81
82## Properties
83| Name | Required | Type | Description |
84| :--- | :------: | :--- | :---------- |
85| type | yes | string | Sensor value type.  Specify one of the following: "iout", "iout_peak", "iout_valley", "pout", "temperature", "temperature_peak", "vout", "vout_peak", "vout_valley". |
86| command | yes | string | PMBus command code expressed in hexadecimal.  Must be prefixed with 0x and surrounded by double quotes. |
87| format | yes | string | Data format of the sensor value returned by the device.  Specify one of the following: "linear_11", "linear_16".
88| exponent | no | number | Exponent value for "linear_16" data format.  Can be positive or negative.  If not specified, the exponent value will be read from VOUT_MODE. |
89
90## Return Value
91true
92
93## Examples
94```
95{
96  "comments": [ "Read output current from READ_IOUT." ],
97  "pmbus_read_sensor": {
98    "type": "iout",
99    "command": "0x8C",
100    "format": "linear_11"
101  }
102}
103
104{
105  "comments": [ "Read output voltage from READ_VOUT.  Specify exponent." ],
106  "pmbus_read_sensor": {
107    "type": "vout",
108    "command": "0x8B",
109    "format": "linear_16",
110    "exponent": -8
111  }
112}
113```
114