1# pmbus_read_sensor
2
3## Description
4
5Reads one sensor for a PMBus regulator rail. Communicates with the device
6directly using the [I2C interface](i2c_interface.md).
7
8This action should be executed during [sensor_monitoring](sensor_monitoring.md)
9for the rail.
10
11### Sensor Type
12
13Currently the following sensor types are supported:
14
15| Type             | Description            |
16| :--------------- | :--------------------- |
17| iout             | Output current         |
18| iout_peak        | Highest output current |
19| iout_valley      | Lowest output current  |
20| pout             | Output power           |
21| temperature      | Temperature            |
22| temperature_peak | Highest temperature    |
23| vout             | Output voltage         |
24| vout_peak        | Highest output voltage |
25| vout_valley      | Lowest output voltage  |
26
27Notes:
28
29- Some regulators only support a subset of these sensor types.
30- Some of these sensor types are not part of the PMBus specification and must be
31  obtained by reading from manufacturer-specific commands.
32
33### Data Format
34
35Currently the following PMBus data formats are supported:
36
37| Format    | Description                                                                                                                                                                                                                |
38| :-------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
39| 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. |
40| 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.                             |
41
42### Exponent For "linear_16" Data Format
43
44The "linear_16" data format requires an exponent value.
45
46If the device supports the PMBus VOUT_MODE command, the exponent value can be
47read from the device.
48
49If VOUT_MODE is not supported by the device, the exponent value must be
50specified using the "exponent" property. The exponent value can normally be
51found in the device documentation (data sheet).
52
53### D-Bus Sensor
54
55A
56[D-Bus sensor object](https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md)
57will be created on the BMC to store the sensor value. This makes the sensor
58available to external interfaces like Redfish.
59
60D-Bus sensors have an object path with the following format:
61
62```text
63/xyz/openbmc_project/sensors/<namespace>/<sensor_name>
64```
65
66The D-Bus sensors `<namespace>` is the general category of the sensor. The
67following table shows how the sensor type is mapped to a D-Bus sensors
68`<namespace>`.
69
70| Sensor Type      | D-Bus `<namespace>` |
71| :--------------- | :------------------ |
72| iout             | current             |
73| iout_peak        | current             |
74| iout_valley      | current             |
75| pout             | power               |
76| temperature      | temperature         |
77| temperature_peak | temperature         |
78| vout             | voltage             |
79| vout_peak        | voltage             |
80| vout_valley      | voltage             |
81
82The D-Bus `<sensor_name>` must be unique across the entire system. It will be
83set to the following:
84
85```text
86<rail_id>_<sensor_type>
87```
88
89For example, if sensor monitoring for rail "vdd0" reads a "vout_peak" sensor,
90the resulting D-Bus `<sensor_name>` will be "vdd0_vout_peak".
91
92Peak and valley sensor values are calculated internally by the regulator since
93it can sample values very frequently and catch transient events. When these
94peak/valley values are read over PMBus, the regulator will often clear its
95internal value and start calculating a new peak/valley. To avoid losing
96information, the D-Bus sensor will contain the highest peak/lowest valley value
97that has been read since the system was powered on. When the system is powered
98off, the D-Bus peak/valley sensor values are cleared.
99
100## Properties
101
102| Name     | Required | Type   | Description                                                                                                                                                   |
103| :------- | :------: | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |
104| type     |   yes    | string | Sensor type. Specify one of the following: "iout", "iout_peak", "iout_valley", "pout", "temperature", "temperature_peak", "vout", "vout_peak", "vout_valley". |
105| command  |   yes    | string | PMBus command code expressed in hexadecimal. Must be prefixed with 0x and surrounded by double quotes.                                                        |
106| format   |   yes    | string | Data format of the sensor value returned by the device. Specify one of the following: "linear_11", "linear_16".                                               |
107| 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.                    |
108
109## Return Value
110
111true
112
113## Examples
114
115```json
116{
117  "comments": ["Read output current from READ_IOUT."],
118  "pmbus_read_sensor": {
119    "type": "iout",
120    "command": "0x8C",
121    "format": "linear_11"
122  }
123}
124```
125
126```json
127{
128  "comments": ["Read output voltage from READ_VOUT.  Specify exponent."],
129  "pmbus_read_sensor": {
130    "type": "vout",
131    "command": "0x8B",
132    "format": "linear_16",
133    "exponent": -8
134  }
135}
136```
137