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. Initially, format version is 1.

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:

"<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:

"<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:

"<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

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	Description

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.

5.2) actions example

    "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:

"<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.