update config file documentation
Entity manager config file readme needs some intent documented, as well
as some specifics, on top of the examples.
Tested:
Ran through spell checker, and launched in markdown browser. Didn't
observe any obvious problems.
Change-Id: Ibc5d5b48bc386baf2b98a0351732f4f61e322692
diff --git a/CONFIG_FORMAT.md b/CONFIG_FORMAT.md
index d3baa1b..44e8774 100644
--- a/CONFIG_FORMAT.md
+++ b/CONFIG_FORMAT.md
@@ -1,23 +1,84 @@
-# Entity Manager
+# Config Files
-Entity manager is a runtime configuration application which parses configuration
-files (in JSON format) and attempts to detect the devices described by the
-configuration files. It also can, based on the configuration, attempt to load
-install devices into sysfs. It takes these configurations and produces a best
-representation of the files on dbus using the xyz.openbmc_project.Configuration
-namespace. It also produces a system.json file for persistence.
+## Intent
+
+Configuration files are intended to represent the minimum amount of
+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
+ 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.
+
+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.
+
+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.
## Configuration Syntax
In most cases a server system is built with multiple hardware modules (circuit
boards) such as baseboard, risers, and hot-swap backplanes. While it is
perfectly legal to combine the JSON configuration information for all the
-hardware modules into a single file if desired, it is also possible 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). When one of the hardware modules
-needs to be upgraded (e.g., a new temperature sensor), only such JSON
-configuration file needs to be be updated.
+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.
Within a configuration file, there is a JSON object which consists of multiple
"string : value" pairs. This Entity Manager defines the following strings.
@@ -40,24 +101,22 @@
| "$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
If you're just getting started and your goal is to add sensors dynamically,
check out [My First Sensors](docs/my_first_sensors.md)
+## Configuration schema
+
+The config schema is documented in [README.md](schemas/README.schema)
## Configuration Records - Baseboard Example
-Required fields are name, probe and exposes.
-
-The configuration JSON files attempt to model the actual hardware modules
-which make up a complete system. An example baseboard JSON file shown below
-defines two fan connectors and two temperature sensors of TMP75 type. These
-objects are considered valid by BMC when the probe command (reads and compares
-the product name in FRU) is successful and this baseboard is named as "WFP
-baseboard".
+The configuration JSON files attempt to model the actual hardware modules which
+make up a complete system. An example baseboard JSON file shown below defines
+two fan connectors and two temperature sensors of TMP75 type. These objects are
+considered valid by BMC when the probe command (reads and compares the product
+name in FRU) is successful and this baseboard is named as "WFP baseboard".
```
{