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:

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

KeywordDescription
typeThe bus connection type. Values (string): SMP_BUS and OMI_BUS
unitOptional. 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):

PriorityDescription
HIGHSerivce is mandatory.
MEDService one at a time, in order, until issue is resolved.
MED_ASame as MED except all in group A replaced at the same time.
MED_BSame as MED except all in group B replaced at the same time.
MED_CSame as MED except all in group C replaced at the same time.
LOWSame 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):

GuardDescription
trueRequest guard on associated part.
falseNo 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).

KeywordDescription
typevalue (string): action
nameThe <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.

KeywordDescription
typevalue (string): callout_self
prioritySee priority table above.
guardSee guard table above.

5.1.3) action type callout_unit

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

KeywordDescription
typevalue (string): callout_unit
nameThe <unit_name> as defined by the units keyword.
prioritySee priority table above.
guardSee 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.

KeywordDescription
typevalue (string): callout_connected
nameThe <bus_name> as defined by the buses keyword.
prioritySee priority table above.
guardSee 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)
KeywordDescription
typevalue (string): callout_bus
nameThe <bus_name> as defined by the buses keyword.
prioritySee priority table above.
guardSee guard table above.

5.1.6) action type callout_clock

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

KeywordDescription
typevalue (string): callout_clock
nameSee clock type table below.
prioritySee priority table above.
guardSee guard table above.

Supported clock types:

Clock TypeDescription
OSC_REF_CLOCK_0Oscillator reference clock 0
OSC_REF_CLOCK_1Oscillator reference clock 1
TOD_CLOCKTime of Day (TOD) clock

5.1.7) action type callout_procedure

This will request to callout a service procedure.

KeywordDescription
typevalue (string): callout_procedure
nameSee procedures table below.
prioritySee priority table above.

Supported procedures:

ProcedureDescription
LEVEL2Request 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).

KeywordDescription
typevalue (string): callout_part
nameSee parts table below.
prioritySee priority table above.

Supported parts:

Part TypeDescription
PNORThe 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.

KeywordDescription
typevalue (string): plugin
nameA string representing the plugin name.
instanceSome plugins may be defined for multiple register/unit instances.

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.