prettier: re-format
Change-Id: I6b22ad83c41e53484812f83ea70e7ce6d9c299cd
Signed-off-by: Zane Shelley <zshelle@us.ibm.com>
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]},
)