format: reformat with latest openbmc-build-scripts
Run all the latest formatters from openbmc-build-scripts. Disable
prettier on the configurations subdirectory because these are
script-formatted already with the repo-local `format-code` extension.
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Change-Id: Ifa4f2ec6688d60fde2a5f42efc96b6046e9be642
diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000..6a9364a
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1 @@
+configurations/*
diff --git a/CONFIG_FORMAT.md b/CONFIG_FORMAT.md
index 6879afa..3d69191 100644
--- a/CONFIG_FORMAT.md
+++ b/CONFIG_FORMAT.md
@@ -3,71 +3,74 @@
## Intent
Configuration files are intended to represent the minimum amount of
-configuration required to describe a given piece of hardware. As such, they are
+configuration required to describe a given piece of hardware. As such, they are
intended to be simple, and are guided by the following principles.
-1. Configuration files should be easy to write. If a tradeoff is to be made
+1. Configuration files should be easy to write. If a tradeoff is to be made
between a config file being complex to write, and a reactor being complex to
- write, the reactor will be the one to hold the complexity. Why?
- - Configuration files will get replicated and built to support hundreds of
- systems over time, and scale linearly with the number of systems. In
- contrast, reactors tend to scale as a logarithm of system count, with each
- new system supported adding fewer and fewer reactors. As such, pushing
- the complexity to the reactors leads to fewer lines of code overall, even
- if the reactor itself contains more complex actions.
- - Reactor writers tend to be domain experts on their subsystem, and
- intimately understand the constraints that are emplaced on that subsystem.
- Config file writers are generally building support for a wide range of
- reactors on a single piece of hardware, and will generally have less
- knowledge of each individual reactors constraints.
+ write, the reactor will be the one to hold the complexity. Why?
-2. Configuration files should trend toward one config file per physical piece
- of hardware, and should avoid attempting to support multiple variations of a
+ - Configuration files will get replicated and built to support hundreds of
+ systems over time, and scale linearly with the number of systems. In
+ contrast, reactors tend to scale as a logarithm of system count, with each
+ new system supported adding fewer and fewer reactors. As such, pushing the
+ complexity to the reactors leads to fewer lines of code overall, even if
+ the reactor itself contains more complex actions.
+ - Reactor writers tend to be domain experts on their subsystem, and
+ intimately understand the constraints that are emplaced on that subsystem.
+ Config file writers are generally building support for a wide range of
+ reactors on a single piece of hardware, and will generally have less
+ knowledge of each individual reactors constraints.
+
+2. Configuration files should trend toward one config file per physical piece of
+ hardware, and should avoid attempting to support multiple variations of a
given piece of hardware in a single file, even at the risk of duplicating
- information. Why?
- - Hardware constraints, bugs, and oddities are generally found over time.
- The initial commit of a configuration file is far from the final time that
- changes will be submitted. Having each individual piece of hardware in
- its own file minimizes the change needed between different components when
- bugs are found, or features are added.
- - Having separate config files reduces the number of platforms that need to
- be tested for any given config file change, thus limiting the "blast
- radius" of particular kinds of changes, as well as making an explicit log
- of what changed for a specific platform.
- - Having one config file per piece of hardware makes it much easier and
- clear for a user to determine if a piece of hardware is supported.
- - Note: This is a "guideline" not a "rule". There are many cases of
- hardware that despite having different part numbers, are actually
- physically identical, and as such, the config files will never differ.
- - Example: SAS modules and cards made by the same company, on the same
- process, and branded with different manufacturers and part numbers.
- - Non-Example: Power supplies. While all pmbus power supplies appear
- similar, there tend to be significant differences in featuresets,
- bugs, and OEM supported firmware features. As such, they require
- separate config files.
+ information. Why?
-3. Configuration files are not a long-term stable ABI. Why?
- - Configuration files occasionally need to modify their schema in pursuit of
- simplicity, or based on a greater understanding of the system level
- constraints.
- - The repo will ensure that all schema changes are enacted such that the
- files in the repo will not be broken as a result of the schema change, and
- will be carried forward. The recommended way to avoid merge problems is
- to upstream your configurations.
- - Note: This drives the requirement that config files shall not be checked
- into OpenBMC meta layers.
+ - Hardware constraints, bugs, and oddities are generally found over time. The
+ initial commit of a configuration file is far from the final time that
+ changes will be submitted. Having each individual piece of hardware in its
+ own file minimizes the change needed between different components when bugs
+ are found, or features are added.
+ - Having separate config files reduces the number of platforms that need to
+ be tested for any given config file change, thus limiting the "blast
+ radius" of particular kinds of changes, as well as making an explicit log
+ of what changed for a specific platform.
+ - Having one config file per piece of hardware makes it much easier and clear
+ for a user to determine if a piece of hardware is supported.
+ - Note: This is a "guideline" not a "rule". There are many cases of hardware
+ that despite having different part numbers, are actually physically
+ identical, and as such, the config files will never differ.
+ - Example: SAS modules and cards made by the same company, on the same
+ process, and branded with different manufacturers and part numbers.
+ - Non-Example: Power supplies. While all pmbus power supplies appear
+ similar, there tend to be significant differences in featuresets, bugs,
+ and OEM supported firmware features. As such, they require separate
+ config files.
+
+3. Configuration files are not a long-term stable ABI. Why?
+
+ - Configuration files occasionally need to modify their schema in pursuit of
+ simplicity, or based on a greater understanding of the system level
+ constraints.
+ - The repo will ensure that all schema changes are enacted such that the
+ files in the repo will not be broken as a result of the schema change, and
+ will be carried forward. The recommended way to avoid merge problems is to
+ upstream your configurations.
+ - Note: This drives the requirement that config files shall not be checked
+ into OpenBMC meta layers.
4. Configurations should represent only the things that are _different_ and
- undetectable between platforms. Why?
- - There are many behaviors that the BMC has that are very easily detected
- at runtime, or where the behavior can be identical between different
- platforms. Things like timeouts, protocol versions, and communcation
- channels can generally be represented with a default that works for all
- platforms, and doesn't need to be an entity-configurable parameter. In
- general, reducing the config files to _only_ the differences reduces
- complexity, and explicitly bounds where dicsussion is needed for platform
- differences, and where a difference is "supported" and "reasonable" to
- maintain in the long run.
+ undetectable between platforms. Why?
+ - There are many behaviors that the BMC has that are very easily detected at
+ runtime, or where the behavior can be identical between different
+ platforms. Things like timeouts, protocol versions, and communcation
+ channels can generally be represented with a default that works for all
+ platforms, and doesn't need to be an entity-configurable parameter. In
+ general, reducing the config files to _only_ the differences reduces
+ complexity, and explicitly bounds where dicsussion is needed for platform
+ differences, and where a difference is "supported" and "reasonable" to
+ maintain in the long run.
## Configuration Syntax
@@ -77,28 +80,28 @@
hardware modules into a single file if desired, it is recommended to divide them
into multiple configuration files. For example, there may be a baseboard JSON
file (describes all devices on the baseboard) and a chassis JSON file (describes
-devices attached to the chassis). Other examples of entities might be
-removable power supplies, fans, and PCIe add in cards.
+devices attached to the chassis). Other examples of entities might be removable
+power supplies, fans, and PCIe add in cards.
Within a configuration file, there is a JSON object which consists of multiple
"string : value" pairs. This Entity Manager defines the following strings.
-| String | Example Value | Description |
-| :-------- | ---------------------------------------- | ---------------------------------------- |
-| "Name" | "X1000 1U Chassis" | Human readable name used for identification and sorting. |
-| "Probe" | "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME':'FFPANEL'})" | Statement which attempts to read from d-bus. The result determines if a configuration record should be applied. The value for probe can be set to “TRUE” in the case the record should always be applied, or set to more complex lookups, for instance a field in a FRU file that is exposed by the frudevice |
-| "Exposes" | [{"Name" : "CPU fan"}, ...] | An array of JSON objects which are valid if the probe result is successful. These objects describe the devices BMC can interact. |
-| "Status" | "disabled" | An indicator that allows for some records to be disabled by default. |
-| "Bind*" | "2U System Fan connector 1" | The record isn't complete and needs to be combined with another to be functional. The value is a unique reference to a record elsewhere. |
-| "DisableNode"| "Fan 1" | Sets the status of another Entity to disabled. |
+| String | Example Value | Description |
+| :------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "Name" | "X1000 1U Chassis" | Human readable name used for identification and sorting. |
+| "Probe" | "xyz.openbmc_project.FruDevice({'BOARD_PRODUCT_NAME':'FFPANEL'})" | Statement which attempts to read from d-bus. The result determines if a configuration record should be applied. The value for probe can be set to “TRUE” in the case the record should always be applied, or set to more complex lookups, for instance a field in a FRU file that is exposed by the frudevice |
+| "Exposes" | [{"Name" : "CPU fan"}, ...] | An array of JSON objects which are valid if the probe result is successful. These objects describe the devices BMC can interact. |
+| "Status" | "disabled" | An indicator that allows for some records to be disabled by default. |
+| "Bind\*" | "2U System Fan connector 1" | The record isn't complete and needs to be combined with another to be functional. The value is a unique reference to a record elsewhere. |
+| "DisableNode" | "Fan 1" | Sets the status of another Entity to disabled. |
Template strings in the form of "$identifier" may be used in configuration
files. The following table describes the template strings currently defined.
-| Template String | Description |
-| :-------------- | :--------------------------------------- |
-| "$bus" | During a I2C bus scan and when the "probe" command is successful, this template string is substituted with the bus number to which the device is connected. |
-| "$address" | When the "probe" is successful, this template string is substituted with the (7-bit) I2C address of the FRU device. |
+| Template String | Description |
+| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "$bus" | During a I2C bus scan and when the "probe" command is successful, this template string is substituted with the bus number to which the device is connected. |
+| "$address" | When the "probe" is successful, this template string is substituted with the (7-bit) I2C address of the FRU device. |
| "$index" | A run-tim enumeration. This template string is substituted with a unique index value when the "probe" command is successful. This allows multiple identical devices (e.g., HSBPs) to exist in a system but each with a unique name. |
## Configuration HowTos
@@ -212,7 +215,6 @@
[Full Configuration](https://github.com/openbmc/entity-manager/blob/master/configurations/WFT_Baseboard.json)
-
#### Configuration Records - Chassis Example
Although fan connectors are considered a part of a baseboard, the physical fans
@@ -257,4 +259,3 @@
The entity-manager can key off of different types and export devices for
specific configurations. Once this is done, the baseboard temperature sensor
daemon can scan the sensors.
-
diff --git a/README.md b/README.md
index ac331b1..e918497 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,18 @@
# Entity Manager
Entity manager is a design for managing physical system components, and mapping
-them to software resources within the BMC. Said resources are designed to allow
+them to software resources within the BMC. Said resources are designed to allow
the flexible adjustment of the system at runtime, as well as the reduction in
the number of independent system configurations one needs to create.
## Definitions
### Entity
+
A server component that is physically separate, detectable through some means,
-and can be added or removed from a given OpenBMC system. Said component can,
-and likely does contain multiple sub-components, but the component itself as a
-whole is referred to as an entity.
+and can be added or removed from a given OpenBMC system. Said component can, and
+likely does contain multiple sub-components, but the component itself as a whole
+is referred to as an entity.
Note, this term is needed because most other terms that could've been used
(Component, Field Replaceable Unit, or Assembly) are already overloaded in the
@@ -19,16 +20,18 @@
entity encompasses.
### Exposes
-A particular feature of an Entity. An Entity generally will have multiple
-Exposes records for the various features that component supports. Some examples
+
+A particular feature of an Entity. An Entity generally will have multiple
+Exposes records for the various features that component supports. Some examples
of features include, LM75 sensors, PID control parameters, or CPU information.
### Probe
-A set of rules for detecting a given entity. Said rules generally take the form
+
+A set of rules for detecting a given entity. Said rules generally take the form
of a D-Bus interface definition.
-
## Goals
+
Entity manager has the following goals (unless you can think of better ones):
1. Minimize the time and debugging required to "port" OpenBMC to new systems
@@ -38,18 +41,18 @@
physically possible.
## Implementation
+
A full BMC setup using Entity Manager consists of a few parts:
-1. **A detection daemon** This is something that can be used to detect
- components at runtime. The most common of these, fru-device, is included in
+1. **A detection daemon** This is something that can be used to detect
+ components at runtime. The most common of these, fru-device, is included in
the Entity-Manager repo, and scans all available I2C buses for IPMI FRU
- EEPROM devices. Other examples of detection daemons include:
- **[peci-pcie](https://github.com/openbmc/peci-pcie):**
- A daemon that utilizes the CPU bus to read in a list of PCIe devices from
- the processor.
- **[smbios-mdr](https://github.com/openbmc/smbios-mdr):**
- A daemon that utilizes the x86 SMBIOS table specification to detect the
- available systems dependencies from BIOS.
+ EEPROM devices. Other examples of detection daemons include:
+ **[peci-pcie](https://github.com/openbmc/peci-pcie):** A daemon that utilizes
+ the CPU bus to read in a list of PCIe devices from the processor.
+ **[smbios-mdr](https://github.com/openbmc/smbios-mdr):** A daemon that
+ utilizes the x86 SMBIOS table specification to detect the available systems
+ dependencies from BIOS.
In many cases, the existing detection daemons are sufficient for a single
system, but in cases where there is a superseding inventory control system in
@@ -59,71 +62,73 @@
more readily, and system configurations can be "verified" rather than
detected.
-2. **An entity manager configuration file** Entity manager configuration files
+2. **An entity manager configuration file** Entity manager configuration files
are located in the ./configurations directory in the entity manager
- repository, and include one file per device supported. Entities are
- detected based on the "Probe" key in the json file. The intention is that
- this folder contains all hardware configurations that OpenBMC supports, to
- allows an easy answer to "Is X device supported". An EM configuration
- contains a number of Exposes records that specify the specific features that
- this Entity supports. Once a component is detected, entity manager will
- publish these Exposes records to D-Bus.
+ repository, and include one file per device supported. Entities are detected
+ based on the "Probe" key in the json file. The intention is that this folder
+ contains all hardware configurations that OpenBMC supports, to allows an easy
+ answer to "Is X device supported". An EM configuration contains a number of
+ Exposes records that specify the specific features that this Entity supports.
+ Once a component is detected, entity manager will publish these Exposes
+ records to D-Bus.
-3. **A reactor** The reactors are things that take the entity manager
+3. **A reactor** The reactors are things that take the entity manager
configurations, and use them to execute and enable the features that they
- describe. One example of this is dbus-sensors, which contains a suite of
+ describe. One example of this is dbus-sensors, which contains a suite of
applications that input the Exposes records for sensor devices, then connect
to the filesystem to create the sensors and scan loops to scan sensors for
- those devices. Other examples of reactors could include: CPU management
+ those devices. Other examples of reactors could include: CPU management
daemons and Hot swap backplane management daemons, or drive daemons.
-**note:** In some cases, a given daemon could be both a detection daemon and a
-reactor when architectures are multi-tiered. An example of this might include a
+**note:** In some cases, a given daemon could be both a detection daemon and a
+reactor when architectures are multi-tiered. An example of this might include a
hot swap backplane daemon, which both reacts to the hot swap being detected, and
also creates detection records of what drives are present.
## Requirements
1. Entity manager shall support the dynamic discovery of hardware at runtime,
- using inventory interfaces. The types of devices include, but are not
- limited to hard drives, hot swap backplanes, baseboards, power supplies,
- CPUs, and PCIe Add-in-cards.
+ using inventory interfaces. The types of devices include, but are not limited
+ to hard drives, hot swap backplanes, baseboards, power supplies, CPUs, and
+ PCIe Add-in-cards.
2. Entity manager shall support the ability to add or remove support for
- particular devices in a given binary image. By default, entity manager will
+ particular devices in a given binary image. By default, entity manager will
support all available and known working devices for all platforms.
-3. Entity manager shall provide data to D-Bus about a particular device such that
- other daemons can create instances of the features being exposed.
+3. Entity manager shall provide data to D-Bus about a particular device such
+ that other daemons can create instances of the features being exposed.
4. Entity manager shall support multiple detection runs, and shall do the
minimal number of changes necessary when new components are detected or no
- longer detected. Some examples of re-detection events might include host
+ longer detected. Some examples of re-detection events might include host
power on, drive plug/unplug, PSU plug/unplug.
5. Entity manager shall have exactly one configuration file per supported device
- model. In some cases this will cause duplicated information between files,
+ model. In some cases this will cause duplicated information between files,
but the ability to list and see all supported device models in a single
place, as well as maintenance when devices do differ in the future is
determined to be more important than duplication of configuration files.
-
### Explicitly out of scope
+
1. Entity manager shall not directly participate in the detection of devices,
and instead will rely on other D-Bus applications to publish interfaces that
can be detected.
2. Entity manager shall not directly participate in management of any specific
- device. This is requirement is intended to intentionally limit the size and
+ device. This is requirement is intended to intentionally limit the size and
feature set of entity manager, to ensure it remains small, and effective to
all users.
### Entity Manager Compatible Software
+
**bmcweb** A webserver implementation that uses the inventory information from
-entity-manager to produce a Redfish compliant REST API.
-**intel-ipmi-oem** An implementation of the IPMI SDR, FRU, and Storage commands
-that utilize Entity Manager as the source of information.
+entity-manager to produce a Redfish compliant REST API. **intel-ipmi-oem** An
+implementation of the IPMI SDR, FRU, and Storage commands that utilize Entity
+Manager as the source of information.
## Additional Documentation
+
1. **[Entity Manager DBus API](https://github.com/openbmc/entity-manager/blob/master/docs/entity_manager_dbus_api.md)**
2. **[My First Sensor Example](https://github.com/openbmc/entity-manager/blob/master/docs/my_first_sensors.md)**
-3. **[Configuration File Schema](https://github.com/openbmc/entity-manager/tree/master/schemas)**
\ No newline at end of file
+3. **[Configuration File Schema](https://github.com/openbmc/entity-manager/tree/master/schemas)**
diff --git a/docs/entity_manager_dbus_api.md b/docs/entity_manager_dbus_api.md
index 0c034d8..0b50e2b 100644
--- a/docs/entity_manager_dbus_api.md
+++ b/docs/entity_manager_dbus_api.md
@@ -10,7 +10,7 @@
### Object Paths:
-#### Entities: /xyz/openbmc_project/Inventory/Item/{Entity Type}/{Entity Name}
+#### Entities: /xyz/openbmc_project/Inventory/Item/{Entity Type}/{Entity Name}
Entities are top level json objects that describe a piece of hardware. They are
groups of configurations with few properties of their own, they are a container
@@ -22,7 +22,7 @@
"global" system configuration. An example would be a TMP75 sensor that is
exposed when the front panel is detected.
-__Example__:
+**Example**:
```
/xyz/openbmc_project/Inventory/Item/Board/Intel_Front_Panel/Front_Panel_Temp
@@ -32,13 +32,14 @@
#### xyz.openbmc_project.{InventoryType}
-See [upstream types](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Inventory/Item)
+See
+[upstream types](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Inventory/Item)
-* BMC
-* Board
-* Chassis
-* CPU
-* ...
+- BMC
+- Board
+- Chassis
+- CPU
+- ...
These types closely align with Redfish types.
@@ -50,7 +51,6 @@
std::string name: name of the inventory item
-
#### xyz.openbmc_project.Configuration
Configuration objects describe components owned by the Entity.
@@ -59,7 +59,7 @@
Properties will contain all non-objects (simple types) exposed by the JSON.
- __Example__:
+**Example**:
```
path: /xyz/openbmc_project/Inventory/Item/Board/Intel_Front_Panel/Front_Panel_Temp
@@ -80,7 +80,7 @@
All members of the dictonary.
-__Example__:
+**Example**:
```
path: /xyz/openbmc_project/Inventory/Item/Board/Intel_Front_Panel/Front_Panel_Temp
@@ -97,11 +97,11 @@
objects may not have more than one level deep of dictionary or list of
dictionary. It is possible to extend in the future to allow nearly infinite
levels deep of dictonary with extending the
-__xyz.openbmc_project.Device.{Object}__ to allow
-__xyz.openbmc_project.Device.{Object}.{SubObject}.{SubObject}__ but that
+**xyz.openbmc_project.Device.{Object}** to allow
+**xyz.openbmc_project.Device.{Object}.{SubObject}.{SubObject}** but that
complexity will be avoided until proven needed.
-__Example__:
+**Example**:
Legal:
diff --git a/docs/my_first_sensors.md b/docs/my_first_sensors.md
index e306748..8e4cfc5 100644
--- a/docs/my_first_sensors.md
+++ b/docs/my_first_sensors.md
@@ -2,12 +2,12 @@
This document is meant to bring you from nothing to using Entity-Manager with
Dbus-Sensors to populate a plug-in card's sensor values on dbus. Once the sensor
-values are on dbus, they can be read via IPMI or Redfish (doing so is beyond
-the scope of this guide).
+values are on dbus, they can be read via IPMI or Redfish (doing so is beyond the
+scope of this guide).
-For the sake of this example, let's pretend there is a PCIe card that exposes
-an 24c02 eeprom and a tmp441 sensor. The PCIe slots are behind an smbus mux on
-the motherboard and are in a device-tree such as this:
+For the sake of this example, let's pretend there is a PCIe card that exposes an
+24c02 eeprom and a tmp441 sensor. The PCIe slots are behind an smbus mux on the
+motherboard and are in a device-tree such as this:
```
aliases {
@@ -53,8 +53,8 @@
```
The first daemon of interest that will run is the FruDevice portion of
-Entity-Manager. The exact layout of a FRU is beyond the scope of this guide,
-but assume the PCIe card's eeprom holds the following information:
+Entity-Manager. The exact layout of a FRU is beyond the scope of this guide, but
+assume the PCIe card's eeprom holds the following information:
```
Product:
@@ -252,5 +252,5 @@
There you are! You now have the two sensors from the two card instances on dbus.
This can be more complex, for instance if your card has a mux you can add it to
-the configuration, which will trigger FruDevice to scan those new buses for
-more devices.
+the configuration, which will trigger FruDevice to scan those new buses for more
+devices.
diff --git a/schemas/README.md b/schemas/README.md
index 15bdf81..5b4ee81 100644
--- a/schemas/README.md
+++ b/schemas/README.md
@@ -1,73 +1,71 @@
-Entity manager configuration file schema
-----------------------------------------
+## Entity manager configuration file schema
Entity manager configuration files are JSON documents and can be validated with
-a JSON schema[1]. This document provides an overview of the general structure
-of an entity manager configuration file.
+a JSON schema[1]. This document provides an overview of the general structure of
+an entity manager configuration file.
An entity manager configuration file consists of one or more entity manager
-configurations. This provides flexibility for system designers - the
+configurations. This provides flexibility for system designers - the
configuration data for an entire platform or set of platforms can be expressed
-in a single file, or can be organized into several smaller files. Thus, the
-top most schema describes a single object or an array of objects.
+in a single file, or can be organized into several smaller files. Thus, the top
+most schema describes a single object or an array of objects.
To remain consistent with the OpenBMC CPP source code file name guidelines,
entity manager configuration file and schema file names must be
lower_snake_case.
-A single entity manager configuration
-----------------------------------------
+## A single entity manager configuration
+
At its core entity manager simply exports objects onto DBus when a specific
-event occurs. As such, an entity manager configuration provides a syntax for
+event occurs. As such, an entity manager configuration provides a syntax for
describing the dbus interfaces to export, the object paths on which to add the
-interfaces and the event that should trigger the export. This is accomplished
+interfaces and the event that should trigger the export. This is accomplished
with four properties.
-Type
-----------------------------------------
-The type property identifies the type of the configuration. When exported,
+## Type
+
+The type property identifies the type of the configuration. When exported,
configuration data will be instantiated as grandchildren of
-/xyz/openbmc_project/inventory/system/<Type>. For a comprehensive list of
+/xyz/openbmc_project/inventory/system/<Type>. For a comprehensive list of
supported types, consult the schema (global.json).
-Name
-----------------------------------------
-The name property identifies the name of the configuration. When exported,
+## Name
+
+The name property identifies the name of the configuration. When exported,
configuration data will be instantiated as children of
-/xyz/openbmc_project/inventory/system/<Type>/<Name>. Additionally, any DBus
+/xyz/openbmc_project/inventory/system/<Type>/<Name>. Additionally, any DBus
interfaces listed in openbmc-dbus.json will be added on
/xyz/openbmc_project/inventory/system/<Type>/<Name>.
-Probe
-----------------------------------------
-The probe property describes the event which will cause entity manager to
-export the configuration to DBus, making it available to other applications.
+## Probe
-Exposes
-----------------------------------------
+The probe property describes the event which will cause entity manager to export
+the configuration to DBus, making it available to other applications.
+
+## Exposes
+
The exposes property describes the configuration data at its most specific
-level. The exposes property is an array of heterogeneous configuration data.
+level. The exposes property is an array of heterogeneous configuration data.
Each exposes element has its own schema which is outlined by the subschemas in
-the schemas directory. Each schema must require a type and name (not to be
+the schemas directory. Each schema must require a type and name (not to be
confused with the Type and Name properties of the parent JSON object) property
since entity manager will construct the Dbus interface name and object path
based on those properties:
/xyz/openbmc_project/inventory/system/Board/RiserCard1/<Name>:
- xyz.openbmc_project.Configuration.<Type>:
- <remaining properties defined by exposes subschema>
+xyz.openbmc_project.Configuration.<Type>:
+<remaining properties defined by exposes subschema>
-Adding new exposes property subschema
-----------------------------------------
+## Adding new exposes property subschema
+
New subschema for the exposes property must be added to the schema directory,
-and then referenced from global.json at /definitions/EMExposesElement. Exposes
-element subschema must require a type and name property (the validator will
-fail otherwise) and should explicitly enumerate all properties and use
-additionalProperties so mistakes can be found
-during validation.
+and then referenced from global.json at /definitions/EMExposesElement. Exposes
+element subschema must require a type and name property (the validator will fail
+otherwise) and should explicitly enumerate all properties and use
+additionalProperties so mistakes can be found during validation.
-Adding new Dbus interfaces
-----------------------------------------
+## Adding new Dbus interfaces
+
To export new interfaces on the configuration parent object e.g.:
/xyz/openbmc_project/inventory/system/Board/RiserCard1 add additional subschema
to openbmc-dbus.json.
diff --git a/schemas/global.json b/schemas/global.json
index 6b6382e..b6100bf 100644
--- a/schemas/global.json
+++ b/schemas/global.json
@@ -38,9 +38,7 @@
"when an element does not define a type property."
],
"not": {
- "required": [
- "Type"
- ]
+ "required": ["Type"]
},
"title": "Missing Type"
},
@@ -50,9 +48,7 @@
"when an element does not define a name property."
],
"not": {
- "required": [
- "Name"
- ]
+ "required": ["Name"]
},
"title": "Missing Name"
}
@@ -88,9 +84,7 @@
}
},
"Logging": {
- "enum": [
- "Off"
- ]
+ "enum": ["Off"]
},
"Name": {
"description": [
@@ -130,12 +124,7 @@
"configurations will be instantiated as children of: ",
"/xyz/openbmc_project/configuration/<Type>"
],
- "enum": [
- "Board",
- "Chassis",
- "NVMe",
- "PowerSupply"
- ]
+ "enum": ["Board", "Chassis", "NVMe", "PowerSupply"]
},
"xyz.openbmc_project.Inventory.Decorator.Asset": {
"$ref": "openbmc-dbus.json#/definitions/xyz/openbmc_project/Inventory/Decorator/Asset"
@@ -159,12 +148,7 @@
"$ref": "openbmc-dbus.json#/definitions/xyz/openbmc_project/Inventory/Item/System"
}
},
- "required": [
- "Exposes",
- "Name",
- "Probe",
- "Type"
- ]
+ "required": ["Exposes", "Name", "Probe", "Type"]
}
},
"title": "Entity Manager Configuration File",
diff --git a/schemas/ibm.json b/schemas/ibm.json
index 84f9cd4..36b4370 100644
--- a/schemas/ibm.json
+++ b/schemas/ibm.json
@@ -17,9 +17,7 @@
"type": "string"
},
"Type": {
- "enum": [
- "IBMCFFPSConnector"
- ]
+ "enum": ["IBMCFFPSConnector"]
},
"I2CBus": {
"description": [
@@ -67,7 +65,6 @@
"The recommended entry format is 'manufacturer,model' where",
"the manufacturer is a string describing the name of the",
"manufacturer and model specifies the model number."
-
],
"type": "object",
"properties": {
@@ -75,9 +72,7 @@
"type": "string"
},
"Type": {
- "enum": [
- "IBMCompatibleSystem"
- ]
+ "enum": ["IBMCompatibleSystem"]
},
"Names": {
"type": "array",
@@ -92,11 +87,7 @@
}
}
},
- "required": [
- "Name",
- "Type",
- "Names"
- ]
+ "required": ["Name", "Type", "Names"]
}
}
}
diff --git a/schemas/intel.json b/schemas/intel.json
index 193fc18..fe4c7e7 100644
--- a/schemas/intel.json
+++ b/schemas/intel.json
@@ -19,18 +19,10 @@
"type": "array"
},
"Type": {
- "enum": [
- "IntelFanConnector"
- ]
+ "enum": ["IntelFanConnector"]
}
},
- "required": [
- "Name",
- "Type",
- "Status",
- "Pwm",
- "Tachs"
- ],
+ "required": ["Name", "Type", "Status", "Pwm", "Tachs"],
"type": "object"
}
}
diff --git a/schemas/legacy.json b/schemas/legacy.json
index 47a6c7b..cabfe5c 100644
--- a/schemas/legacy.json
+++ b/schemas/legacy.json
@@ -388,18 +388,12 @@
"$ref": "#/definitions/Types/Type"
}
},
- "required": [
- "Name",
- "Type"
- ],
+ "required": ["Name", "Type"],
"type": "object"
},
"Types": {
"Address": {
- "type": [
- "string",
- "array"
- ]
+ "type": ["string", "array"]
},
"AllowedFailures": {
"type": "number"
@@ -417,16 +411,10 @@
"type": "string"
},
"BridgeGpio": {
- "type": [
- "number",
- "array"
- ]
+ "type": ["number", "array"]
},
"Bus": {
- "type": [
- "string",
- "number"
- ]
+ "type": ["string", "number"]
},
"C1": {
"type": "number"
@@ -461,11 +449,7 @@
"type": "array"
}
},
- "required": [
- "Name",
- "Pwm",
- "Tachs"
- ],
+ "required": ["Name", "Pwm", "Tachs"],
"type": "object"
},
"CpuID": {
@@ -499,9 +483,7 @@
"type": "array"
},
"GpioPolarity": {
- "enum": [
- "Low"
- ]
+ "enum": ["Low"]
},
"Index": {
"type": "number"
@@ -635,10 +617,7 @@
"type": "object"
},
"PresenceGpio": {
- "type": [
- "number",
- "array"
- ]
+ "type": ["number", "array"]
},
"Pwm": {
"type": "number"
@@ -669,10 +648,7 @@
},
"Tachs": {
"items": {
- "type": [
- "number",
- "string"
- ]
+ "type": ["number", "string"]
},
"type": "array"
},
@@ -700,12 +676,7 @@
"type": "number"
}
},
- "required": [
- "Direction",
- "Name",
- "Severity",
- "Value"
- ],
+ "required": ["Direction", "Name", "Severity", "Value"],
"type": "object"
},
"type": "array"
diff --git a/schemas/openbmc-dbus.json b/schemas/openbmc-dbus.json
index 8190b08..184d2f4 100644
--- a/schemas/openbmc-dbus.json
+++ b/schemas/openbmc-dbus.json
@@ -37,9 +37,7 @@
"type": "string"
}
},
- "required": [
- "AssetTag"
- ],
+ "required": ["AssetTag"],
"type": "object"
}
},
@@ -52,9 +50,7 @@
"type": "number"
}
},
- "required": [
- "ProductId"
- ],
+ "required": ["ProductId"],
"type": "object"
}
},
diff --git a/schemas/pid_zone.json b/schemas/pid_zone.json
index 4e4e41a..3905c13 100644
--- a/schemas/pid_zone.json
+++ b/schemas/pid_zone.json
@@ -17,12 +17,7 @@
"type": "string"
}
},
- "required": [
- "FailSafePercent",
- "MinThermalOutput",
- "Name",
- "Type"
- ]
+ "required": ["FailSafePercent", "MinThermalOutput", "Name", "Type"]
}
}
}
diff --git a/schemas/virtual_sensor.json b/schemas/virtual_sensor.json
index 391f695..3584489 100644
--- a/schemas/virtual_sensor.json
+++ b/schemas/virtual_sensor.json
@@ -13,27 +13,19 @@
"type": "object",
"properties": {
"MaxValidInput": {
- "description": [
- "Maximum valid value of an input sensor"
- ],
+ "description": ["Maximum valid value of an input sensor"],
"type": "number"
},
"MaxValue": {
- "description": [
- "Maximum sensor value"
- ],
+ "description": ["Maximum sensor value"],
"$ref": "legacy.json#/definitions/Types/MaxValue"
},
"MinValidInput": {
- "description": [
- "Miniumum valid value of an input sensor"
- ],
+ "description": ["Miniumum valid value of an input sensor"],
"type": "number"
},
"MinValue": {
- "description": [
- "Minimum sensor value"
- ],
+ "description": ["Minimum sensor value"],
"$ref": "legacy.json#/definitions/Types/MinValue"
},
"Name": {
@@ -60,9 +52,7 @@
"The type of calculation this sensor uses."
],
"type": "string",
- "enum": [
- "ModifiedMedian"
- ]
+ "enum": ["ModifiedMedian"]
},
"Units": {
"description": [
@@ -72,12 +62,7 @@
"$ref": "legacy.json#/definitions/Types/Units"
}
},
- "required": [
- "Name",
- "Sensors",
- "Type",
- "Units"
- ]
+ "required": ["Name", "Sensors", "Type", "Units"]
}
}
}
diff --git a/scripts/validate_configs.py b/scripts/validate_configs.py
index 7d580c2..5ba8945 100755
--- a/scripts/validate_configs.py
+++ b/scripts/validate_configs.py
@@ -5,10 +5,11 @@
"""
import argparse
import json
-import jsonschema.validators
import os
import sys
+import jsonschema.validators
+
DEFAULT_SCHEMA_FILENAME = "global.json"
@@ -17,24 +18,40 @@
description="Entity manager configuration validator",
)
parser.add_argument(
- "-s", "--schema", help=(
+ "-s",
+ "--schema",
+ help=(
"Use the specified schema file instead of the default "
- "(__file__/../../schemas/global.json)"))
+ "(__file__/../../schemas/global.json)"
+ ),
+ )
parser.add_argument(
- "-c", "--config", action='append', help=(
+ "-c",
+ "--config",
+ action="append",
+ help=(
"Validate the specified configuration files (can be "
"specified more than once) instead of the default "
- "(__file__/../../configurations/**.json)"))
+ "(__file__/../../configurations/**.json)"
+ ),
+ )
parser.add_argument(
- "-e", "--expected-fails", help=(
+ "-e",
+ "--expected-fails",
+ help=(
"A file with a list of configurations to ignore should "
- "they fail to validate"))
+ "they fail to validate"
+ ),
+ )
parser.add_argument(
- "-k", "--continue", action='store_true', help=(
- "keep validating after a failure"))
+ "-k",
+ "--continue",
+ action="store_true",
+ help="keep validating after a failure",
+ )
parser.add_argument(
- "-v", "--verbose", action='store_true', help=(
- "be noisy"))
+ "-v", "--verbose", action="store_true", help="be noisy"
+ )
args = parser.parse_args()
schema_file = args.schema
@@ -42,11 +59,14 @@
try:
source_dir = os.path.realpath(__file__).split(os.sep)[:-2]
schema_file = os.sep + os.path.join(
- *source_dir, 'schemas', DEFAULT_SCHEMA_FILENAME)
+ *source_dir, "schemas", DEFAULT_SCHEMA_FILENAME
+ )
except Exception:
sys.stderr.write(
"Could not guess location of {}\n".format(
- DEFAULT_SCHEMA_FILENAME))
+ DEFAULT_SCHEMA_FILENAME
+ )
+ )
sys.exit(2)
schema = {}
@@ -55,22 +75,22 @@
schema = json.load(fd)
except FileNotFoundError:
sys.stderr.write(
- "Could not read schema file '{}'\n".format(schema_file))
+ "Could not read schema file '{}'\n".format(schema_file)
+ )
sys.exit(2)
config_files = args.config or []
if len(config_files) == 0:
try:
source_dir = os.path.realpath(__file__).split(os.sep)[:-2]
- configs_dir = os.sep + os.path.join(*source_dir, 'configurations')
+ configs_dir = os.sep + os.path.join(*source_dir, "configurations")
data = os.walk(configs_dir)
for root, _, files in data:
for f in files:
- if f.endswith('.json'):
+ if f.endswith(".json"):
config_files.append(os.path.join(root, f))
except Exception:
- sys.stderr.write(
- "Could not guess location of configurations\n")
+ sys.stderr.write("Could not guess location of configurations\n")
sys.exit(2)
configs = []
@@ -80,7 +100,8 @@
configs.append(json.load(fd))
except FileNotFoundError:
sys.stderr.write(
- "Could not parse config file '{}'\n".format(config_file))
+ "Could not parse config file '{}'\n".format(config_file)
+ )
sys.exit(2)
expected_fails = []
@@ -91,12 +112,15 @@
expected_fails.append(line.strip())
except Exception:
sys.stderr.write(
- "Could not read expected fails file '{}'\n".format(
- args.expected_fails))
+ "Could not read expected fails file '{}'\n".format(
+ args.expected_fails
+ )
+ )
sys.exit(2)
base_uri = "file://{}/".format(
- os.path.split(os.path.realpath(schema_file))[0])
+ os.path.split(os.path.realpath(schema_file))[0]
+ )
resolver = jsonschema.RefResolver(base_uri, schema)
validator = jsonschema.Draft7Validator(schema, resolver=resolver)