doc: format with markdownlint
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Change-Id: Id1efc27791e219e5fbfe08023143be2f59037307
diff --git a/.markdownlint.yaml b/.markdownlint.yaml
new file mode 100644
index 0000000..f5cfbee
--- /dev/null
+++ b/.markdownlint.yaml
@@ -0,0 +1,5 @@
+default: true
+MD024:
+ siblings_only: true
+MD013:
+ stern: true
diff --git a/README.md b/README.md
index df63ef7..81f124f 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,28 @@
# phosphor-dbus-interfaces
+
YAML descriptors of standard D-Bus interfaces.
The format is described by the [sdbusplus binding generation tool sdbus++][].
## Building
-This project can be built with `meson`. The typical `meson` workflow is:
+This project can be built with `meson`. The typical `meson` workflow is:
`meson builddir && ninja -C builddir`.
The meson files used to handle the YAML files are automatically generated
-and found under the `gen` subdirectory. When adding or removing YAML files,
-this must be regenerated. This can be done with the helper script found
+and found under the `gen` subdirectory. When adding or removing YAML files,
+this must be regenerated. This can be done with the helper script found
in the `gen` subdirectory: `cd gen && ./regenerate-meson`.
## Configuration
Only the xyz/openbmc_project and org/freedesktop interfaces are built by
-default. Other interfaces can be enabled by meson options:
+default. Other interfaces can be enabled by meson options:
- com/ibm - `-Ddata_com_ibm=true`
- org/open_power - `-Ddata_org_open_power=true`
Example: `meson builddir -Ddata_com_ibm=true && ninja -C builddir`
+
## References
[sdbusplus binding generation tool sdbus++]: https://github.com/openbmc/sdbusplus/blob/master/README.md#binding-generation-tool
diff --git a/yaml/com/ibm/ipzvpd/README.md b/yaml/com/ibm/ipzvpd/README.md
index 842c61f..6604577 100644
--- a/yaml/com/ibm/ipzvpd/README.md
+++ b/yaml/com/ibm/ipzvpd/README.md
@@ -1,4 +1,5 @@
# IPZ VPD D-Bus Interfaces
+
IPZ is a VPD (Vital Product Data) format used in IBM Power systems.
The format consists of keywords that are stored as key-value
pairs (Keyword name and its value). Keywords are grouped into records,
@@ -16,5 +17,5 @@
belong to that record are represented as properties under that interface.
The type of every property shall be a byte array.
-[1]:https://www-355.ibm.com/systems/power/openpower/posting.xhtml?postingId=1D060729AC96891885257E1B0053BC95
-[2]:https://github.com/openbmc/docs/blob/master/designs/vpd-collection.md
+[1]: https://www-355.ibm.com/systems/power/openpower/posting.xhtml?postingId=1D060729AC96891885257E1B0053BC95
+[2]: https://github.com/openbmc/docs/blob/master/designs/vpd-collection.md
diff --git a/yaml/xyz/openbmc_project/BIOSConfig/README.md b/yaml/xyz/openbmc_project/BIOSConfig/README.md
index f553cda..3627ebc 100644
--- a/yaml/xyz/openbmc_project/BIOSConfig/README.md
+++ b/yaml/xyz/openbmc_project/BIOSConfig/README.md
@@ -1,46 +1,49 @@
-Remote BIOS Configuration via BMC
-Overview
-Provides ability for the user to view and modify the
-BIOS setup configuration parameters remotely via BMC at any Host state.
-Modifications to the parameters take place upon the next system reboot or
-immediate based on the host firmware.
-Please refer https://gerrit.openbmc-project.xyz/c/openbmc/docs/+/29320
+# Remote BIOS Configuration via BMC
-Remote BIOS Configuration (RBC) service exposes D-Bus methods for
-BIOS settings management operations.
+## Overview
-RBC Manager Interface
-xyz.openbmc_project.BIOSConfigManager provides following methods, properties.
+Provides ability for the user to view and modify the BIOS setup configuration
+parameters remotely via BMC at any Host state. Modifications to the parameters
+take place upon the next system reboot or immediate based on the host firmware.
-Object Path : /xyz/openbmc_project/bios_config/manager0
+Please refer to the [design][design] for more details.
-xyz.openbmc_project.BIOSConfigManager
+Remote BIOS Configuration (RBC) service exposes D-Bus methods for BIOS settings
+management operations.
-methods:
-SetAttribute -To set the particular BIOS attribute with new value.
-GetAttribute -To get the bios attribute current and pending values.
-GetPendingAttributes -To get all pending bios Atrributes list.
-SetPendingAttributes -To set all pending bios Atrributes list.
+## RBC Manager Interface
+### Interface xyz.openbmc_project.BIOSConfigManager
-Properites:
-ResetBIOSSettings - To reset the BIOS settings based on the Reset Flag.
-AllBaseAttributes-To store all bios attributes details.
-
-Signals:
-PendingAttributesCreated - Signal sent out, when Pending attributes list created.
-
-PasswordInterface:
-
-xyz.openbmc_project.BIOSConfig.Password provides following Methods and Properities.
-
-xyz.openbmc_project.BIOSConfig.Password Interface
+- Object Path: `/xyz/openbmc_project/bios_config/manager0`
Methods:
-VerifyPassword
-ChangePassword
+
+- `SetAttribute` -To set the particular BIOS attribute with new value.
+- `GetAttribute` -To get the bios attribute current and pending values.
+- `GetPendingAttributes` -To get all pending bios Atrributes list.
+- `SetPendingAttributes` -To set all pending bios Atrributes list.
+
+Properites:
+
+- `ResetBIOSSettings` - To reset the BIOS settings based on the Reset Flag.
+- `AllBaseAttributes` - To store all bios attributes details.
+
+Signals:
+
+- `PendingAttributesCreated` - Signal sent out, when Pending attributes list
+ created.
+
+### Interface xyz.openbmc_project.BIOSConfig.Password
+
+Methods:
+
+- `VerifyPassword`
+- `ChangePassword`
Properities:
-IsPasswordInitDone - To indicate BIOS password related details are recevied or not.
+- `IsPasswordInitDone` - To indicate BIOS password related details are received
+ or not.
+[design]: https://github.com/openbmc/docs/blob/master/designs/remote-bios-configuration.md
diff --git a/yaml/xyz/openbmc_project/Certs/README.md b/yaml/xyz/openbmc_project/Certs/README.md
index 2a88a36..abfdf6d 100644
--- a/yaml/xyz/openbmc_project/Certs/README.md
+++ b/yaml/xyz/openbmc_project/Certs/README.md
@@ -1,5 +1,7 @@
# BMC Certificate management
+## Overview
+
Certificate management allows to replace the existing certificate and private
key file with another (possibly certification Authority (CA) signed)
certificate and private key file. Certificate management allows the user to
@@ -7,28 +9,28 @@
update the certificate, using an unencrypted certificate and private key file
in .pem format, which includes both private key and signed certificate.
-### Signed Certificate upload Design flow(Pre-generated):
+### Signed Certificate upload Design flow(Pre-generated)
- The REST Server copies the certificate and private key file to a temporary
location.
- REST server should map the URI to the target DBus application (Certs) object.
The recommendation for the D-Bus application implementing certificate D-Bus
objects is to use the same path structure as the REST endpoint.
- e.g.:
- - The URI /xyz/openbmc_project/certs/server/https maps to instance
- of the certificate application handling Https server certificate.
- - The URI /xyz/openbmc_project/certs/client/ldap maps to instance
- of the certificate application handling LDAP client certificate.
- - The URI /xyz/openbmc_project/certs/authority/ldap maps to instance
- of the certificate application handling Certificate Autohority
- certificates.
+ e.g.:
+ - The URI /xyz/openbmc_project/certs/server/https maps to instance
+ of the certificate application handling Https server certificate.
+ - The URI /xyz/openbmc_project/certs/client/ldap maps to instance
+ of the certificate application handling LDAP client certificate.
+ - The URI /xyz/openbmc_project/certs/authority/ldap maps to instance
+ of the certificate application handling Certificate Autohority
+ certificates.
- REST server should call the install method of the certificate application
instance.
- Certificate manager application also implements d-bus object
xyz.openbmc_project.Certs.Manager. This includes the collection of
"certificates specific d-bus objects" installed in the system. This d-bus
provide option to view the certificate on PEM format and delete the same.
- Refer https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail for details.
+ Refer [Wikipedia][privacy-enhanced-mail] for details.
- Applications should subscribe the xyz.openbmc_project.Certs.Manager
to see any new certificate is uploaded or change in the existing
certificates.
@@ -37,59 +39,67 @@
- In case of delete action, certificate manager creates a new self signed
certificate after successful delete (regards only server type certificates)
-### REST interface details:
+[privacy-enhanced-mail]: https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail
- ```
- url: /xyz/openbmc_project/certs/server/https
- Description: Update https server signed certificate and the private key.
- Method: PUT
+### REST interface
- url: /xyz/openbmc_project/certs/server/https/<cert_id>
- Description: Delete https server signed certificate and the private key.
- Method: DELETE
+```plain
+url: /xyz/openbmc_project/certs/server/https
+Description: Update https server signed certificate and the private key.
+Method: PUT
- url: /xyz/openbmc_project/certs/client/ldap
- Description: Update ldap client certificate and the private key.
- Method: PUT
+url: /xyz/openbmc_project/certs/server/https/<cert_id>
+Description: Delete https server signed certificate and the private key.
+Method: DELETE
- url: /xyz/openbmc_project/certs/client/ldap/<cert_id>
- Description: Delete ldap client certificate and the private key.
- Method: DELETE
+url: /xyz/openbmc_project/certs/client/ldap
+Description: Update ldap client certificate and the private key.
+Method: PUT
- Return codes
+url: /xyz/openbmc_project/certs/client/ldap/<cert_id>
+Description: Delete ldap client certificate and the private key.
+Method: DELETE
- 200 Success
- 400 Invalid certificate and private key file.
- 405 Method not supported.
- 500 Internal server error
+Return codes
- ```
+ 200 Success
+ 400 Invalid certificate and private key file.
+ 405 Method not supported.
+ 500 Internal server error
+
+```
## CSR
-### User flow for generating and installing Certificates(CSR Based):
- Certificate Signing Request [CSR](https://en.wikipedia.org/wiki/Certificate_signing_request)
-is a message sent from an applicant to a certitificate authority in order to
-apply for a digital identity certificate. This section provides the details of
-the CSR based certificate user flow.
-- The user performs the CSR/create interface
- BMC creates new private key and CSR object which includes CSR information.
-- The user performs the CSR/export interface
- Allows the user to export the CSR file which is part of newly created
- CSR object. This can be provided to the CA to create SSL certificate.
-- The user perform the certificate upload on appropriate services.
- Example: if trying to replace the HTTPS certificate for a Manager,
- navigate to the Manager’s Certificate object upload interface.
- The Upload method internally pairs the private key used in the first
- step with the installed certificate.
+### User flow for generating and installing Certificates(CSR Based)
-### Assumptions:
+[Certificate Signing Request][csr](CSR) is a message sent from an applicant to
+a certitificate authority in order to apply for a digital identity certificate.
+This section provides the details of the CSR based certificate user flow.
+
+- The user performs the CSR/create interface
+ BMC creates new private key and CSR object which includes CSR information.
+- The user performs the CSR/export interface
+ Allows the user to export the CSR file which is part of newly created
+ CSR object. This can be provided to the CA to create SSL certificate.
+- The user perform the certificate upload on appropriate services.
+ Example: if trying to replace the HTTPS certificate for a Manager,
+ navigate to the Manager’s Certificate object upload interface.
+ The Upload method internally pairs the private key used in the first
+ step with the installed certificate.
+
+[csr]: https://en.wikipedia.org/wiki/Certificate_signing_request
+
+### Assumptions
+
- BMC updates the private key associated to CSR for any new CSR request.
- BMC upload process automatically appends certificate file with system CSR
private key, for the service which requirs certificate and key.
-- CSR based Certificate validation is alway's based on private key in the system.
+- CSR based Certificate validation is alway's based on private key in the
+ system.
### CSR Request
+
- CSR requests initiated through D-Bus are time-consuming and might result
D-Bus time-out error.
- To overcome the time-out error, parent process is forked and CSR operation
@@ -113,11 +123,12 @@
### Example usage for the GenerateCSR POST request
- ```
- url: /redfish/v1/CertificateService
- Action: #CertificateService.GenerateCSR {
+```yaml
+url: /redfish/v1/CertificateService
+Action: #CertificateService.GenerateCSR {
"City": "HYB",
- "CertificateCollection": "/redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/",
+ "CertificateCollection":
+ "/redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates/",
"CommonName": "www.company.com",
"ContactPerson":"myname",
"AlternativeNames":["mycompany.com","mycompany2.com"],
@@ -135,19 +146,21 @@
"State": "TX",
"SurName": "XX",
"UnstructuredName": "xxx"
- }
- Description: This is used to perform a certificate signing request.
- Method: POST
+}
+Description: This is used to perform a certificate signing request.
+Method: POST
- ```
+```
-### Additional interfaces:
+### Additional interfaces
+
- CertificateService.ReplaceCertificate
- Allows the user to replace an existing certificate.
+ Allows the user to replace an existing certificate.
-### d-bus interfaces:
+### d-bus interfaces
#### d-bus interface to install certificate and private Key
+
- Certs application must:
- validate the certificate and Private key file by checking, if the Private
key matches the public key in the certificate file.
@@ -163,26 +176,31 @@
create a new self signed certificate and will install the same.
### Boot process
-- certificate management instances should be created based on the system
- configuration.
-- Incase of no Https certificate or invalid Https certificate, certificate
- manager should update the https certificate with self signed certificate.
+- certificate management instances should be created based on the system
+ configuration.
-### Repository:
- phosphor-certificate-manager
+- Incase of no Https certificate or invalid Https certificate, certificate
+ manager should update the https certificate with self signed certificate.
+
+### Repository
+
+phosphor-certificate-manager
+
### Redfish Certificate Support
+
#### Certificate Upload
+
- Certificate Manager implements "xyz.openbmc_project.Certs.Install" interface
for installing certificates in the system.
- Redfish initiates certificate upload by issuing a POST request on the Redfish
CertificateCollection with the certificate file. Acceptable body formats are:
raw pem text or json that is acceptable by action
- [CertificateService.ReplaceCertificate](
- https://www.dmtf.org/sites/default/files/standards/documents/DSP2046_2019.1.pdf)
+ [CertificateService.ReplaceCertificate](https://www.dmtf.org/sites/default/files/standards/documents/DSP2046_2019.1.pdf)
For example the HTTPS certificate upload POST request is issued on URI
"/redfish/v1/Managers/bmc/NetworkProtocol/HTTPS/Certificates"
+
- Bmcweb receives the POST request and it maps the Redfish URI to the
corresponding Certificate Manager D-Bus URI.
e.g: HTTPS certificate collection URI
@@ -207,6 +225,7 @@
ID of the certificate is appended to the collection URI.
#### Certificate Replace
+
- Certificate Object implements "xyz.openbmc_project.Certs.Replace" interface to
for replacing existing certificate.
- Redfish issues Replace certificate request by invoking the ReplaceCertificate
@@ -225,22 +244,25 @@
certificate details.
#### Bootup
+
- During bootup certificate objects created for the existing certificates.
+
### Errors thrown by Certificate Manager
+
- NotAllowed exception thrown if Install method invoked with a certificate
already existing. At present only one certificate per server and client
certificate type is allowed.
- InvalidCertificate excption thrown for validation errors.
#### Certificate Deletion
+
- For server and client certificate type the certificate deletion is not
allowed. In case of authority certificate type the delete option is
acceptable and can be done on individial certificates, for example:
- ```
- url: redfish/v1/Managers/bmc/Truststore/Certificates/1
- Method: DELETE
+```plain
+url: redfish/v1/Managers/bmc/Truststore/Certificates/1
+Method: DELETE
- Returns: code 204 with empty body content.
- ```
-
+Returns: code 204 with empty body content.
+```
diff --git a/yaml/xyz/openbmc_project/Chassis/README.md b/yaml/xyz/openbmc_project/Chassis/README.md
index cc2ccdf..b32a54d 100644
--- a/yaml/xyz/openbmc_project/Chassis/README.md
+++ b/yaml/xyz/openbmc_project/Chassis/README.md
@@ -1,47 +1,59 @@
# Chassis Power Control
## Overview
+
Chassis Power Control service exposes D-Bus methods for chassis power operations
### Power Button Interface
+
Power button interface `xyz.openbmc_project.Chassis.Buttons.Power`
provides following methods, signals.
#### methods
-* simPress - To emulate physical power button press.
-* simLongPress - To emulate physical power button long press.
+
+- simPress - To emulate physical power button press.
+- simLongPress - To emulate physical power button long press.
#### signals
-* Released - Power button released signal.
-* Pressed - Power button pressed signal.
-* PressedLong - Power button long pressed signal.
+
+- Released - Power button released signal.
+- Pressed - Power button pressed signal.
+- PressedLong - Power button long pressed signal.
### ID Button Interface
+
ID button interface `xyz.openbmc_project.Chassis.Buttons.ID`
provides following methods, signals.
#### methods
-* simPress - To emulate ID button press.
+
+- simPress - To emulate ID button press.
#### signals
-* Released - ID button released signal.
-* Pressed - ID button pressed signal.
+
+- Released - ID button released signal.
+- Pressed - ID button pressed signal.
### Reset Button Interface
+
ID button interface `xyz.openbmc_project.Chassis.Buttons.Reset`
provides following methods, signals.
#### methods
-* simPress - To emulate reset button press.
+
+- simPress - To emulate reset button press.
#### signals
-* Released - Reset button released signal.
-* Pressed - Reset button pressed signal.
+
+- Released - Reset button released signal.
+- Pressed - Reset button pressed signal.
### Host Selector Button Interface
+
Selector button interface `xyz.openbmc_project.Chassis.Buttons.HostSelector`
provides following property.
### properties
+
Position - Value of the Host selector.
-MaxPosition - Max value that the Position value can hold.
\ No newline at end of file
+MaxPosition - Max value that the Position value can hold.
diff --git a/yaml/xyz/openbmc_project/Common/Callout/README.md b/yaml/xyz/openbmc_project/Common/Callout/README.md
index 9ba0ef7..995f958 100644
--- a/yaml/xyz/openbmc_project/Common/Callout/README.md
+++ b/yaml/xyz/openbmc_project/Common/Callout/README.md
@@ -1,3 +1,5 @@
+# Callouts
+
## Introduction
A callout is typically an indication of a faulty hardware component in a system.
@@ -14,7 +16,8 @@
An OpenBMC error has associated metadata, the same is true for a callout. Such
metadata would be defined in the callout YAML interface. Here is an example (for
xyz.openbmc_project.Error.Callout.IIC) :
-```
+
+```yaml
- name: IIC
meta:
- str: "CALLOUT_IIC_BUS=%s"
@@ -22,6 +25,7 @@
- str: "CALLOUT_IIC_ADDR=%hu"
type: uint16
```
+
An application wanting to add an IIC callout will have to provide values for the
metadata fields above. These fields will also let the error handling component
figure out that this is in fact an IIC callout.
@@ -29,12 +33,14 @@
A callout is typically associated with an error log. For eg,
`xyz.openbmc_project.Error.Foo` may want to add an IIC callout. This is
indicated in Foo's YAML interface as follows :
-```
+
+```yaml
- name: Foo
description: this is the error Foo
inherits:
- xyz.openbmc_project.Error.Callout.IIC
```
+
The way this inheritance will be implemented is that, Foo's metadata will
include Callout.IIC's as well, so an application wanting to add an IIC callout
will have to provide values for Foo and IIC metadata. Like mentioned before,
@@ -44,7 +50,8 @@
Currently, defined callout interfaces in turn inherit
`xyz.openbmc_project.Error.Callout.Device`, which has metadata common to
callouts :
-```
+
+```yaml
- name: Device
meta:
- str: "CALLOUT_ERRNO=%d"
@@ -52,6 +59,7 @@
- str: "CALLOUT_DEVICE_PATH=%s"
type: string
```
+
This way, say an application wants to express an IIC callout in terms of a
device path, for lack of IIC information. The application can add the callout
metadata fields for both Callout.Device and Callout.IIC, but provide values
@@ -66,17 +74,17 @@
Taking an example of a generic device callout here, but this would be the flow
in general :
-* An application commits an error that has associated callout metadata. This
+- An application commits an error that has associated callout metadata. This
will cause the error-log server to create a d-bus object for the error.
-* The error-log server will detect that callout metadata is present, will
+- The error-log server will detect that callout metadata is present, will
extract the same and hand it over to a sub-module which will map callout
metadata to one or more inventory object paths, and will create an
association between the error object and the inventory object(s). The
mapping from callout metadata to inventory objects is mostly done via
the aid of code generated by the system MRW parsers.
-* Generated code : consider a case where an application wants to callout
+- Generated code : consider a case where an application wants to callout
an EEPROM on the BMC planar, via a device path, such as
/sys/devices/platform/ahb/ahb:apb/1e78a000.i2c/i2c-11/i2c-11/11-0051/eeprom.
This would have to be mapped to the BMC planar as the FRU to be called out.
diff --git a/yaml/xyz/openbmc_project/Common/FactoryReset/README.md b/yaml/xyz/openbmc_project/Common/FactoryReset/README.md
index c488756..d7fbcd8 100644
--- a/yaml/xyz/openbmc_project/Common/FactoryReset/README.md
+++ b/yaml/xyz/openbmc_project/Common/FactoryReset/README.md
@@ -11,6 +11,7 @@
## Known Implementations (listed by D-Bus service)
### xyz.openbmc_project.Network
+
Path: `/xyz/openbmc_project/network`
The network factory reset overwrites the configuration for all configured
network interfaces to a DHCP setting. Configuration changes will take effect
@@ -18,6 +19,7 @@
reboot.
### xyz.openbmc_project.Software.BMC.Updater
+
Path: `/xyz/openbmc_project/software`
-The BMC software updater factory reset clears any volumes and persistence files
+The BMC software updater factory reset clears any volumes and persistence files
created by the BMC processes. This reset occurs only on the next BMC reboot.
diff --git a/yaml/xyz/openbmc_project/Control/README.msl.md b/yaml/xyz/openbmc_project/Control/README.msl.md
index d44e1be..cd853ab 100644
--- a/yaml/xyz/openbmc_project/Control/README.msl.md
+++ b/yaml/xyz/openbmc_project/Control/README.msl.md
@@ -8,7 +8,7 @@
in a manufacturing or field environment.
If an OpenBMC implementation provides MinimumShipLevelRequired, it must be
-on `/xyz/openbmc_project/control/minimum_ship_level_required`. There are
+on `/xyz/openbmc_project/control/minimum_ship_level_required`. There are
**no** requirements on how the setting is used; implementations are free to
react to the value of the setting however they choose.
@@ -18,7 +18,7 @@
MeetsMinimumShipLevel.
MeetsMinimumShipLevel can be implemented on any object in the inventory
-namespace. Again, there are no requirements on what an implementation does
+namespace. Again, there are no requirements on what an implementation does
when a particular inventory object does or does not meet the minimum ship
level.
@@ -29,21 +29,21 @@
boot, unless a user explicitly specifies otherwise.
Phosphor OpenBMC provides a basic implementation of MinimumShipLevelRequired.
-It maintains a setting store and interface for the setting value. This
+It maintains a setting store and interface for the setting value. This
implementation is suitable for the hypothetical platform implementation
requirements, allowing a user to toggle the setting back and forth.
To enable verification that MSL has been satisfied, the hypothetical platform
implementation would need to write an application that implements
-MeetsMinimumShipLevel on the inventory assets to be verified. At present
-Phosphor OpenBMC does not provide any applications that do this. If your
+MeetsMinimumShipLevel on the inventory assets to be verified. At present
+Phosphor OpenBMC does not provide any applications that do this. If your
application is general purpose and could meet the needs of others, consider
-contributing it to Phosphor OpenBMC. A possible implementation for the
+contributing it to Phosphor OpenBMC. A possible implementation for the
hypothetical fan control card might be an application that validates a number
of hwmon sensors exist and then sets the MinimumShipLevelRequired on the
fan inventory object accordingly.
Finally, the setting and the inventory assets must be compared and the server
-prevented from powering on. This could be accomplished with a custom application
+prevented from powering on. This could be accomplished with a custom application
or for simple logic, with
[PDM](https://github.com/openbmc/phosphor-dbus-monitor) rules.
diff --git a/yaml/xyz/openbmc_project/Control/Service/README.md b/yaml/xyz/openbmc_project/Control/Service/README.md
index 55ffa94..8cc7e7b 100644
--- a/yaml/xyz/openbmc_project/Control/Service/README.md
+++ b/yaml/xyz/openbmc_project/Control/Service/README.md
@@ -1,13 +1,18 @@
# Service Management
## Overview
+
Applications must use service manager daemon to configure services like
phosphor-ipmi-net, bmcweb, obmc-console etc in the system, instead of directly
controlling the same using 'systemd' or 'iptables'. This way client
applications doesn't need to change to configure services, when the
-implementations differ. The list of services supported are
-`"phosphor-ipmi-net", "bmcweb", "phosphor-ipmi-kcs", "start-ipkvm",
-"obmc-console"`.
+implementations differ. The list of services supported are:
+
+- "bmcweb"
+- "obmc-console"`
+- "phosphor-ipmi-kcs"
+- "phosphor-ipmi-net"
+- "start-ipkvm"
## Implementation Details
@@ -29,37 +34,38 @@
`/etc/systemd/system/<Service unit name>/` is updated and the unit is restarted
through `org.freedesktop.systemd1`.
-#### xyz.openbmc_project.Control.Service.Attributes interface
-##### properties
+### xyz.openbmc_project.Control.Service.Attributes interface
-* Enabled - indicates whether the service is enabled or disabled, `true`
- indicates the service will be started on the next boot and `false
- indicates that service will not be started on the next boot. This
- property can be used to change the service behaviour on the next
- boot, `true` to start the service on the next boot and `false` to
- not start the service on the next boot. Even if the service is
- disabled, on the next boot it can be started if there are other
- service dependencies to satisy. The service cannot be enabled if the
- service is masked.
+#### properties
-* Masked - indicates whether the service is masked, `true` indicates the
- service is permanently disabled and `false` indicates the service
- is enabled. If the property is set to `true`, then the service is
- permanently disabled and the service is stopped. If the property
- is set to `false` then the service is enabled and starts running.
+- Enabled - indicates whether the service is enabled or disabled, `true`
+ indicates the service will be started on the next boot and `false` indicates
+ that service will not be started on the next boot. This property can be used
+ to change the service behaviour on the next boot, `true` to start the service
+ on the next boot and `false` to not start the service on the next boot. Even
+ if the service is disabled, on the next boot it can be started if there are
+ other service dependencies to satisy. The service cannot be enabled if the
+ service is masked.
-* Running - indicates the current state of the service, `true` if the service
- is running and `false` if the service is not running. This property
- can be used to change the running state of the service, to start the
- service set to `true` and to stop the service set to `false`. The
- service cannot be started if the service is Masked.
+- Masked - indicates whether the service is masked, `true` indicates the
+ service is permanently disabled and `false` indicates the service
+ is enabled. If the property is set to `true`, then the service is
+ permanently disabled and the service is stopped. If the property
+ is set to `false` then the service is enabled and starts running.
-#### xyz.openbmc_project.Control.Service.SocketAttributes interface
-##### properties
+- Running - indicates the current state of the service, `true` if the service
+ is running and `false` if the service is not running. This property
+ can be used to change the running state of the service, to start the
+ service set to `true` and to stop the service set to `false`. The
+ service cannot be started if the service is Masked.
-* Port - Port number to which the service is configured to listen, if
- applicable for service. Services like obmc-console will not
- implement this interface.
+### xyz.openbmc_project.Control.Service.SocketAttributes interface
+
+#### properties
+
+- Port - Port number to which the service is configured to listen, if
+ applicable for service. Services like obmc-console will not
+ implement this interface.
## Usage
@@ -70,5 +76,3 @@
RMCP+ port number can be modified from the default port number 623 to a custom
one by updating the `Port` property value under the interface
`xyz.openbmc_project.Control.Service.SocketAttributes`.
-
-
diff --git a/yaml/xyz/openbmc_project/Ipmi/SESSION_README.md b/yaml/xyz/openbmc_project/Ipmi/SESSION_README.md
index c59b251..4ad60f2 100644
--- a/yaml/xyz/openbmc_project/Ipmi/SESSION_README.md
+++ b/yaml/xyz/openbmc_project/Ipmi/SESSION_README.md
@@ -1,25 +1,26 @@
# Session Management
## Overview
+
IPMI RMCP+ sessions are created and maintained by phosphor-ipmi-net daemon,
whereas we need to provide details about the same using phosphor-ipmi-host.
Hence IPMI RMCP+ session details has to be exposed through D-Bus interface,
so that both phosphor-ipmi-host & phosphr-ipmi-net will be in sync.
+### xyz.openbmc_project.Ipmi.SessionInfo interface
-#### xyz.openbmc_project.Ipmi.SessionInfo interface
-##### properties
-* SessionHandle - SessionHandle,unique one-byte number to locate the session.
-* Channel - Session created channel.
-* SessionPrivilege - Privilege of the session.
-* RemoteIPAddr – Remote IP address.
-* RemotePort - Remote port address.
-* RemoteMACAddress -Remote MAC Address.
-* UserID - Session created by given user id.
+#### properties
+- SessionHandle - SessionHandle,unique one-byte number to locate the session.
+- Channel - Session created channel.
+- SessionPrivilege - Privilege of the session.
+- RemoteIPAddr – Remote IP address.
+- RemotePort - Remote port address.
+- RemoteMACAddress -Remote MAC Address.
+- UserID - Session created by given user id.
+### xyz.openbmc_project.Object.Delete
-#### xyz.openbmc_project.Object.Delete
#### methods
-* Delete - To delete the session object in the system.
+- Delete - To delete the session object in the system.
diff --git a/yaml/xyz/openbmc_project/Led/README.md b/yaml/xyz/openbmc_project/Led/README.md
index 254e587..91eed5d 100644
--- a/yaml/xyz/openbmc_project/Led/README.md
+++ b/yaml/xyz/openbmc_project/Led/README.md
@@ -35,50 +35,54 @@
Definition of LED groups could be static or generated from MRW and must be in
YAML format. A group definition looks like this:
-```
+
+```yaml
bmc_booted:
- led_1:
- Action: On
- Frequency: 1000
- led_2:
- Action: Blink
- Frequency: 1000
- DutyOn: 50
+ led_1:
+ Action: On
+ Frequency: 1000
+ led_2:
+ Action: Blink
+ Frequency: 1000
+ DutyOn: 50
enclosure_identify:
- id_front:
- Action: Blink
- Frequency: 1000
- DutyOn: 50
- id_rear:
- Action: Blink
- Frequency: 1000
- DutyOn: 50
+ id_front:
+ Action: Blink
+ Frequency: 1000
+ DutyOn: 50
+ id_rear:
+ Action: Blink
+ Frequency: 1000
+ DutyOn: 50
```
+
This says that the group `bmc_booted` consists of 2 physical LEDs in it.
When this group is acted on, led_1 will turn solid [ON], while led_2
would be blinking at 50% duty cycle.
-## Dbus interfaces for LED groups.
+## Dbus interfaces for LED groups
-Refer: [specification](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/Group.interface.yaml)
+Refer to the [specification][specification].
+
+[specification]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/Group.interface.yaml
There is only one property called **asserted** defined on groups and when set to
boolean **true**, the actions listed for the LEDs in that group will get into
effect as described above.
When the property is set to **false**, the actions are un-done.
-* Henceforth, the term **asserted** would mean writing boolean **true**
+- Henceforth, the term **asserted** would mean writing boolean **true**
onto `assert` property of the group. Term **de-assert** would mean
writing **false** to `assert` property.
## Group Dbus information
-**Path: "/xyz/openbmc_project/led/groups/<name>"**
-**Interface: "xyz.openbmc_Project.Led.Group"**
+**Path: `/xyz/openbmc_project/led/groups/<name>`**
+**Interface: `xyz.openbmc_Project.Led.Group`**
Using the yaml definition above, a user can just set the `asserted` property to
-boolean `true` on '/xyz/openbmc_project/led/groups/enclosure_identify' and that
+boolean `true` on `/xyz/openbmc_project/led/groups/enclosure_identify` and that
would result in blinking the front and rear Identify LEDs of the enclosure.
## Mandatory groups
@@ -89,7 +93,8 @@
the group as such is deemed required.
Example: The Group yaml may just be;
-```
+
+```yaml
bmc_booted:
power_on:
```
@@ -103,29 +108,29 @@
Describing the Physical LED here just for documenting it and strictly NOT to
be used outside of the firmware code.
-## Dbus interfaces for physical LEDs.
+## Dbus interfaces for physical LEDs
-Refer: [specification](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/Physical.interface.yaml)
+Refer to the [specification][specification].
+
+[specification]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/Physical.interface.yaml
## Dbus information
-**Path: "/xyz/openbmc_project/led/physical/<name>"**
-**Interface: "xyz.openbmc_Project.Led.Physical"**
+**Path: `/xyz/openbmc_project/led/physical/<name>`**
+**Interface: `xyz.openbmc_Project.Led.Physical`**
Using **/xyz/openbmc_project/led/groups/enclosure_identify** as example;
setting the `asserted` property to `true` would result in these actions in
-*id_front* and *id_rear* physical LEDs.
+`id_front` and `id_rear` physical LEDs.
-1) Property *DutyOn* is set to `50` in;
- `/xyz/openbmc/project/led/physical/id_front` and
- `/xyz/openbmc/project/led/physical/id_rear`
+1. Property `DutyOn` is set to `50` in;
+ `/xyz/openbmc/project/led/physical/id_front` and
+ `/xyz/openbmc/project/led/physical/id_rear`
-2) Property *State* is set to `xyz.openbmc_project.Led.Physical.Action.On` in
+2. Property `State` is set to `xyz.openbmc_project.Led.Physical.Action.On` in
`/xyz/openbmc/project/led/physical/id_front` and
`/xyz/openbmc/project/led/physical/id_rear`
Which means, if some test wants to verify if the action on Group really resulted
in acting on physical LED, those are the properties to be read from physical
service.
-
-# END of Document
diff --git a/yaml/xyz/openbmc_project/Logging/README.md b/yaml/xyz/openbmc_project/Logging/README.md
index fc316d9..c6d7ec3 100644
--- a/yaml/xyz/openbmc_project/Logging/README.md
+++ b/yaml/xyz/openbmc_project/Logging/README.md
@@ -1,66 +1,101 @@
# OpenBMC logging
- * Provides a mechanism for logging events and errors to the journal.
- * Creates error entry D-Bus objects when an error is reported/committed.
- * Persists error entries across power off.
+
+- Provides a mechanism for logging events and errors to the journal.
+- Creates error entry D-Bus objects when an error is reported/committed.
+- Persists error entries across power off.
## Error definitions
+
### Generic error definitions
-* Generic errors used by applications are defined at
- [phosphor-dbus-interfaces](https://github.com/openbmc/phosphor-dbus-interfaces)
-* Generic errors can be used by all the applications by including the generated
+
+- Generic errors used by applications are defined at
+ [phosphor-dbus-interfaces][phosphor-dbus-interfaces].
+- Generic errors can be used by all the applications by including the generated
elog-errors.hpp header file.
+[phosphor-dbus-interfaces]: https://github.com/openbmc/phosphor-dbus-interfaces
+
### Application error definitions
-* There are errors that are not generic and are very specific to the
+
+- There are errors that are not generic and are very specific to the
application. Such errors are defined in the application that uses the error.
-* Refer to [openpower-debug-collector](https://github.com/openbmc/openpower-debug-collector)
+- Refer to [openpower-debug-collector][openpower-debug-collector].
+
+[openpower-debug-collector]: https://github.com/openbmc/openpower-debug-collector
### Error YAML files
- * Every error defined will have an error YAML file and a corresponding error
- metadata YAML file.
- * The error YAML file contains the error name and a one-line description of the error.
- An example of an error YAML file can be found [here](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Common/File.errors.yaml).
- * The error metadata YAML file captures required data. The format of the data is defined in the error metadata file.
- An example of an error metadata YAML file can be found [here](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Common/File.metadata.yaml)
+
+- Every error defined will have an error YAML file and a corresponding error
+ metadata YAML file.
+- The error YAML file contains the error name and a one-line description of the
+ error.
+ An example of an error YAML file can be found [here][error-example].
+- The error metadata YAML file captures required data. The format of the data
+ is defined in the error metadata file. An example of an error metadata YAML
+ file can be found [here][metadata-example].
+
+[error-example]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Common/File.errors.yaml
+[metadata-example]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Common/File.metadata.yaml
## Logging to journal
- * Applications can log debug/error information to the journal using
- the **log** API
- - Refer to [log.hpp](https://github.com/openbmc/phosphor-logging/blob/master/phosphor-logging/log.hpp)
- * Applications can commit errors to the journal using the **report** or
+
+- Applications can log debug/error information to the journal using
+ the **log** API
+ - Refer to [log.hpp][log-header].
+- Applications can commit errors to the journal using the **report** or
**commit** API
- - Refer to [elog.hpp](https://github.com/openbmc/phosphor-logging/blob/master/phosphor-logging/elog.hpp)
- - Logging entry D-Bus objects are created for the committed errors.
+ - Refer to [elog.hpp][elog-header].
+ - Logging entry D-Bus objects are created for the committed errors.
+
+[log-header]: https://github.com/openbmc/phosphor-logging/blob/master/phosphor-logging/log.hpp
+[elog-header]: https://github.com/openbmc/phosphor-logging/blob/master/phosphor-logging/elog.hpp
## Delete All interface
-* Use the [DeleteAll.interface.yaml](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Collection/DeleteAll.interface.yaml)
- for deleting all the logging entries.
+- Use the [DeleteAll.interface.yaml][deleteall] for deleting all the logging
+ entries.
+
+[deleteall]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Collection/DeleteAll.interface.yaml
## REST commands
+
### Logging in
- * Before you can do anything, you need to first login.
-```
-$export bmc=xx.xx.xx.xx
-$curl -c cjar -b cjar -k -X POST -H "Content-Type: application/json" -d '{"data": [ "root", "<root password>" ] }' https://{$bmc}/login
+
+- Before you can do anything, you need to first login.
+
+```sh
+export bmc=xx.xx.xx.xx
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": [ "root", "<root-password>" ] }' \
+ https://{$bmc}/login
```
### List logging child objects recursively
-```
-$curl -c cjar -b cjar -k https://${bmc}/xyz/openbmc_project/logging/list
+
+```sh
+curl -c cjar -b cjar -k https://${bmc}/xyz/openbmc_project/logging/list
```
### List logging attributes of child objects recursively
-```
-$curl -c cjar -b cjar -s -k -H 'Content-Type: application/json'; -d '{"data" : []}' -X GET https://${bmc}/xyz/openbmc_project/logging/enumerate
+
+```sh
+curl -c cjar -b cjar -s -k -H "Content-Type: application/json" -X GET \
+ -d '{"data" : []}' \
+ https://${bmc}/xyz/openbmc_project/logging/enumerate
```
### Delete logging entries
-```
-$curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/logging/entry/<entry num>/action/Delete
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": []}' \
+ https://${bmc}/xyz/openbmc_project/logging/entry/<entry-num>/action/Delete
```
### Delete all logging entries
-```
-$curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll -d "{\"data\": [] }"
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d "{\"data\": [] }" \
+ https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
```
diff --git a/yaml/xyz/openbmc_project/MCTP/README.md b/yaml/xyz/openbmc_project/MCTP/README.md
index cac4a80..57a5044 100644
--- a/yaml/xyz/openbmc_project/MCTP/README.md
+++ b/yaml/xyz/openbmc_project/MCTP/README.md
@@ -1,4 +1,4 @@
-## Overview
+# Overview
MCTP D-Bus interfaces are implemented by the MCTP control process daemon
alias mcptd and aids in the discovery of MCTP enabled devices by application
@@ -12,7 +12,7 @@
the removal of the MCTP endpoints and removes the D-Bus objects corresponding to
those endpoints. MCTP bridges are not modelled in the D-Bus.
-### D-Bus object modelling
+## D-Bus object modelling
The root D-Bus object path for the mctpd is `/xyz/openbmc_project/mctp`. There
will be a D-Bus object for every endpoint that is discovered by the mctpd.
@@ -36,8 +36,7 @@
network ID then it is exposed on the D-Bus. The D-Bus object path is
`xyz/openbmc_project/mctp/<NetworkId>` where NetworkId is the locally
defined [network identfier][1] and implements the
- `xyz.openbmc_project.Common.UUID` interface and the UUID property is the MCTP
- network ID.
+`xyz.openbmc_project.Common.UUID` interface and the UUID property is the MCTP
+network ID.
[1]: https://github.com/openbmc/docs/blob/master/designs/mctp/mctp-kernel.md#addressing
-
diff --git a/yaml/xyz/openbmc_project/Network/README.md b/yaml/xyz/openbmc_project/Network/README.md
index 100ae86..555bc49 100644
--- a/yaml/xyz/openbmc_project/Network/README.md
+++ b/yaml/xyz/openbmc_project/Network/README.md
@@ -3,8 +3,9 @@
## Overview
A Network Manager is a daemon which handles network management operations.
-It must implement the `xyz.openbmc_project.Network.SystemConfiguration.interface`
-and `org.freedesktop.DBus.ObjectManager`.
+It must implement the
+`xyz.openbmc_project.Network.SystemConfiguration.interface` and
+`org.freedesktop.DBus.ObjectManager`.
When the network manager daemon comes up, it should create objects
implementing physical link/virtual interfaces such as
@@ -25,7 +26,7 @@
## D-Bus Objects
-#### Interface Objects
+### Interface Objects
Interface objects can be physical as well as virtual.
@@ -34,7 +35,7 @@
E.g. `/xyz/openbmc_project/network/<interfacename>`
-#### IP Address Objects
+### IP Address Objects
There can be multiple IP address objects under an interface object.
These objects can be deleted by the delete function.
@@ -47,7 +48,7 @@
`/xyz/openbmc_project/network/<interface>/ipv6/<id>`
-#### Network Configuration Object
+### Network Configuration Object
The network configuration object will have system configuration parameters:
@@ -55,166 +56,249 @@
## Commands
-#### Create Static IPv4 Address
+### Create Static IPv4 Address
+```sh
+busctl call xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/<interface> \
+ xyz.openbmc_project.Network.IP.Create \
+ IP ssys "xyz.openbmc_project.Network.IP.Protocol.IPv4" \
+ "<IP Address>" <Netmask Prefix> "<Network Gateway>"
```
-busctl call xyz.openbmc_project.Network /xyz/openbmc_project/network/<interface> xyz.openbmc_project.Network.IP.Create IP ssys "xyz.openbmc_project.Network.IP.Protocol.IPv4" "<IP Address>" <Netmask Prefix> "<Network Gateway>"
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data":["xyz.openbmc_project.Network.IP.Protocol.IPv4","<IP Address>", <Netmask Prefix>, "<Network Gateway>"]
-}' https://${bmc}/xyz/openbmc_project/network/<interface>/action/IP
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{
+ "data": [
+ "xyz.openbmc_project.Network.IP.Protocol.IPv4",
+ "<IP Address",
+ <Netmask Prefix>,
+ "<Network Gateway>"
+ ]
+ }' \
+ https://${bmc}/xyz/openbmc_project/network/<interface>/action/IP
```
E.g.
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data":["xyz.openbmc_project.Network.IP.Protocol.IPv4","8.8.8.8", 24, "8.8.8.0"]}' https://${bmc}/xyz/openbmc_project/network/eth0/action/IP
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{
+ "data": [
+ "xyz.openbmc_project.Network.IP.Protocol.IPv4",
+ "8.8.8.8",
+ 24,
+ "8.8.8.0"
+ ]
+ }' \
+ https://${bmc}/xyz/openbmc_project/network/eth0/action/IP
```
-Note: After creating the IP address object enumerate the network interface object to get the IPv4 id.
+Note: After creating the IP address object enumerate the network interface
+object to get the IPv4 id.
-#### Delete IPv4 Address
+### Delete IPv4 Address
-```
-busctl call xyz.openbmc_project.Network /xyz/openbmc_project/network/<interface>/ipv4/<id> xyz.openbmc_project.Object.Delete Delete
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/network/<interface>/ipv4/<id>
+```sh
+busctl call xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/<interface>/ipv4/<id> \
+ xyz.openbmc_project.Object.Delete Delete
```
-#### Default Gateway
-
-##### Get
-
-```
-busctl get-property xyz.openbmc_project.Network /xyz/openbmc_project/network/config xyz.openbmc_project.Network.SystemConfiguration DefaultGateway
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" https://${bmc}/xyz/openbmc_project/network/config/attr/DefaultGateway
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X DELETE \
+ https://${bmc}/xyz/openbmc_project/network/<interface>/ipv4/<id>
```
-##### Set
+### Default Gateway
+#### Get
+
+```sh
+busctl get-property xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/config \
+ xyz.openbmc_project.Network.SystemConfiguration DefaultGateway
```
-busctl set-property xyz.openbmc_project.Network /xyz/openbmc_project/network/config xyz.openbmc_project.Network.SystemConfiguration DefaultGateway s "<DefaultGateway>"
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" \
+ https://${bmc}/xyz/openbmc_project/network/config/attr/DefaultGateway
```
+
+#### Set
+
+```sh
+busctl set-property xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/config \
+ xyz.openbmc_project.Network.SystemConfiguration \
+ DefaultGateway s "<DefaultGateway>"
```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -d '{"data": "<DefaultGateway>"}' https://${bmc}/xyz/openbmc_project/network/config/attr/DefaultGateway
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
+ -d '{"data": "<DefaultGateway>"}' \
+ https://${bmc}/xyz/openbmc_project/network/config/attr/DefaultGateway
```
NOTE: The default gateway must be pingable, if not 0.0.0.0 will be used.
-#### HostName
+### HostName
-##### Get
+#### Get
-```
-busctl get-property xyz.openbmc_project.Network /xyz/openbmc_project/network/config xyz.openbmc_project.Network.SystemConfiguration HostName
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" https://${bmc}/xyz/openbmc_project/network/config/attr/HostName
+```sh
+busctl get-property xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/config \
+ xyz.openbmc_project.Network.SystemConfiguration HostName
```
-##### Set
-
-```
-busctl set-property xyz.openbmc_project.Network /xyz/openbmc_project/network/config xyz.openbmc_project.Network.SystemConfiguration HostName s "<HostName>"
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -d '{"data": "<HostName>"}' https://${bmc}/xyz/openbmc_project/network/config/attr/HostName
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" \
+ https://${bmc}/xyz/openbmc_project/network/config/attr/HostName
```
-#### DHCP
+#### Set
-##### Get
-
-```
-busctl get-property xyz.openbmc_project.Network /xyz/openbmc_project/network/eth0 xyz.openbmc_project.Network.EthernetInterface DHCPEnabled
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" https://${bmc}/xyz/openbmc_project/network/eth0/attr/DHCPEnabled
+```sh
+busctl set-property xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/config \
+ xyz.openbmc_project.Network.SystemConfiguration HostName s "<HostName>"
```
-##### Enable
-
-```
-busctl set-property xyz.openbmc_project.Network /xyz/openbmc_project/network/eth0 xyz.openbmc_project.Network.EthernetInterface DHCPEnabled b 1
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT -d '{"data": 1}' https://${bmc}/xyz/openbmc_project/network/eth0/attr/DHCPEnabled
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
+ -d '{"data": "<HostName>"}' \
+ https://${bmc}/xyz/openbmc_project/network/config/attr/HostName
```
-#### MAC Address
+### DHCP
-##### Get
+#### Get
-```
-busctl get-property xyz.openbmc_project.Network /xyz/openbmc_project/network/eth0 xyz.openbmc_project.Network.MACAddress MACAddress
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" https://${bmc}/xyz/openbmc_project/network/<interface>/attr/MACAddress
+```sh
+busctl get-property xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/eth0 \
+ xyz.openbmc_project.Network.EthernetInterface DHCPEnabled
```
-##### Set
-
-```
-busctl set-property xyz.openbmc_project.Network /xyz/openbmc_project/network/<interface> xyz.openbmc_project.Network.MACAddress MACAddress s "<MAC Address>"
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/jon" -X PUT -d '{"data": "<MAC Address>" }' https://${bmc}/xyz/openbmc_project/network/<interface>/attr/MACAddress
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" \
+ https://${bmc}/xyz/openbmc_project/network/eth0/attr/DHCPEnabled
```
-NOTE: MAC address should be a local admin MAC (2nd bit of first byte should be on).
+#### Enable
-#### Network Factory Reset
-
-```
-busctl call xyz.openbmc_project.Network /xyz/openbmc_project/network xyz.openbmc_project.Common.FactoryReset Reset
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data":[] }' https://${bmc}/xyz/openbmc_project/network/action/Reset
+```sh
+busctl set-property xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/eth0 \
+ xyz.openbmc_project.Network.EthernetInterface DHCPEnabled b 1
```
-#### VLAN
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
+ -d '{"data": 1}' \
+ https://${bmc}/xyz/openbmc_project/network/eth0/attr/DHCPEnabled
+```
-##### Create
+### MAC Address
+#### Get
+
+```sh
+busctl get-property xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/eth0 \
+ xyz.openbmc_project.Network.MACAddress MACAddress
```
-busctl call xyz.openbmc_project.Network /xyz/openbmc_project/network xyz.openbmc_project.Network.VLAN.Create VLAN su "<interface>" <VLAN id>
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" \
+ https://${bmc}/xyz/openbmc_project/network/<interface>/attr/MACAddress
```
+
+#### Set
+
+```sh
+busctl set-property xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/<interface> \
+ xyz.openbmc_project.Network.MACAddress MACAddress s "<MAC Address>"
```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data":["<interface>", <VLAN id>] }' https://${bmc}/xyz/openbmc_project/network/action/VLAN
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
+ -d '{"data": "<MAC Address>" }' \
+ https://${bmc}/xyz/openbmc_project/network/<interface>/attr/MACAddress
+```
+
+NOTE: MAC address should be a local admin MAC (2nd bit of first byte should be
+on).
+
+### Network Factory Reset
+
+```sh
+busctl call xyz.openbmc_project.Network /xyz/openbmc_project/network \
+ xyz.openbmc_project.Common.FactoryReset Reset
+```
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data":[] }' https://${bmc}/xyz/openbmc_project/network/action/Reset
+```
+
+### VLAN
+
+#### Create
+
+```sh
+busctl call xyz.openbmc_project.Network /xyz/openbmc_project/network \
+ xyz.openbmc_project.Network.VLAN.Create VLAN su "<interface>" <VLAN id>
+```
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data":["<interface>", <VLAN id>] }' \
+ https://${bmc}/xyz/openbmc_project/network/action/VLAN
```
E.g.
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST -d '{"data":["eth0",50] }' https://${bmc}/xyz/openbmc_project/network/action/VLAN
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data":["eth0",50] }' \
+ https://${bmc}/xyz/openbmc_project/network/action/VLAN
```
-##### Delete
+#### Delete
+```sh
+busctl call xyz.openbmc_project.Network \
+ /xyz/openbmc_project/network/<VLAN interface> \
+ xyz.openbmc_project.Object.Delete Delete
```
-busctl call xyz.openbmc_project.Network /xyz/openbmc_project/network/<VLAN interface> xyz.openbmc_project.Object.Delete Delete
-```
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/network/<VLAN interface>
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X DELETE \
+ https://${bmc}/xyz/openbmc_project/network/<VLAN interface>
```
E.g.
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/network/eth0_50
+
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" -X DELETE \
+ https://${bmc}/xyz/openbmc_project/network/eth0_50
```
-##### Enumerate
+#### Enumerate
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" https://${bmc}/xyz/openbmc_project/network/<VLAN interface>/enumerate
+```sh
+curl -c cjar -b cjar -k -H "Content-Type: application/json" \
+ https://${bmc}/xyz/openbmc_project/network/<VLAN interface>/enumerate
```
-#### IPMI VLAN and IP
+### IPMI VLAN and IP
-##### Create
+#### Create
-```
+```sh
ipmitool -I dbus lan set 1 ipsrc static
ipmitool -I dbus lan set 1 ipaddr <IP address>
@@ -231,9 +315,9 @@
NOTE: It takes 4-5 seconds to create the VLAN and configure the IP.
If a VLAN interface is not desired don't set the VLAN id above.
-##### Delete
+#### Delete
-```
+```sh
ipmitool -I dbus lan set 1 vlan id off
ipmitool -I dbus raw 0x06 0x40 // To the save settings
diff --git a/yaml/xyz/openbmc_project/Smbios/README.md b/yaml/xyz/openbmc_project/Smbios/README.md
index d81d72d..d7229d8 100644
--- a/yaml/xyz/openbmc_project/Smbios/README.md
+++ b/yaml/xyz/openbmc_project/Smbios/README.md
@@ -1,22 +1,27 @@
# SMBIOS MDR V2
## Overview
+
SMBIOS MDR V2 service exposes D-Bus methods for SMBIOS Version 2 operations.
### SMBIOS MDR V2 Interface
+
SMBIOS MDR V2 interface `xyz.openbmc_project.Smbios.MDR_V2` provides following
methods.
+
#### methods
-* GetDirectoryInformation - Get the directory with directory index.
-* GetDataInformation - Get the data information with id index and data set ID.
-* SendDirectoryInformation - Send directory information to SMBIOS directory.
-* GetDataOffer - Get data set ID.
-* SendDataInformation - Send data information with directory index.
-* FindIdIndex - Find id index by data info.
-* SynchronizeDirectoryCommonData - Synchronize directory common data before
-SMBIOS data start to transfer.
-* AgentSynchronizeData - Synchronize SMBIOS data from file after data transfer
-complete.
+
+- GetDirectoryInformation - Get the directory with directory index.
+- GetDataInformation - Get the data information with id index and data set ID.
+- SendDirectoryInformation - Send directory information to SMBIOS directory.
+- GetDataOffer - Get data set ID.
+- SendDataInformation - Send data information with directory index.
+- FindIdIndex - Find id index by data info.
+- SynchronizeDirectoryCommonData - Synchronize directory common data before
+ SMBIOS data start to transfer.
+- AgentSynchronizeData - Synchronize SMBIOS data from file after data transfer
+ complete.
#### properties
-* DirEntries - Numbers of directory entries. Default: 0
+
+- DirEntries - Numbers of directory entries. Default: 0
diff --git a/yaml/xyz/openbmc_project/Software/README.md b/yaml/xyz/openbmc_project/Software/README.md
index 2416123..9726c44 100644
--- a/yaml/xyz/openbmc_project/Software/README.md
+++ b/yaml/xyz/openbmc_project/Software/README.md
@@ -5,72 +5,72 @@
There are two types of processes involved in software version management and
code update:
-1. *ImageManager* - This is a process which manages a collection of, likely
- temporary, images located somewhere in a file system.
- These are images which are available on the BMC for update.
-2. *ItemUpdater* - This is a process which manages specific storage elements,
- likely for an inventory item, to determine which software
- versions are installed onto that item. A specific example of
- this would be a process that controls and updates the BIOS
- flash module for a managed host.
+1. _ImageManager_ - This is a process which manages a collection of, likely
+ temporary, images located somewhere in a file system.
+ These are images which are available on the BMC for update.
+2. _ItemUpdater_ - This is a process which manages specific storage elements,
+ likely for an inventory item, to determine which software
+ versions are installed onto that item. A specific example of
+ this would be a process that controls and updates the BIOS
+ flash module for a managed host.
-A simple system design would be to include a single *ImageManager* and two
+A simple system design would be to include a single _ImageManager_ and two
*ItemUpdater*s: one for the BMC itself and one for the Host.
### ImageManager
-The *ImageManager* would provide interfaces at `/xyz/openbmc_project/software`
+The _ImageManager_ would provide interfaces at `/xyz/openbmc_project/software`
to allow additional images to be added to the BMC, such as Object.Add() for
-REST and DownloadViaTFTP() for TFTP. The standard Object.Delete() interface
+REST and DownloadViaTFTP() for TFTP. The standard Object.Delete() interface
would also be provided to facilitate removing images which are no longer
-needed. Images maintained in the file system would be presented as a
+needed. Images maintained in the file system would be presented as a
corresponding `/xyz/openbmc_project/software/<id>` object. In addition, the
`xyz.openbmc_project.Common.FilePath` interface would be provided to specify
the location of the image.
-It is assumed that the *ImageManager* has [at least] a bare minimum amount of
+It is assumed that the _ImageManager_ has [at least] a bare minimum amount of
parsing knowledge, perhaps due to a common image format, to allow it to
populate all of the properties of `xyz.openbmc_project.Software.Version` and
-`xyz.openbmc_project.Inventory.Decorator.Compatible`. *ItemUpdater*s will
+`xyz.openbmc_project.Inventory.Decorator.Compatible`. *ItemUpdater*s will
likely listen for standard D-Bus signals to identify new images being created.
### ItemUpdater
-The *ItemUpdater* is responsible for monitoring for new `Software.Version`
+The _ItemUpdater_ is responsible for monitoring for new `Software.Version`
elements being created to identify versions that are applicable to the
-inventory element(s) it is managing. The *ItemUpdater* should dynamically
+inventory element(s) it is managing. The _ItemUpdater_ should dynamically
create an `xyz.openbmc_project.Software.Activation` interface under
`/xyz/openbmc_project/software/`, an association of type
`{active_image,software_version}` between the `Software.Version` and
`Software.Activation` under `/xyz/openbmc_project/software/`, and an
association of type `{activation,item}` between the `Inventory.Item` and
-`Software.Activation` under `/xyz/openbmc_project/software/<id>`. Application
+`Software.Activation` under `/xyz/openbmc_project/software/<id>`. Application
of the software image is then handled through the `RequestedActivation`
property of the `Software.Activation` interface.
-In many cases, the *ItemUpdater*'s creation of the `Software.Activation`
-interface will be at the exact same path as the *ImageManager*'s
-`Software.Version` instance (ie. `/xyz/openbmc_project/software/<id>`). This is
+In many cases, the _ItemUpdater_'s creation of the `Software.Activation`
+interface will be at the exact same path as the _ImageManager_'s
+`Software.Version` instance (ie. `/xyz/openbmc_project/software/<id>`). This is
appropriate when the software image can be applied to exactly one device in the
-system at exactly one storage location. In cases where multiple devices could
+system at exactly one storage location. In cases where multiple devices could
updated with the same image or multiple locations in the same device could hold
the same image (such as a primary / secondary flash bank relationship), the
-*ItemUpdater* should create `Software.Activation` interfaces as a sub-path of
+_ItemUpdater_ should create `Software.Activation` interfaces as a sub-path of
the corresponding image, such as `/xyz/openbmc_project/software/<id>/<device>`.
-The *ItemUpdater* should, if possible, also create its own
+The _ItemUpdater_ should, if possible, also create its own
`xyz.openbmc_project.Software.Version` objects, and appropriate associations
for software versions that are currently present on the managed inventory
-element(s). This provides a mechanism for interrogation of the
-software versions when the *ImageManager* no longer contains a copy.
+element(s). This provides a mechanism for interrogation of the
+software versions when the _ImageManager_ no longer contains a copy.
## Details
### Image Identifier
-The *ImageManager* and *ItemUpdater* should use a common, though perhaps
+The _ImageManager_ and _ItemUpdater_ should use a common, though perhaps
implementation specific, algorithm for the `<id>` portion of a D-Bus path for
-each `Software.Version`. This allows the same software version to be contained
+each `Software.Version`. This allows the same software version to be contained
in multiple locations but represented by the same object path.
A reasonable algorithm might be:
@@ -79,15 +79,15 @@
### Compatibility
Identifying that a particular Software image is for a particular system element
-can be challenging. For the BMC, two different images may both be the same size
-but for vastly different hardware. If the image for one system is applied onto
+can be challenging. For the BMC, two different images may both be the same size
+but for vastly different hardware. If the image for one system is applied onto
the BMC for another it is quite possible that the image won't even boot
-properly. It is therefore important to be able to specify more details than
+properly. It is therefore important to be able to specify more details than
simply "BMC" or "Host".
Early on implementations used the `Software.Version.Purpose` property and a
custom string in the `Software.ExtendedVersion` to align software images with
-appropriate hardware. This lead to an ever-increasing set of `Purpose`
+appropriate hardware. This lead to an ever-increasing set of `Purpose`
enumeration values and inconsistent implementations of software update routines.
The `Inventory.Decorator.Compatible` interface was introduced to give
@@ -97,23 +97,23 @@
consistent mapping of `Software.Version` instances to the system element the
image is applicable to.
-At the same path as the `Software.Version`, an *ImageManager* should create an
+At the same path as the `Software.Version`, an _ImageManager_ should create an
`xyz.openbmc_project.Inventory.Decorator.Compatible` interface containing
strings identifying the system element this image can be applied to.
Correspondingly, the Inventory Item corresponding to the system element should
-have the same string in its `Inventory.Decorator.Compatible` interface. These
+have the same string in its `Inventory.Decorator.Compatible` interface. These
strings shall be of the following format:
-* `<org>.Software.Element.<identifer>.Type.<type>`
+- `<org>.Software.Element.<identifer>.Type.<type>`
Where:
-* `<org>` corresponds to the organization owning the `<identifier>`, such as
+- `<org>` corresponds to the organization owning the `<identifier>`, such as
`xyz.openbmc_project` or `com.foo_corp`.
-* `<identifier>` is a unique name for the element, such as `SystemFoo` or
- `BoardBar`. Typically these would be code names for the hardware element such
+- `<identifier>` is a unique name for the element, such as `SystemFoo` or
+ `BoardBar`. Typically these would be code names for the hardware element such
as `Witherspoon`.
-* `<type>` is an identifier for sub-element the image corresponds to and is
+- `<type>` is an identifier for sub-element the image corresponds to and is
documented in the `<org>/Software/Element/<identifier>.interface` file under
the `Type` enumeration.
@@ -125,7 +125,7 @@
If an image contains sub-sections which can be applied to multiple system
elements, the image should contain `Compatible` strings for each sub-section.
-It is expected that the *ItemUpdater* is aware of how to find the sub-section
+It is expected that the _ItemUpdater_ is aware of how to find the sub-section
appropriate for any element(s) being Activated.
### Activation States
@@ -133,106 +133,106 @@
`xyz.openbmc_project.Software.Activation` has a property Activation that can
be in the following states:
-1. *NotReady* - Indicating that the *ItemUpdater* is still processing the
- version and it is therefore not ready for activation. This
- might be used on an image that has a security header while
- verification is being performed.
-2. *Invalid* - Indicating that, while the `Software.Version.Purpose` suggested
- the image was valid for a managed element, a detailed analysis
- by the *ItemUpdater* showed that it was not. Reasons may
- include image corruption detected via CRC or security
- verification failure. An event may be recorded with additional
- details.
-3. *Ready* - Indicating that the `Software.Version` can be activated.
-4. *Activating* - Indicating that the `Software.Version` is in the process of
- being activated.
-5. *Active* - The `Software.Version` is active on the managed element. Note
- that on systems with redundant storage devices a version might
- be *Active* but not the primary version.
-6. *Failed* - The `Software.Version` or the storage medium on which it is stored
- has failed. An event may be recorded with additional details.
-7. *Staged* - The `Software.Version` is in staged flash region. This will be
- moved from staged flash region to active flash region upon reset.
- Staged flash region is the designated flash area which is used to
- store the integrity validated firmware image that comes in during
- firmware update process. Note that the staged image is not
- necessarily a functional firmware.
+1. _NotReady_ - Indicating that the _ItemUpdater_ is still processing the
+ version and it is therefore not ready for activation. This
+ might be used on an image that has a security header while
+ verification is being performed.
+2. _Invalid_ - Indicating that, while the `Software.Version.Purpose` suggested
+ the image was valid for a managed element, a detailed analysis
+ by the _ItemUpdater_ showed that it was not. Reasons may
+ include image corruption detected via CRC or security
+ verification failure. An event may be recorded with additional
+ details.
+3. _Ready_ - Indicating that the `Software.Version` can be activated.
+4. _Activating_ - Indicating that the `Software.Version` is in the process of
+ being activated.
+5. _Active_ - The `Software.Version` is active on the managed element. Note
+ that on systems with redundant storage devices a version might
+ be _Active_ but not the primary version.
+6. _Failed_ - The `Software.Version` or the storage medium on which it is stored
+ has failed. An event may be recorded with additional details.
+7. _Staged_ - The `Software.Version` is in staged flash region. This will be
+ moved from staged flash region to active flash region upon reset.
+ Staged flash region is the designated flash area which is used to
+ store the integrity validated firmware image that comes in during
+ firmware update process. Note that the staged image is not
+ necessarily a functional firmware.
### Image Apply Time
`xyz.openbmc_project.Software.ApplyTime` has a property called
RequestedApplyTime that indicates when the newly applied software image will
-be activated. RequestedApplyTime is a D-Bus property that maps to the
+be activated. RequestedApplyTime is a D-Bus property that maps to the
"ApplyTime" property in the Redfish UpdateService schema. Below are the
currently supported values and the value can be supplied through
HttpPushUriApplyTime object:
-1. *Immediate* - Indicating that the `Software.Version` needs to be activated
- immediately.
-2. *OnReset* - Indicating that the `Software.Version` needs to be activated
- on the next reset.
+1. _Immediate_ - Indicating that the `Software.Version` needs to be activated
+ immediately.
+2. _OnReset_ - Indicating that the `Software.Version` needs to be activated
+ on the next reset.
### Blocking State Transitions
It is sometimes useful to block a system state transition while activations
-are being performed. For example, we do not want to boot a managed host while
-its BIOS is being updated. In order to facilitate this, the interface
+are being performed. For example, we do not want to boot a managed host while
+its BIOS is being updated. In order to facilitate this, the interface
`xyz.openbmc_project.Software.ActivationBlocksTransition` may be added to any
-object with `Software.Activation` to indicate this behavior. See that
+object with `Software.Activation` to indicate this behavior. See that
interface for more details.
It is strongly suggested that any activations are completed prior to a managed
-BMC reboot. This could be facilitated with systemd service specifiers.
+BMC reboot. This could be facilitated with systemd service specifiers.
### Software Versions
-All version identifiers are implementation specific strings. No format
+All version identifiers are implementation specific strings. No format
should be assumed.
Some software versions are a collection of images, each with their own version
-identifiers. The `xyz.openbmc_project.Software.ExtendedVersion` interface
+identifiers. The `xyz.openbmc_project.Software.ExtendedVersion` interface
can be added to any `Software.Version` to express the versioning of the
aggregation.
### Activation Progress
The `xyz.openbmc_project.Software.ActivationProgress` interface is provided
-to show current progress while a software version is *Activating*. It is
-expected that an *ItemUpdater* will dynamically create this interface while
-the version is *Activating* and dynamically remove it when the activation is
+to show current progress while a software version is _Activating_. It is
+expected that an _ItemUpdater_ will dynamically create this interface while
+the version is _Activating_ and dynamically remove it when the activation is
complete (or failed).
### Handling Redundancy
The `xyz.openbmc_project.Software.RedundancyPriority` interface is provided to
express the relationship between two (or more) software versions activated for
-a single managed element. It is expected that all installed versions are listed
-as *Active* and the `Priority` shows which version is the primary and which are
+a single managed element. It is expected that all installed versions are listed
+as _Active_ and the `Priority` shows which version is the primary and which are
available for redundancy.
Prior to `Activation`, it can be useful to indicate a desired
-`RedundancyPriority`. This can be done by setting the `Priority` on the
-`RequestedRedundancyPriority` interface. Some *ItemUpdater* implementations
+`RedundancyPriority`. This can be done by setting the `Priority` on the
+`RequestedRedundancyPriority` interface. Some _ItemUpdater_ implementations
may not honor this field or be unable to comply with the request, in which
case the resulting `Activation` may result in one of two conditions: a
-`ActivationState = Failed` or an `ActivateState = Active`` with a
+`ActivationState = Failed` or an `ActivateState = Active` with a
`RedundancyPriority = 0 (High)`.
### Image Clean Up
-An *ItemUpdater* is responsible for garabage collecting images contained on the
-elements it is managing. Often an element can only contain a single image so
-this is a natural side-effect of the update process. In other cases, the
-*ItemUpdater* may remove images based on the `RedundancyPriority` assigned to an
+An _ItemUpdater_ is responsible for garabage collecting images contained on the
+elements it is managing. Often an element can only contain a single image so
+this is a natural side-effect of the update process. In other cases, the
+_ItemUpdater_ may remove images based on the `RedundancyPriority` assigned to an
image.
-The *ItemManager* should expose `Object.Delete()` methods to remove images from
-the BMC filesystem. It is possible that some *ItemUpdater*s will call this
+The _ItemManager_ should expose `Object.Delete()` methods to remove images from
+the BMC filesystem. It is possible that some *ItemUpdater*s will call this
method once the `Version` is successfully activated.
-In some designs there may be multiple *ItemUpdater* instances which are handling
+In some designs there may be multiple _ItemUpdater_ instances which are handling
update for different system elements, all of which can potentially apply the
-same software image (as in a multi-host design). The *ItemManager* may
+same software image (as in a multi-host design). The _ItemManager_ may
optionally monitor the `Software.Activation` signals and actively garbage
collect an image once all `Software.Activation` under the `.../software/<id>`
path are either `Active` or `Staged`.
@@ -244,7 +244,7 @@
should be added to along side `Software.Version` to represent
its state from the same service.
-```
+```sh
busctl introspect $SERVICE /xyz/openbmc_project/software/software_0
...
xyz.openbmc_project.Software.Version interface -
@@ -255,36 +255,35 @@
...
```
-The *ItemUpdater* manages the fields such as `WriteProtected` to help provide
+The _ItemUpdater_ manages the fields such as `WriteProtected` to help provide
information on how the software is managed.
## REST use-cases
-### Find all software versions on the system, either active or available.
+### Find all software versions on the system, either active or available
-List `/xyz/openbmc_project/software/`. This list can be filtered to just
+List `/xyz/openbmc_project/software/`. This list can be filtered to just
active listing `.../software/active/` and following the `software_version`
-association to retrieve version information. To list just "functional" or
+association to retrieve version information. To list just "functional" or
running versions list `/xyz/openbmc_project/software/functional/`.
-### Find all software versions on a managed element.
+### Find all software versions on a managed element
List `/xyz/openbmc_project/inventory/.../<item>/activation` association.
### Upload new version via REST
-HTTP PUT to `/xyz/openbmc_project/software/`. *ImageManager* will assign the
+HTTP PUT to `/xyz/openbmc_project/software/`. _ImageManager_ will assign the
`<id>` when called for Object.Add().
### Upload new version via ???
Need additional interfaces defined for alternative upload methods.
-### Activate a version.
+### Activate a version
-Modify `RequestedActivation` to *Active* on the desired `Activation`.
+Modify `RequestedActivation` to _Active_ on the desired `Activation`.
-### Switch primary image.
+### Switch primary image
Set `Priority` to 0 on the desired `RedundancyPriority` interface.
-
diff --git a/yaml/xyz/openbmc_project/State/README.md b/yaml/xyz/openbmc_project/State/README.md
index 8bbf447..0cfc004 100644
--- a/yaml/xyz/openbmc_project/State/README.md
+++ b/yaml/xyz/openbmc_project/State/README.md
@@ -3,61 +3,62 @@
## Overview
The goal of the phosphor-state-manager repository is to control and track the
-states of the different software entities in a system. All users will usually
+states of the different software entities in a system. All users will usually
implement the BMC state interfaces, and some, when creating servers will do the
-Host and Chassis state interfaces. These interfaces will be the mechanism by
+Host and Chassis state interfaces. These interfaces will be the mechanism by
which you determine the state of their corresponding instances, as well as
-reboot the BMC and hosts, and turn on and off power to the chassis. The
+reboot the BMC and hosts, and turn on and off power to the chassis. The
interfaces are designed in a way to support a many to many mappings of each
interface.
-There are three states to track and control on a BMC based server. The states
+There are three states to track and control on a BMC based server. The states
below in () represent the actual parameter name as found in
`/xyz/openbmc_project/state/`+`/bmcX,/hostY,/chassisZ` where X,Y,Z are the
-instances (in most cases 0). For all three states, the software tracks a
+instances (in most cases 0). For all three states, the software tracks a
current state, and a requested transition.
-1. *BMC* : The BMC has either started all required systemd services and reached
-it's required target (Ready) or it's on it's way there (NotReady). Users can
-request a (Reboot).
+1. _BMC_ : The BMC has either started all required systemd services and reached
+ it's required target (Ready) or it's on it's way there (NotReady). Users can
+ request a (Reboot).
-2. *Host* : The host is either (Off), (Running), or it's (Quiesced).
-Running simply implies that the processors are executing instructions. Users
-can request the host be in a (Off), (On), or (Reboot) state. More details on
-different Reboot options below.
-Quiesced means the host OS is in a quiesce state and the system should be
-checked for errors. For more information refer to
-[Error Handling of systemd](https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md#error-handling-of-systemd)
+2. _Host_ : The host is either (Off), (Running), or it's (Quiesced).
+ Running simply implies that the processors are executing instructions. Users
+ can request the host be in a (Off), (On), or (Reboot) state. More details on
+ different Reboot options below.
+ Quiesced means the host OS is in a quiesce state and the system should be
+ checked for errors. For more information refer to
+ [Error Handling of systemd][1].
-3. *Chassis* : The chassis is either (Off) or (On)
-This represents the state of power to the chassis. The Chassis being on
-is a pre-req to the Host being running. Users can request for the chassis to be
-(Off) or (On). A transition to one or the other is implied by the transition
-not matching the current state.
+3. _Chassis_ : The chassis is either (Off) or (On)
+ This represents the state of power to the chassis. The Chassis being on
+ is a pre-req to the Host being running. Users can request for the chassis to
+ be (Off) or (On). A transition to one or the other is implied by the
+ transition not matching the current state.
-A simple system design would be to include a single *BMC*, *Host*, and
-*Chassis*.
+A simple system design would be to include a single _BMC_, _Host_, and
+_Chassis_.
Details of the properties and their valid settings can be found in the state
-manager dbus interface [specification](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/)
+manager dbus interface [specification][2].
### BMC
-The *BMC* would provide interfaces at
+The _BMC_ would provide interfaces at
`/xyz/openbmc_project/state/bmc<instance>`
-### *Host*
+### _Host_
-The *Host* would provide interfaces at
+The _Host_ would provide interfaces at
`/xyz/openbmc_project/state/host<instance>`
-### *Chassis*
+### _Chassis_
-The *Chassis* would provide interfaces at
+The _Chassis_ would provide interfaces at
`/xyz/openbmc_project/state/chassis<instance>`
-### *Chassis System*
-This is an instance under *Chassis* and provide interface at
+### _Chassis System_
+
+This is an instance under _Chassis_ and provide interface at
`/xyz/openbmc_project/state/chassis_system<instance>`
Instance 0 (chassis_system0) will be treated as a complete chassis system
@@ -77,24 +78,24 @@
`chassis0` and `host0` are special. If they exist, they are guaranteed to talk
to the system as a whole as if it was a system with one BMC, one chassis and
one host. If there are multiple hosts, then bmc0/chassis0/host0
-will *not* exist. In the event of multiple BMCs or Chassis, bmc0 and chassis0
+will _not_ exist. In the event of multiple BMCs or Chassis, bmc0 and chassis0
will act on all entities as if they are one (if at all possible).
This behaviour means that existing code will continue to work, or error out
if the request would be ambiguous and probably not what the user wanted.
For example, if a system has two chassis, only powering off the first chassis
-(while leaving the second chassis on) is certainly *not* what the API user had
+(while leaving the second chassis on) is certainly _not_ what the API user had
in mind as they likely desired to hard power off the system. In such a
multi-chassis system, starting counting from 1 rather than 0 would avoid this
-problem, while allowing an API user to *intentionally* only power off one
+problem, while allowing an API user to _intentionally_ only power off one
chassis. With chassis0 being special, it would allow existing code to continue
to function on this multi-chassis system.
For example, a system with multiple hosts would have BMCs, Chassis and Hosts
-*all* start numbering from 1 rather than 0. This is because multiple hosts
+_all_ start numbering from 1 rather than 0. This is because multiple hosts
could be in the same chassis, or controlled by the same BMC, so taking action
-against them would *not* be what the API user intended.
+against them would _not_ be what the API user intended.
It is safe to continue to write code referencing bmc0, host0 and
chassis0 and that code will continue to function, or error out rather than
@@ -102,24 +103,27 @@
## Hard vs. Soft Power Off
-A hard power off is where you simply cut power to a chassis. You don't give
+A hard power off is where you simply cut power to a chassis. You don't give
the software running on that chassis any chance to cleanly shut down.
A soft power off is where you send a notification to the host that is running
on that chassis that a shutdown is requested, and wait for that host firmware
-to indicate it has shut itself down. Once complete, power is then removed
+to indicate it has shut itself down. Once complete, power is then removed
from the chassis. By default, a host off or reboot request does the soft
-power off. If a user desires a cold reboot then they should simply issue a
+power off. If a user desires a cold reboot then they should simply issue a
power off transition request to the chassis, and then issue an on transition
request to the host.
## Operating System State and Boot Progress Properties
-[OperatingSystemState](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/OperatingSystem/Status.interface.yaml)
-property is used to track different progress states of the OS or the hypervisor
-boot, while the [BootProgress](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/Boot/Progress.interface.yaml)
-property is used mainly for indicating system firmware boot progress.
-The enumerations used in both the cases are influenced by standard interfaces
-like IPMI 2.0 (Section 42.2, Sensor Type Codes and Data, Table 42, Base OS
-boot status) and PLDM state spec (DSP0249, Section 6.3, State Sets Tables,
-Table 7 – Boot-Related State Sets, Set ID - 196 Boot Progress).
+[OperatingSystemState][3] property is used to track different progress states
+of the OS or the hypervisor boot, while the [BootProgress][4] property is used
+mainly for indicating system firmware boot progress. The enumerations used in
+both the cases are influenced by standard interfaces like IPMI 2.0 (Section
+42.2, Sensor Type Codes and Data, Table 42, Base OS boot status) and PLDM state
+spec (DSP0249, Section 6.3, State Sets Tables, Table 7 – Boot-Related State
+Sets, Set ID - 196 Boot Progress).
+[1]: https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md#error-handling-of-systemd
+[2]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/
+[3]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/OperatingSystem/Status.interface.yaml
+[4]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/xyz/openbmc_project/State/Boot/Progress.interface.yaml
diff --git a/yaml/xyz/openbmc_project/User/README.md b/yaml/xyz/openbmc_project/User/README.md
index 1ce17e0..16a0911 100644
--- a/yaml/xyz/openbmc_project/User/README.md
+++ b/yaml/xyz/openbmc_project/User/README.md
@@ -1,52 +1,66 @@
# User Management
## Overview
+
User Manager service exposes D-Bus methods for user management operations.
### User Manager Interface
+
User manager interface `xyz.openbmc_project.User.Manager` provides following
methods, properties and signals.
#### xyz.openbmc_project.User.Manager interface
+
##### methods
-* CreateUser - To create new user to the system.
-* RenameUser - To rename existing user to new name in the system.
+
+- CreateUser - To create new user to the system.
+- RenameUser - To rename existing user to new name in the system.
##### properties
-* AllGroups - To list all the groups supported in the system.
-* AllPrivileges - To list all the privileges supported in the system.
+
+- AllGroups - To list all the groups supported in the system.
+- AllPrivileges - To list all the privileges supported in the system.
##### signals
-* UserRenamed - Signal sent out when user is renamed in the system.
+
+- UserRenamed - Signal sent out when user is renamed in the system.
#### xyz.openbmc_project.User.AccountPolicy interface
+
##### properties
-* MaxLoginAttemptBeforeLockout - Permissible attempt before locking out the
-user for failed login attempts.
-* AccountUnlockTimeout - Timeout (in seconds) to unlock the account after a
-lockout.
-* MinPasswordLength - Minimum password length, which can be set.
-* RememberOldPasswordTimes – Number of times old password shouldn’t be allowed
-when updating password for the user.
+
+- MaxLoginAttemptBeforeLockout - Permissible attempt before locking out the
+ user for failed login attempts.
+- AccountUnlockTimeout - Timeout (in seconds) to unlock the account after a
+ lockout.
+- MinPasswordLength - Minimum password length, which can be set.
+- RememberOldPasswordTimes – Number of times old password shouldn’t be allowed
+ when updating password for the user.
### Users Interface
+
User manager daemon, will create user objects for every user existing
in the system under object path `/xyz/openbmc_project/user/<user name>`.
Each user object can be handled through 'org.freedesktop.DBus.ObjectManager'.
User object will expose following properties and methods.
#### xyz.openbmc_project.User.Attributes interface
+
##### properties
-* UserPrivilege - Privilege of the user.
-* UserGroups - Groups to which the user belongs.
-* UserEnabled - User enabled state.
-* UserLockedForFailedAttempt - Locked or unlocked state of the user account.
+
+- UserPrivilege - Privilege of the user.
+- UserGroups - Groups to which the user belongs.
+- UserEnabled - User enabled state.
+- UserLockedForFailedAttempt - Locked or unlocked state of the user account.
#### xyz.openbmc_project.Object.Delete
-#### methods
-* Delete - To delete the user object in the system.
-##Note
+#### methods
+
+- Delete - To delete the user object in the system.
+
+## Note
+
This interface doesn't provide ways to set / update password. The same must
be set / updated through pam_chauthtok() (PAM modules). This is to avoid
sending out password through D-Bus.
diff --git a/yaml/xyz/openbmc_project/VirtualMedia/README.md b/yaml/xyz/openbmc_project/VirtualMedia/README.md
index 40afa3f..267e3ee 100644
--- a/yaml/xyz/openbmc_project/VirtualMedia/README.md
+++ b/yaml/xyz/openbmc_project/VirtualMedia/README.md
@@ -1,4 +1,6 @@
# Virtual Media
All exposed objects, their paths and interfaces are described
-in [openbmc/docs/designs/VirtualMedia.md](https://github.com/openbmc/docs/blob/master/designs/VirtualMedia.md).
\ No newline at end of file
+in [openbmc/docs/designs/VirtualMedia.md][design].
+
+[design]: https://github.com/openbmc/docs/blob/master/designs/VirtualMedia.md