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 95Actions with a `guard` keyword can only use the following values (boolean): 96 97| Guard | Description | 98|-------|----------------------------------------------------------------------| 99| true | Request guard on associated part. | 100| false | No guard request. | 101 102#### 5.1.1) action type `action` 103 104This is a special action type that allows using an action that has already been 105defined (nested actions). 106 107| Keyword | Description | 108|---------|--------------------------------------------------------------------| 109| type | value (string): `action` | 110| name | The `<action_name>` of a previously predefined action. | 111 112#### 5.1.2) action type `callout_self` 113 114This will request to callout the chip defined by this file. 115 116| Keyword | Description | 117|----------|-------------------------------------------------------------------| 118| type | value (string): `callout_self` | 119| priority | See `priority` table above. | 120| guard | See `guard` table above. | 121 122#### 5.1.3) action type `callout_unit` 123 124This will request to callout a unit of the chip defined by this file. 125 126| Keyword | Description | 127|----------|-------------------------------------------------------------------| 128| type | value (string): `callout_unit` | 129| name | The `<unit_name>` as defined by the `units` keyword. | 130| priority | See `priority` table above. | 131| guard | See `guard` table above. | 132 133#### 5.1.4) action type `callout_connected` 134 135This will request to callout a connected chip/unit on the other side of a bus. 136 137| Keyword | Description | 138|----------|-------------------------------------------------------------------| 139| type | value (string): `callout_connected` | 140| name | The `<bus_name>` as defined by the `buses` keyword. | 141| priority | See `priority` table above. | 142| guard | See `guard` table above. | 143 144#### 5.1.5) action type `callout_bus` 145 146This will request to callout all parts associated with a bus (RX/TX endpoints 147and everything else in between the endpoints). Bus callouts have very specific 148priority: 149 150- If an SMP cable exists, callout the cable with priority `HIGH`. 151- Callout both RX and TX endpoints with priority `MED_A`. 152- Callout everything else in between with priority `LOW`. 153 154In some special cases, the callout priority of the endpoints may differ from the 155default `MED_A`. In which case, the optional priority properties can be used. 156 157| Keyword | Description | 158|-------------|----------------------------------------------------------------| 159| type | value (string): `callout_bus` | 160| name | The `<bus_name>` as defined by the `buses` keyword. | 161| rx_priority | Optional priority of the receiving side endpoint | 162| tx_priority | Optional priority of the transfer side endpoint | 163| guard | See `guard` table above. | 164 165#### 5.1.6) action type `callout_clock` 166 167This will request to callout a clock associated with this chip. 168 169| Keyword | Description | 170|----------|-------------------------------------------------------------------| 171| type | value (string): `callout_clock` | 172| name | See `clock type` table below. | 173| priority | See `priority` table above. | 174| guard | See `guard` table above. | 175 176Supported clock types: 177 178| Clock Type | Description | 179|-----------------|------------------------------------------------------------| 180| OSC_REF_CLOCK_0 | Oscillator reference clock 0 | 181| OSC_REF_CLOCK_1 | Oscillator reference clock 1 | 182 183#### 5.1.7) action type `callout_procedure` 184 185This will request to callout a service procedure. 186 187| Keyword | Description | 188|----------|-------------------------------------------------------------------| 189| type | value (string): `callout_procedure` | 190| name | See `procedures` table below. | 191| priority | See `priority` table above. | 192 193Supported procedures: 194 195| Procedure | Description | 196|-----------|------------------------------------------------------------------| 197| LEVEL2 | Request Level 2 support | 198 199#### 5.1.8) action type `callout_part` 200 201This will request special part callouts that cannot be managed by the other 202callout actions (e.g. the PNOR). 203 204| Keyword | Description | 205|----------|-------------------------------------------------------------------| 206| type | value (string): `callout_part` | 207| name | See `parts` table below. | 208| priority | See `priority` table above. | 209 210Supported parts: 211 212| Part | Description | 213|----------|-------------------------------------------------------------------| 214 215#### 5.1.9) action type `plugin` 216 217Some RAS actions require additional support that cannot be defined easily in 218these data files. User application can defined plugins to perform these 219additional tasks. Use of this keyword should be avoided if possible. Remember, 220the goal is to make the user applications as data driven as possible to avoid 221platform specific code. 222 223| Keyword | Description | 224|----------|-------------------------------------------------------------------| 225| type | value (string): `plugin` | 226| name | A string representing the plugin name. | 227 228### 5.2) `actions` example 229 230```json 231 "actions" : { 232 "self_L" : [ 233 { 234 "type" : "callout_self", 235 "priority" : "LOW", 236 "guard" : false 237 }, 238 ], 239 "level2_M_self_L" : [ 240 { 241 "type" : "callout_procedure", 242 "name" : "LEVEL2", 243 "priority" : "MED" 244 }, 245 { 246 "type" : "action", 247 "name" : "self_L" 248 } 249 ] 250 } 251``` 252 253## 6) `signatures` keyword (required) 254 255The value of this keyword is a JSON object representing all of the signatures 256from this chip requiring RAS actions. Each element of this object will have the 257format: 258 259``` 260"<sig_id>" : { "<sig_bit>" : { "<sig_inst>" : "<action_name>", ... }, ... } 261``` 262 263Where `<sig_id>` (16-bit), `<sig_bit>` (8-bit), and `<sig_inst>` (8-bit) are 264lower case hexadecimal values with NO preceeding '0x'. See the details of these 265fields in the isolator's `Signature` object. The `<action_name>` is a label 266defined in by the `actions` keyword above. 267