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