xref: /openbmc/openpower-hw-diags/analyzer/ras-data/ras-data-definition.md (revision 506db4c8dfd0b67f8516d1cb8e3c01b2074aea2e)

# RAS Data File definition

When hardware reports an error, the analyzer will call the isolator which will
return a list of active attentions in the hardware, referred to as `signatures`.
The analyzer will then filter and sort the list to find the root cause
signature. The RAS Data files are used to define, in a data driven fashion, the
appropriate RAS actions that should be taken for the root cause signature.

The RAS Data will be defined in the JSON data format. Each file will contain a
single JSON object (with nested values) which will define the RAS actions for a
single chip model and EC level.

## 1) `model_ec` keyword (required)

The value of this keyword is a `string` representing a 32-bit hexidecimal number
in the format `[0-9A-Fa-f]{8}`. This value is used to determine the chip model
and EC level in which this data is defined.

## 2) `version` keyword (required)

A new version number should be used for each new RAS data file format so that
user applications will know how to properly parse the files. The value of this
keyword is a positive integer. Version `1` has been deprecated. The current
version is `2`.

## 3) `units` keyword

The value of this keyword is a JSON object representing all of the guardable
unit targets on this chip. Each element of this object will have the format:

```text
"<unit_name>" : "<relative_devtree_path>"
```

Where `<unit_name>` is simply an alphanumeric label for the unit and
`<relative_devtree_path>` is a string representing the devtree path of the unit
relative to the chip defined by the file. When necessary, the user application
should be able to concatenate the devtree path of the chip and the relative
devtree path of the unit to get the full devtree path of the unit.

## 4) `buses` keyword

The value of this keyword is a JSON object representing all of the buses
connected to this chip. Each element of this object will have the format:

```text
"<bus_name>" : { <bus_details> }
```

Where `<bus_name>` is simply an alphanumeric label for the bus and
`<bus_details>` is a JSON object containing details of the bus connection.

### 4.1) `<bus_details>` object

This describes how the bus is connected to this chip. Note that the `unit`
keyword is optional and the chip is used as the endpoint connection instead.
This is usually intended to be used when the chip is the child and we need to
find the connected `parent` chip/unit.

| Keyword | Description                                                       |
| ------- | ----------------------------------------------------------------- |
| type    | The bus connection type. Values (string): `SMP_BUS` and `OMI_BUS` |
| unit    | Optional. The `<unit_name>` of the bus endpoint on this chip.     |

## 5) `actions` keyword (required)

The value of this keyword is a JSON object representing all of the defined
actions available for the file. Each element of this object contains an array of
RAS actions, to be performed in order, with the format:

```text
"<action_name>" : [ { <action_element> }, ... ]
```

Where `<action_name>` is simply an alphanumeric label for a set of actions. This
will be the keyword referenced by the `signatures` or by a special
`<action_element>` for nested actions (see below).

### 5.1) `<action_element>` object

All `<action_element>` are JSON objects and they all require the `type` keyword,
which is used to determine the action type. The remaining required keywords are
dependent on the action type.

Actions with a `priority` keyword can only use the following values (string):

| Priority | Description                                                        |
| -------- | ------------------------------------------------------------------ |
| `HIGH`   | Serivce is mandatory.                                              |
| `MED`    | Service one at a time, in order, until issue is resolved.          |
| `MED_A`  | Same as `MED` except all in group A replaced at the same time.     |
| `MED_B`  | Same as `MED` except all in group B replaced at the same time.     |
| `MED_C`  | Same as `MED` except all in group C replaced at the same time.     |
| `LOW`    | Same as `MED*`, but only if higher priority service does not work. |

NOTE: If a part is called out more than once, only the highest priority callout
will be used.

Actions with a `guard` keyword can only use the following values (boolean):

| Guard | Description                       |
| ----- | --------------------------------- |
| true  | Request guard on associated part. |
| false | No guard request.                 |

#### 5.1.1) action type `action`

This is a special action type that allows using an action that has already been
defined (nested actions).

| Keyword | Description                                            |
| ------- | ------------------------------------------------------ |
| type    | value (string): `action`                               |
| name    | The `<action_name>` of a previously predefined action. |

#### 5.1.2) action type `callout_self`

This will request to callout the chip defined by this file.

| Keyword  | Description                    |
| -------- | ------------------------------ |
| type     | value (string): `callout_self` |
| priority | See `priority` table above.    |
| guard    | See `guard` table above.       |

#### 5.1.3) action type `callout_unit`

This will request to callout a unit of the chip defined by this file.

| Keyword  | Description                                          |
| -------- | ---------------------------------------------------- |
| type     | value (string): `callout_unit`                       |
| name     | The `<unit_name>` as defined by the `units` keyword. |
| priority | See `priority` table above.                          |
| guard    | See `guard` table above.                             |

#### 5.1.4) action type `callout_connected`

This will request to callout a connected chip/unit on the other side of a bus.

| Keyword  | Description                                         |
| -------- | --------------------------------------------------- |
| type     | value (string): `callout_connected`                 |
| name     | The `<bus_name>` as defined by the `buses` keyword. |
| priority | See `priority` table above.                         |
| guard    | See `guard` table above.                            |

#### 5.1.5) action type `callout_bus`

This will request to callout all parts associated with a bus (RX/TX endpoints
and everything else in between the endpoints). All parts will be called out with
the same priority. If a particular part, like the endpoints, need to be called
out at a different priority, they will need to be called out using a different
action type. For example:

- `callout_self` with priority `MED_A`. (RX endpoint MED_A)
- `callout_connected` with priority `MED_A`. (TX endpoint MED_A)
- `callout_bus` with priority `LOW`. (everything else LOW)

| Keyword  | Description                                         |
| -------- | --------------------------------------------------- |
| type     | value (string): `callout_bus`                       |
| name     | The `<bus_name>` as defined by the `buses` keyword. |
| priority | See `priority` table above.                         |
| guard    | See `guard` table above.                            |

#### 5.1.6) action type `callout_clock`

This will request to callout a clock associated with this chip.

| Keyword  | Description                     |
| -------- | ------------------------------- |
| type     | value (string): `callout_clock` |
| name     | See `clock type` table below.   |
| priority | See `priority` table above.     |
| guard    | See `guard` table above.        |

Supported clock types:

| Clock Type      | Description                  |
| --------------- | ---------------------------- |
| OSC_REF_CLOCK_0 | Oscillator reference clock 0 |
| OSC_REF_CLOCK_1 | Oscillator reference clock 1 |
| TOD_CLOCK       | Time of Day (TOD) clock      |

#### 5.1.7) action type `callout_procedure`

This will request to callout a service procedure.

| Keyword  | Description                         |
| -------- | ----------------------------------- |
| type     | value (string): `callout_procedure` |
| name     | See `procedures` table below.       |
| priority | See `priority` table above.         |

Supported procedures:

| Procedure | Description             |
| --------- | ----------------------- |
| LEVEL2    | Request Level 2 support |

#### 5.1.8) action type `callout_part`

This will request special part callouts that cannot be managed by the other
callout actions (e.g. the PNOR).

| Keyword  | Description                    |
| -------- | ------------------------------ |
| type     | value (string): `callout_part` |
| name     | See `parts` table below.       |
| priority | See `priority` table above.    |

Supported parts:

| Part Type | Description                  |
| --------- | ---------------------------- |
| PNOR      | The part containing the PNOR |

#### 5.1.9) action type `plugin`

Some RAS actions require additional support that cannot be defined easily in
these data files. User application can defined plugins to perform these
additional tasks. Use of this keyword should be avoided if possible. Remember,
the goal is to make the user applications as data driven as possible to avoid
platform specific code.

| Keyword  | Description                                                       |
| -------- | ----------------------------------------------------------------- |
| type     | value (string): `plugin`                                          |
| name     | A string representing the plugin name.                            |
| instance | Some plugins may be defined for multiple register/unit instances. |

### 5.2) `actions` example

```json
    "actions" : {
        "self_L" : [
            {
                "type"     : "callout_self",
                "priority" : "LOW",
                "guard"    : false
            },
        ],
        "level2_M_self_L" : [
            {
                "type"     : "callout_procedure",
                "name"     : "LEVEL2",
                "priority" : "MED"
            },
            {
                "type" : "action",
                "name" : "self_L"
            }
        ]
    }
```

## 6) `signatures` keyword (required)

The value of this keyword is a JSON object representing all of the signatures
from this chip requiring RAS actions. Each element of this object will have the
format:

```text
"<sig_id>" : { "<sig_bit>" : { "<sig_inst>" : "<action_name>", ... }, ... }
```

Where `<sig_id>` (16-bit), `<sig_bit>` (8-bit), and `<sig_inst>` (8-bit) are
lower case hexadecimal values with NO preceeding '0x'. See the details of these
fields in the isolator's `Signature` object. The `<action_name>` is a label
defined in by the `actions` keyword above.