prettier: re-format
Prettier is enabled in openbmc-build-scripts on Markdown, JSON, and YAML
files to have consistent formatting for these file types. Re-run the
formatter on the whole repository.
Change-Id: If06b0aed2cee53bcc5789e56eb6c30ca245394e7
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
diff --git a/README.md b/README.md
index 7cd4892..ca535d0 100644
--- a/README.md
+++ b/README.md
@@ -1,152 +1,170 @@
Phosphor Inventory Manager (PIM) is an implementation of the
-xyz.openbmc_project.Inventory.Manager DBus interface, and supporting tools.
-PIM uses a combination of build-time YAML files, run-time calls to the Notify
-method of the Manager interface, and association definition JSON files to
-provide a generalized inventory state management solution.
+xyz.openbmc_project.Inventory.Manager DBus interface, and supporting tools. PIM
+uses a combination of build-time YAML files, run-time calls to the Notify method
+of the Manager interface, and association definition JSON files to provide a
+generalized inventory state management solution.
## YAML
-PIM includes a YAML parser (pimgen.py). For PIM to do anything useful, a
-set of YAML files must be provided externally that tell it what to do.
-Examples can be found in the examples directory.
+
+PIM includes a YAML parser (pimgen.py). For PIM to do anything useful, a set of
+YAML files must be provided externally that tell it what to do. Examples can be
+found in the examples directory.
The following top level YAML tags are supported:
-* description - An optional description of the file.
-* events - One or more events that PIM should monitor.
+- description - An optional description of the file.
+- events - One or more events that PIM should monitor.
-----
+---
+
**events**
Supported event tags are:
-* name - A globally unique event name.
-* description - An optional description of the event.
-* type - The event type. Supported types are: *match* and *startup*.
-* actions - The responses to the event.
+- name - A globally unique event name.
+- description - An optional description of the event.
+- type - The event type. Supported types are: _match_ and _startup_.
+- actions - The responses to the event.
Subsequent tags are defined by the event type.
------
+---
+
**match**
Supported match tags are:
-* signatures - A DBus match specification.
-* filters - Filters to apply when a match occurs.
+- signatures - A DBus match specification.
+- filters - Filters to apply when a match occurs.
------
+---
+
**startup**
Supported startup tags are:
-* filters - Filters to apply at startup.
+- filters - Filters to apply at startup.
-----
+---
+
**filters**
Supported filter tags are:
-* name - The filter to use.
+- name - The filter to use.
Subsequent tags are defined by the filter type.
The available filters provided by PIM are:
-* propertyChangedTo - Only match events when the specified property has
-the specified value.
-* propertyIs - Only match events when the specified property has
-the specified value.
-
-----
-**propertyChangedTo**
-
-The property under test is obtained from an sdbus message
-generated from an org.freedesktop.DBus.Properties.PropertiesChanged
-signal payload.
-
-Supported arguments for the propertyChangedTo filter are:
-* interface - The interface hosting the property to be checked.
-* property - The property to check.
-* value - The value to check.
-
-----
-**propertyIs**
-
-The property under test is obtained by invoking
-org.freedesktop.Properties.Get on the specified interface.
-
-Supported arguments for the propertyIs filter are:
-* path - The object hosting the property to be checked.
-* interface - The interface hosting the property to be checked.
-* property - The property to check.
-* value - The value to check.
-* service - An optional DBus service name.
-
-The service argument is optional. If provided that service will
-be called explicitly. If omitted, the service will be obtained
-with an xyz.openbmc_project.ObjectMapper lookup.
-
-propertyIs can be used in an action condition context when the
-action operates on a dbus object path.
+- propertyChangedTo - Only match events when the specified property has the
+ specified value.
+- propertyIs - Only match events when the specified property has the specified
+ value.
---
+
+**propertyChangedTo**
+
+The property under test is obtained from an sdbus message generated from an
+org.freedesktop.DBus.Properties.PropertiesChanged signal payload.
+
+Supported arguments for the propertyChangedTo filter are:
+
+- interface - The interface hosting the property to be checked.
+- property - The property to check.
+- value - The value to check.
+
+---
+
+**propertyIs**
+
+The property under test is obtained by invoking org.freedesktop.Properties.Get
+on the specified interface.
+
+Supported arguments for the propertyIs filter are:
+
+- path - The object hosting the property to be checked.
+- interface - The interface hosting the property to be checked.
+- property - The property to check.
+- value - The value to check.
+- service - An optional DBus service name.
+
+The service argument is optional. If provided that service will be called
+explicitly. If omitted, the service will be obtained with an
+xyz.openbmc_project.ObjectMapper lookup.
+
+propertyIs can be used in an action condition context when the action operates
+on a dbus object path.
+
+---
+
**actions**
Supported action tags are:
-* name - The action to perform.
+- name - The action to perform.
Subsequent tags are defined by the action type.
The available actions provided by PIM are:
-* destroyObject - Destroy the specified DBus object.
-* setProperty - Set the specified property on the specified DBus object.
+- destroyObject - Destroy the specified DBus object.
+- setProperty - Set the specified property on the specified DBus object.
-----
+---
+
**destroyObject**
Supported arguments for the destroyObject action are:
-* paths - The paths of the objects to remove from DBus.
-* conditions - An array of conditions.
-Conditions are tested and logically ANDed. If the conditions do not
-pass, the object is not destroyed. Any condition that accepts a path
-parameter is supported.
+- paths - The paths of the objects to remove from DBus.
+- conditions - An array of conditions.
-----
+Conditions are tested and logically ANDed. If the conditions do not pass, the
+object is not destroyed. Any condition that accepts a path parameter is
+supported.
+
+---
+
**setProperty**
Supported arguments for the setProperty action are:
-* interface - The interface hosting the property to be set.
-* property - The property to set.
-* paths - The objects hosting the property to be set.
-* value - The value to set.
-* conditions - An array of conditions.
-Conditions are tested and logically ANDed. If the conditions do not
-pass, the property is not set. Any condition that accepts a path
-parameter is supported.
+- interface - The interface hosting the property to be set.
+- property - The property to set.
+- paths - The objects hosting the property to be set.
+- value - The value to set.
+- conditions - An array of conditions.
-----
+Conditions are tested and logically ANDed. If the conditions do not pass, the
+property is not set. Any condition that accepts a path parameter is supported.
+
+---
+
**createObjects**
Supported arguments for the createObjects action are:
-* objs - A dictionary of objects to create.
-----
+- objs - A dictionary of objects to create.
+
+---
+
## Creating Associations
-PIM can create [associations][1] between inventory items and other D-Bus objects.
+
+PIM can create [associations][1] between inventory items and other D-Bus
+objects.
This functionality is optional and is controlled with the
-`--enable-associations` configure option. It defaults to disabled.
+`--enable-associations` configure option. It defaults to disabled.
To use this, the associations to create should be defined in a JSON file which
is specified by the `ASSOCIATIONS_FILE_PATH` configure variable, which defaults
-to `/usr/share/phosphor-inventory-manager/associations.json`. This file is
+to `/usr/share/phosphor-inventory-manager/associations.json`. This file is
processed at runtime.
An example of this JSON is:
+
```
[
{
@@ -170,9 +188,9 @@
```
Then, when/if PIM creates the
-`xyz/openbmc_project/system/chassis/motherboard/cpu0/core1` inventory object,
-it will add an `xyz.openbmc_project.Association.Definitions` interface on it
-such that the object mapper creates the 2 association objects:
+`xyz/openbmc_project/system/chassis/motherboard/cpu0/core1` inventory object, it
+will add an `xyz.openbmc_project.Association.Definitions` interface on it such
+that the object mapper creates the 2 association objects:
```
/xyz/openbmc_project/inventory/system/chassis/motherboard/cpu0/core1/sensors
@@ -185,6 +203,7 @@
```
The JSON description is:
+
```
[
{
@@ -211,17 +230,17 @@
```
In the case where different systems that require different associations reside
-in the same flash image, multiple JSON files must be used. These files must be
-in the same directory as the default associations file would go, but it does
-not matter what they are named as long as the name ends in '.json'. Each file
-then contains a 'condition' entry that specifies an inventory path, interface,
-property, and list of values. If the actual value of that property is in the
+in the same flash image, multiple JSON files must be used. These files must be
+in the same directory as the default associations file would go, but it does not
+matter what they are named as long as the name ends in '.json'. Each file then
+contains a 'condition' entry that specifies an inventory path, interface,
+property, and list of values. If the actual value of that property is in the
list of values, then the condition is met and those associations are activated.
-If a file with a conditions section is found, then the default associations
-file is ignored. The end result is that associations are only ever loaded from
-one file, either the default file if there aren't any files with conditions in
-them, or the first file that had a condition that matched.
+If a file with a conditions section is found, then the default associations file
+is ignored. The end result is that associations are only ever loaded from one
+file, either the default file if there aren't any files with conditions in them,
+or the first file that had a condition that matched.
An example is:
@@ -261,14 +280,15 @@
```
This states that these associations are valid if the system/chassis/motherboard
-inventory object has a Model property with a value of either ModelA or
-ModelB.
+inventory object has a Model property with a value of either ModelA or ModelB.
The values field supports the same types as in the inventory, so either a 'bool'
-(true/false), 'int64\_t,' 'string', or 'std::vector<uint8_t>'([1, 2]).
+(true/false), 'int64_t,' 'string', or 'std::vector<uint8_t>'([1, 2]).
-----
+---
+
## Building
+
After running pimgen.py, build PIM using the following steps:
```
@@ -282,4 +302,6 @@
```
./bootstrap.sh clean
```
-[1]: https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
+
+[1]:
+ https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations