1# RAS Data File definition 2 3When hardware reports an error, the analyzer will call the isolator which will 4return a list of active attentions in the hardware, referred to as `signatures`. 5The analyzer will then filter and sort the list to find the root cause 6signature. The RAS Data files are used to define, in a data driven fashion, the 7appropriate RAS actions that should be taken for the root cause signature. 8 9The RAS Data will be defined in the JSON data format. Each file will contain a 10single JSON object (with nested values) which will define the RAS actions for a 11single chip model and EC level. 12 13## 1) `model_ec` keyword (required) 14 15The value of this keyword is a `string` representing a 32-bit hexidecimal number 16in the format `[0-9A-Fa-f]{8}`. This value is used to determine the chip model 17and EC level in which this data is defined. 18 19## 2) `version` keyword (required) 20 21A new version number should be used for each new RAS data file format so that 22user applications will know how to properly parse the files. The value of this 23keyword is a positive integer. Initially, format version is `1`. 24 25## 3) `units` keyword 26 27The value of this keyword is a JSON object representing all of the guardable 28unit targets on this chip. Each element of this object will have the format: 29 30``` 31"<unit_name>" : "<relative_devtree_path>" 32``` 33 34Where `<unit_name>` is simply an alphanumeric label for the unit and 35`<relative_devtree_path>` is a string representing the devtree path of the unit 36relative to the chip defined by the file. When necessary, the user application 37should be able to concatenate the devtree path of the chip and the relative 38devtree path of the unit to get the full devtree path of the unit. 39 40## 4) `buses` keyword 41 42The value of this keyword is a JSON object representing all of the buses 43connected to this chip. Each element of this object will have the format: 44 45``` 46"<bus_name>" : { <bus_details> } 47``` 48 49Where `<bus_name>` is simply an alphanumeric label for the bus and 50`<bus_details>` is a JSON object containing details of the bus connection. 51 52### 4.1) `<bus_details>` object 53 54This describes how the bus is connected to this chip. Note that the `unit` 55keyword is optional and the chip is used as the endpoint connection instead. 56This is usually intended to be used when the chip is the child and we need to 57find the connected `parent` chip/unit. 58 59| Keyword | Description | 60|---------|--------------------------------------------------------------------| 61| type | The bus connection type. Values (string): `SMP_BUS` and `OMI_BUS` | 62| unit | Optional. The `<unit_name>` of the bus endpoint on this chip. | 63 64## 5) `actions` keyword (required) 65 66The value of this keyword is a JSON object representing all of the defined 67actions available for the file. Each element of this object contains an array of 68RAS actions, to be performed in order, with the format: 69 70``` 71"<action_name>" : [ { <action_element> }, ... ] 72``` 73 74Where `<action_name>` is simply an alphanumeric label for a set of actions. 75This will be the keyword referenced by the `signatures` or by a special 76`<action_element>` for nested actions (see below). 77 78### 5.1) `<action_element>` object 79 80All `<action_element>` are JSON objects and they all require the `type` keyword, 81which is used to determine the action type. The remaining required keywords are 82dependent on the action type. 83 84Actions with a `priority` keyword can only use the following values (string): 85 86| Priority | Description | 87|----------|-------------------------------------------------------------------| 88| `HIGH` | Serivce is mandatory. | 89| `MED` | Service one at a time, in order, until issue is resolved. | 90| `MED_A` | Same as `MED` except all in group A replaced at the same time. | 91| `MED_B` | Same as `MED` except all in group B replaced at the same time. | 92| `MED_C` | Same as `MED` except all in group C replaced at the same time. | 93| `LOW` | Same as `MED*`, but only if higher priority service does not work.| 94 95NOTE: If a part is called out more than once, only the highest priority callout 96will be used. 97 98Actions with a `guard` keyword can only use the following values (boolean): 99 100| Guard | Description | 101|-------|----------------------------------------------------------------------| 102| true | Request guard on associated part. | 103| false | No guard request. | 104 105#### 5.1.1) action type `action` 106 107This is a special action type that allows using an action that has already been 108defined (nested actions). 109 110| Keyword | Description | 111|---------|--------------------------------------------------------------------| 112| type | value (string): `action` | 113| name | The `<action_name>` of a previously predefined action. | 114 115#### 5.1.2) action type `callout_self` 116 117This will request to callout the chip defined by this file. 118 119| Keyword | Description | 120|----------|-------------------------------------------------------------------| 121| type | value (string): `callout_self` | 122| priority | See `priority` table above. | 123| guard | See `guard` table above. | 124 125#### 5.1.3) action type `callout_unit` 126 127This will request to callout a unit of the chip defined by this file. 128 129| Keyword | Description | 130|----------|-------------------------------------------------------------------| 131| type | value (string): `callout_unit` | 132| name | The `<unit_name>` as defined by the `units` keyword. | 133| priority | See `priority` table above. | 134| guard | See `guard` table above. | 135 136#### 5.1.4) action type `callout_connected` 137 138This will request to callout a connected chip/unit on the other side of a bus. 139 140| Keyword | Description | 141|----------|-------------------------------------------------------------------| 142| type | value (string): `callout_connected` | 143| name | The `<bus_name>` as defined by the `buses` keyword. | 144| priority | See `priority` table above. | 145| guard | See `guard` table above. | 146 147#### 5.1.5) action type `callout_bus` 148 149This will request to callout all parts associated with a bus (RX/TX endpoints 150and everything else in between the endpoints). All parts will be called out with 151the same priority. If a particular part, like the endpoints, need to be called 152out at a different priority, they will need to be called out using a different 153action type. For example: 154 155- `callout_self` with priority `MED_A`. (RX endpoint MED_A) 156- `callout_connected` with priority `MED_A`. (TX endpoint MED_A) 157- `callout_bus` with priority `LOW`. (everything else LOW) 158 159| Keyword | Description | 160|-------------|----------------------------------------------------------------| 161| type | value (string): `callout_bus` | 162| name | The `<bus_name>` as defined by the `buses` keyword. | 163| priority | See `priority` table above. | 164| guard | See `guard` table above. | 165 166#### 5.1.6) action type `callout_clock` 167 168This will request to callout a clock associated with this chip. 169 170| Keyword | Description | 171|----------|-------------------------------------------------------------------| 172| type | value (string): `callout_clock` | 173| name | See `clock type` table below. | 174| priority | See `priority` table above. | 175| guard | See `guard` table above. | 176 177Supported clock types: 178 179| Clock Type | Description | 180|-----------------|------------------------------------------------------------| 181| OSC_REF_CLOCK_0 | Oscillator reference clock 0 | 182| OSC_REF_CLOCK_1 | Oscillator reference clock 1 | 183| TOD_CLOCK | Time of Day (TOD) clock | 184 185#### 5.1.7) action type `callout_procedure` 186 187This will request to callout a service procedure. 188 189| Keyword | Description | 190|----------|-------------------------------------------------------------------| 191| type | value (string): `callout_procedure` | 192| name | See `procedures` table below. | 193| priority | See `priority` table above. | 194 195Supported procedures: 196 197| Procedure | Description | 198|-----------|------------------------------------------------------------------| 199| LEVEL2 | Request Level 2 support | 200 201#### 5.1.8) action type `callout_part` 202 203This will request special part callouts that cannot be managed by the other 204callout actions (e.g. the PNOR). 205 206| Keyword | Description | 207|----------|-------------------------------------------------------------------| 208| type | value (string): `callout_part` | 209| name | See `parts` table below. | 210| priority | See `priority` table above. | 211 212Supported parts: 213 214| Part Type | Description | 215|---------------|--------------------------------------------------------------| 216| PNOR | The part containing the PNOR | 217 218#### 5.1.9) action type `plugin` 219 220Some RAS actions require additional support that cannot be defined easily in 221these data files. User application can defined plugins to perform these 222additional tasks. Use of this keyword should be avoided if possible. Remember, 223the goal is to make the user applications as data driven as possible to avoid 224platform specific code. 225 226| Keyword | Description | 227|----------|-------------------------------------------------------------------| 228| type | value (string): `plugin` | 229| name | A string representing the plugin name. | 230| instance | Some plugins may be defined for multiple register/unit instances. | 231 232### 5.2) `actions` example 233 234```json 235 "actions" : { 236 "self_L" : [ 237 { 238 "type" : "callout_self", 239 "priority" : "LOW", 240 "guard" : false 241 }, 242 ], 243 "level2_M_self_L" : [ 244 { 245 "type" : "callout_procedure", 246 "name" : "LEVEL2", 247 "priority" : "MED" 248 }, 249 { 250 "type" : "action", 251 "name" : "self_L" 252 } 253 ] 254 } 255``` 256 257## 6) `signatures` keyword (required) 258 259The value of this keyword is a JSON object representing all of the signatures 260from this chip requiring RAS actions. Each element of this object will have the 261format: 262 263``` 264"<sig_id>" : { "<sig_bit>" : { "<sig_inst>" : "<action_name>", ... }, ... } 265``` 266 267Where `<sig_id>` (16-bit), `<sig_bit>` (8-bit), and `<sig_inst>` (8-bit) are 268lower case hexadecimal values with NO preceeding '0x'. See the details of these 269fields in the isolator's `Signature` object. The `<action_name>` is a label 270defined in by the `actions` keyword above. 271