1# rail
2
3## Description
4
5A voltage rail that is enabled or monitored by the power sequencer device.
6
7The "check_status_vout", "compare_voltage_to_limit", and "gpio" properties
8specify how to obtain the pgood status of the rail. You can specify more than
9one of these properties.
10
11The "check_status_vout" method is usually the most accurate. For example, if a
12pgood fault occurs, the power sequencer device may automatically shut off
13related rails. Ideally the device will only set fault bits in STATUS_VOUT for
14the rail with the pgood fault. However, all the related rails will likely appear
15to be faulted by the other methods.
16
17The "compare_voltage_to_limit" method is helpful when a rail fails to power on
18during the power on sequence and the power sequencer device waits indefinitely
19for it to power on.
20
21The "gpio" method is necessary when no PMBus information is available for the
22rail. It is also helpful when a rail fails to power on during the power on
23sequence and the power sequencer device waits indefinitely for it to power on.
24
25## Properties
26
27| Name                     |      Required       | Type                    | Description                                                                                                                                                                                                                                                                                                                    |
28| :----------------------- | :-----------------: | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
29| name                     |         yes         | string                  | Unique name for the rail. Can only contain letters (A-Z, a-z), numbers (0-9), period (.), and underscore (\_).                                                                                                                                                                                                                 |
30| presence                 |         no          | string                  | D-Bus inventory path of a system component which must be present in order for the rail to be present. If this property is not specified, the rail is assumed to always be present.                                                                                                                                             |
31| page                     | see [notes](#notes) | number                  | PMBus PAGE number of the rail.                                                                                                                                                                                                                                                                                                 |
32| is_power_supply_rail     |         no          | boolean (true or false) | If true, this rail is produced by a power supply. Power supply rails require special error handling. If an error is detected in a power supply device, and the pgood status is false for a power supply rail, the power supply error is logged as the cause of the pgood failure. The default value of this property is false. |
33| check_status_vout        |         no          | boolean (true or false) | If true, determine the pgood status of the rail by checking the value of the PMBus STATUS_VOUT command. If one of the error bits is set, the rail pgood will be considered false. The default value of this property is false.                                                                                                 |
34| compare_voltage_to_limit |         no          | boolean (true or false) | If true, determine the pgood status of the rail by comparing the output voltage (READ_VOUT) to the undervoltage fault limit (VOUT_UV_FAULT_LIMIT). If the output voltage is below this limit, the rail pgood will be considered false. The default value of this property is false.                                            |
35| gpio                     |         no          | [gpio](gpio.md)         | Determine the pgood status of the rail by reading a GPIO.                                                                                                                                                                                                                                                                      |
36
37### Notes
38
39- The "page" property is required if the "check_status_vout" or
40  "compare_voltage_to_limit" property is true.
41
42## Examples
43
44```json
45{
46  "name": "VDD_CPU0",
47  "page": 11,
48  "check_status_vout": true
49}
50```
51
52```json
53{
54  "name": "VCS_CPU1",
55  "presence": "/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu1",
56  "gpio": { "line": 60 }
57}
58```
59