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): `peer`, `parent`, `child`| 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| position | value (integer): 0 or 1 | 173| priority | See `priority` table above. | 174| guard | See `guard` table above. | 175 176#### 5.1.7) action type `callout_procedure` 177 178This will request to callout a service procedure. 179 180| Keyword | Description | 181|----------|-------------------------------------------------------------------| 182| type | value (string): `callout_procedure` | 183| name | The `procedures` table below. | 184| priority | See `priority` table above. | 185 186Supported procedures: 187 188| Procedure | Description | 189|-----------|------------------------------------------------------------------| 190| LEVEL2 | Request Level 2 support | 191 192#### 5.1.8) action type `callout_part` 193 194This will request special part callouts that cannot be managed by the other 195callout actions (e.g. the PNOR). 196 197| Keyword | Description | 198|----------|-------------------------------------------------------------------| 199| type | value (string): `callout_part` | 200| name | The `parts` table below. | 201| priority | See `priority` table above. | 202 203Supported parts: 204 205| Part | Description | 206|----------|-------------------------------------------------------------------| 207 208#### 5.1.9) action type `plugin` 209 210Some RAS actions require additional support that cannot be defined easily in 211these data files. User application can defined plugins to perform these 212additional tasks. Use of this keyword should be avoided if possible. Remember, 213the goal is to make the user applications as data driven as possible to avoid 214platform specific code. 215 216| Keyword | Description | 217|----------|-------------------------------------------------------------------| 218| type | value (string): `plugin` | 219| name | A string representing the plugin name. | 220 221### 5.2) `actions` example 222 223```json 224 "actions" : { 225 "self_L" : [ 226 { 227 "type" : "callout_self", 228 "priority" : "LOW", 229 "guard" : false 230 }, 231 ], 232 "level2_M_self_L" : [ 233 { 234 "type" : "callout_procedure", 235 "name" : "LEVEL2", 236 "priority" : "MED" 237 }, 238 { 239 "type" : "action", 240 "name" : "self_L" 241 } 242 ] 243 } 244``` 245 246## 6) `signatures` keyword (required) 247 248The value of this keyword is a JSON object representing all of the signatures 249from this chip requiring RAS actions. Each element of this object will have the 250format: 251 252``` 253"<sig_id>" : { "<sig_bit>" : { "<sig_inst>" : "<action_name>", ... }, ... } 254``` 255 256Where `<sig_id>` (16-bit), `<sig_bit>` (8-bit), and `<sig_inst>` (8-bit) are 257lower case hexadecimal values with NO preceeding '0x'. See the details of these 258fields in the isolator's `Signature` object. The `<action_name>` is a label 259defined in by the `actions` keyword above. 260