prettier: re-format
Change-Id: I6b22ad83c41e53484812f83ea70e7ce6d9c299cd
Signed-off-by: Zane Shelley <zshelle@us.ibm.com>
diff --git a/README.md b/README.md
index 452adcf..8b406dd 100644
--- a/README.md
+++ b/README.md
@@ -1,60 +1,55 @@
-openpower-libhei: Hardware Error Isolation for POWER Systems
-============================================================
+# openpower-libhei: Hardware Error Isolation for POWER Systems
This library is a common, portable code base for isolating errors reported by
hardware registers on POWER Systems chips.
The primary consumers (and requirements drivers) will be:
- * [OpenBMC Hardware Diagnostics][]
- * [POWER Systems Hostboot firmware][]
- * POWER Systems FSP firmware
-Core API
---------
+- [OpenBMC Hardware Diagnostics][]
+- [POWER Systems Hostboot firmware][]
+- POWER Systems FSP firmware
+
+## Core API
See the [primary API definitions][] for details on how to use this library.
-Integration
------------
+## Integration
This library can be integrated into a user application's source (either
imported, or as a git subtree/submodule) or built as static library.
-User Application Requirements and APIs
---------------------------------------
+## User Application Requirements and APIs
- * The process to access hardware register data will vary per user application.
- Therefore, this library will declare the hardware access [user APIs][], but
- each user application must implement the APIs for their own environment.
- * This library will not contain data regarding hardware specific information.
- Instead, that information will be provided by the user application in the
- form of the [Chip Data Files][].
- * Tracing, or logging, methods will vary per user application. Therefore, this
- library will declare the tracing/logging [user APIs][], but each user
- application must implement the APIs for their own environment.
+- The process to access hardware register data will vary per user application.
+ Therefore, this library will declare the hardware access [user APIs][], but
+ each user application must implement the APIs for their own environment.
+- This library will not contain data regarding hardware specific information.
+ Instead, that information will be provided by the user application in the form
+ of the [Chip Data Files][].
+- Tracing, or logging, methods will vary per user application. Therefore, this
+ library will declare the tracing/logging [user APIs][], but each user
+ application must implement the APIs for their own environment.
-Environment configuration
--------------------------
+## Environment configuration
- * `__HEI_ENABLE_HW_WRITE`: When defined, it will allow hardware write support.
- Note that the Chip Data Files will contain rules for clearing and masking
- register bits. Both of which will require modifying hardware registers,
- which is not allowed by user applications like OpenBMC or FSP firmware.
+- `__HEI_ENABLE_HW_WRITE`: When defined, it will allow hardware write support.
+ Note that the Chip Data Files will contain rules for clearing and masking
+ register bits. Both of which will require modifying hardware registers, which
+ is not allowed by user applications like OpenBMC or FSP firmware.
-Development Notes
------------------
+## Development Notes
- * The Hostboot environment only supports up to **C++14**. Therefore, this
- library cannot use anything newer at this time.
- * Hostboot has a very limited environment. It does not include libc or
- libstdc++. However, Hostboot has implemented select functions from those
- libraries as needed. For details, you can reference `src/include/` in the
- [POWER Systems Hostboot firmware][].
+- The Hostboot environment only supports up to **C++14**. Therefore, this
+ library cannot use anything newer at this time.
+- Hostboot has a very limited environment. It does not include libc or
+ libstdc++. However, Hostboot has implemented select functions from those
+ libraries as needed. For details, you can reference `src/include/` in the
+ [POWER Systems Hostboot firmware][].
-Building
---------
+## Building
For a standard OpenBMC release build, you want something like:
+
```
meson -Dtests=disabled <build_dir>
ninja -C <build_dir>
@@ -62,14 +57,14 @@
```
For a test / debug build, a typical configuration is:
+
```
meson -Dtests=enabled <build_dir>
ninja -C <build_dir> test
```
-[OpenBMC Hardware Diagnostics]: https://github.com/openbmc/openpower-hw-diags
-[POWER Systems Hostboot firmware]: https://github.com/open-power/hostboot
-[primary API definitions]: src/hei_main.hpp
-[user APIs]: src/hei_user_interface.hpp
-[Chip Data Files]: src/chip_data/CHIP_DATA.md
-
+[openbmc hardware diagnostics]: https://github.com/openbmc/openpower-hw-diags
+[power systems hostboot firmware]: https://github.com/open-power/hostboot
+[primary api definitions]: src/hei_main.hpp
+[user apis]: src/hei_user_interface.hpp
+[chip data files]: src/chip_data/CHIP_DATA.md
diff --git a/src/chip_data/CHIP_DATA.md b/src/chip_data/CHIP_DATA.md
index a3cb561..6dc8ca6 100644
--- a/src/chip_data/CHIP_DATA.md
+++ b/src/chip_data/CHIP_DATA.md
@@ -3,20 +3,21 @@
The Chip Data Files define everything we need to know about a chip type. Their
purpose is to keep libhei agnostic to specific chip information. Required
information includes:
- * All hardware addresses needed for error isolation.
- * A definition of how errors propagate from register to register.
- * A list of top level registers to use as a starting point for isolation.
- * A list of additional registers to capture for each register bit (for debug).
- * Rules defining how to clear and mask register bits (only applicable if
- `__HEI_ENABLE_HW_WRITE` is defined).
-File extensions are not required, but it is recommended to use the
-extension `.cdb` (chip data binary).
+- All hardware addresses needed for error isolation.
+- A definition of how errors propagate from register to register.
+- A list of top level registers to use as a starting point for isolation.
+- A list of additional registers to capture for each register bit (for debug).
+- Rules defining how to clear and mask register bits (only applicable if
+ `__HEI_ENABLE_HW_WRITE` is defined).
+
+File extensions are not required, but it is recommended to use the extension
+`.cdb` (chip data binary).
## Requirements
- * These files must be consumable by different host architectures. So all data
- fields within the files will be stored in big-endian format (use endian.h).
+- These files must be consumable by different host architectures. So all data
+ fields within the files will be stored in big-endian format (use endian.h).
## File Format
@@ -24,11 +25,11 @@
The following data will be defined at the very beginning of each Chip Data File:
-| Bytes | Desc | Value/Example |
-|:-----:|:---------------------|:-------------------------------------------|
-| 8 | chip data keyword | 0x4348495044415441 (ascii for "CHIPDATA") |
-| 4 | chip model/level | Unique ID defined by data file owner |
-| 1 | file version | Version 1 => 0x01, Version 2 => 0x02, etc. |
+| Bytes | Desc | Value/Example |
+| :---: | :---------------- | :----------------------------------------- |
+| 8 | chip data keyword | 0x4348495044415441 (ascii for "CHIPDATA") |
+| 4 | chip model/level | Unique ID defined by data file owner |
+| 1 | file version | Version 1 => 0x01, Version 2 => 0x02, etc. |
The user application will use the chip model/level ID to determine which Chip
Data File(s) should be used for the chip(s) that exist in the user application's
@@ -40,25 +41,24 @@
registers referenced by the isolation nodes for this chip starting with:
| Bytes | Desc | Value/Example |
-|:-----:|:-----------------|:------------------------------|
-| 4 | register keyword | 0x52454753 (ascii for "REGS") |
-| 3 | # of registers | 0 is invalid |
+| :---: | :--------------- | :---------------------------- |
+| 4 | register keyword | 0x52454753 (ascii for "REGS") |
+| 3 | # of registers | 0 is invalid |
Then, each register will start with:
| Bytes | Desc | Value/Example |
-|:-----:|:-----------------------|:------------------------------------------|
-| 3 | register ID | Unique ID defined by data file owner |
-| 1 | register type | See appendix for supported register types |
-| 1 | attribute flags | For each bit 0:disabled and 1:enabled |
-| 1 | # of address instances | 0 is invalid |
+| :---: | :--------------------- | :---------------------------------------- |
+| 3 | register ID | Unique ID defined by data file owner |
+| 1 | register type | See appendix for supported register types |
+| 1 | attribute flags | For each bit 0:disabled and 1:enabled |
+| 1 | # of address instances | 0 is invalid |
The register ID must be unique for all registers withing the Chip Data File.
-Supported attribute flags (bits ordered 0-7, left to right):
- 0: When enabled, the register is readable.
- 1: When enabled, the register is writable.
- 2-7: Reserved (default disabled)
+Supported attribute flags (bits ordered 0-7, left to right): 0: When enabled,
+the register is readable. 1: When enabled, the register is writable. 2-7:
+Reserved (default disabled)
#### 2.1) Register Instances
@@ -70,9 +70,9 @@
instance addresses for a register. Each instance will have the following:
| Bytes | Desc | Value/Example |
-|:-----:|:-----------|:-------------------------------------------------|
-| 1 | instance # | Unique value within the register |
-| * | address | The address size is defined by the register type |
+| :---: | :--------- | :----------------------------------------------- |
+| 1 | instance # | Unique value within the register |
+| \* | address | The address size is defined by the register type |
### 3) Isolation Nodes
@@ -83,24 +83,23 @@
Immediately following all of the metadata described in section 2:
| Bytes | Desc | Value/Example |
-|:-----:|:-----------------------|:------------------------------|
-| 4 | isolation node keyword | 0x4e4f4445 (ascii for "NODE") |
-| 2 | # of isolation nodes | 0 is invalid |
+| :---: | :--------------------- | :---------------------------- |
+| 4 | isolation node keyword | 0x4e4f4445 (ascii for "NODE") |
+| 2 | # of isolation nodes | 0 is invalid |
Then, each node will start the following data:
-| Bytes | Desc | Value/Example |
-|:-----:|:-----------------------|:-------------------------------------|
-| 2 | node ID | Unique ID defined by data file owner |
-| 1 | register type | See appendix for supported types |
-| 1 | # of node instances | 0 is invalid |
+| Bytes | Desc | Value/Example |
+| :---: | :------------------ | :----------------------------------- |
+| 2 | node ID | Unique ID defined by data file owner |
+| 1 | register type | See appendix for supported types |
+| 1 | # of node instances | 0 is invalid |
The node ID must be unique for all nodes within a Chip Data File.
-**IMPORTANT:**
-All registers referenced in a node's isolation rules must be of the same
-register type expressed in this field. This will ensure there is no ambiguity
-when resolving the bitwise expressions in the isolation rules.
+**IMPORTANT:** All registers referenced in a node's isolation rules must be of
+the same register type expressed in this field. This will ensure there is no
+ambiguity when resolving the bitwise expressions in the isolation rules.
#### 3.1) Isolation Node Instances
@@ -108,11 +107,11 @@
have the following:
| Bytes | Desc | Value/Example |
-|:-----:|:-----------------------|:-----------------------------|
-| 1 | instance # | Unique value within the node |
-| 1 | # of capture registers | |
-| 1 | # of isolation rules | 0 is invalid |
-| 1 | # of child nodes | |
+| :---: | :--------------------- | :--------------------------- |
+| 1 | instance # | Unique value within the node |
+| 1 | # of capture registers | |
+| 1 | # of isolation rules | 0 is invalid |
+| 1 | # of child nodes | |
##### 3.1.1) Capture Registers
@@ -124,28 +123,29 @@
immediately following the metadata for each node instance.
| Bytes | Desc | Value/Example |
-|:-----:|:------------------|:--------------------------|
-| 3 | register ID | See section 2 for details |
-| 1 | register instance | See section 2 for details |
+| :---: | :---------------- | :------------------------ |
+| 3 | register ID | See section 2 for details |
+| 1 | register instance | See section 2 for details |
**Version 2 and newer:**
The user application can now specify registers to be captured when isolating to
-a specific bit in an isolation node as opposed to any bit in the isolation
-node. This can reduce the amount of default data captured if a particular bit
-requires capturing registers that are uninteresting to the other bits.
+a specific bit in an isolation node as opposed to any bit in the isolation node.
+This can reduce the amount of default data captured if a particular bit requires
+capturing registers that are uninteresting to the other bits.
Beginning with **version 2**, the following will be appended to the above
capture register metadata:
| Bytes | Desc | Value/Example |
-|:-----:|:---------------------------------------|:----------------|
-| 1 | bit position within the isolation node | see notes below |
+| :---: | :------------------------------------- | :-------------- |
+| 1 | bit position within the isolation node | see notes below |
Notes:
-* The bit position will not exceed number of bits defined by the register type.
-* The order of the bit position is dependent on the register type.
-* A value of **255** indicates the register will be captured for all bit
+
+- The bit position will not exceed number of bits defined by the register type.
+- The order of the bit position is dependent on the register type.
+- A value of **255** indicates the register will be captured for all bit
positions within the isolation node.
##### 3.1.2) Isolation Rules
@@ -161,9 +161,9 @@
capture register metadata for a node instance, if any exists.
| Bytes | Desc | Value/Example |
-|:-----:|:----------------|:-------------------------------------------|
-| 1 | attention type | See appendix for supported attention types |
-| * | rule expression | See expression definition in appendix |
+| :---: | :-------------- | :----------------------------------------- |
+| 1 | attention type | See appendix for supported attention types |
+| \* | rule expression | See expression definition in appendix |
Note that the size of the expression field is variable. See the appendix for
details.
@@ -178,16 +178,17 @@
instance:
| Bytes | Desc | Value/Example |
-|:-----:|:-----------------------------------|:------------------|
-| 1 | bit position within the resolution | See notes below |
-| 2 | child node ID | See node metadata |
-| 1 | child node instance | See node metadata |
+| :---: | :--------------------------------- | :---------------- |
+| 1 | bit position within the resolution | See notes below |
+| 2 | child node ID | See node metadata |
+| 1 | child node instance | See node metadata |
Notes:
-* The size of the isolation rule resolution is defined by the register type
+
+- The size of the isolation rule resolution is defined by the register type
represented by this node.
-* The bit position will not exceed the register size.
-* The order of the bit position is dependent on the register type.
+- The bit position will not exceed the register size.
+- The order of the bit position is dependent on the register type.
### 4) Root Nodes
@@ -196,45 +197,46 @@
section starts with:
| Bytes | Desc | Value/Example |
-|:-----:|:----------------------------|:------------------------------|
-| 4 | root isolation node keyword | 0x524f4f54 (ascii for "ROOT") |
-| 1 | # of root nodes | 0 is invalid |
+| :---: | :-------------------------- | :---------------------------- |
+| 4 | root isolation node keyword | 0x524f4f54 (ascii for "ROOT") |
+| 1 | # of root nodes | 0 is invalid |
Each isolation tree will report attentions for a single attention type and there
can only be one tree per attention type. Immediately following the above
metadata will be the following for each root node:
| Bytes | Desc | Value/Example |
-|:-----:|:-------------------|:-------------------------------------------|
-| 1 | attention type | See appendix for supported attention types |
-| 2 | root node ID | See node ID description in section 3 |
-| 1 | root node instance | See node instance description in section 3 |
+| :---: | :----------------- | :----------------------------------------- |
+| 1 | attention type | See appendix for supported attention types |
+| 2 | root node ID | See node ID description in section 3 |
+| 1 | root node instance | See node instance description in section 3 |
## Appendix
### 1) Supported Register Types
- * Power Systems SCOM register
- * Type value: 0x01
- * Address size: 4 bytes
- * Register size: 8 bytes
- * Bit order: ascending (0-63, left to right)
+- Power Systems SCOM register
- * Power Systems Indirect SCOM register
- * Type value: 0x02
- * Address size: 8 bytes
- * Register size: 8 bytes
- * Bit order: ascending (0-63, left to right)
+ - Type value: 0x01
+ - Address size: 4 bytes
+ - Register size: 8 bytes
+ - Bit order: ascending (0-63, left to right)
+
+- Power Systems Indirect SCOM register
+ - Type value: 0x02
+ - Address size: 8 bytes
+ - Register size: 8 bytes
+ - Bit order: ascending (0-63, left to right)
### 2) Supported Attention Types
| Value | Description |
-|:-----:|:------------------------------------------------------------|
-| 1 | System checkstop hardware attention |
-| 2 | Unit checkstop hardware attention |
-| 3 | Recoverable hardware attention |
-| 4 | SW or HW event requiring action by the service processor FW |
-| 5 | SW or HW event requiring action by the host FW |
+| :---: | :---------------------------------------------------------- |
+| 1 | System checkstop hardware attention |
+| 2 | Unit checkstop hardware attention |
+| 3 | Recoverable hardware attention |
+| 4 | SW or HW event requiring action by the service processor FW |
+| 5 | SW or HW event requiring action by the host FW |
### 3) Expressions
@@ -256,10 +258,10 @@
The following is the complete byte definition of the expression:
| Bytes | Description/Value |
-|:-----:|:------------------------------------------------------|
-| 1 | expression type = 0x01 |
-| 3 | register ID, see section 2 for register details |
-| 1 | register instance, see section 2 for register details |
+| :---: | :---------------------------------------------------- |
+| 1 | expression type = 0x01 |
+| 3 | register ID, see section 2 for register details |
+| 1 | register instance, see section 2 for register details |
As you can see, the register ID and instance can be used to find this register's
metadata (e.g. the address) from the register lists (see section 2).
@@ -271,9 +273,9 @@
The following is the complete byte definition of the expression:
| Bytes | Description/Value |
-|:-----:|:--------------------------------------------------|
-| 1 | expression type = 0x02 |
-| * | An unsigned integer constant (**see note below**) |
+| :---: | :------------------------------------------------ |
+| 1 | expression type = 0x02 |
+| \* | An unsigned integer constant (**see note below**) |
**IMPORTANT:** The size of the constant is determined by the register type
specified by the containing node. See section 3 for node details.
@@ -299,47 +301,46 @@
A bitwise AND operation (i.e. `EXPR_1 & EXPR_2`).
| Bytes | Description/Value |
-|:-----:|:-----------------------|
-| 1 | expression type = 0x10 |
-| 1 | # of sub-expressions |
-| * | all sub-expressions |
+| :---: | :--------------------- |
+| 1 | expression type = 0x10 |
+| 1 | # of sub-expressions |
+| \* | all sub-expressions |
##### 3.2.2) OR expression
A bitwise OR operation (i.e. `EXPR_1 | EXPR_2`).
| Bytes | Description/Value |
-|:-----:|:-----------------------|
-| 1 | expression type = 0x11 |
-| 1 | # of sub-expressions |
-| * | all sub-expressions |
+| :---: | :--------------------- |
+| 1 | expression type = 0x11 |
+| 1 | # of sub-expressions |
+| \* | all sub-expressions |
##### 3.2.3) NOT expression
A bitwise NOT operation (i.e. `~EXPR`).
| Bytes | Description/Value |
-|:-----:|:-----------------------|
-| 1 | expression type = 0x12 |
-| * | sub-expression |
+| :---: | :--------------------- |
+| 1 | expression type = 0x12 |
+| \* | sub-expression |
##### 3.2.4) Left shift expression
A left shift operation (i.e. `EXPR << shift_value`).
| Bytes | Description/Value |
-|:-----:|:-----------------------|
-| 1 | expression type = 0x13 |
-| 1 | shift value |
-| * | sub-expression |
+| :---: | :--------------------- |
+| 1 | expression type = 0x13 |
+| 1 | shift value |
+| \* | sub-expression |
##### 3.2.5) Right shift expression
A left shift operation (i.e. `EXPR >> shift_value`).
| Bytes | Description/Value |
-|:-----:|:-----------------------|
-| 1 | expression type = 0x14 |
-| 1 | shift value |
-| * | sub-expression |
-
+| :---: | :--------------------- |
+| 1 | expression type = 0x14 |
+| 1 | shift value |
+| \* | sub-expression |
diff --git a/xml/chip_data_xml.md b/xml/chip_data_xml.md
index 5052056..a82043d 100644
--- a/xml/chip_data_xml.md
+++ b/xml/chip_data_xml.md
@@ -2,11 +2,12 @@
The machine readable Chip Data XML files are used to generate the Chip Data
Binary files that are consumed directly by the Hardware Error Isolator (simply
-referred to as 'the isolator'). Details of the isolator and the
-[Chip Data Binary][] format and requirements can be found in the
+referred to as 'the isolator'). Details of the isolator and the [Chip Data
+Binary][] format and requirements can be found in the
[openbmc/openpower-libhei][] project.
-[Chip Data Binary]: https://github.com/openbmc/openpower-libhei/blob/master/src/chip_data/CHIP_DATA.md
+[chip data binary]:
+ https://github.com/openbmc/openpower-libhei/blob/master/src/chip_data/CHIP_DATA.md
[openbmc/openpower-libhei]: https://github.com/openbmc/openpower-libhei
## 1) Chip Files - Root Element: `<chip>`
@@ -49,20 +50,19 @@
The data described by the XML in these files represents attention isolation
trees. Each tree node will contain:
- * A list of registers related to this node (FIRs, masks, config regs, etc.).
+- A list of registers related to this node (FIRs, masks, config regs, etc.).
- * A list of registers to store in logs for additional debug, if necessary.
+- A list of registers to store in logs for additional debug, if necessary.
- * A set of rules describing registers and bit operations required to determine
- if there are active attentions for supported attention types.
+- A set of rules describing registers and bit operations required to determine
+ if there are active attentions for supported attention types.
- * A bit definition indicating if an active attention has been found or if it
- originated from another node.
+- A bit definition indicating if an active attention has been found or if it
+ originated from another node.
-**Important Note:**
-A node typically represents a Fault Isolation Register (FIR). However, other
-hardware registers, like `c_err_rpt` registers, or a combination of registers
-could be used as well.
+**Important Note:** A node typically represents a Fault Isolation Register
+(FIR). However, other hardware registers, like `c_err_rpt` registers, or a
+combination of registers could be used as well.
For readability and maintainability, the data for each node will be stored in
separate XML files.
@@ -89,17 +89,18 @@
defined for this node and the order of the bit `pos` attribute (left to right
vs. right to left). Supported types:
- * POWER Systems SCOM register
- * Attribute value: SCOM
- * Address length: 4 bytes
- * Register length: 8 bytes
- * Bit order: ascending (0-63, left to right)
+- POWER Systems SCOM register
- * POWER Systems Indirect SCOM register
- * Attribute value: IDSCOM
- * Address length: 8 bytes
- * Register length: 8 bytes
- * Bit order: ascending (0-63, left to right)
+ - Attribute value: SCOM
+ - Address length: 4 bytes
+ - Register length: 8 bytes
+ - Bit order: ascending (0-63, left to right)
+
+- POWER Systems Indirect SCOM register
+ - Attribute value: IDSCOM
+ - Address length: 8 bytes
+ - Register length: 8 bytes
+ - Bit order: ascending (0-63, left to right)
### 2.4) Element `<register>` (conditionally optional)
@@ -118,21 +119,21 @@
The hardware operation accessibility. Supported values:
-| Value | Description |
-|--------|----------------------------------------------------------------|
-| RO | read-only access |
-| WO | write-only access |
-| RW | read and write access (default when 'access' is not specified) |
+| Value | Description |
+| ----- | -------------------------------------------------------------- |
+| RO | read-only access |
+| WO | write-only access |
+| RW | read and write access (default when 'access' is not specified) |
#### 2.4.3) Element `<instance>` (required)
-It is possible that a register could have multiple instances within a
-chip. For example, the same register could exist for each core on a processor
-chip. Generally, the isolation rules and bit definition for registers like these
-are the same for each instance. The only difference would be the register
-addresses associated with each instance. So, instead of repeating the same
-information in multiple files, there will be an `<instance>` element for each
-unique instance of the register.
+It is possible that a register could have multiple instances within a chip. For
+example, the same register could exist for each core on a processor chip.
+Generally, the isolation rules and bit definition for registers like these are
+the same for each instance. The only difference would be the register addresses
+associated with each instance. So, instead of repeating the same information in
+multiple files, there will be an `<instance>` element for each unique instance
+of the register.
##### 2.4.3.1) Attribute `reg_inst` (required)
@@ -153,16 +154,16 @@
This may seem redundant because in most cases the `<register>` elements will
align exactly with this list. However, consider a special case:
- * There is a set of FIR bits that represent a unit within a chip.
- * That same set exists for each instance of that chip unit.
- * To save space in the hardware, a particular FIR may contain a set for more
- than one chip unit.
- * For example, sixteen bits per set and four sets per FIR could represent
- eight units in just two FIRs).
+- There is a set of FIR bits that represent a unit within a chip.
+- That same set exists for each instance of that chip unit.
+- To save space in the hardware, a particular FIR may contain a set for more
+ than one chip unit.
+- For example, sixteen bits per set and four sets per FIR could represent eight
+ units in just two FIRs).
-Therefore, if we set up the bit definition and rules for a node to represent
-the hardware units instead of the FIRs, the register instances will not match
-the node instances.
+Therefore, if we set up the bit definition and rules for a node to represent the
+hardware units instead of the FIRs, the register instances will not match the
+node instances.
#### 2.5.1) Attribute `node_inst` (required)
@@ -182,12 +183,11 @@
See the `reg_inst` attribute for each `<instance>` of `<register>`.
-**Important Note:**
-This value is interpreted as an array, where the index is the instance value of
-the `node_inst` attribute of the `<capture_group>` element. Therefore, this
-requires the number of instances represented by this attribute to equal the
-number of instances represented by the the `node_inst` attribute of the
-`<capture_group>` element.
+**Important Note:** This value is interpreted as an array, where the index is
+the instance value of the `node_inst` attribute of the `<capture_group>`
+element. Therefore, this requires the number of instances represented by this
+attribute to equal the number of instances represented by the the `node_inst`
+attribute of the `<capture_group>` element.
### 2.6) Element `<rule>` (conditionally optional)
@@ -238,33 +238,35 @@
Each `<expr>` will have an expression type. Supported types are:
| `type` | Description | Sub-elements | `value1` | `value2` |
-|--------|--------------------|:------------:|---------------|--------------|
+| ------ | ------------------ | :----------: | ------------- | ------------ |
| reg | register reference | | reg name | reg instance |
| int | integer constant | | integer value | |
-| and | bitwise AND | 2 or more | | |
-| or | bitwise OR | 2 or more | | |
-| not | bitwise NOT | 1 | | |
-| lshift | left shift | 1 | shift value | |
-| rshift | right shift | 1 | shift value | |
+| and | bitwise AND | 2 or more | | |
+| or | bitwise OR | 2 or more | | |
+| not | bitwise NOT | 1 | | |
+| lshift | left shift | 1 | shift value | |
+| rshift | right shift | 1 | shift value | |
Table notes:
- * Some types require the sub-elements or `value1`/`value2` attributes, but they
- are only required if explicitly stated in the table above.
- * Sub-elements are expressions and will be resolved before handling the
- containing expression.
+
+- Some types require the sub-elements or `value1`/`value2` attributes, but they
+ are only required if explicitly stated in the table above.
+- Sub-elements are expressions and will be resolved before handling the
+ containing expression.
Expression type notes:
- * A register reference is a special expression that indicates the contents of
- the target register should be used for this expression. Generally, this means
- reading the register value from hardware. The `value1` attribute is required
- for this expression type and will indicate the name of the target register.
- The `value2` attribute is optional and indicates the target register
- instance. If omitted, the register instance will match the node instance(s)
- represented by this rule.
- * An integer constant is simply a right-justified, unsigned integer. The
- `value1` attribute for this expression type will contain the integer value.
- The length of the number is defined by the `reg_type` attribute of the root
- `<attn_node>` element.
+
+- A register reference is a special expression that indicates the contents of
+ the target register should be used for this expression. Generally, this means
+ reading the register value from hardware. The `value1` attribute is required
+ for this expression type and will indicate the name of the target register.
+ The `value2` attribute is optional and indicates the target register instance.
+ If omitted, the register instance will match the node instance(s) represented
+ by this rule.
+- An integer constant is simply a right-justified, unsigned integer. The
+ `value1` attribute for this expression type will contain the integer value.
+ The length of the number is defined by the `reg_type` attribute of the root
+ `<attn_node>` element.
### 2.7) Element `<bit>` (conditionally optional)
@@ -284,9 +286,9 @@
#### 2.7.2) Attribute `child_node` (optional)
If this attribute exists, it means the event that raised the attention in this
-bit originated from another node. The value of this attribute is the name of
-the child node, which can be found in the `name` attribute of the `<attn_node>`
-root element.
+bit originated from another node. The value of this attribute is the name of the
+child node, which can be found in the `name` attribute of the `<attn_node>` root
+element.
#### 2.7.3) Attribute `node_inst` (optional)
@@ -294,11 +296,10 @@
`child_node` is specified. Also, if `child_node` is specified and this attribute
is omitted, the default value of 0 is used.
-**Important Note:**
-This value is actually interpreted as an array where the index is the instance
-value of the current node. Therefore, this requires the number of instances
-represented by this attribute to equal the number of instances represented by
-the current node.
+**Important Note:** This value is actually interpreted as an array where the
+index is the instance value of the current node. Therefore, this requires the
+number of instances represented by this attribute to equal the number of
+instances represented by the current node.
A list and/or range value (see appendix) may be used to represent the attribute
value. For example, say we have a node with four possible instances and a bit
@@ -323,9 +324,10 @@
Some chips have a lot of local FIR registers, especially POWER processor chips,
and nearly all of these FIRs follow the same pattern where:
- * The MASK, ACTION, WOF, etc. register are on the same address offset from the
- FIR address.
- * Attention rules are defined by the associated MASK and ACTION registers.
+
+- The MASK, ACTION, WOF, etc. register are on the same address offset from the
+ FIR address.
+- Attention rules are defined by the associated MASK and ACTION registers.
Therefore, this special `<local_fir>` element is simply provided as shorthand
for these common patterns. Under the covers it will generate the required
@@ -341,7 +343,7 @@
of these registers exist, use the following values:
| Value | Description |
-|-------|-------------------------------------|
+| ----- | ----------------------------------- |
| | neither WOF nor ACT2 registers |
| W | include WOF register |
| 2 | include ACT2 register |
@@ -355,14 +357,14 @@
Under the covers, the following registers will be generated (see the `config`
attribute for details on the WOF and ACT2 registers):
-| name | addr | access |
-|-----------------|--------|--------|
-| `name` | addr+0 | RW |
-| `name_MASK` | addr+3 | RW |
-| `name_ACT0` | addr+6 | RW |
-| `name_ACT1` | addr+7 | RW |
-| `name_WOF` | addr+8 | RW |
-| `name_ACT2` | addr+9 | RW |
+| name | addr | access |
+| ----------- | ------ | ------ |
+| `name` | addr+0 | RW |
+| `name_MASK` | addr+3 | RW |
+| `name_ACT0` | addr+6 | RW |
+| `name_ACT1` | addr+7 | RW |
+| `name_WOF` | addr+8 | RW |
+| `name_ACT2` | addr+9 | RW |
#### 2.8.4) Element `<action>` (required 1 or more)
@@ -379,19 +381,19 @@
this attribute:
| Value | Rule |
-|-------|-------------------------------------|
+| ----- | ----------------------------------- |
| 00 | FIR & ~MASK & ~ACT0 & ~ACT1 |
-| 01 | FIR & ~MASK & ~ACT0 & ACT1 |
-| 10 | FIR & ~MASK & ACT0 & ~ACT1 |
-| 11 | FIR & ~MASK & ACT0 & ACT1 |
+| 01 | FIR & ~MASK & ~ACT0 & ACT1 |
+| 10 | FIR & ~MASK & ACT0 & ~ACT1 |
+| 11 | FIR & ~MASK & ACT0 & ACT1 |
| 000 | FIR & ~MASK & ~ACT0 & ~ACT1 & ~ACT2 |
-| 001 | FIR & ~MASK & ~ACT0 & ~ACT1 & ACT2 |
-| 010 | FIR & ~MASK & ~ACT0 & ACT1 & ~ACT2 |
-| 011 | FIR & ~MASK & ~ACT0 & ACT1 & ACT2 |
-| 100 | FIR & ~MASK & ACT0 & ~ACT1 & ~ACT2 |
-| 101 | FIR & ~MASK & ACT0 & ~ACT1 & ACT2 |
-| 110 | FIR & ~MASK & ACT0 & ACT1 & ~ACT2 |
-| 111 | FIR & ~MASK & ACT0 & ACT1 & ACT2 |
+| 001 | FIR & ~MASK & ~ACT0 & ~ACT1 & ACT2 |
+| 010 | FIR & ~MASK & ~ACT0 & ACT1 & ~ACT2 |
+| 011 | FIR & ~MASK & ~ACT0 & ACT1 & ACT2 |
+| 100 | FIR & ~MASK & ACT0 & ~ACT1 & ~ACT2 |
+| 101 | FIR & ~MASK & ACT0 & ~ACT1 & ACT2 |
+| 110 | FIR & ~MASK & ACT0 & ACT1 & ~ACT2 |
+| 111 | FIR & ~MASK & ACT0 & ACT1 & ACT2 |
## 3) Appendix
@@ -402,11 +404,11 @@
### 3.2) Number Lists and Ranges
- * Lists are expressed by a comma separated list (e.g. "0,2,4,6,8").
- * Ranges represent consecutive ascending or descending numbers (including both
- endpoints) and are expressed using a colon (e.g. "8:15" or "15:8").
- * Lists and ranges can be combined. For example, a value of "0,2:4,6" expands
- to 0, 2, 3, 4, and 6.
+- Lists are expressed by a comma separated list (e.g. "0,2,4,6,8").
+- Ranges represent consecutive ascending or descending numbers (including both
+ endpoints) and are expressed using a colon (e.g. "8:15" or "15:8").
+- Lists and ranges can be combined. For example, a value of "0,2:4,6" expands to
+ 0, 2, 3, 4, and 6.
### 3.3) Notice Regarding `model_ec` Attributes
@@ -421,7 +423,7 @@
are:
| Value | Description |
-|---------------|----------------------|
+| ------------- | -------------------- |
| `EXPLORER_11` | Explorer chip EC 1.1 |
| `EXPLORER_20` | Explorer chip EC 2.0 |
| `P10_10` | P10 chip EC 1.0 |
@@ -429,11 +431,10 @@
### 3.4) Supported Attention Types
-| Value | Description |
-|-------|----------------------------------------------------------------------|
-| CS | System checkstop hardware attention. |
-| UCS | Unit checkstop hardware attention. |
-| RE | Recoverable hardware attention. |
-| SPA | SW or HW event requiring action by the service processor firmware. |
-| HA | SW or HW event requiring action by the host firmware. |
-
+| Value | Description |
+| ----- | ------------------------------------------------------------------ |
+| CS | System checkstop hardware attention. |
+| UCS | Unit checkstop hardware attention. |
+| RE | Recoverable hardware attention. |
+| SPA | SW or HW event requiring action by the service processor firmware. |
+| HA | SW or HW event requiring action by the host firmware. |
diff --git a/xml/setup.py b/xml/setup.py
index 15b6496..74e91c9 100644
--- a/xml/setup.py
+++ b/xml/setup.py
@@ -1,35 +1,34 @@
+import os
+import subprocess
from setuptools import setup
from setuptools.command.build_py import build_py
-import os
-import subprocess
-
# Typically in files like this we'd use find_packages() to traverse directories
# for any static packages. However, we are trying to add data to a package that
# will actually exist in another repository. Therefore, we have to explicitly
# list out the package name, directory, and data information.
# We are building data for the following module:
-package_name = 'pel.hwdiags'
+package_name = "pel.hwdiags"
# Since we are not using find_packages() we have to provide a package directory,
# but in this case nothing exists because there are no static package
# directories. Therefore, we will just use the empty string.
-package_dir = ''
+package_dir = ""
# Split the package data directory into its components.
-data_dir_components = [ *package_name.split('.'), 'data' ]
+data_dir_components = [*package_name.split("."), "data"]
# It is important to note that '/' must be used as the path separator, even on
# Windows. Setuptools will automatically convert the slashes where appropriate.
-package_data_glob = '/'.join( data_dir_components )
+package_data_glob = "/".join(data_dir_components)
+
# This is a custom build class that is used to dynamically build the data files.
class my_build_py(build_py):
def run(self):
- if not self.dry_run: # honor --dry-run flag
-
+ if not self.dry_run: # honor --dry-run flag
# Make sure the build directory for the data exists.
# Yes, os.path.join() is necessary in this case, which is different
# that what is stated above regarding package_data_glob.
@@ -42,20 +41,29 @@
# module.
# TODO: The list of data file directories will need to be
# configurable via the package config in the bitbake recipes.
- for chip in ('p10', 'explorer'):
- subprocess.run([ './parse_chip_data_xml', '--json',
- '-i', chip, '-o', data_dir ], check=True)
+ for chip in ("p10", "explorer"):
+ subprocess.run(
+ [
+ "./parse_chip_data_xml",
+ "--json",
+ "-i",
+ chip,
+ "-o",
+ data_dir,
+ ],
+ check=True,
+ )
# Call the superclass run() to ensure everything else builds.
super().run()
setup(
- name = 'openpower-hw-diags-pel-parser-data',
- version = os.getenv('PELTOOL_VERSION', '1.0'),
- classifiers = [ 'License :: OSI Approved :: Apache Software License' ],
- cmdclass = { 'build_py': my_build_py }, # register custom build class
- packages = [ package_name ],
- package_dir = { package_name: package_dir },
- package_data = { package_name: [ package_data_glob ] },
+ name="openpower-hw-diags-pel-parser-data",
+ version=os.getenv("PELTOOL_VERSION", "1.0"),
+ classifiers=["License :: OSI Approved :: Apache Software License"],
+ cmdclass={"build_py": my_build_py}, # register custom build class
+ packages=[package_name],
+ package_dir={package_name: package_dir},
+ package_data={package_name: [package_data_glob]},
)