markdownlint: clean up all warnings
This is a [mostly] format-only change to get the repository into a
state where it conforms with markdownlint.
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
Change-Id: Ia07c7b3540cff8b25b7093f715c6617644340036
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 3d1c1ad..7e093b4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -17,7 +17,7 @@
OpenBMC relies on the Open Compute Project to provide guidelines on inclusive
naming. The OCP guidelines can be found here:
-https://www.opencompute.org/documents/ocp-terminology-guidelines-for-inclusion-and-openness
+<https://www.opencompute.org/documents/ocp-terminology-guidelines-for-inclusion-and-openness>
## Structure
@@ -47,7 +47,7 @@
allows other contributors that work for your employer to skip the CLA signing
process, they can just be added to the existing CCLA Schedule A.
-After signing a CLA, send it to manager@lfprojects.org.
+After signing a CLA, send it to <manager@lfprojects.org>.
If you're looking for a place to get started with OpenBMC, you may want to take
a look at the issues tagged with 'bitesize'. These are fixes or enhancements
@@ -56,12 +56,12 @@
Check out that list here:
-https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Aopenbmc+label%3Abitesize
+<https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Aopenbmc+label%3Abitesize>
If you need further details on any of these issues, feel free to add comments.
Performing code reviews is another good way to get started. Go to
-https://gerrit.openbmc.org and click on the "all" and "open" menu items, or if
+<https://gerrit.openbmc.org> and click on the "all" and "open" menu items, or if
you are interested in a particular repository - for example, "bmcweb" - type
"status:open project:openbmc/bmcweb" into the search bar and press the "search"
button. Then select a review. Remember to be positive and add value with every
@@ -78,7 +78,7 @@
Python source should all conform to PEP8. This style is well established within
the Python community and can be verified with the 'pycodestyle' tool.
-https://www.python.org/dev/peps/pep-0008/
+<https://www.python.org/dev/peps/pep-0008/>
### Python Formatting
@@ -91,7 +91,7 @@
file is all that's needed. If so desired, enforcement of 80 (vs. the default 79)
chars is fine as well:
-```
+```toml
[pycodestyle]
max-line-length = 80
```
@@ -102,7 +102,7 @@
repository maintainer's discretion as to whether to enforce the aforementioned
rules. These rules can be enforced by adding the following to the setup.cfg:
-```
+```toml
[pycodestyle]
ignore= NONE
```
@@ -123,7 +123,7 @@
For C code, we typically use the Linux coding style, which is documented at:
-http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst
+<http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/Documentation/process/submitting-patches.rst>
In short:
@@ -135,7 +135,9 @@
This style can mostly be verified with 'astyle' as follows:
- astyle --style=linux --indent=tab=8 --indent=force-tab=8
+```bash
+astyle --style=linux --indent=tab=8 --indent=force-tab=8
+```
### C++
@@ -235,11 +237,13 @@
Exceptions to this are allowed in the form of links, which can be represented in
the form of:
-''' This implements [1]
+```markdown
+This implements [1]
....
-[1] https://openbmc.org/myverylongurl. '''
+[1]: https://openbmc.org/myverylongurl.
+```
All commit messages must include a "Signed-off-by" line, which indicates that
you the contributor have agreed to the Developer Certificate of Origin (see
@@ -258,7 +262,7 @@
Commit messages should include a "Tested" field describing how you tested the
code changes in the patch. Example:
-```
+```text
Tested: I ran unit tests with "make check" (added 2 new tests) and manually
tested on Witherspoon that Foo daemon no longer crashes at boot.
```
@@ -272,9 +276,8 @@
The guidelines in the Linux kernel are very useful:
-https://www.kernel.org/doc/html/latest/process/submitting-patches.html
-
-https://www.kernel.org/doc/html/latest/process/submit-checklist.html
+- <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>
+- <https://www.kernel.org/doc/html/latest/process/submit-checklist.html>
Your contribution will generally need to be reviewed before being accepted.
@@ -282,22 +285,22 @@
The OpenBMC Gerrit server supports GitHub credentials, its link is:
-https://gerrit.openbmc.org/#/q/status:open
+<https://gerrit.openbmc.org/#/q/status:open>
_One time setup_: Login to the WebUI with your GitHub credentials and verify on
your Account Settings that your SSH keys were imported:
-https://gerrit.openbmc.org/#/settings/
+<https://gerrit.openbmc.org/#/settings/>
Most repositories are supported by the Gerrit server, the current list can be
found under Projects -> List:
-https://gerrit.openbmc.org/#/admin/projects/
+<https://gerrit.openbmc.org/#/admin/projects/>
If you're going to be working with Gerrit often, it's useful to create an SSH
host block in ~/.ssh/config. Ex:
-```
+```text
Host openbmc.gerrit
Hostname gerrit.openbmc.org
Port 29418
@@ -325,7 +328,7 @@
repository to automatically add a Change-Id to your commit messages. The steps
are:
-```
+```bash
gitdir=$(git rev-parse --git-dir)
curl https://gerrit.openbmc.org/tools/hooks/commit-msg -o ${gitdir}/hooks/commit-msg
chmod +x ${gitdir}/hooks/commit-msg`
@@ -381,9 +384,9 @@
- D-Bus interfaces are defined in the `phosphor-dbus-interfaces` repository at:
- https://github.com/openbmc/phosphor-dbus-interfaces
+<https://github.com/openbmc/phosphor-dbus-interfaces>
-See: http://dbus.freedesktop.org/doc/dbus-api-design.html
+See: <http://dbus.freedesktop.org/doc/dbus-api-design.html>
## Best practices for C
@@ -455,6 +458,7 @@
## Developer's Certificate of Origin 1.1
+```text
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
@@ -478,3 +482,4 @@
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.
+```
diff --git a/IPMITOOL-cheatsheet.md b/IPMITOOL-cheatsheet.md
index 22729a8..0c473f8 100644
--- a/IPMITOOL-cheatsheet.md
+++ b/IPMITOOL-cheatsheet.md
@@ -5,112 +5,112 @@
## Power
-#### 1. View server status
+### 1. View server status
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power status
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power status
```
-#### 2. Server power on
+### 2. Server power on
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power on
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power on
```
-#### 3. Server power off
+### 3. Server power off
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power off
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power off
```
-#### 4. Server power reset
+### 4. Server power reset
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power reset
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power reset
```
-#### 5. Server power cycle
+### 5. Server power cycle
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power cycle
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power cycle
```
-#### 6. Server power soft
+### 6. Server power soft
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power soft
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power soft
```
-#### 7. Send a diagnostic interrupt directly to the processor(not support)
+### 7. Send a diagnostic interrupt directly to the processor(not support)
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power diag
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" power diag
```
## Users
-#### 1. View information for all users
+### 1. View information for all users
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user list
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user list
```
-#### 2. Display a brief summary of BMC users
+### 2. Display a brief summary of BMC users
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user summary
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user summary
```
-#### 3. Create a BMC user with a given name
+### 3. Create a BMC user with a given name
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user set name <userid> <username>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user set name <userid> <username>
```
-#### 4. Set a given user with a given password
+### 4. Set a given user with a given password
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user set password <userid>[<password>]
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user set password <userid>[<password>]
```
-#### 5. Disable designated users from accessing BMC
+### 5. Disable designated users from accessing BMC
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user disable <userid>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user disable <userid>
```
-#### 6. Enable the specified user to access BMC
+### 6. Enable the specified user to access BMC
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user enable <userid>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user enable <userid>
```
## Field-replaceable Unit (FRU)
-#### 1. View FRU information
+### 1. View FRU information
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" fru list
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" fru list
```
## Sensor Data Record (SDR)
-#### 1. View SDR information
+### 1. View SDR information
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sdr
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sdr
```
-#### 2. Query related SDR information in BMC
+### 2. Query related SDR information in BMC
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sdr info
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sdr info
```
-#### 3. View sensor date records
+### 3. View sensor date records
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sdr list [all|full|compact|event|mcloc|fru|generic]
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sdr list [all|full|compact|event|mcloc|fru|generic]
##
all : All SDR records (sensors and positioners)
@@ -124,86 +124,82 @@
## Sensors
-#### 1. View sensor information
+### 1. View sensor information
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sensor list
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sensor list
```
## Management Controller (MC)
-#### 1. Instruct the BMC to perform a cold reset
+### 1. Instruct the BMC to perform a cold reset
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" mc reset cold
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" mc reset cold
```
-#### 2. Instruct the BMC to perform a warm reset(not supported)
+### 2. Instruct the BMC to perform a warm reset(not supported)
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" mc reset warm
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" mc reset warm
```
-#### 3. View BMC information
+### 3. View BMC information
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" mc info
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" mc info
```
-#### 4. View the currently available operation options of BMC
+### 4. View the currently available operation options of BMC
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" mc getenables
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" mc getenables
```
## Channels
-#### 1. Display the authentication function about the selected information
+### 1. Display the authentication function about the selected information channel
-#### channel
-
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" channel authcap <channel number> <max privilege>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" channel authcap <channel number> <max privilege>
```
-#### 2. Display the information for the selected channel
+### 2. Display the information for the selected channel
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" channel info [<channel number>]
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" channel info [<channel number>]
```
-#### 3. View channel information
+### 3. View channel information
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" channel info
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" channel info
```
## Chassis
-#### 1. Display information about the high-level status of the system rack and
+### 1. Display information about the high-level status of the system rack and power subsystem
-#### power subsystem.
-
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis status
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis status
```
-#### 2. The command will return the power on time
+### 2. The command will return the power on time
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis poh
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis poh
```
-#### 3. Query the reason for the last system restart.(not supported)
+### 3. Query the reason for the last system restart.(not supported)
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis restart_cause
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis restart_cause
```
-#### 4. Set rack power strategy in case of power failure
+### 4. Set rack power strategy in case of power failure
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis policy <state>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis policy <state>
##
list : return supported policies
@@ -212,10 +208,10 @@
always-off : stay off after power is restored
```
-#### 5. View and change power status
+### 5. View and change power status
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis power
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis power
##
status : show current status
@@ -226,10 +222,10 @@
cycle : power cycle
```
-#### 6. Set boot device for next system restart
+### 6. Set boot device for next system restart
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device>
```
##
@@ -246,57 +242,51 @@
| cdrom | boot from the CD/DVD |
| bios | enter bios settings |
-##
-
If you want to make your override persistent over reboots use the `persistent`
option:
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device> options=persistent
```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device> options=persistent
-```
-
-##
If the main host machine is based on the x86 CPU you need also pay attention to
the legacy/EFI mode selector. By default IPMI overrides boot source with the
legacy mode enabled. To set EFI mode use `efiboot` option:
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device> options=efiboot
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device> options=efiboot
```
You can combine options with a help of `,`:
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device> options=persistent,efiboot
```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device> options=persistent,efiboot
-```
-
-##
To read current boot source override setting:
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootparam get 5
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootparam get 5
```
-#### 7. Control panel logo light
+### 7. Control panel logo light
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis identify <interval>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis identify <interval>
```
## Local Area Network(LAN)
-#### 1. Output the current configuration information of a given channel
+### 1. Output the current configuration information of a given channel
-```
- $ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" lan print [<channel number>]
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" lan print [<channel number>]
```
-#### 2. Set the given parameters for the given channel
+### 2. Set the given parameters for the given channel
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" lan set <channel> <command> <parameter>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" lan set <channel> <command> <parameter>
##
Valid parameter
ipaddr <x.x.x.x> : Set ip for this channel
@@ -312,56 +302,54 @@
## System Event Log (SEL)
-#### 1. Query the relevant information about SEL and its content in BMC
+### 1. Query the relevant information about SEL and its content in BMC
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sel info
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sel info
```
-#### 2. Clear the information in SEL,but it cannot be undone.
+### 2. Clear the information in SEL,but it cannot be undone
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sel clear
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sel clear
```
-#### 3. Delete a single event
+### 3. Delete a single event
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sel delete <number>
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sel delete <number>
```
-#### 4. Display the current time of the SEL clock
+### 4. Display the current time of the SEL clock
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sel time get
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sel time get
```
## Session
-#### 1. Display session information
+### 1. Display session information
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" session info all
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" session info all
```
## Serial Over Lan (SOL)
-#### 1. Retrieve Serial-Over-LAN configuration information for the specified
+### 1. Retrieve Serial-Over-LAN configuration information for the specified channel
-#### channel.
-
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sol info [<channel number>]
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sol info [<channel number>]
```
-#### 2. Put ipmitool into Serial Over LAN mode
+### 2. Put ipmitool into Serial Over LAN mode
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sol activate
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sol activate
```
-#### 3. Disable serial LAN in BMC mode
+### 3. Disable serial LAN in BMC mode
-```
-$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sol deactivate
+```bash
+ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" sol deactivate
```
diff --git a/README.md b/README.md
index 9b569bf..cc84a64 100644
--- a/README.md
+++ b/README.md
@@ -11,9 +11,9 @@
## Contact
-- Mail: openbmc@lists.ozlabs.org https://lists.ozlabs.org/listinfo/openbmc
-- List Archive: https://lore.kernel.org/openbmc/
-- Discord: https://discord.gg/69Km47zH98
+- Mail: `openbmc@lists.ozlabs.org` <https://lists.ozlabs.org/listinfo/openbmc>
+- List Archive: <https://lore.kernel.org/openbmc/>
+- Discord: <https://discord.gg/69Km47zH98>
## OpenBMC Development
diff --git a/REDFISH-cheatsheet.md b/REDFISH-cheatsheet.md
index 21edf44..1e71a1a 100644
--- a/REDFISH-cheatsheet.md
+++ b/REDFISH-cheatsheet.md
@@ -9,7 +9,7 @@
## Query Redfish Service Root
-```
+```bash
export bmc=xx.xx.xx.xx
curl -k https://${bmc}/redfish/v1
```
@@ -18,9 +18,9 @@
## Establish Redfish connection session
-##### Method 1
+### Method 1
-```
+```bash
export bmc=xx.xx.xx.xx
curl --insecure -H "Content-Type: application/json" -X POST -D headers.txt https://${bmc}/redfish/v1/SessionService/Sessions -d '{"UserName":"root", "Password":"0penBmc"}'
```
@@ -28,13 +28,13 @@
A file, headers.txt, will be created. Find the `"X-Auth-Token"` in that file.
Save it away in an env variable like so:
-```
+```bash
export bmc_token=<token>
```
-##### Method 2
+### Method 2
-```
+```bash
export bmc=xx.xx.xx.xx
export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/...
@@ -46,7 +46,7 @@
## View Redfish Objects
-```
+```bash
curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Chassis
curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Managers
curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Systems
@@ -56,7 +56,7 @@
## View sessions
-```
+```bash
curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/SessionService/Sessions
```
@@ -66,25 +66,25 @@
Host soft power off:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulShutdown"}'
```
Host hard power off:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "ForceOff"}'
```
Host power on:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "On"}'
```
Reboot Host:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Systems/system/Actions/ComputerSystem.Reset -d '{"ResetType": "GracefulRestart"}'
```
@@ -92,7 +92,7 @@
## BMC reboot
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Managers/bmc/Actions/Manager.Reset -d '{"ResetType": "GracefulRestart"}'
```
@@ -102,7 +102,7 @@
Proceed with caution:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Managers/bmc/Actions/Manager.ResetToDefaults -d '{"ResetType": "ResetAll"}'
```
@@ -112,13 +112,13 @@
Display logging entries:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Systems/system/LogServices/EventLog/Entries
```
Delete logging entries:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Systems/system/LogServices/EventLog/Actions/LogService.Reset
```
@@ -128,7 +128,7 @@
Firmware update: Note the `<image file path>` must be a tarball.
-```
+```bash
uri=$(curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/UpdateService | jq -r ' .HttpPushUri')
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -X POST -T <image file path> https://${bmc}${uri}
@@ -137,7 +137,7 @@
Firmware update using multi-part form data: Note the `<apply time>` can be
`OnReset` or `Immediate`.
-```
+```bash
uri=$(curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/UpdateService | jq -r ' .MultipartHttpPushUri')
curl -k -H "X-Auth-Token: $token" -H "Content-Type:multipart/form-data" -X POST -F UpdateParameters="{\"Targets\":[\"/redfish/v1/Managers/bmc\"],\"@Redfish.OperationApplyTime\":<apply time>};type=application/json" -F "UpdateFile=@<image file path>;type=application/octet-stream" https://${bmc}${uri}
@@ -147,13 +147,13 @@
contains the address of the TFTP service:
`xx.xx.xx.xx/obmc-phosphor-xxxxx-xxxxxxxxx.static.mtd.tar`
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate -d '{"TransferProtocol":"TFTP","ImageURI":"<image file path>"}'
```
TFTP Firmware update with protocol in ImageURI:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/UpdateService/Actions/UpdateService.SimpleUpdate -d '{"ImageURI":"tftp://<image file path>"}'
```
@@ -163,7 +163,7 @@
Change password to "0penBmc1":
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH -d '{"Password": "0penBmc1"}' https://${bmc}/redfish/v1/AccountService/Accounts/root
```
@@ -173,19 +173,19 @@
Enter into BIOS setup on boot
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH https://${bmc}/redfish/v1/Systems/system -d '{"Boot":{"BootSourceOverrideEnabled": "Continuous","BootSourceOverrideTarget": "BiosSetup"}}'
```
Fully boot
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH https://${bmc}/redfish/v1/Systems/system -d '{"Boot":{"BootSourceOverrideEnabled": "Disabled","BootSourceOverrideTarget": "None"}}'
```
Change Legacy/EFI selector (valid only if host is based on the x86 CPU)
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH https://${bmc}/redfish/v1/Systems/system -d '{"Boot":{"BootSourceOverrideEnabled": "Once","BootSourceOverrideTarget": "None","BootSourceOverrideMode": "UEFI"}}'
```
@@ -195,13 +195,13 @@
Add a NTP Server
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH https://${bmc}/redfish/v1/Managers/bmc/NetworkProtocol -d '{"NTP":{"NTPServers":["time.nist.gov"]}}'
```
Now enable NTP
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH https://${bmc}/redfish/v1/Managers/bmc/NetworkProtocol -d '{"NTP":{"ProtocolEnabled": true}}'
```
@@ -209,7 +209,7 @@
## Disable IPMI
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH https://${bmc}/redfish/v1/Managers/bmc/NetworkProtocol -d '{"IPMI":{"ProtocolEnabled": false}}'
```
diff --git a/REST-cheatsheet.md b/REST-cheatsheet.md
index 2f1d3ba..6a862ae 100644
--- a/REST-cheatsheet.md
+++ b/REST-cheatsheet.md
@@ -2,13 +2,13 @@
This document is intended to provide a set of REST client commands for OpenBMC
usage. OpenBMC REST is disabled by default in bmcweb. For more information, see
-https://github.com/openbmc/bmcweb/commit/47c9e106e0057dd70133d50e928e48cbc68e709a.
+<https://github.com/openbmc/bmcweb/commit/47c9e106e0057dd70133d50e928e48cbc68e709a>.
Most of the functionality previously provided by OpenBMC REST is available in
Redfish.
## Using CURL commands
-### Notes on authentication:
+### Notes on authentication
The original REST server, from the phosphor-rest-server repository, uses
authentication handled by the curl cookie jar files. The bmcweb REST server can
@@ -22,33 +22,35 @@
### Establish REST connection session
- Using just the cookie jar files for the phosphor-rest server:
- ```
- $ export bmc=xx.xx.xx.xx
- $ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
- ```
+
+```bash
+ export bmc=xx.xx.xx.xx
+ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
+```
+
- If passing in the username/password as part of the URL, no unique login call
is required. The URL format is:
- ```
+```bash
<username>:<password>@<hostname>/<path>...
- ```
+```
- For example:
+For example:
- ```
- $ export bmc=xx.xx.xx.xx
- $ curl -k -X GET https://root:0penBmc@${bmc}/xyz/openbmc_project/list
- ```
+```bash
+ export bmc=xx.xx.xx.xx
+ curl -k -X GET https://root:0penBmc@${bmc}/xyz/openbmc_project/list
+```
- Token based authentication.
- ```
- $ export bmc=xx.xx.xx.xx
- $ export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
- ```
+```bash
+ export bmc=xx.xx.xx.xx
+ export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
+```
- The third method is recommended.
+The third method is recommended.
### Commands
@@ -56,133 +58,133 @@
implementations as described above, this assumes that if bmcweb is used it is
using the 'Token based' login method as described above:
-```
-$ export bmc=xx.xx.xx.xx
-$ export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
-$ curl -k -H "X-Auth-Token: $token" https://$bmc/xyz/openbmc_project/...
+```bash
+export bmc=xx.xx.xx.xx
+export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
+curl -k -H "X-Auth-Token: $token" https://$bmc/xyz/openbmc_project/...
```
- List and enumerate:
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/list
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/enumerate
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/list
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/enumerate
+```
- List sub-objects:
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/
+```
- Host soft power off:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.Off"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.Off"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```
- Host hard power off:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Chassis.Transition.Off"}' https://${bmc}//xyz/openbmc_project/state/chassis0/attr/RequestedPowerTransition
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Chassis.Transition.Off"}' https://${bmc}//xyz/openbmc_project/state/chassis0/attr/RequestedPowerTransition
+```
- Host power on:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```
- Reboot Host:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Host.Transition.Reboot"}' https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Host.Transition.Reboot"}' https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```
- Reboot BMC:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.BMC.Transition.Reboot"}' https://${bmc}/xyz/openbmc_project/state/bmc0/attr/RequestedBMCTransition
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.BMC.Transition.Reboot"}' https://${bmc}/xyz/openbmc_project/state/bmc0/attr/RequestedBMCTransition
+```
- Display logging entries:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate
+```
- Delete logging entries:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/<entry_id>
- $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/<entry_id>
+ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
+```
- Delete dump entries:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/dump/entry/<entry_id>
- $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/dump/action/DeleteAll
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/dump/entry/<entry_id>
+ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/dump/action/DeleteAll
+```
- Delete images from system:
- Delete image:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/<image id>/action/Delete
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/<image id>/action/Delete
+```
- - Delete all non-running images:
+- Delete all non-running images:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/action/DeleteAll
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/action/DeleteAll
+```
- Clear gard records:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset
+```
- Control boot source override:
- Read current boot source override settings:
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/control/host0/boot/enumerate
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/control/host0/boot/enumerate
+```
- - Set boot source:
+- Set boot source:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootSource -d '{"data": "xyz.openbmc_project.Control.Boot.Source.Sources.Default"}'
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootSource -d '{"data": "xyz.openbmc_project.Control.Boot.Source.Sources.Default"}'
+```
- - Set boot mode:
+- Set boot mode:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootMode -d '{"data": "xyz.openbmc_project.Control.Boot.Mode.Modes.Regular"}'
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootMode -d '{"data": "xyz.openbmc_project.Control.Boot.Mode.Modes.Regular"}'
+```
- - Set boot type (valid only if host is based on the x86 CPU):
+- Set boot type (valid only if host is based on the x86 CPU):
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootType -d '{"data": "xyz.openbmc_project.Control.Boot.Type.Types.EFI"}'
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootType -d '{"data": "xyz.openbmc_project.Control.Boot.Type.Types.EFI"}'
+```
- - Set boot source override persistent:
+- Set boot source override persistent:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/one_time/attr/Enabled -d '{"data": "false"}'
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/one_time/attr/Enabled -d '{"data": "false"}'
+```
- - Enable boot source override:
+- Enable boot source override:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/Enabled -d '{"data": "true"}'
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/Enabled -d '{"data": "true"}'
+```
- Set NTP and Nameserver:
@@ -190,20 +192,20 @@
- NTP Server:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": ["pool.ntp.org"] }' https://${bmc}/xyz/openbmc_project/network/eth0/attr/NTPServers
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": ["pool.ntp.org"] }' https://${bmc}/xyz/openbmc_project/network/eth0/attr/NTPServers
+```
- - Name Server:
+- Name Server:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": ["time.google.com"] }' https://${bmc}/xyz/openbmc_project/network/eth0/attr/Nameservers
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": ["time.google.com"] }' https://${bmc}/xyz/openbmc_project/network/eth0/attr/Nameservers
+```
- Configure time ownership and time sync method:
The introduction about time setting is here:
- https://github.com/openbmc/phosphor-time-manager
+ <https://github.com/openbmc/phosphor-time-manager>
Note: Starting from OpenBMC 2.6 (with systemd v239), systemd's timedated
introduces a new beahvior that it checks the NTP services' status during
@@ -219,62 +221,62 @@
- Read:
- ```
- $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
- $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
+ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
+```
- - Write:
+- Write:
- Time owner:
+Time owner:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.BMC" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Host" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Split" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Both" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.BMC" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Host" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Split" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Owner.Owners.Both" }' https://${bmc}/xyz/openbmc_project/time/owner/attr/TimeOwner
+```
- Time sync method:
+Time sync method:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Synchronization.Method.NTP" }' https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Synchronization.Method.Manual" }' https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Synchronization.Method.NTP" }' https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.Time.Synchronization.Method.Manual" }' https://${bmc}/xyz/openbmc_project/time/sync_method/attr/TimeSyncMethod
+```
- Power Supply Redundancy:
- Read:
- ```
- $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy
+```
- - Write (Enable/Disable):
+- Write (Enable/Disable):
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy/attr/PowerSupplyRedundancyEnabled -d '{"data": 1}'
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy/attr/PowerSupplyRedundancyEnabled -d '{"data": 0}'
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy/attr/PowerSupplyRedundancyEnabled -d '{"data": 1}'
+ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy/attr/PowerSupplyRedundancyEnabled -d '{"data": 0}'
+```
- Factory Reset:
- Factory reset host and BMC software:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset
+```
- - Factory reset network setting:
+- Factory reset network setting:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/network/action/Reset
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/network/action/Reset
+```
- - Enable field mode:
+- Enable field mode:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X PUT -d '{"data":1}' https://${bmc}/xyz/openbmc_project/software/attr/FieldModeEnabled
- ```
+```bash
+ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X PUT -d '{"data":1}' https://${bmc}/xyz/openbmc_project/software/attr/FieldModeEnabled
+```
- and then reboot BMC.
+and then reboot BMC.
diff --git a/anti-patterns.md b/anti-patterns.md
index 4af2093..afb6356 100644
--- a/anti-patterns.md
+++ b/anti-patterns.md
@@ -72,7 +72,7 @@
### Identification
-```
+```bitbake
RDEPENDS_${PN} = "libsystemd"
```
@@ -87,9 +87,11 @@
errors - the net effect being unnecessary shared library packages being
installed into images.
-Consult
-https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-RDEPENDS
-for information on when to use explicit runtime dependencies.
+Consult [Yocto Project Mega-Manual][mega-manual-rdepends] for information on
+when to use explicit runtime dependencies.
+
+[mega-manual-rdepends]:
+ https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#var-RDEPENDS
### Background
@@ -109,7 +111,7 @@
In systemd unit files:
-```
+```systemd
[Service]
ExecStart=/usr/bin/env some-application
@@ -129,13 +131,13 @@
part of the implementation that satisfied the live patch requirement. For
example:
-```
+```bash
/usr/bin/phosphor-hwmon
```
on a read-only filesystem becomes:
-```
+```bash
/usr/local/bin/phosphor-hwmon`
```
@@ -147,7 +149,7 @@
that supports live patching of any file in the read-only filesystem has emerged.
Assuming a writeable filesystem exists _somewhere_ on the bmc, something like:
-```
+```bash
mkdir -p /var/persist/usr
mkdir -p /var/persist/work/usr
mount -t overlay -o lowerdir=/usr,upperdir=/var/persist/usr,workdir=/var/persist/work/usr overlay /usr
@@ -162,7 +164,7 @@
service files and replace with the fully qualified path to the application being
launched. For example, given an application in /usr/bin:
-```
+```bash
sed -i s,/usr/bin/env ,/usr/bin/, foo.service
```
@@ -202,7 +204,7 @@
From the hier(7) man page:
-```
+```bash
/usr/bin This is the primary directory for executable programs. Most programs
executed by normal users which are not needed for booting or for repairing the
system and which are not installed locally should be placed in this directory.
@@ -238,7 +240,7 @@
Example C++ code:
-```
+```cpp
using InternalFailure = sdbusplus::xyz::openbmc_project::Common::Error::InternalFailure;
try
{
@@ -314,7 +316,7 @@
- Analyzer tool: Consider breaking the log down and including several
properties which an analyzer can leverage. For instance, tagging the log
with 'Internal' is not helpful. However, breaking that down into something
- like [UserInput][ipmi][Network] tells at a quick glance that the input
+ like `[UserInput][IPMI][Network]` tells at a quick glance that the input
received for configuring the network via an IPMI command was invalid.
Categorization and system impact are key things to focus on when creating
logs for an analysis application.
@@ -342,7 +344,7 @@
applications take the following as command line parameters to enable extra
debug:
-- 0xff, --vv, -vv, -v, --verbose, <and more>
+- 0xff, --vv, -vv, -v, --verbose, `<and more>`
Along these same lines, some applications then have their own internal methods
of writing debug data. They use std::cout, printf, fprintf, ... Doing this
@@ -372,9 +374,9 @@
Desire to expose a DBus interface to drive GPIOs, for example:
-- https://lore.kernel.org/openbmc/YV21cD3HOOGi7K2f@heinlein/
-- https://lore.kernel.org/openbmc/CAH2-KxBV9_0Dt79Quy0f4HkXXPdHfBw9FsG=4KwdWXBYNEA-ew@mail.gmail.com/
-- https://lore.kernel.org/openbmc/YtPrcDzaxXiM6vYJ@heinlein.stwcx.org.github.beta.tailscale.net/
+- <https://lore.kernel.org/openbmc/YV21cD3HOOGi7K2f@heinlein/>
+- <https://lore.kernel.org/openbmc/CAH2-KxBV9_0Dt79Quy0f4HkXXPdHfBw9FsG=4KwdWXBYNEA-ew@mail.gmail.com/>
+- <https://lore.kernel.org/openbmc/YtPrcDzaxXiM6vYJ@heinlein.stwcx.org.github.beta.tailscale.net/>
### Description
@@ -502,9 +504,9 @@
most only plausible to parse using a regex while also reducing human
readability. For example:
-```
+```cpp
error(
- "Error getting time, PATH={BMC_TIME_PATH} TIME INTERACE={TIME_INTF} ERROR={ERR_EXCEP}",
+ "Error getting time, PATH={BMC_TIME_PATH} TIME INTERFACE={TIME_INTF} ERROR={ERR_EXCEP}",
"BMC_TIME_PATH", bmcTimePath, "TIME_INTF", timeInterface,
"ERR_EXCEP", e);
```
@@ -546,20 +548,20 @@
[phosphor-time-manager-lg2]:
https://github.com/openbmc/phosphor-time-manager/blob/5ce9ac0e56440312997b25771507585905e8b360/manager.cpp#L98
-```
+```cpp
info("Time mode has been changed to {MODE}", "MODE", newMode);
```
By default, this renders in the output of `journalctl` as:
-```
+```text
Sep 23 06:09:57 bmc phosphor-time-manager[373]: Time mode has been changed to xyz.openbmc_project.Time.Synchronization.Method.NTP
```
However, we can use some journalctl commandline options to inspect the
structured data associated with the log entry:
-```
+```bash
# journalctl --identifier=phosphor-time-manager --boot --output=verbose | grep -v '^ _' | head -n 9
Sat 2023-09-23 06:09:57.645208 UTC [s=85c1cb5f8e02445aa110a5164c9c07f6;i=244;b=ffd111d3cdca41c8893bb728a1c6cb20;m=133a5a0;t=606009314d0d9;x=9a54e8714754a6cb]
PRIORITY=6
diff --git a/architecture/LED-architecture.md b/architecture/LED-architecture.md
index 2f7e5a9..eae407c 100644
--- a/architecture/LED-architecture.md
+++ b/architecture/LED-architecture.md
@@ -7,7 +7,7 @@
## D-Bus
-```
+```text
Service xyx.openbmc_project.LED.GroupManager
Path /xyz/openbmc_project/led/groups/<label>
Interfaces xyz.openbmc_project.Led.Group
@@ -18,16 +18,16 @@
## REST
-```
+```text
PUT /xyz/openbmc_project/led/groups/<group>/attr/Asserted
```
The LED group state can be changed by setting the Asserted value to boolean 0
or 1. In the following example, the lamp_test group is being asserted...
-```
- curl -b cjar -k -X PUT -H "Content-Type: application/json" -d '{"data": 1}' \
- https://${bmc}/xyz/openbmc_project/led/groups/lamp_test/attr/Asserted
+```bash
+curl -b cjar -k -X PUT -H "Content-Type: application/json" -d '{"data": 1}' \
+ https://${bmc}/xyz/openbmc_project/led/groups/lamp_test/attr/Asserted
```
## REDFISH
@@ -41,14 +41,14 @@
All applicable Inventory D-Bus objects would have a forward association mapping
to LED Group D-Bus object, namely:
-```
+```text
- identify_led_group
```
All applicable LED Group D-Bus objects would have an association mapping to
inventory D-Bus object, namely:
-```
+```text
- identify_inventory_object
```
@@ -72,14 +72,14 @@
used. All applicable Inventory D-Bus objects would have a forward association
mapping to LED Group D-Bus object, namely;
-```
+```text
- fault_led_group
```
All applicable LED Group D-Bus objects would have an association mapping to
inventory D-Bus object, namely:
-```
+```text
- fault_inventory_object
```
@@ -111,7 +111,7 @@
_Add a fault LED to the device tree with a corresponding gpio pin..._
-```
+```dts
leds {
compatible = "gpio-leds";
@@ -123,7 +123,7 @@
_The kernel will then create..._
-```
+```text
ls -l /sys/class/leds/fault/
total 0
-rw-r--r-- 1 root root 4096 Jun 21 20:04 brightness
@@ -142,7 +142,7 @@
machines layout. Customized yaml files are placed into the machines specific
Yocto location. As an example:
-```
+```text
meta-ibm/meta-palmetto/recipes-phosphor/leds/palmetto-led-manager-config/led.yaml
```
@@ -156,22 +156,21 @@
`fault` but do so differently. The lamp_test would also drive a blink signal to
the physical `power` LED if one was created.
-```
+```yaml
EnclosureFault:
- fault:
- Action: 'On'
- DutyOn: 50
- Period: 0
+ fault:
+ Action: "On"
+ DutyOn: 50
+ Period: 0
lamp_test:
- fault:
- Action: 'Blink'
- DutyOn: 20
- Period: 100
- power:
- Action: 'Blink'
- DutyOn: 20
- Period: 100
-
+ fault:
+ Action: "Blink"
+ DutyOn: 20
+ Period: 100
+ power:
+ Action: "Blink"
+ DutyOn: 20
+ Period: 100
```
### Required Groups
@@ -181,38 +180,37 @@
## Yocto packaging
-1. Create a tailored LED manager file
+1. Create a tailored LED manager file
- E.g.
- `meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config-native.bb`
+ E.g.
+ `meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config-native.bb`
- ```
- SUMMARY = "Phosphor LED Group Management for Romulus"
- PR = "r1"
+ ```bitbake
+ SUMMARY = "Phosphor LED Group Management for Romulus"
+ PR = "r1"
- inherit native
- inherit obmc-phosphor-utils
- inherit obmc-phosphor-license
+ inherit native
+ inherit obmc-phosphor-utils
+ inherit obmc-phosphor-license
- PROVIDES += "virtual/phosphor-led-manager-config-native"
+ PROVIDES += "virtual/phosphor-led-manager-config-native"
- SRC_URI += "file://led.yaml"
- S = "${WORKDIR}"
+ SRC_URI += "file://led.yaml"
+ S = "${WORKDIR}"
- # Overwrites the default led.yaml
- do_install() {
- SRC=${S}
- DEST=${D}${datadir}/phosphor-led-manager
- install -D ${SRC}/led.yaml ${DEST}/led.yaml
- }
- ```
+ # Overwrites the default led.yaml
+ do_install() {
+ SRC=${S}
+ DEST=${D}${datadir}/phosphor-led-manager
+ install -D ${SRC}/led.yaml ${DEST}/led.yaml
+ }
+ ```
-2. Change your machine's preferred provider for the led-manager in the conf
- file
+2. Change your machine's preferred provider for the led-manager in the conf file
- E.g. `meta-ibm/meta-romulus/conf/machine/romulus.conf`
+ E.g. `meta-ibm/meta-romulus/conf/machine/romulus.conf`
- `PREFERRED_PROVIDER_virtual/phosphor-led-manager-config-native = "romulus-led-manager-config-native"`
+ `PREFERRED_PROVIDER_virtual/phosphor-led-manager-config-native = "romulus-led-manager-config-native"`
[led d-bus readme]:
https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/README.md
diff --git a/architecture/code-update/code-update-deprecated.md b/architecture/code-update/code-update-deprecated.md
index 9babbff..b03d344 100644
--- a/architecture/code-update/code-update-deprecated.md
+++ b/architecture/code-update/code-update-deprecated.md
@@ -102,12 +102,12 @@
An OpenBMC system can download an update image from a TFTP server, and apply
updates, controlled via REST. The general procedure is:
-1. Prepare system for update
-2. Configure update settings
-3. Initiate update
-4. Check flash status
-5. Apply update
-6. Reboot the BMC
+1. Prepare system for update
+2. Configure update settings
+3. Initiate update
+4. Check flash status
+5. Apply update
+6. Reboot the BMC
### Prepare system for update
diff --git a/architecture/code-update/code-update-diagrams.md b/architecture/code-update/code-update-diagrams.md
index a00609a..7afa1ed 100644
--- a/architecture/code-update/code-update-diagrams.md
+++ b/architecture/code-update/code-update-diagrams.md
@@ -4,7 +4,7 @@
## High-Level Overview
-```
+```ascii
┌──────────────┐ ┌─────────────┐ ┌────────────┐
│User Interface│ │Image Manager│ │Item Updater│
└──────┬───────┘ └──────┬──────┘ └──────┬─────┘
diff --git a/architecture/code-update/code-update.md b/architecture/code-update/code-update.md
index 2070d74..3e415bb 100644
--- a/architecture/code-update/code-update.md
+++ b/architecture/code-update/code-update.md
@@ -7,180 +7,181 @@
This document describes the code update that supports both layouts.
-### Steps to Update
+## Steps to Update
The following are the steps to update the BMC.
1. Get a BMC image tar: After building OpenBMC, you will end up with a set of
image files in `tmp/deploy/images/<platform>/`.
-- The UBI layout image is
- `obmc-phosphor-image-<platform>-<timestamp>.ubi.mtd.tar`
-- The static layout image is
- `obmc-phosphor-image-<platform>-<timestamp>.static.mtd.tar`
+ - The UBI layout image is
+ `obmc-phosphor-image-<platform>-<timestamp>.ubi.mtd.tar`
+ - The static layout image is
+ `obmc-phosphor-image-<platform>-<timestamp>.static.mtd.tar`
-The BMC tar image contains 5 files: u-boot, kernel, ro, and rw partitions and
-the MANIFEST file, which contains information about the image such as the image
-purpose, version, KeyType (Key type used for signature), HashType (SHA type used
-for key generation) and MachineName (name of machine used while building image,
-and this will be used for validation of image build). A MANIFEST file might look
-like
+ The BMC tar image contains 5 files: u-boot, kernel, ro, and rw partitions and
+ the MANIFEST file, which contains information about the image such as the
+ image purpose, version, KeyType (Key type used for signature), HashType (SHA
+ type used for key generation) and MachineName (name of machine used while
+ building image, and this will be used for validation of image build). A
+ MANIFEST file might look like
-```
-purpose=xyz.openbmc_project.Software.Version.VersionPurpose.BMC
-version=2.7.0-dev
-KeyType=OpenBMC
-HashType=RSA-SHA256
-MachineName=tiogapass
-```
+ ```text
+ purpose=xyz.openbmc_project.Software.Version.VersionPurpose.BMC
+ version=2.7.0-dev
+ KeyType=OpenBMC
+ HashType=RSA-SHA256
+ MachineName=tiogapass
+ ```
2. Transfer the generated BMC image to the BMC via one of the following methods:
-- Method 1: Via Redfish Upload:
- https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md#firmware-update.
- If using this method skip ahead to step 5!
-- Method 2: Via scp: Copy the generated BMC image to the `/tmp/images/`
- directory on the BMC.
-- Method 3: Via REST Upload:
- https://github.com/openbmc/docs/blob/master/rest-api.md#uploading-images
-- Method 4: Via TFTP: Perform a POST request to call the `DownloadViaTFTP`
- method of `/xyz/openbmc_project/software`.
+ - Method 1: Via Redfish Upload:
+ <https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md#firmware-update>.
+ If using this method skip ahead to step 5!
+ - Method 2: Via scp: Copy the generated BMC image to the `/tmp/images/`
+ directory on the BMC.
+ - Method 3: Via REST Upload:
+ <https://github.com/openbmc/docs/blob/master/rest-api.md#uploading-images>
+ - Method 4: Via TFTP: Perform a POST request to call the `DownloadViaTFTP`
+ method of `/xyz/openbmc_project/software`.
-Methods 3 and 4 require additional options in bmcweb to be enabled.
+ Methods 3 and 4 require additional options in bmcweb to be enabled.
3. Note the version id generated for that image file. The version id is a hash
value of 8 hexadecimal numbers, generated by SHA-512 hashing the version
string contained in the image and taking the first 8 characters. Get the
version id via one of the following methods:
-- Method 1: From the BMC command line, note the most recent directory name
- created under `/tmp/images/`, in this example it'd be `2a1022fe`:
+ - Method 1: From the BMC command line, note the most recent directory name
+ created under `/tmp/images/`, in this example it'd be `2a1022fe`:
- ```
- # ls -l /tmp/images/
- total 0
- drwx------ 2 root root 80 Aug 22 07:54 2a1022fe
- drwx------ 2 root root 80 Aug 22 07:53 488449a2
- ```
+ ```text
+ # ls -l /tmp/images/
+ total 0
+ drwx------ 2 root root 80 Aug 22 07:54 2a1022fe
+ drwx------ 2 root root 80 Aug 22 07:53 488449a2
+ ```
-- Method 2: This method _only_ works if there are no `Ready` images at the start
- of transferring the image. Using the REST API, note the object that has its
- Activation property set to Ready, in this example it'd be `2a1022fe`:
+ - Method 2: This method _only_ works if there are no `Ready` images at the
+ start of transferring the image. Using the REST API, note the object that
+ has its Activation property set to Ready, in this example it'd be
+ `2a1022fe`:
- ```
- $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/enumerate
- {
- "data": {
- "/xyz/openbmc_project/software/2a1022fe": {
- "Activation": "xyz.openbmc_project.Software.Activation.Activations.Ready",
- ```
+ ```text
+ $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/enumerate
+ {
+ "data": {
+ "/xyz/openbmc_project/software/2a1022fe": {
+ "Activation": "xyz.openbmc_project.Software.Activation.Activations.Ready",
+ ```
-- Method 3: Calculate the version id beforehand from the image with:
+ - Method 3: Calculate the version id beforehand from the image with:
- ```
- tar xfO <BMC tar image> MANIFEST | sed -ne '/version=/ {s/version=//;p}' | head -n1 | tr -d '\n' | sha512sum | cut -b 1-8
- ```
+ ```bash
+ tar xfO <BMC tar image> MANIFEST | sed -ne '/version=/ {s/version=//;p}' | head -n1 | tr -d '\n' | sha512sum | cut -b 1-8
+ ```
4. To initiate the update, set the `RequestedActivation` property of the desired
image to `Active`, substitute `<id>` with the hash value noted on the
previous step, this will write the contents of the image to the BMC chip via
one of the following methods:
-- Method 1: From the BMC command line:
+ - Method 1: From the BMC command line:
- ```
- busctl set-property xyz.openbmc_project.Software.BMC.Updater \
- /xyz/openbmc_project/software/<id> \
- xyz.openbmc_project.Software.Activation RequestedActivation s \
- xyz.openbmc_project.Software.Activation.RequestedActivations.Active
+ ```bash
+ busctl set-property xyz.openbmc_project.Software.BMC.Updater \
+ /xyz/openbmc_project/software/<id> \
+ xyz.openbmc_project.Software.Activation RequestedActivation s \
+ xyz.openbmc_project.Software.Activation.RequestedActivations.Active
- ```
+ ```
-- Method 2: Using the REST API:
+ - Method 2: Using the REST API:
- ```
- curl -b cjar -k -H "Content-Type: application/json" -X PUT \
- -d '{"data":
- "xyz.openbmc_project.Software.Activation.RequestedActivations.Active"}' \
- https://${bmc}/xyz/openbmc_project/software/<id>/attr/RequestedActivation
- ```
+ ```bash
+ curl -b cjar -k -H "Content-Type: application/json" -X PUT \
+ -d '{"data":
+ "xyz.openbmc_project.Software.Activation.RequestedActivations.Active"}' \
+ https://${bmc}/xyz/openbmc_project/software/<id>/attr/RequestedActivation
+ ```
5. (Optional) Check the flash progress. This interface is only available during
the activation progress and is not present once the activation is completed
via one of the following:
-- Method 1: From Redfish: A task is returned from the Redfish upload. The task
- can be used to monitor the progress.
+ - Method 1: From Redfish: A task is returned from the Redfish upload. The
+ task can be used to monitor the progress.
- ```
- curl -k https://${bmc}/redfish/v1/TaskService/Tasks/0
- ```
+ ```bash
+ curl -k https://${bmc}/redfish/v1/TaskService/Tasks/0
+ ```
-- Method 2: From the BMC command line:
+ - Method 2: From the BMC command line:
- ```
- busctl get-property xyz.openbmc_project.Software.BMC.Updater \
- /xyz/openbmc_project/software/<id> \
- xyz.openbmc_project.Software.ActivationProgress Progress
- ```
+ ```bash
+ busctl get-property xyz.openbmc_project.Software.BMC.Updater \
+ /xyz/openbmc_project/software/<id> \
+ xyz.openbmc_project.Software.ActivationProgress Progress
+ ```
-- Method 3: Using the REST API:
+ - Method 3: Using the REST API:
- ```
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>/attr/Progress
- ```
+ ```bash
+ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>/attr/Progress
+ ```
6. Check that the activation is complete by verifying the "Activation" property
is set to "Active" via one of the following methods:
-- Method 1: From Redfish: Check the task returned from the Redfish upload.
+ - Method 1: From Redfish: Check the task returned from the Redfish upload.
- ```
- curl -k https://${bmc}/redfish/v1/TaskService/Tasks/0
- ```
+ ```bash
+ curl -k https://${bmc}/redfish/v1/TaskService/Tasks/0
+ ```
-- Method 2: From the BMC command line:
+ - Method 2: From the BMC command line:
- ```
- busctl get-property xyz.openbmc_project.Software.BMC.Updater \
- /xyz/openbmc_project/software/<id> \
- xyz.openbmc_project.Software.Activation Activation
- ```
+ ```bash
+ busctl get-property xyz.openbmc_project.Software.BMC.Updater \
+ /xyz/openbmc_project/software/<id> \
+ xyz.openbmc_project.Software.Activation Activation
+ ```
-- Method 3: Using the REST API:
+ - Method 3: Using the REST API:
- ```
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>
- ```
+ ```bash
+ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>
+ ```
7. Reboot the BMC for the image to take effect.
-- Method 1: From Redfish: If ApplyTime was set to "Immediate", the BMC will
- automatically reboot:
- https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md#firmware-applytime.
- To reboot the BMC manually see:
- https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md#bmc-reboot.
+ - Method 1: From Redfish: If ApplyTime was set to "Immediate", the BMC will
+ automatically reboot:
+ <https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md#firmware-applytime>.
+ To reboot the BMC manually see:
+ <https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md#bmc-reboot>.
-- Method 2: From the BMC command line:
+ - Method 2: From the BMC command line:
- ```
- reboot
- ```
+ ```bash
+ reboot
+ ```
-- Method 3: Using the REST API:
+ - Method 3: Using the REST API:
- ```
- curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
- -d '{"data": "xyz.openbmc_project.State.BMC.Transition.Reboot"}' \
- https://${bmc}/xyz/openbmc_project/state/bmc0/attr/RequestedBMCTransition
- ```
+ ```bash
+ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
+ -d '{"data": "xyz.openbmc_project.State.BMC.Transition.Reboot"}' \
+ https://${bmc}/xyz/openbmc_project/state/bmc0/attr/RequestedBMCTransition
+ ```
-### Associations
+## Associations
In addition to all software images, several associations are listed at
`/xyz/openbmc_project/software/`:
-```
+```bash
curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
https://${bmc}/xyz/openbmc_project/software/
{
@@ -198,101 +199,101 @@
1. A "functional" association to the "running" BMC and host images
-There is only one functional association per BMC and one functional association
-per host. The functional/running BMC image is the BMC image with the lowest
-priority when rebooting the BMC. The functional image does not update until the
-BMC is rebooted. The functional host image behaves the same way except that it
-updates on a power on or reboot of the host.
+ There is only one functional association per BMC and one functional
+ association per host. The functional/running BMC image is the BMC image with
+ the lowest priority when rebooting the BMC. The functional image does not
+ update until the BMC is rebooted. The functional host image behaves the same
+ way except that it updates on a power on or reboot of the host.
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
- https://${bmc}/xyz/openbmc_project/software/functional
-{
- "data": {
- "endpoints": [
- "/xyz/openbmc_project/software/46e65782",
- "/xyz/openbmc_project/software/493a00ad"
- ]
- },
- "message": "200 OK",
- "status": "ok"
-}
-```
+ ```bash
+ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
+ https://${bmc}/xyz/openbmc_project/software/functional
+ {
+ "data": {
+ "endpoints": [
+ "/xyz/openbmc_project/software/46e65782",
+ "/xyz/openbmc_project/software/493a00ad"
+ ]
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
2. An "active" association to the active BMC and host images
-Note: Several BMC images might be active, this is true for the host images as
-well.
+ Note: Several BMC images might be active, this is true for the host images as
+ well.
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
- https://${bmc}/xyz/openbmc_project/software/active
-{
- "data": {
- "endpoints": [
- "/xyz/openbmc_project/software/46e65782",
- "/xyz/openbmc_project/software/493a00ad",
- "/xyz/openbmc_project/software/88c153b1"
- ]
- },
- "message": "200 OK",
- "status": "ok"
-}
-```
+ ```bash
+ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
+ https://${bmc}/xyz/openbmc_project/software/active
+ {
+ "data": {
+ "endpoints": [
+ "/xyz/openbmc_project/software/46e65782",
+ "/xyz/openbmc_project/software/493a00ad",
+ "/xyz/openbmc_project/software/88c153b1"
+ ]
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
3. An "updateable" association to the programmable components
-This is used for identifying firmware components which are programmable via BMC
-OOB interfaces like Redfish/IPMI. All updateable firmware components must expose
-the updateable association so that upper applications like Redfish/IPMI will
-know about updateable firmwares.
+ This is used for identifying firmware components which are programmable via
+ BMC OOB interfaces like Redfish/IPMI. All updateable firmware components must
+ expose the updateable association so that upper applications like
+ Redfish/IPMI will know about updateable firmwares.
-To know the updateable software components:
+ To know the updateable software components:
-```
-# busctl call xyz.openbmc_project.ObjectMapper \
- /xyz/openbmc_project/software/updatable org.freedesktop.DBus.Properties \
- Get ss xyz.openbmc_project.Association endpoints
-v as 1 "/xyz/openbmc_project/software/1201fc36"
-```
+ ```bash
+ busctl call xyz.openbmc_project.ObjectMapper \
+ /xyz/openbmc_project/software/updatable org.freedesktop.DBus.Properties \
+ Get ss xyz.openbmc_project.Association endpoints
+ v as 1 "/xyz/openbmc_project/software/1201fc36"
+ ```
-Redfish interface uses 'updateable' association in SoftwareInventory schema.
+ Redfish interface uses 'updateable' association in SoftwareInventory schema.
4. An additional association is located at
`/xyz/openbmc_project/software/<id>/inventory` for "associating" a software
image with an inventory item.
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
- https://${bmc}/xyz/openbmc_project/software/493a00ad/inventory
-{
- "data": {
- "endpoints": [
- "/xyz/openbmc_project/inventory/system/chassis/motherboard/boxelder/bmc"
- ]
- },
- "message": "200 OK",
- "status": "ok"
-}
-```
+ ```bash
+ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
+ https://${bmc}/xyz/openbmc_project/software/493a00ad/inventory
+ {
+ "data": {
+ "endpoints": [
+ "/xyz/openbmc_project/inventory/system/chassis/motherboard/boxelder/bmc"
+ ]
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
-To get all software images associated with an inventory item:
+ To get all software images associated with an inventory item:
-```
-curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
- https://${bmc}/xyz/openbmc_project/inventory/system/chassis/activation
-{
- "data": {
- "endpoints": [
- "/xyz/openbmc_project/software/46e65782"
- ]
- },
- "message": "200 OK",
- "status": "ok"
-}
-```
+ ```bash
+ curl -c cjar -b cjar -k -H "Content-Type: application/json" -X GET \
+ https://${bmc}/xyz/openbmc_project/inventory/system/chassis/activation
+ {
+ "data": {
+ "endpoints": [
+ "/xyz/openbmc_project/software/46e65782"
+ ]
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
-### MANIFEST File
+## MANIFEST File
A file named "MANIFEST" must be included in any image tar uploaded, downloaded
via TFTP, or copied to the BMC.
@@ -319,11 +320,11 @@
- extended_version - A more detailed version, which could include versions of
different components in the image.
-### Deleting an Image
+## Deleting an Image
To delete an image:
-```
+```bash
curl -c cjar -b cjar -k -H "Content-Type: application/json" \
-X POST https://${bmc}/xyz/openbmc_project/software/<$id>/action/delete \
-d "{\"data\": [] }"
@@ -333,13 +334,13 @@
To delete all non-functional images, whether BMC or host images:
-```
+```bash
curl -c cjar -b cjar -k -H "Content-Type: application/json" \
-X POST https://${bmc}/xyz/openbmc_project/software/action/deleteAll \
-d "{\"data\": [] }"
```
-### Software Field Mode
+## Software Field Mode
Field mode is meant for systems shipped from manufacturing to a customer. Field
mode offers a way to provide security and ensure incorrect patches don't get
@@ -351,7 +352,7 @@
Field mode can be enabled by running the following command:
-```
+```bash
curl -b cjar -k -H 'Content-Type: application/json' -X PUT -d '{"data":1}' \
https://${bmc}/xyz/openbmc_project/software/attr/FieldModeEnabled
@@ -360,7 +361,7 @@
Although field mode is meant to be a one-way operation, it can be disabled by a
user with admin privileges by running the following commands on the BMC:
-```
+```bash
fw_setenv fieldmode
systemctl unmask usr-local.mount
@@ -369,15 +370,15 @@
```
More information on field mode can be found here:
-https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/FieldMode.interface.yaml
+<https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/FieldMode.interface.yaml>
-### Software Factory Reset
+## Software Factory Reset
Software factory reset resets the BMC and host firmware to its factory state by
clearing out any read/write data. To software factory reset run the following
command and then reboot the BMC:
-```
+```bash
curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' \
https://${bmc}/xyz/openbmc_project/software/action/Reset
@@ -389,11 +390,11 @@
any host patches located in `/usr/local/share/pnor/`.
The factory reset interface can be found here:
-https://github.com/openbmc/phosphor-dbus-interfaces/blob/02b39246d45ea029a1652a49cc20eab7723dd63b/xyz/openbmc_project/Common/FactoryReset.interface.yaml
+<https://github.com/openbmc/phosphor-dbus-interfaces/blob/02b39246d45ea029a1652a49cc20eab7723dd63b/xyz/openbmc_project/Common/FactoryReset.interface.yaml>
-### Image Storage Location
+## Image Storage Location
-#### Static layout
+### Static layout
When a BMC image is activated, each `image-<name>` is written to the BMC chip's
partitions indicated by the `<name>`:
@@ -403,7 +404,7 @@
- image-rofs
- image-rwfs
-#### UBI layout
+### UBI layout
When a BMC image is activated (i.e. when "RequestedActivation" is set to
"Active"), UBI volumes are created on the BMC chip for the image. The alternate
@@ -412,8 +413,8 @@
images to be stored. By default, only the BMC chip is used. To use both, set
"BMC_RO_MTD" to "alt-bmc+bmc".
-### Implementation
+## Implementation
More information about the implementation of the code update can be found at
-https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software
-and https://github.com/openbmc/phosphor-bmc-code-mgmt
+<https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software>
+and <https://github.com/openbmc/phosphor-bmc-code-mgmt>
diff --git a/architecture/code-update/firmware-update-over-redfish.md b/architecture/code-update/firmware-update-over-redfish.md
index 2a56398..b962ced 100644
--- a/architecture/code-update/firmware-update-over-redfish.md
+++ b/architecture/code-update/firmware-update-over-redfish.md
@@ -16,12 +16,13 @@
## Background and References
-The existing firmware update details for OpenBMC can be found [here][2]. It uses
-a custom REST api for uploading and then activating the input image.
+The existing firmware update details for OpenBMC can be found in the
+[architecture][2]. It uses a custom REST api for uploading and then activating
+the input image.
-The Redfish schema for firmware update can be found [here][3]. Note the
-referenced doc points to the most recent version of the schema and that is what
-you'll want to load into your browser (at the time of this writing it is
+The Redfish schema for firmware update can be found in the [DMTF schemas][3].
+Note the referenced doc points to the most recent version of the schema and that
+is what you'll want to load into your browser (at the time of this writing it is
[v1_4_0][4]).
Some differences between the Redfish API and OpenBMC's existing API:
@@ -106,7 +107,7 @@
The pseudo flow for an update is:
-```
+```bash
Discover UpdateService location
HttpPushUri = GET https://${bmc}/redfish/v1/UpdateService
POST ApplyTime property in
@@ -139,7 +140,7 @@
provide status of inventory items back to the user. Here is the mapping of
[phosphor activation states][13] to [Redfish Status States][14].
-```
+```text
NotReady -> Disabled
Invalid -> Disabled
Ready -> Disabled
@@ -179,7 +180,7 @@
The pseudo flow for an update is:
-```
+```bash
# Discover SimpleUpdate URI Action location
GET https://${bmc}/redfish/v1/UpdateService
diff --git a/architecture/code-update/host-code-update.md b/architecture/code-update/host-code-update.md
index 57f4413..729b0ae 100644
--- a/architecture/code-update/host-code-update.md
+++ b/architecture/code-update/host-code-update.md
@@ -1,138 +1,139 @@
# Host Code Update
Reference:
-https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software
+<https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software>
Following are the steps to update the host firmware (or "BIOS"). This assumes
the host is not accessing its firmware.
1. Get a squashfs image:
-- Build op-build: https://github.com/open-power/op-build
-- After building, the image should be a tarball in the output/images directory
- called <system type>.pnor.squashfs.tar
+ - Build op-build: <https://github.com/open-power/op-build>
+ - After building, the image should be a tarball in the output/images
+ directory called `<system type>.pnor.squashfs.tar`
2. Transfer the generated squashfs image to the BMC via one of the following
methods:
-- Method 1: Via scp: Copy the generated squashfs image to the `/tmp/images/`
- directory on the BMC.
-- Method 2: Via REST Upload:
- https://github.com/openbmc/docs/blob/master/rest-api.md#uploading-images
-- Method 3: Via TFTP: Perform a POST request to call the `DownloadViaTFTP`
- method of `/xyz/openbmc_project/software`.
+ - Method 1: Via scp: Copy the generated squashfs image to the `/tmp/images/`
+ directory on the BMC.
+ - Method 2: Via REST Upload:
+ <https://github.com/openbmc/docs/blob/master/rest-api.md#uploading-images>
+ - Method 3: Via TFTP: Perform a POST request to call the `DownloadViaTFTP`
+ method of `/xyz/openbmc_project/software`.
- ```
- curl -b cjar -k -H "Content-Type: application/json" -X POST \
- -d '{"data": ["<filename>", "<TFTP server IP address"]}' \
- https://${bmc}/xyz/openbmc_project/software/action/DownloadViaTFTP
- ```
+ ```bash
+ curl -b cjar -k -H "Content-Type: application/json" -X POST \
+ -d '{"data": ["<filename>", "<TFTP server IP address"]}' \
+ https://${bmc}/xyz/openbmc_project/software/action/DownloadViaTFTP
+ ```
3. Note the version id generated for that image file. The version id is a hash
value of 8 hexadecimal numbers, generated by SHA-512 hashing the version
string contained in the image and taking the first 8 characters. Get the
version id via one of the following methods:
-- Method 1: From the BMC command line, note the most recent directory name
- created under `/tmp/images/`, in this example it'd be `2a1022fe`:
+ - Method 1: From the BMC command line, note the most recent directory name
+ created under `/tmp/images/`, in this example it'd be `2a1022fe`:
- ```
- # ls -l /tmp/images/
- total 0
- drwx------ 2 root root 80 Aug 22 07:54 2a1022fe
- drwx------ 2 root root 80 Aug 22 07:53 488449a2
- ```
+ ```bash
+ # ls -l /tmp/images/
+ total 0
+ drwx------ 2 root root 80 Aug 22 07:54 2a1022fe
+ drwx------ 2 root root 80 Aug 22 07:53 488449a2
+ ```
-- Method 2: This method _only_ works if there are no `Ready` images at the start
- of transferring the image. Using the REST API, note the object that has its
- Activation property set to Ready, in this example it'd be `2a1022fe`:
+ - Method 2: This method _only_ works if there are no `Ready` images at the
+ start of transferring the image. Using the REST API, note the object that
+ has its Activation property set to Ready, in this example it'd be
+ `2a1022fe`:
- ```
- $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/enumerate
- {
- "data": {
- "/xyz/openbmc_project/software/2a1022fe": {
- "Activation": "xyz.openbmc_project.Software.Activation.Activations.Ready",
- ```
+ ```json
+ $ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/enumerate
+ {
+ "data": {
+ "/xyz/openbmc_project/software/2a1022fe": {
+ "Activation": "xyz.openbmc_project.Software.Activation.Activations.Ready",
+ ```
-- Method 3: Calculate the version id beforehand from the image with:
+ - Method 3: Calculate the version id beforehand from the image with:
- ```
- tar xfO <squashfs image tar> MANIFEST | sed -ne '/version=/ {s/version=//;p}' | head -n1 | tr -d '\n' | sha512sum | cut -b 1-8
- ```
+ ```bash
+ tar xfO <squashfs image tar> MANIFEST | sed -ne '/version=/ {s/version=//;p}' | head -n1 | tr -d '\n' | sha512sum | cut -b 1-8
+ ```
4. To initiate the update, set the `RequestedActivation` property of the desired
image to `Active`, substitute `<id>` with the hash value noted on the
previous step, this will write the contents of the image to a UBI volume in
the PNOR chip via one of the following methods:
-- Method 1: From the BMC command line:
+ - Method 1: From the BMC command line:
- ```
- busctl set-property org.open_power.Software.Host.Updater \
- /xyz/openbmc_project/software/<id> \
- xyz.openbmc_project.Software.Activation RequestedActivation s \
- xyz.openbmc_project.Software.Activation.RequestedActivations.Active
+ ```bash
+ busctl set-property org.open_power.Software.Host.Updater \
+ /xyz/openbmc_project/software/<id> \
+ xyz.openbmc_project.Software.Activation RequestedActivation s \
+ xyz.openbmc_project.Software.Activation.RequestedActivations.Active
- ```
+ ```
-- Method 2: Using the REST API:
+ - Method 2: Using the REST API:
- ```
- curl -b cjar -k -H "Content-Type: application/json" -X PUT \
- -d '{"data":
- "xyz.openbmc_project.Software.Activation.RequestedActivations.Active"}' \
- https://${bmc}/xyz/openbmc_project/software/<id>/attr/RequestedActivation
- ```
+ ```bash
+ curl -b cjar -k -H "Content-Type: application/json" -X PUT \
+ -d '{"data":
+ "xyz.openbmc_project.Software.Activation.RequestedActivations.Active"}' \
+ https://${bmc}/xyz/openbmc_project/software/<id>/attr/RequestedActivation
+ ```
5. (Optional) Check the flash progress. This interface is only available during
the activation progress and is not present once the activation is completed
via one of the following:
-- Method 1: From the BMC command line:
+ - Method 1: From the BMC command line:
- ```
- busctl get-property org.open_power.Software.Host.Updater \
- /xyz/openbmc_project/software/<id> \
- xyz.openbmc_project.Software.Activation Progress
- ```
+ ```bash
+ busctl get-property org.open_power.Software.Host.Updater \
+ /xyz/openbmc_project/software/<id> \
+ xyz.openbmc_project.Software.Activation Progress
+ ```
-- Method 2: Using the REST API:
+ - Method 2: Using the REST API:
- ```
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>/attr/Progress
- ```
+ ```bash
+ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>/attr/Progress
+ ```
6. Check the activation is complete by verifying the Activation property is set
to Active via one of the following methods:
-- Method 1: From the BMC command line:
+ - Method 1: From the BMC command line:
- ```
- busctl get-property org.open_power.Software.Host.Updater \
- /xyz/openbmc_project/software/<id> \
- xyz.openbmc_project.Software.Activation Activation
- ```
+ ```bash
+ busctl get-property org.open_power.Software.Host.Updater \
+ /xyz/openbmc_project/software/<id> \
+ xyz.openbmc_project.Software.Activation Activation
+ ```
-- Method 2: Using the REST API:
+ - Method 2: Using the REST API:
- ```
- curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>
- ```
+ ```bash
+ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>
+ ```
-### Patching the host firmware
+## Patching the host firmware
Copy the partition binary file to `/usr/local/share/pnor/` on the BMC.
The partition binary file must be named the same as the partition name that
intends to patch, ex: `ATTR_TMP`.
-### Associations, MANIFEST File, Deleting an Image, Software Field Mode, and Software Factory Reset
+## Associations, MANIFEST File, Deleting an Image, Software Field Mode, and Software Factory Reset
Information about associations, the MANIFEST file, deleting an image, software
field mode, and software factory reset can be found at
[code-update.md#associations](code-update.md#associations)
-### Implementation
+## Implementation
-https://github.com/openbmc/openpower-pnor-code-mgmt
+<https://github.com/openbmc/openpower-pnor-code-mgmt>
diff --git a/architecture/interface-overview.md b/architecture/interface-overview.md
index ebc38db..0a525b9 100644
--- a/architecture/interface-overview.md
+++ b/architecture/interface-overview.md
@@ -24,7 +24,7 @@
OpenBMC's services and the interfaces they provide are controlled by `systemd`.
This document references OpenBMC `systemd` unit names to help link concepts to
the source code. The reader is assumed to be familiar with [systemd concepts][].
-The templated units ("unit@.service") may be omitted for clarity. Relevant
+The templated units (`unit@.service`) may be omitted for clarity. Relevant
details from the unit file may be shown, such as the program which implements a
service.
@@ -54,7 +54,7 @@
particular system. This section is intended to be referenced by additional
documentation which gives details for specific BMC and host implementations.
-```
+```ascii
+----------------+ +----------------+
| BMC | | Host |
| | | |
@@ -99,7 +99,7 @@
listed here by port number. More information about each service is given in
sections below or in the appendix.
-```
+```ascii
+----------------------------------+
| BMC |
| |
@@ -149,7 +149,7 @@
- Client access via ssh port 2200.
- The hostlogger facility.
-```
+```ascii
+---------------------------+ +-----------------+
| BMC | | Host |
ipmitool sol | | | |
@@ -172,7 +172,7 @@
OpenBMC provides a custom HTTP/Web server called BMCWeb.
-```
+```ascii
+--------------------------------------------------+
| BMC |
| |
@@ -213,7 +213,7 @@
OpenBMC provides a host IPMI service.
-```
+```ascii
+---------------+ +-----------------+
| BMC | | Host |
| | | |
@@ -235,7 +235,7 @@
communication) between OpenBMC applications. Note that other methods are used,
for example Unix domain sockets.
-```
+```ascii
+--------------------------------------------------+
| BMC |
| |
@@ -273,7 +273,7 @@
"management network" to distinguish it from the payload network the host system
is connected to. These are typically separate networks.
-```
+```ascii
+-----------+ +----------------+
| BMC | | Host |
management | | | |
@@ -285,7 +285,7 @@
The BMC may be served by a Network Controller Sideband Interface (NC-SI) which
maintains a logically separate network from the host, as shown in this diagram:
-```
+```ascii
+-----------+ +----------------+
| BMC | | Host |
management | | | |
@@ -305,7 +305,7 @@
The BMC's management network may be provided by its host system and have no
direct connection external to the host, as shown in this diagram:
-```
+```ascii
+-----------+ +----------------+
| BMC | | Host |
| | | |
@@ -320,7 +320,7 @@
The BMC's management network may be connected to USB (LAN over USB):
-```
+```ascii
+-----------+ +----------------+
| BMC | | Host |
+-+ | | | |
@@ -381,7 +381,7 @@
more. Also known as out of band IPMI. Contrast with host-IPMI which interacts
with the host and with Redfish which provides alternate function.
-The BMC's RMCP+ IPMI interface is designed to be operated by the `[ipmitool][]`
+The BMC's RMCP+ IPMI interface is designed to be operated by the [ipmitool][]
external command.
[ipmi session management]:
@@ -406,7 +406,7 @@
### obmc-console
This refers to support for multiple independent consoles in
-https://github.com/openbmc/obmc-console and two applications:
+<https://github.com/openbmc/obmc-console> and two applications:
- The `obmc-console-server` abstracts the host console (UART) connection as a
Unix domain socket.
@@ -417,14 +417,14 @@
### hostlogger
Refers to the BMC service provided by the `hostlogger` program here:
-https://github.com/openbmc/phosphor-hostlogger which listens to the
+<https://github.com/openbmc/phosphor-hostlogger> which listens to the
`obmc-console-server` and logs host console messages into the BMC's file system.
### BMCWeb web server
Refers to the custom HTTP/Web server with source here:
-https://github.com/openbmc/bmcweb Note that BMCWeb is configurable per
-https://github.com/openbmc/bmcweb#configuration with build-time options to
+<https://github.com/openbmc/bmcweb> Note that BMCWeb is configurable per
+<https://github.com/openbmc/bmcweb#configuration> with build-time options to
control which interfaces it provides. For example, there are configurations
options to:
@@ -438,26 +438,26 @@
### Redfish
Refers to the set of Redfish REST APIs served by the BMCWeb web server. See
-details here: https://github.com/openbmc/bmcweb/blob/master/Redfish.md with docs
-here: https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md
+details here: <https://github.com/openbmc/bmcweb/blob/master/Redfish.md> with
+docs here: <https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md>
### phosphor-dbus-rest
Refers to the legacy REST APIs optionally served by the BMCWeb server. Docs:
-https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md
+<https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md>
### KVM-IP
Refers to the OpenBMC implementation of the Remote Frame Buffer (RFB, aka VNC)
protocol which lets you operate the host system's keyboard, video, and mouse
-(KVM) remotely. See https://github.com/openbmc/obmc-ikvm/blob/master/README.md
+(KVM) remotely. See <https://github.com/openbmc/obmc-ikvm/blob/master/README.md>
Also known as IPKvm. Do not confuse with Kernel Virtual Machine (the other KVM).
### Virtual media
-Also known as: remote media and USB-over-IP. Design:
-https://github.com/openbmc/docs/blob/master/designs/VirtualMedia.md Contrast
-with LAN-over-USB.
+- Also known as: remote media and USB-over-IP.
+- Design: <https://github.com/openbmc/docs/blob/master/designs/VirtualMedia.md>
+- Contrast with LAN-over-USB.
### Virtual USB
diff --git a/architecture/ipmi-architecture.md b/architecture/ipmi-architecture.md
index 5f38989..633d93a 100644
--- a/architecture/ipmi-architecture.md
+++ b/architecture/ipmi-architecture.md
@@ -14,7 +14,7 @@
Completion Code and optional data. So the first step is to break apart channels
and the IPMI queue.
-```
+```ascii
/------------------\
/----------------------------\ | |
| KCS/BT - Host | <-All IPMI cmds-> | |
@@ -264,13 +264,13 @@
Some types that are supported are as follows:
-- standard integer types (uint8_t, uint16_t, uint32_t, int, long, etc.)
-- bool (extracts a single bit, same as uint1_t)
-- multi-precision integers (uint<N>)
-- std::bitset<N>
-- std::optional<T> - extracts T if there are enough remaining bits/bytes
-- std::array<T, N> - extracts N elements of T if possible
-- std::vector<T> - extracts elements of T from the remaining bytes
+- standard integer types (`int8_t`, `uint16_t`, `uint32_t`, `int`, `long`, etc.)
+- `bool` (extracts a single bit, same as `uint1_t`)
+- multi-precision integers (`uint<N>`)
+- `std::bitset<N>`
+- `std::optional<T>` - extracts T if there are enough remaining bits/bytes
+- `std::array<T, N>` - extracts N elements of T if possible
+- `std::vector<T>` - extracts elements of T from the remaining bytes
- any additional types can be created by making a pack/unpack template
For partial byte types, the least-significant bits of the next full byte are
diff --git a/architecture/object-mapper.md b/architecture/object-mapper.md
index 59ca584..1086ccc 100644
--- a/architecture/object-mapper.md
+++ b/architecture/object-mapper.md
@@ -12,7 +12,8 @@
## Methods
-The official YAML interface definition can be found [here][1].
+The official YAML interface definition can be found in
+[phosphor-dbus-interfaces][1].
### GetObject
@@ -30,7 +31,7 @@
- Map of service names to their interfaces
-```
+```bash
dbus-send --system --print-reply \
--dest=xyz.openbmc_project.ObjectMapper \
/xyz/openbmc_project/object_mapper \
@@ -73,7 +74,7 @@
- Map of object paths to a map of service names to their interfaces
-```
+```bash
dbus-send --system --print-reply \
--dest=xyz.openbmc_project.ObjectMapper \
/xyz/openbmc_project/object_mapper \
@@ -137,7 +138,7 @@
- Map of object paths to a map of service names to their interfaces that is in
the associated endpoints
-```
+```bash
dbus-send --system --print-reply \
--dest=xyz.openbmc_project.ObjectMapper \
/xyz/openbmc_project/object_mapper \
@@ -213,7 +214,7 @@
- Map of object paths to a map of service names to their interfaces that are in
the associated endpoints that end with `id`
-```text
+```bash
ID="chassis"
ASSOCIATION="powered_by"
dbus-send --system --print-reply \
@@ -287,7 +288,7 @@
- array of object paths in that subtree
-```
+```bash
dbus-send --system --print-reply \
--dest=xyz.openbmc_project.ObjectMapper \
/xyz/openbmc_project/object_mapper \
@@ -322,7 +323,7 @@
- array of object paths in that subtree that is in the associated endpoints
-```
+```bash
dbus-send --system --print-reply \
--dest=xyz.openbmc_project.ObjectMapper \
/xyz/openbmc_project/object_mapper \
@@ -370,7 +371,7 @@
- Map of object paths to a map of service names to their interfaces that are in
the associated endpoints that ends with `id`
-```text
+```bash
ID="chassis"
ASSOCIATION="powered_by"
dbus-send --system --print-reply \
@@ -419,7 +420,7 @@
- A map of object paths to a map of services names to their interfaces
-```
+```bash
dbus-send --system --print-reply \
--dest=xyz.openbmc_project.ObjectMapper \
@@ -479,7 +480,7 @@
This `Associations` property is an array of tuples of the form:
-```
+```text
[forward, reverse, object path]
```
@@ -490,7 +491,7 @@
When an object with, for example, an object path of `pathA` uses the following
values:
-```
+```json
["foo", "bar", "pathB"]
```
@@ -521,11 +522,11 @@
`org.openbmc.Associations`. While the mapper still supports this interface as
well for the time being, new code should use the `xyz` version.
-#### Example Use Case
+### Example Use Case
Associate an error log with the inventory item that caused it.
-```
+```text
# Error log
"/xyz/openbmc_project/logging/entry/3": {
...
diff --git a/architecture/openbmc-systemd.md b/architecture/openbmc-systemd.md
index 39ed729..db5cbeb 100644
--- a/architecture/openbmc-systemd.md
+++ b/architecture/openbmc-systemd.md
@@ -45,7 +45,7 @@
If you dig into its .requires relationship, you'll see the following in the file
system
-```
+```shell
ls -1 /lib/systemd/system/obmc-host-start@0.target.requires/
obmc-host-startmin@0.target
phosphor-reset-host-reboot-attempts@0.service
@@ -63,7 +63,7 @@
Next if we look at the `obmc-host-startmin@0.target`, we see this:
-```
+```shell
ls -1 /lib/systemd/system/obmc-host-startmin@0.target.requires/
obmc-chassis-poweron@0.target
start_host@0.service
@@ -76,7 +76,7 @@
The `obmc-chassis-poweron@0.target` has corresponding services associated with
it:
-```
+```shell
ls -1 /lib/systemd/system/obmc-chassis-poweron@0.target.requires/
op-power-start@0.service
op-wait-power-on@0.service
@@ -180,22 +180,22 @@
1. A service within a target fails
-- If the service is a "oneshot" type, and the service is required (not wanted)
- by the target then the target will fail if the service fails - Define a
- behavior for when the target fails using the "OnFailure" option (i.e. go to a
- new failure target if any required service fails)
-- If the service is not a "oneshot", then it can not fail the target (the target
- only knows that it started successfully) - Define a behavior for when the
- service fails (OnFailure) option. - The service can not have
- "RemainAfterExit=yes" otherwise, the OnFailure action does not occur until the
- service is stopped (instead of when it fails) - \*See more information below
- on [RemainAfterExit](#RemainAfterExit)
+ - If the service is a "oneshot" type, and the service is required (not
+ wanted) by the target then the target will fail if the service fails -
+ Define a behavior for when the target fails using the "OnFailure" option
+ (i.e. go to a new failure target if any required service fails)
+ - If the service is not a "oneshot", then it can not fail the target (the
+ target only knows that it started successfully) - Define a behavior for
+ when the service fails (OnFailure) option. - The service can not have
+ "RemainAfterExit=yes" otherwise, the OnFailure action does not occur until
+ the service is stopped (instead of when it fails) - \*See more information
+ below on [RemainAfterExit](#remainafterexit)
2. A failure outside of a normal systemd target/service (host watchdog expires,
host checkstop detected)
-- The service which detects this failure is responsible for logging the
- appropriate error, and instructing systemd to go to the appropriate target
+ - The service which detects this failure is responsible for logging the
+ appropriate error, and instructing systemd to go to the appropriate target
Within OpenBMC, there is a host quiesce target. This is the target that other
host related targets should go to when they hit a failure. Other software within
@@ -242,7 +242,7 @@
For now, document the current dependencies on a witherspoon system for
reference.
-```
+```text
R = Requires
W = Wants
A = After
@@ -253,7 +253,7 @@
### Soft Power Off
-```
+```text
obmc-host-shutdown.target
R: xyz.openbmc_project.Ipmi.Internal.SoftPowerOff.service
W: obmc-host-stopping.target (S)
@@ -288,7 +288,7 @@
#### Synchronization Target Dependencies
-```
+```text
obmc-power-stop.target
W: obmc-power-stop-pre.target
A: obmc-power-stop-pre.target
diff --git a/architecture/sensor-architecture.md b/architecture/sensor-architecture.md
index 8502ee3..909e975 100644
--- a/architecture/sensor-architecture.md
+++ b/architecture/sensor-architecture.md
@@ -14,7 +14,7 @@
## D-Bus
-```
+```text
Service xyz.openbmc_project.Hwmon-<hash>.Hwmon1
Path /xyz/openbmc_project/sensors/<type>/<label>
Interfaces xyz.openbmc_project.Sensor.[*], others (see below)
@@ -22,7 +22,7 @@
Signals: All properties for an interface will broadcast signal changed
```
-**Path definitions**
+### Path definitions
- **<type\>** : The [HWMon class][2] name in lower case.
@@ -32,9 +32,9 @@
- Examples include `ambient, cpu0, fan5`
**Note**: The label shall comply with "Valid Object Paths" of [D-Bus Spec][3],
-that shall only contain the ASCII characters "[A-Z][a-z][0-9]\_".
+that shall only contain the ASCII characters `[A-Z][a-z][0-9]\_`.
-**Hash definition**
+### Hash definition
The hash value in the service name is used to give the service a unique and
stable name. It is a decimal number that is obtained by hashing characteristics
@@ -140,21 +140,21 @@
[Warning.interface.yaml][6]
-```
+```yaml
properties:
- - name: WarningHigh
- type: int64
- - name: WarningLow
- type: int64
- - name: WarningAlarmHigh
- type: boolean
- - name: WarningAlarmLow
- type: boolean
+ - name: WarningHigh
+ type: int64
+ - name: WarningLow
+ type: int64
+ - name: WarningAlarmHigh
+ type: boolean
+ - name: WarningAlarmLow
+ type: boolean
```
Maps to
-```
+```text
busctl --system introspect xyz.openbmc_project.Hwmon-3301914901.Hwmon1 \
/xyz/openbmc_project/Sensors/temperature/ambient \
xyz.openbmc_project.Sensor.Threshold.Warning | grep property
@@ -168,15 +168,17 @@
### REST
-```
-"/xyz/openbmc_project/Sensors/temperature/ambient": {
- "Scale": -3,
- "Unit": "xyz.openbmc_project.Sensor.Value.Unit.DegreesC",
- "Value": 30125,
- "WarningAlarmHigh": 0,
- "WarningAlarmLow": 0,
- "WarningHigh": 40000,
- "WarningLow": 10000
+```json
+{
+ "/xyz/openbmc_project/Sensors/temperature/ambient": {
+ "Scale": -3,
+ "Unit": "xyz.openbmc_project.Sensor.Value.Unit.DegreesC",
+ "Value": 30125,
+ "WarningAlarmHigh": 0,
+ "WarningAlarmLow": 0,
+ "WarningHigh": 40000,
+ "WarningLow": 10000
+ }
}
```
@@ -185,12 +187,12 @@
Aside from the `xyz.openbmc_project.Sensor` interfaces, the sensor D-Bus objects
may also expose the following interfaces:
-1. `xyz.openbmc_project.Control.FanSpeed`
- - Provides a Target property to set a fan RPM value
-2. `xyz.openbmc_project.Control.FanPwm`
- - Provides a Target property to set a fan PWM value
-3. `xyz.openbmc_project.State.Decorator.OperationalStatus`
- - Provides a Functional property that tracks the state of any fault files
+1. `xyz.openbmc_project.Control.FanSpeed`
+ - Provides a Target property to set a fan RPM value
+2. `xyz.openbmc_project.Control.FanPwm`
+ - Provides a Target property to set a fan PWM value
+3. `xyz.openbmc_project.State.Decorator.OperationalStatus`
+ - Provides a Functional property that tracks the state of any fault files
### Signals
@@ -217,37 +219,39 @@
within the [machine configuration][7]. The children of the `obmc/hwmon`
directory should follow the path of either:
-1. The children of the `devicetree/base` directory path on the system, as
- defined by the kernel. The code obtains this from the OF_FULLNAME udev
- environment variable.
+1. The children of the `devicetree/base` directory path on the system, as
+ defined by the kernel. The code obtains this from the OF_FULLNAME udev
+ environment variable.
-2. If the device isn't in the device tree, then the device path can be used.
+2. If the device isn't in the device tree, then the device path can be used.
As an example, the Palmetto [configuration][8] file for the ambient temperature
sensor.
-```
+```text
recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/bus@1e78a000/i2c-bus@c0/tmp423@4c.conf
+
```
which maps to this specific sensor and conf file on the system...
-```
+```text
/sys/firmware/devicetree/base/ahb/apb/bus@1e78a000/i2c-bus@c0/tmp423@4c
/etc/default/obmc/hwmon/ahb/apb/bus@1e78a000/i2c@c0/tmp423@4c.conf
+
```
This next example shows using the device path as opposed to the devicetree path
for the OCC device on an OpenPOWER system. Note how a '--' replaces a ':' in the
directory names for the conf file.
-```
+```text
recipes-phosphor/sensors/phosphor-hwmon%/obmc/hwmon/devices/platform/gpio-fsi/fsi0/slave@00--00/00--00--00--06/sbefifo1-dev0/occ-hwmon.1.conf
```
which maps to this specific sensor and conf file on the system...
-```
+```text
/sys/devices/platform/gpio-fsi/fsi0/slave@00:00/00:00:00:06/sbefifo1-dev0/occ-hwmon.1
/etc/default/obmc/hwmon/devices/platform/gpio-fsi/fsi0/slave@00--00/00--00--00--06/sbefifo1-dev0/occ-hwmon.1.conf
```
@@ -255,12 +259,15 @@
In order for the sensor to be exposed to D-Bus, the configuration file must
describe the sensor attributes. Attributes follow a format.
-```
+```text
xxx_yyy#=value
xxx = Attribute
-# = Association number (i.e. 1-n)
+
+# = Association number (i.e. 1-n)
+
yyy = HWMon sensor type (i.e. temp, pwm)
+
```
| Attribute | Interfaces Added |
@@ -283,26 +290,22 @@
In this conf example the tmp423 chip is wired to two temperature sensors. The
values must be described in 10<sup>-3</sup> degrees Celsius.
-```
-LABEL_temp1=ambient
-WARNLO_temp1=10000
-WARNHI_temp1=40000
+```text
+LABEL_temp1=ambient WARNLO_temp1=10000 WARNHI_temp1=40000
-LABEL_temp2=cpu
-WARNLO_temp2=10000
-WARNHI_temp2=80000
+LABEL_temp2=cpu WARNLO_temp2=10000 WARNHI_temp2=80000
```
-#### Additional Config File Entries
+### Additional Config File Entries
The phosphor-hwmon code supports these additional config file entries:
-**INTERVAL**
+#### INTERVAL
The interval, in microseconds, at which sensors should be read. If not specified
the interval is 1000000us (1 second).
-```
+```text
INTERVAL=1000000
```
@@ -311,21 +314,21 @@
Used to support scaled sensor readings, where value = (raw sensor reading) \*
gain + offset
-```
-GAIN_in3 = 5.0 #GAIN is a double
-OFFSET_in3 = 6 #OFFSET is an integer
+```text
+GAIN_in3 = 5.0 #GAIN is a double OFFSET_in3 = 6 #OFFSET is an integer
```
-**MINVALUE**, **MAXVALUE**
+#### MINVALUE / MAXVALUE
If found, will be used to set the MinValue/MaxValue properties on the
`xyz.openbmc_project.Sensor.Value` interface.
-```
+```text
MINVALUE_temp1 = 1
+
```
-**MODE**
+#### MODE
Needed for certain device drivers, specifically the OpenPOWER OCC driver, where
the instance number (the N in tempN_input) is dynamic and instead another file
@@ -333,9 +336,8 @@
For example
-```
-temp26_input:29000
-temp26_label:171
+```text
+temp26_input:29000 temp26_label:171
```
Where the 26 is just what hwmon assigns, but the 171 corresponds to something
@@ -343,44 +345,44 @@
The config file would then have:
-```
-MODE_temp26 = "label" #Tells the code to look in temp26_label
-LABEL_temp171 = "dimm3_temp" #Says that temp26_input holds dimm3_temp
+```text
+MODE_temp26 = "label" #Tells the code to look in temp26_label LABEL_temp171 =
+"dimm3_temp" #Says that temp26_input holds dimm3_temp
```
-**REMOVERCS**
+#### REMOVERCS
Contains a list of device driver errno values where if these are obtained when
reading the hardware, the corresponding sensor object will be removed from D-Bus
until it is successfully read again.
-```
-REMOVERCS = "5,6" #If any sensor on the device returns a 5 or 6, remove it.
-REMOVERCS_temp1 = "42" #If reading temp1_input returns a 42, remove it.
+```text
+REMOVERCS = "5,6" #If any sensor on the device returns a 5 or 6, remove it.
+REMOVERCS_temp1 = "42" #If reading temp1_input returns a 42, remove it.
```
-**TARGET_MODE**
+#### TARGET_MODE
Allows one to choose the fan target mode, either RPM or PWM, if the device
driver exposes both methods.
-```
+```text
TARGET_MODE = "RPM"
```
-**PWM_TARGET**
+#### PWM_TARGET
For fans that are PWM controlled, can be used to map the pwmN file to a fan M.
-```
+```text
PWM_TARGET_fan0 = 1 #Use the pwm1 file to control fan 0
```
-**ENABLE**
+#### ENABLE
Will write a value to a pwmN_enable file on startup if present.
-```
+```text
ENABLE_fan1 = 2 #Write a 2 to pwm1_enable
```
@@ -393,7 +395,7 @@
Sensor reading, according to IPMI spec, is calculated as:
-```none
+```text
y = L[(Mx + B * 10^(bExp)) * 10^(rExp)]
```
@@ -411,14 +413,14 @@
As you can tell, one should choose the coefficients based on possible sensor
reading range and desired resolution. Commonly, B=0, we would have
- Supported range: [0, 255 * M * 10^(scale - rExp)]
- Resolution: M * 10^(scale - rExp)
+- Supported range: [0, 255 \* M \* 10^(scale - rExp)]
+- Resolution: M \* 10^(scale - rExp)
For a concrete example, let's say a voltage sensor reports between 0 to 5.0V.
hwmon sysfs scales the value by 1000, so the sensor value read over DBus is
between 0 and 5000. A possible configuration for this is:
-```none
+```text
multiplierM: 20
offsetB: 0
bExp: 0
@@ -429,14 +431,16 @@
so for a DBus sensor value of 4986 meaning 4.986V, phosphor-ipmi-host would
encode it as
+```text
x: 4986 / 20 = 249
M: 20
rExp: -3
+```
When ipmitool sensor list is called, the tool fetches sensor factors and
computes value as:
-```none
+```text
y = 20 * 249 * 10^-3 = 4.98 (V)
```
diff --git a/architecture/user-management.md b/architecture/user-management.md
index 51d2497..7135441 100644
--- a/architecture/user-management.md
+++ b/architecture/user-management.md
@@ -75,12 +75,12 @@
User Manager service exposes D-Bus methods for user-management operations. It
exposes `xyz.openbmc_project.User.Manager` as a service and handles objects
through `org.freedesktop.DBus.ObjectManager`. Please refer
-https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/User
+<https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/User>
for detailed user management D-Bus API and interfaces.
## OpenBMC - User Management - High Level architectural diagram
-```
+```ascii
WEBSERVER/REDFISH
========================================================================
|| ________________ | ________________ | |**********************| ||
@@ -122,7 +122,7 @@
## User management - overview
-```
+```ascii
user management
+---------------------------------------------------------+
| phosphor-user-manager |
@@ -160,7 +160,7 @@
## OpenBMC - User Management - User creation from webserver flow - with all groups
-```
+```ascii
------------------------------------|---------------------------------- -|-----------------------------|
WEBSERVER | Common User Manager | IPMI & REDFISH(webserver) |
------------------------------------|------------------------------------|-----------------------------|
@@ -205,7 +205,7 @@
## OpenBMC - User Management - User creation from IPMI - 'ipmi' Group only
-```
+```ascii
------------------------------------|---------------------------------- -|-----------------------------|
IPMI | Common User Manager | pam_unix/pam_ipmi storage |
------------------------------------|------------------------------------|-----------------------------|
@@ -258,7 +258,7 @@
## OpenBMC - User Management - User deletion from webserver flow - with all groups
-```
+```ascii
------------------------------------|---------------------------------- -|-----------------------------|
WEBSERVER | Common User Manager | IPMI & REDFISH(webserver) |
------------------------------------|------------------------------------|-----------------------------|
@@ -293,7 +293,7 @@
## OpenBMC - User Management - User deletion from IPMI - 'ipmi' Group only
-```
+```ascii
------------------------------------|---------------------------------- -|
IPMI | Common User Manager |
------------------------------------|------------------------------------|
@@ -331,7 +331,7 @@
modules are used such that `pam_authenticate()` can be used for both local &
remote users.
-```
+```ascii
+----------------------------------+
| Stacked PAM Authentication |
| +-----------------------+ |
@@ -362,7 +362,7 @@
`pam_ipmicheck` and `pam_ipmisave` modules loaded as first & last modules in
stacked pam modules.
-```
+```ascii
+------------------+---------------+
| Stacked PAM - Password |
| |
@@ -401,7 +401,7 @@
## Authorization flow (except IPMI)
-```
+```ascii
+
|
|
@@ -510,7 +510,7 @@
1. Preprogrammed password unique to each device
2. Forcing user to generate new authentication account, before using the device.
-### Generating user during deployment:
+### Generating user during deployment
To adhere above mentioned guideline and to make OpenBMC more secure, this design
specifies about forcing end-user to generate a new account, during deployment
@@ -521,7 +521,7 @@
method have access to IPMI, REDFISH & Webserver and can be used to create more
accounts through out-of-band interfaces.
-### Special user - root – user id 0:
+### Special user - root – user id 0
Exposing root account (user id 0) to end-user by default (other than debug /
developer scenario) is security risk. Hence current architecture recommends not
@@ -540,7 +540,7 @@
(Note: `root` user will not be listed as user account in any interfaces like
IPMI / REDFISH from user management point of view).
-### Deployment for systems without in-band interfaces:
+### Deployment for systems without in-band interfaces
Any systems which doesn’t have in-band system interface can generate passwords
uniquely for each & every device or can expose a default user name & password
diff --git a/cheatsheet.md b/cheatsheet.md
index 8518c30..ed6109d 100644
--- a/cheatsheet.md
+++ b/cheatsheet.md
@@ -7,14 +7,14 @@
The kernel recipe is in:
-```
+```text
meta-phosphor/common/recipes-kernel/linux/linux-obmc_X.Y.bb
```
To use a local git tree, change the `SRC_URI` to a git:// URL without a
hostname, and remove the `protocol=git` parameter. For example:
-```
+```bitbake
SRC_URI = "git:///home/jk/devel/linux;branch=${KBRANCH}"
```
@@ -25,27 +25,27 @@
The Palmetto target is `palmetto`.
-```
-$ cd openbmc
-$ . setup palmetto
-$ bitbake obmc-phosphor-image
+```bash
+cd openbmc
+. setup palmetto
+bitbake obmc-phosphor-image
```
## Building for Zaius
The Zaius target is `zaius`.
-```
-$ cd openbmc
-$ . setup zaius
-$ bitbake obmc-phosphor-image
+```bash
+cd openbmc
+. setup zaius
+bitbake obmc-phosphor-image
```
## Building a specific machine configuration
If the system you want to build contains different machine configurations:
-```
+```text
meta-<layer>/meta-<system>/conf/machine/machineA.conf
meta-<layer>/meta-<system>/conf/machine/machineB.conf
```
@@ -53,10 +53,10 @@
You can specify the machine configuration you want to build by passing the name
to the `setup`.
-```
-$ cd openbmc
-$ . setup machineB
-$ bitbake obmc-phosphor-image
+```bash
+cd openbmc
+. setup machineB
+bitbake obmc-phosphor-image
```
## Building the OpenBMC SDK
@@ -65,15 +65,15 @@
running on a 'PPC' or 'x86' system? You can build the sdk receive a fakeroot
environment.
-```
-$ bitbake -c populate_sdk obmc-phosphor-image
-$ ./tmp/deploy/sdk/openbmc-phosphor-glibc-x86_64-obmc-phosphor-image-armv5e-toolchain-2.1.sh
+```bash
+bitbake -c populate_sdk obmc-phosphor-image
+./tmp/deploy/sdk/openbmc-phosphor-glibc-x86_64-obmc-phosphor-image-armv5e-toolchain-2.1.sh
```
Follow the prompts. After it has been installed the default to setup your env
will be similar to this command
-```
+```bash
. /opt/openbmc-phosphor/2.1/environment-setup-armv5e-openbmc-linux-gnueabi
```
@@ -81,7 +81,7 @@
You can reconfigure your build by removing the build/conf dir:
-```
+```bash
rm -rf build/conf
```
@@ -91,7 +91,7 @@
## `busctl`
-http://www.freedesktop.org/software/systemd/man/busctl.html
+<http://www.freedesktop.org/software/systemd/man/busctl.html>
Great tool to issue D-Bus commands via cli. That way you don't have to wait for
the code to hit the path on the system. Great for running commands with QEMU
@@ -99,7 +99,7 @@
Run as:
-```
+```bash
busctl call <path> <interface> <object> <method> <parameters>
```
@@ -113,25 +113,25 @@
upstream or temporary work-arounds that add to QEMU's capabilities where
appropriate.
-```
+```bash
qemu-system-arm -m 256 -M palmetto-bmc -nographic \
--drive file=<path>/flash-palmetto,format=raw,if=mtd \
--net nic \
--net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostname=qemu
+ -drive file=<path>/flash-palmetto,format=raw,if=mtd \
+ -net nic \
+ -net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostname=qemu
```
If you get an error you likely need to build QEMU (see the section in this
document). If no error and QEMU starts up just change the port when interacting
with the BMC...
-```
+```bash
curl -c cjar -b cjar -k -H "Content-Type: application/json" \
--X POST https://localhost:2443/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
+ -X POST https://localhost:2443/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
```
or
-```
+```bash
ssh -p 2222 root@localhost
```
@@ -139,7 +139,7 @@
## Building QEMU
-```
+```bash
git clone https://github.com/openbmc/qemu.git
cd qemu
git submodule update --init dtc
@@ -157,13 +157,13 @@
your qemu session runs in the bridges subnet so no port forwarding is needed.
There are packages needed to yourself a virbr0 such as...
-```
+```bash
apt-get install libvirt libvirt-bin bridge-utils uml-utilities qemu-system-common
qemu-system-arm -m 256 -M palmetto-bmc -nographic \
--drive file=<path>/flash-palmetto,format=raw,if=mtd \
--net nic,macaddr=C0:FF:EE:00:00:02,model=ftgmac100 \
--net bridge,id=net0,helper=/usr/lib/qemu-bridge-helper,br=virbr0
+ -drive file=<path>/flash-palmetto,format=raw,if=mtd \
+ -net nic,macaddr=C0:FF:EE:00:00:02,model=ftgmac100 \
+ -net bridge,id=net0,helper=/usr/lib/qemu-bridge-helper,br=virbr0
```
There are some other useful parms like that can redirect the console to another
@@ -174,22 +174,22 @@
Login:
-```
+```bash
curl -c cjar -k -X POST -H "Content-Type: application/json" -d '{"data": [ "root", "0penBmc" ] }' https://${bmc}/login
```
Connect to host console:
-```
+```bash
ssh -p 2200 root@bmc
```
Power on:
-```
+```bash
curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
- -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' \
- https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+ -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' \
+ https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
```
## GDB
@@ -203,16 +203,17 @@
1. Setup SDK environment;
2. Run below GDB commands:
- ```
- cd <sysroot_of_sdk_build>
- $GDB <relative_path_to_exeutable> <path_to_core_file>
- ```
+
+```bash
+cd <sysroot_of_sdk_build>
+$GDB <relative_path_to_exeutable> <path_to_core_file>
+```
## Coredump
By default coredump is disabled in OpenBMC. To enable coredump:
-```
+```bash
echo '/tmp/core_%e.%p' | tee /proc/sys/kernel/core_pattern
ulimit -c unlimited
```
@@ -223,7 +224,7 @@
rwfs. To do this, you can list this path and then remove those files which you'd
prefer the originals or remove the deletion overlay to restore files.
-```
+```bash
/run/initramfs/rw/cow/
```
@@ -249,14 +250,18 @@
- Set `DL_DIR` Bitbake environment variable to the location of your shared
downloads directory by editing the `build/conf/local.conf` file:
- ```
- DL_DIR ?= "<path>/<to>/<existing>/downloads"
- ```
+
+```bitbake
+DL_DIR ?= "<path>/<to>/<existing>/downloads"
+```
+
- Or create a symbol link:
- ```
- ln -sf <path>/<to>/<existing>/downloads build/downloads
- ```
- Then do the build. It will save a lot of time from downloading codes.
+
+```bash
+ln -sf <path>/<to>/<existing>/downloads build/downloads
+```
+
+Then do the build. It will save a lot of time from downloading codes.
## Using git proxy
@@ -268,7 +273,7 @@
Below is an example wrapper in `~/bin` assuming a socks5 proxy at port 9054:
-```
+```bash
#!/bin/sh
## Use connect-proxy as git proxy wrapper which supports SOCKS5
## Install with `apt-get install connect-proxy`
@@ -284,7 +289,7 @@
`devtool` is a convenient utility in Yocto to make changes in the local
directory. Typical usage is:
-```
+```bash
# To create a local copy of recipe's code and build with it:
devtool modify <recipe>
cd build/workspace/sources/<recipe> # And make changes
@@ -308,28 +313,36 @@
the code locally, build and test it.
1. Use devtool to create a local repo:
- ```
+
+ ```bash
devtool modify phosphor-ipmi-host
```
+
devtool clones the repo into `build/workspace/sources/phosphor-ipmi-host`,
creates and checkout branch `devtool`.
+
2. Make changes in the repo, e.g. adding code to handle new ipmi commands or
simply adding trace logs.
+
3. Now you can build the whole image or the ipmi recipe itself:
- ```
+
+ ```bash
bitbake obmc-phosphor-image # Build the whole image
bitbake phosphor-ipmi-host # Build the recipe
```
+
4. To test your change, either flash the whole image or replace the changed
binary. Note that the changed code is built into `libapphandler.so` and it is
used by both host and net ipmi daemon. It is recommended that you copy the
changed binary to BMC because it is easier to test:
- ```
+
+ ```bash
# Replace libapphandler.so.0.0.0
scp build/workspace/sources/phosphor-ipmi-host/oe-workdir/package/usr/lib/ipmid-providers/libapphandler.so.0.0.0 root@bmc:/usr/lib/ipmid-providers/
systemctl restart phosphor-ipmi-host.service # Restart the inband ipmi daemon
# Or restart phosphor-ipmi-net.service if you want to test net ipmi.
```
+
5. Now you can test your changes.
## Develop linux kernel
@@ -353,7 +366,7 @@
You can modify the code and build the kernel as usual as follows:
-```
+```bash
bitbake linux-obmc -c build
```
@@ -361,7 +374,7 @@
If you need to change the config and save it as defconfig for further use:
-```
+```bash
bitbake linux-obmc -c menuconfig
# Edit the configs and after save it generates
# .config.new as the new kernel config
@@ -386,14 +399,16 @@
to a tftp server, name it to `fitImage`
2. Reboot BMC and press keys to enter uboot shell;
3. In uboot:
- ```
- setenv ethaddr <mac:addr> # Set mac address if there it is unavailable
- setenv ipaddr 192.168.0.80 # Set BMC IP
- setenv serverip 192.168.0.11 # Set tftp server IP
- tftp 0x83000000 fitImage # Load fit image to ram. Use 0x43000000 on AST2400
- bootm 0x83000000 # Boot from fit image
- ```
- Then you are running an OpenBMC with your updated kernel.
+
+```bash
+setenv ethaddr <mac:addr> # Set mac address if there it is unavailable
+setenv ipaddr 192.168.0.80 # Set BMC IP
+setenv serverip 192.168.0.11 # Set tftp server IP
+tftp 0x83000000 fitImage # Load fit image to ram. Use 0x43000000 on AST2400
+bootm 0x83000000 # Boot from fit image
+```
+
+Then you are running an OpenBMC with your updated kernel.
[1]: https://github.com/openbmc/phosphor-host-ipmid
[2]:
diff --git a/console.md b/console.md
index fddc204..f086cc9 100644
--- a/console.md
+++ b/console.md
@@ -12,32 +12,38 @@
To connect to an OpenBMC console session remotely, just ssh to your BMC on
port 2200. Use the same login credentials you would for a normal ssh session:
- $ ssh -p 2200 [user]@[bmc-hostname]
+```bash
+ssh -p 2200 [user]@[bmc-hostname]
+```
## Local console connections
If you're already logged into an OpenBMC machine, you can start a console
session directly, using:
- $ obmc-console-client
+```bash
+obmc-console-client
+```
To exit from a console, type:
+```text
return ~ .
+```
Note that if you're on an ssh connection, you'll need to 'escape' the ~
character, by entering it twice:
+```text
return ~ ~ .
+```
This is because obmc-console-client is an ssh session, and a double `~` is
required to escape the "inner" (obmc-console-client) ssh session.
## Logging
-Console logs are kept in:
-
- /var/log/obmc-console.log
+Console logs are kept in: `/var/log/obmc-console.log`
This log is limited in size, and will wrap after hitting that limit (currently
set at 16kB).
diff --git a/cpp-style-and-conventions.md b/cpp-style-and-conventions.md
index 341c083..6a7c4cd 100644
--- a/cpp-style-and-conventions.md
+++ b/cpp-style-and-conventions.md
@@ -12,9 +12,9 @@
principles that help us align the software we develop with the constraints
within the problem domain being solved by OpenBMC. These are:
-1. Code should be clear and concise.
-2. Code should be written with modern practices.
-3. Code should be performant.
+1. Code should be clear and concise.
+2. Code should be written with modern practices.
+3. Code should be performant.
### Code should be clear and concise
@@ -52,7 +52,7 @@
recommend the book "Effective Modern C++" as a way to get up to speed on the
differences between C++98/03 and C++11/14/17/20.
-### Code should be performant.
+### Code should be performant
OpenBMC targets embedded processors that typically have 32-64MB of flash and
similar processing power of a typical smart-watch available in 2016. This means
@@ -70,7 +70,7 @@
Please follow the guidelines established by the C++ Core Guidelines (CCG).
-https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md
+<https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md>
[[Last reviewed revision is 53bc78f]]
@@ -164,14 +164,14 @@
- Utilize 'Allman' style brackets. Brackets are on their own line at the same
indentation level as the statement that creates the scope.
-```
+```cpp
if (condition)
{
...
}
```
-```
+```cpp
void foo()
{
...
@@ -180,7 +180,7 @@
- Even one line conditional and loop statements should have brackets.
-```
+```cpp
/// Wrong.
if (condition)
do_something;
@@ -197,7 +197,7 @@
- Content within a namespace should be at the same indentation level as the
namespace itself.
-```
+```cpp
namespace foo
{
@@ -208,7 +208,7 @@
- Content within a class / struct should be indented.
-```
+```cpp
class Foo
{
public:
@@ -218,7 +218,7 @@
- Content within a function / conditional / loop should be indented.
-```
+```cpp
void foo()
{
while (1)
@@ -233,7 +233,7 @@
- Switch / case statements should be indented.
-```
+```cpp
switch (foo)
{
case bar:
@@ -255,7 +255,7 @@
labels are preferred or should be regularly used, but simply when they are
used, this is how they are to be used.)
-```
+```cpp
void foo()
{
if (bar)
@@ -275,13 +275,13 @@
}
```
-### Naming Conventions.
+### Naming Conventions
- We generally abstain from any prefix or suffix on names.
- Acronyms should be same-case throughout and follow the requirements as in
their appropriate section.
-```
+```cpp
/// Correct.
SomeBMCType someBMCVariable = bmcFunction();
@@ -293,7 +293,7 @@
Header inclusion order for a header file:
-```
+```text
local headers (e.g. "daemon_sys.hpp")
c-libraries
cpp-libraries (including openbmc libraries)
@@ -301,7 +301,7 @@
Header inclusion order for a source file:
-```
+```text
source.hpp (if applicable)
local headers
c-libraries
@@ -330,7 +330,7 @@
- Exception: A for-convenience template type alias of a template class may end
in `_t` to match the conventions of the STL.
-```
+```cpp
template <typename T>
class Foo
{
@@ -371,7 +371,7 @@
- Follow NL.18: Use C++-style declarator layout.
-```
+```cpp
foo(T& bar, const S* baz); /// Correct.
foo(T &bar, const S *baz); /// Incorrect.
```
@@ -380,7 +380,7 @@
- Insert whitespace after a conditional and before parens.
-```
+```cpp
if (...)
while (...)
for (...)
@@ -388,14 +388,14 @@
- Insert whitespace around binary operators for readability.
-```
+```cpp
foo((a-1)/b,c-2); /// Incorrect.
foo((a - 1) / b, c - 2); /// Correct.
```
- Do not insert whitespace around unary operators.
-```
+```cpp
a = * b; /// Incorrect.
a = & b; /// Incorrect.
a = b -> c; /// Incorrect.
@@ -405,7 +405,7 @@
- Do not insert whitespace inside parens or between a function call and
parameters.
-```
+```cpp
foo(x, y); /// Correct.
foo ( x , y ); /// Incorrect.
@@ -416,7 +416,7 @@
- Prefer line-breaks after operators to show continuation.
-```
+```cpp
if (this1 == that1 &&
this2 == that2) /// Correct.
@@ -427,7 +427,7 @@
- Long lines should have continuation start at the same level as the parens or
all all items inside the parens should be at a 2-level indent.
-```
+```cpp
reallyLongFunctionCall(foo,
bar,
baz); // Correct.
@@ -445,7 +445,7 @@
baz); // Incorrect.
```
-### Misc Guidelines.
+### Misc Guidelines
- Always use `size_t` or `ssize_t` for things that are sizes, counts, etc. You
need a strong rationale for using a sized type (ex. `uint8_t`) when a size_t
diff --git a/designs/README.md b/designs/README.md
index 7c8f46f..d6e12b7 100644
--- a/designs/README.md
+++ b/designs/README.md
@@ -1,3 +1,5 @@
+# Overview
+
This is a directory of design documents.
Newly authored design documents are encouraged to follow the
diff --git a/designs/binarystore-via-blobs.md b/designs/binarystore-via-blobs.md
index de841a2..ecb73c4 100644
--- a/designs/binarystore-via-blobs.md
+++ b/designs/binarystore-via-blobs.md
@@ -1,6 +1,6 @@
# BMC Generic Binary Blob Store via OEM IPMI Blob Transport
-Author: Kun Yi (kunyi@google.com, kunyi!)
+Author: Kun Yi <kunyi@google.com> `kunyi!`
Created: 2018-12-07
@@ -37,8 +37,8 @@
## Background and References
-Please read the IPMI Blob protocol design as primer
-[here](https://github.com/openbmc/phosphor-ipmi-blobs/blob/master/README.md).
+Please read the IPMI Blob protocol design as
+[primer](https://github.com/openbmc/phosphor-ipmi-blobs/blob/master/README.md).
Under the hood, the binary blobs are stored as a binary
[protocol buffer](https://github.com/protocolbuffers/protobuf), or "protobuf" in
diff --git a/designs/bios-bmc-smm-error-logging.md b/designs/bios-bmc-smm-error-logging.md
index 71a4704..2959268 100644
--- a/designs/bios-bmc-smm-error-logging.md
+++ b/designs/bios-bmc-smm-error-logging.md
@@ -2,11 +2,11 @@
Author:
-- Brandon Kim / brandonkim@google.com / @brandonk
+- Brandon Kim <brandonkim@google.com> `@brandonk`
Other contributors:
-- Marco Cruz-Heredia / mcruzheredia@google.com
+- Marco Cruz-Heredia <mcruzheredia@google.com>
Created: Mar 15, 2022
@@ -60,24 +60,24 @@
separate libraries shared between `phosphor-ipmi-flash` and this daemon to
reduce duplication of code.
-Taken from Marco's (mcruzheredia@google.com) internal design document for the
+Taken from Marco's <mcruzheredia@google.com> internal design document for the
circular buffer, the data structure of its header will look like the following:
-| Name | Size | Offset | Written by | Description |
-| ----------------------------------- | -------------------------------- | ----------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| BMC Interface Version | 4 bytes | 0x0 | BMC at init | Allows the BIOS to determine if it is compatible with the BMC |
-| BIOS Interface Version | 4 bytes | 0x4 | BIOS at init | Allows the BMC to determine if it is compatible with the BIOS |
-| Magic Number | 16 bytes | 0x8 | BMC at init | Magic number to set the state of the queue as described below. Written by BMC once the memory region is ready to be used. Must be checked by BIOS before logging. BMC can change this number when it suspects data corruption to prevent BIOS from writing anything during reinitialization |
-| Queue size | 3 bytes | 0x18 | BMC at init | Indicates the size of the region allocated for the circular queue. Written by BMC on init only, should not change during runtime. **This includes the size of the header and UE region size** |
-| Uncorrectable Error region size | 2 bytes | 0x1b | BMC at init | Indicates the size of the region reserved for Uncorrectable Error (UE) logs. Written by BMC on init only, should not change during runtime |
-| BMC flags | 4 bytes | 0x1d | BMC | <ul><li>BIT0 - BMC UE reserved region “switch”<ul><li>Toggled when BMC reads a UE from the reserved region.</li></ul><li>BIT1 - Overflow<ul><li>Lets BIOS know BMC has seen the overflow incident</li><li>Toggled when BMC acks the overflow incident</li></ul><li>BIT2 - BMC_READY<ul><li>BMC sets this bit once it has received any initialization information it needs to get from the BIOS before it’s ready to receive logs.</li></ul> |
-| BMC read pointer | 3 bytes | 0x21 | BMC | Used to allow the BIOS to detect when the BMC was unable to read the previous error logs in time to prevent the circular buffer from overflowing. |
-| Padding | 4 bytes | 0x24 | Reserved | Padding for 8 byte alignment |
-| BIOS flags | 4 bytes | 0x28 | BIOS | <ul><li>BIT0 - BIOS UE reserved region “switch”<ul><li> Toggled when BIOS writes a UE to the reserved region.</li></ul><li>BIT1 - Overflow<ul><li>Lets the BMC know that it missed an error log</li><li>Toggled when BIOS sees overflow and not already overflowed</li></ul><li>BIT2 - Incomplete Initialization<ul><li>Set when BIOS has attempted to initialize but did not see BMC ack back with `BMC_READY` bit in BMC flags</li></ul> |
-| BIOS write pointer | 3 bytes | 0x2c | BIOS | Indicates where the next log will be written by BIOS. Used to tell BMC when it should read a new log |
-| Padding | 1 byte | 0x2f | Reserved | Padding for 8 byte alignment |
-| Uncorrectable Error reserved region | TBD1 | 0x30 | BIOS | Reserved region only for UE logs. This region is only used if the rest of the buffer is going to overflow and there is no unread UE log already in the region. |
-| Error Logs from BIOS | Size of the Buffer - 0x30 - TBD1 | 0x30 + TBD1 | BIOS | Logs vary by type, so each log will self-describe with a header. This region will fill up the rest of the buffer |
+| Name | Size | Offset | Written by | Description |
+| ----------------------------------- | -------------------------------- | ----------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| BMC Interface Version | 4 bytes | 0x0 | BMC at init | Allows the BIOS to determine if it is compatible with the BMC |
+| BIOS Interface Version | 4 bytes | 0x4 | BIOS at init | Allows the BMC to determine if it is compatible with the BIOS |
+| Magic Number | 16 bytes | 0x8 | BMC at init | Magic number to set the state of the queue as described below. Written by BMC once the memory region is ready to be used. Must be checked by BIOS before logging. BMC can change this number when it suspects data corruption to prevent BIOS from writing anything during reinitialization |
+| Queue size | 3 bytes | 0x18 | BMC at init | Indicates the size of the region allocated for the circular queue. Written by BMC on init only, should not change during runtime. **This includes the size of the header and UE region size** |
+| Uncorrectable Error region size | 2 bytes | 0x1b | BMC at init | Indicates the size of the region reserved for Uncorrectable Error (UE) logs. Written by BMC on init only, should not change during runtime |
+| BMC flags | 4 bytes | 0x1d | BMC | **BIT0 - BMC UE reserved region “switch”**: Toggled when BMC reads a UE from the reserved region.<br>**BIT1 - Overflow**: Lets BIOS know BMC has seen the overflow incident. Toggled when BMC acks the overflow incident<br>**BIT2 - BMC_READY**: BMC sets this bit once it has received any initialization information it needs to get from the BIOS before it’s ready to receive logs. |
+| BMC read pointer | 3 bytes | 0x21 | BMC | Used to allow the BIOS to detect when the BMC was unable to read the previous error logs in time to prevent the circular buffer from overflowing. |
+| Padding | 4 bytes | 0x24 | Reserved | Padding for 8 byte alignment |
+| BIOS flags | 4 bytes | 0x28 | BIOS | **BIT0 - BIOS UE reserved region “switch”**: Toggled when BIOS writes a UE to the reserved region.<br>**BIT1 - Overflow**: Lets the BMC know that it missed an error log. Toggled when BIOS sees overflow and not already overflowed<br>**BIT2 - Incomplete Initialization**: Set when BIOS has attempted to initialize but did not see BMC ack back with `BMC_READY` bit in BMC flags |
+| BIOS write pointer | 3 bytes | 0x2c | BIOS | Indicates where the next log will be written by BIOS. Used to tell BMC when it should read a new log |
+| Padding | 1 byte | 0x2f | Reserved | Padding for 8 byte alignment |
+| Uncorrectable Error reserved region | TBD1 | 0x30 | BIOS | Reserved region only for UE logs. This region is only used if the rest of the buffer is going to overflow and there is no unread UE log already in the region. |
+| Error Logs from BIOS | Size of the Buffer - 0x30 - TBD1 | 0x30 + TBD1 | BIOS | Logs vary by type, so each log will self-describe with a header. This region will fill up the rest of the buffer |
### Initialization
@@ -140,12 +140,12 @@
- bios-bmc-smm-error-logger
- This repository will implement the daemon described in this document
- - Proposed maintainer: wltu@google.com , brandonkim@google.com
+ - Proposed maintainer: <wltu@google.com> , <brandonkim@google.com>
- libbej
- This repository will follow the PLDM RDE specification as much as possible
for RDE BEJ decoding (initially, encoding may come in the future) and will
host a library written in C
- - Proposed maintainer: wltu@google.com , brandonkim@google.com
+ - Proposed maintainer: <wltu@google.com> , <brandonkim@google.com>
## Testing
diff --git a/designs/bmc-boot-ready.md b/designs/bmc-boot-ready.md
index 1d43d3b..7a1e12e 100644
--- a/designs/bmc-boot-ready.md
+++ b/designs/bmc-boot-ready.md
@@ -25,9 +25,9 @@
## Background and References
-The mailing list discussion can be found [here][1]. The BMC currently has three
-major [state][2] management interfaces in a system. The BMC, Chassis, and Host.
-Within each state interface, the current state and requested state are tracked.
+The [mailing list discussion][1] can be found. The BMC currently has three major
+[state][2] management interfaces in a system. The BMC, Chassis, and Host. Within
+each state interface, the current state and requested state are tracked.
The [BMC][3] state object is considered `Ready` once the systemd
`multi-user.target` has successfully started all if its services.
diff --git a/designs/bmc-health-monitor.md b/designs/bmc-health-monitor.md
index 185d302..e1882cf 100644
--- a/designs/bmc-health-monitor.md
+++ b/designs/bmc-health-monitor.md
@@ -1,4 +1,4 @@
-### BMC Health Monitor
+# BMC Health Monitor
Author: Vijay Khemka <vijaykhemka@fb.com>, Sui Chen <suichen@google.com>, Jagpal
Singh Gill <paligill@gmail.com>
@@ -162,7 +162,7 @@
Each metric will be exposed on a specific object path and above interfaces will
be implemented at these paths.
-```
+```text
/xyz/openbmc_project
|- /xyz/openbmc_project/metric/bmc/memory/total
|- /xyz/openbmc_project/metric/bmc/memory/free
@@ -188,7 +188,7 @@
In case there are multiple devices of same type, the D-Bus path can be extended
to add context about **"which device"**. For example -
-```
+```text
/xyz/openbmc_project/metric/device-0/memory/total
/xyz/openbmc_project/metric/device-1/memory/total
...
@@ -226,7 +226,7 @@
pretty significant. Given the amount of functionality needed for openBMC,
Collectd seems heavyweight. Majority of phosphor-health-monitor code will be
around exposing the metrics on Dbus which will also be needed for Collectd
- plugin. Hence, directly reading from /proc/<fileX> seems lightweight as code
+ plugin. Hence, directly reading from `/proc/<fileX>` seems lightweight as code
already exist for it.
- Collected has minimal support for threshold monitoring and doesn't allow
starting systemd services on threshold violations.
diff --git a/designs/bmc-reboot-cause-update.md b/designs/bmc-reboot-cause-update.md
index 45571e8..1e10374 100644
--- a/designs/bmc-reboot-cause-update.md
+++ b/designs/bmc-reboot-cause-update.md
@@ -58,37 +58,37 @@
1. Driver Provision by BMC Vendors:
-- Each BMC vendor must provide a driver to retrieve the BMC reboot cause and
- record the result at the specified location.
+ - Each BMC vendor must provide a driver to retrieve the BMC reboot cause and
+ record the result at the specified location.
2. Definition and Identification of Reboot Cause Type **Software Reset**:
-- This one is still under discussion, please refer to the following link for
- more detail:
- https://lore.kernel.org/all/9565c496-44d8-4214-8038-931926210d0f@roeck-us.net/
+ - This one is still under discussion, please refer to the following link for
+ more detail:
+ <https://lore.kernel.org/all/9565c496-44d8-4214-8038-931926210d0f@roeck-us.net/>
3. Revise the Definition of **WDIOF_CARDRESET**:
-- The **WDIOF_CARDRESET** type will now specifically indicate resets caused by
- the watchdog.
+ - The **WDIOF_CARDRESET** type will now specifically indicate resets caused
+ by the watchdog.
4. Clarification of The **Power-on-reset case**:
-- When a BMC reset occured, but the flag in the bootstatus remains unchanged by
- the watchdog driver (i.e., it stays at 0), this indicates that a
- **Power-on-reset** has occurred.
+ - When a BMC reset occured, but the flag in the bootstatus remains unchanged
+ by the watchdog driver (i.e., it stays at 0), this indicates that a
+ **Power-on-reset** has occurred.
5. Update Reboot Cause Interpretation:
-| phosphor-state-manager | bootstatus value | watchdog driver |
-| ---------------------- | ---------------- | -------------------------------- |
-| WDIOF_CARDRESET | 0x20 | return 0x20 if reset by Watchdog |
-| POR | 0x00 | Do nothing |
+ | phosphor-state-manager | bootstatus value | watchdog driver |
+ | ---------------------- | ---------------- | -------------------------------- |
+ | WDIOF_CARDRESET | 0x20 | return 0x20 if reset by Watchdog |
+ | POR | 0x00 | Do nothing |
6. Generate Corresponding Event Log:
-- After interpreting the reboot cause, the system should issue the corresponding
- event log based on the determined type.
+ - After interpreting the reboot cause, the system should issue the
+ corresponding event log based on the determined type.
## Alternatives Considered
diff --git a/designs/bmc-reset-with-host-up.md b/designs/bmc-reset-with-host-up.md
index 0a308eb..7d0425b 100644
--- a/designs/bmc-reset-with-host-up.md
+++ b/designs/bmc-reset-with-host-up.md
@@ -116,8 +116,8 @@
within phosphor-state-manager. Any system or company specific services can be
installed in the common targets:
-- obmc-chassis-powerreset@.target.require
-- obmc-host-reset@.target.requires
+- `obmc-chassis-powerreset@.target.require`
+- `obmc-host-reset@.target.requires`
### Automated Recovery when host does not respond
diff --git a/designs/bmc-service-failure-debug-and-recovery.md b/designs/bmc-service-failure-debug-and-recovery.md
index a8afd64..92fac51 100644
--- a/designs/bmc-service-failure-debug-and-recovery.md
+++ b/designs/bmc-service-failure-debug-and-recovery.md
@@ -389,20 +389,20 @@
BMC's behaviour in this way allows the use of the `serio_raw` driver (which has
the restriction that userspace can't access the status value).
-[1]
-https://lore.kernel.org/lkml/37e75b07-a5c6-422f-84b3-54f2bea0b917@www.fastmail.com/
+[1]:
+ https://lore.kernel.org/lkml/37e75b07-a5c6-422f-84b3-54f2bea0b917@www.fastmail.com/
#### Prototype Implementation Supporting Power10 Platforms
A concrete implementation of the proposal's userspace daemon is available on
Github:
-https://github.com/amboar/debug-trigger/
+<https://github.com/amboar/debug-trigger/>
Deployment requires additional kernel support in the form of patches at [2].
-[2]
-https://github.com/amboar/linux/compare/2dbb5aeba6e55e2a97e150f8371ffc1cc4d18180...for/openbmc/kcs-raw
+[2]:
+ https://github.com/amboar/linux/compare/2dbb5aeba6e55e2a97e150f8371ffc1cc4d18180...for/openbmc/kcs-raw
### Alternatives Considered
@@ -458,7 +458,7 @@
### Proposed Design
-This will build upon the existing [target-fail-monitoring][1] design. The
+This will build upon the existing [target-fail-monitoring][3] design. The
monitor service will be enhanced to also take json file(s) which list critical
services to monitor.
@@ -482,7 +482,7 @@
the BMC state into Quiesced
- bmcweb looks at BMC state to return appropriate state to external clients
-[1]:
+[3]:
https://github.com/openbmc/docs/blob/master/designs/target-fail-monitoring.md
### Alternatives Considered
diff --git a/designs/boot-progress.md b/designs/boot-progress.md
index 3b4082b..f25e7f0 100644
--- a/designs/boot-progress.md
+++ b/designs/boot-progress.md
@@ -1,6 +1,6 @@
# System Boot Progress on OpenBMC
-Author: Andrew Geissler (geissonator)
+Author: Andrew Geissler `geissonator`
Other contributors: None
@@ -41,8 +41,7 @@
Redfish represents system state in a variety of ways. The BMC, Chassis, and
System all implement a [Status][6] object. This provides a list of generic
`State` options which are applicable to Redfish objects. OpenBMC has the
-following mapping for phosphor-state-manager to the Redfish System
-[Status][state]:
+following mapping for phosphor-state-manager to the Redfish System [Status][7]:
- `xyz.openbmc_project.State.Host.HostState.Running` : `Enabled`
- `xyz.openbmc_project.State.Host.HostState.Quiesced` : `Quiesced`
@@ -73,7 +72,7 @@
Note that this design does not include multi-host computer system concepts but
it also does not preclude them. The `BootProgress` D-Bus property is associated
-with a `/xyz/openbmc_project/state/host<X>` instance where <X> is the host
+with a `/xyz/openbmc_project/state/host<X>` instance where `<X>` is the host
instance. Similarly, the Redfish system object is also an instance based object.
## Requirements
diff --git a/designs/certificate-revocation-list.md b/designs/certificate-revocation-list.md
index 889428b..c0e3e82 100644
--- a/designs/certificate-revocation-list.md
+++ b/designs/certificate-revocation-list.md
@@ -1,6 +1,6 @@
# Certificate Revocation List on BMC
-Author: Nan Zhou (nanzhoumails@gmail.com)
+Author: Nan Zhou <nanzhoumails@gmail.com>
Created: 02/25/2022
diff --git a/designs/ci-authorization.md b/designs/ci-authorization.md
index c00eb22..d0d988b 100644
--- a/designs/ci-authorization.md
+++ b/designs/ci-authorization.md
@@ -29,8 +29,11 @@
the general-developers team, manual intervention (ok-to-test) is required by a
project maintainer to trigger the automated CI processes.
-Additional reading: https://en.wikipedia.org/wiki/Continuous_integration
-https://jenkins.io/ https://help.github.com/articles/about-organizations/
+Additional reading:
+
+- <https://en.wikipedia.org/wiki/Continuous_integration>
+- <https://jenkins.io/>
+- <https://help.github.com/articles/about-organizations/>
## Requirements
diff --git a/designs/code-update.md b/designs/code-update.md
index 179636e..8257e1b 100644
--- a/designs/code-update.md
+++ b/designs/code-update.md
@@ -28,8 +28,8 @@
1. Able to start an update, given a firmware image and update settings.
-- Update settings shall be able to specify when to apply the image, for example
- immediately or on device reset or on-demand.
+ - Update settings shall be able to specify when to apply the image, for
+ example immediately or on device reset or on-demand.
2. Able to retrieve the update progress and status.
3. Able to produce an interface complaint with
@@ -372,7 +372,7 @@
- Different type hardware components:
Upgrade for different type hardware components can be handled either by
- different <deviceX>CodeUpdater daemons or by a single daemon for hardware
+ different `<deviceX>CodeUpdater` daemons or by a single daemon for hardware
components with common features, for example, PLDMd may handle update for
devices using PLDM specification. Such updates can be invoked in parallel from
BMCWeb and tracked via different tasks.
@@ -446,7 +446,7 @@
#### Cons
- Server would still need maintain some info so it can map client's task status
- request to Dbus path for /xyz/openbmc_project/Software/<deviceX> for calling
+ request to Dbus path for `/xyz/openbmc_project/Software/<deviceX>` for calling
getActivationStatus and getActivationProgress.
- Aforementioned [issue](https://github.com/openbmc/bmcweb/issues/202) is more
of an implementation problem which can be resolved through implementation
diff --git a/designs/dump-manager.md b/designs/dump-manager.md
index 67d12bf..3f7613f 100644
--- a/designs/dump-manager.md
+++ b/designs/dump-manager.md
@@ -37,7 +37,7 @@
some sources allow the dump to be extracted manually without a failure to
understand the current state or analyze a suspected problems.
-### Type of dumps supported.
+### Type of dumps supported
These are some of the dumps supported by dump manager.
@@ -83,7 +83,7 @@
-#### Dump manager needs to provide interfaces for
+### Dump manager needs to provide interfaces for
- Create a dump: Initiate the creation of the dump, based on an error condition
or a user request.
@@ -112,7 +112,7 @@
-#### Brief design points of existing phosphor-debug-collector
+### Brief design points of existing phosphor-debug-collector
- A create interface which assumes the type is BMC dump and returns an ID to the
caller for the user-initiated dumps.
@@ -138,7 +138,7 @@
- The dump manager calls dreport with a dump type got from the monitor and write
data to a path based on dump id.
-#### Updates proposed to the existing phosphor-debug-collector.
+### Updates proposed to the existing phosphor-debug-collector
- External D-Bus interface needs to specify the type of the dump since a user
can request multiple types of dumps
@@ -149,7 +149,7 @@
- The InitiateOffload function will be implemented to download the dump.
- Status of the dump, whether offloaded or not, will be added to the dump entry.
-### Dump manager interfaces.
+### Dump manager interfaces
- Dump Manager DBus object provides interfaces for creating and managing dump
diff --git a/designs/ecc-dbus-sel.md b/designs/ecc-dbus-sel.md
index bc1db98..9fbb0d6 100644
--- a/designs/ecc-dbus-sel.md
+++ b/designs/ecc-dbus-sel.md
@@ -1,10 +1,10 @@
-### ECC Error SEL for BMC
+# ECC Error SEL for BMC
Author: Will Liang
Created: 2019-02-26
-#### Problem Description
+## Problem Description
The IPMI SELs only define memory Error Correction Code (ECC) errors for host
memory rather than BMC.
@@ -13,7 +13,7 @@
Event Log (SEL). Whenever ECC occurs, the BMC generates an event with the
appropriate information and adds it to the SEL.
-#### Background and References
+## Background and References
The IPMI specification defines memory system event log about ECC/other
correctable or ECC/other uncorrectable and whether ECC/other correctable memory
@@ -27,7 +27,7 @@
[[1]Intelligent Platform Management Interface Specification v2.0 rev 1.1, section 41](https://www.intel.com/content/www/us/en/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html)
-#### Requirements
+## Requirements
Currently, the OpenBMC project does not support ECC event logs in D-Bus because
there is no relevant ECC information in the OpenBMC D-Bus architecture. The new
@@ -36,7 +36,7 @@
driver. And make sure the EDAC driver must be loaded and ECC/other correctable
or ECC/other uncorrectable counts need to be obtained from the EDAC driver.
-#### Proposed Design
+## Proposed Design
ECC-enabled memory controllers can detect and correct errors in operating
systems (such as certain versions of Linux, macOS, and Windows) that allow
@@ -68,7 +68,7 @@
(default:100) is saved in the configuration file, and the user can modify the
value if necessary.
-##### phosphor-ecc.service
+### phosphor-ecc.service
This will always run the application and look up the ECC error count every
second after service is started. On first start, it resets all correctable ECC
@@ -89,7 +89,7 @@
`ueCount` and `isLoggingLimitReached` will be created which generated the error
type for the ECC logs.
-##### Create the ECC SEL
+### Create the ECC SEL
Use the `phosphor-sel-logger` package to record the following logs in BMC SEL
format.
@@ -101,19 +101,19 @@
- logging limit reached log : When the correctable ECC log reaches the
`maximum quantity`.
-#### Alternatives Considered
+## Alternatives Considered
Another consideration is that there is no stopping the recording of the ECC
logging mechanism. When the checks `ce_count` and value exceeds the previous
value, it will record the ECC log. But this will encounter a lot of ECC logs,
and BMC memory will also be occupied.
-#### Impacts
+## Impacts
This application implementation only needs to make some changes when creating
the event log, so it has minimal impact on the rest of the system.
-#### Testing
+## Testing
Depending on the platform hardware design, this test requires an ECC driver to
make fake ECC errors and then check the scenario is good.
diff --git a/designs/entity-manager-hw-id-vpd-discover-via-device-tree.md b/designs/entity-manager-hw-id-vpd-discover-via-device-tree.md
index 8e61021..ef8544b 100644
--- a/designs/entity-manager-hw-id-vpd-discover-via-device-tree.md
+++ b/designs/entity-manager-hw-id-vpd-discover-via-device-tree.md
@@ -65,8 +65,8 @@
element via third party driver. From here, the data blob is copied to a
predetermined location in RAM, where it is retrieved and parsed by HPE-specific
code in u-Boot (open-sourced, and available at
-https://github.com/HewlettPackard/gxp-uboot). In the future, we'll be aiming to
-upstream as much 'HPE-critical' u-boot code as needed so that an HPE-specific
+<https://github.com/HewlettPackard/gxp-uboot>). In the future, we'll be aiming
+to upstream as much 'HPE-critical' u-boot code as needed so that an HPE-specific
u-boot fork will not be needed to boot HPE hardware.
Additionally, code in u-Boot gathers MAC addresses for the BMC's network
@@ -145,23 +145,23 @@
## Alternatives Considered
-### Entity-Manager probes are extended to handle reading data from arbitrary<br/>device-tree nodes
+### Entity-Manager probes are extended to handle reading data from arbitrary device-tree nodes
-#### Pros:
+#### Pros
1. No new daemon required
-#### Cons:
+#### Cons
1. May encourage undesired device-tree exploitation
-### A reserved-memory node in device-tree is used for transport of<br/>'serial-number' and 'model' ID data
+### A reserved-memory node in device-tree is used for transport of 'serial-number' and 'model' ID data
-#### Pros:
+#### Pros
1. Reserved-memory is commonly used for passing data from firmware
-#### Cons:
+#### Cons
1. Has no well-known handles for common properties like /model or /serial-number
like device-tree does; makes more sense for keeping arbitrary data instead of
@@ -178,7 +178,7 @@
### All VPD is exposed as devicetree attributes under /chosen/
-#### Pros:
+#### Pros
1. Is a well-established device-tree node
2. Is not being used by other BMC platforms, so easy to enable/disable service
@@ -186,7 +186,7 @@
3. Values can be set from u-Boot via modifications to the flattened device tree
available to it (applicable to arbitrary device-tree paths)
-#### Cons:
+#### Cons
1. Not a 'usual' location for passing this kind HW-tied data. Unlikely to ever
be used for moving product data by other entities, so such a daemon would be
@@ -194,39 +194,39 @@
2. Presenting HW-specific data here appears to go against the intended use of
'chosen' node
-### Vital product data is published to u-Boot environment variables, then<br/>transferred to D-Bus
+### Vital product data is published to u-Boot environment variables, then transferred to D-Bus
-#### Pros:
+#### Pros
1. Would increase code reuse and testing
-#### Cons:
+#### Cons
1. Potential issues with limited writes to memory where u-boot env variables are
stored in memory.
2. HPE component that retrieves VPD from HPE's secure element has no
knowledge/ability to alter u-boot environmental variables
-### Use an HPE-specific daemon instead of a generalized'[channel]-> D-Bus'<br/>daemon
+### Use an HPE-specific daemon instead of a generalized'[channel]-> D-Bus' daemon
-#### Pros:
+#### Pros
1. Simpler (slightly?) code
2. Would only fire for HPE platforms
3. Better abstraction
-#### Cons:
+#### Cons
1. Doesn't save much effort compared to a generalized non-HPE-specific solution
2. Harder to leverage code for potential future cases
### Service is hosted in Entity-Manager [ACCEPTED after TOF re-examination]
-#### Pros:
+#### Pros
1. Would operate in parallel to existing Fru_Device daemon
-#### Cons:
+#### Cons
1. Community doesn't want to host VPD -> DBus daemons in Entity-Manager repo
@@ -235,25 +235,25 @@
the existing fru-device daemon rather than to create a dedicated repo for a
daemon as simple as this one, or to force into another even less-related repo.
-https://github.com/openbmc/technical-oversight-forum/issues/38
+<https://github.com/openbmc/technical-oversight-forum/issues/38>
### Service is hosted in Phosphor-u-boot-env-mgr
-#### Pros:
+#### Pros
1. Repo is already associated with u-boot operations
-#### Cons:
+#### Cons
1. Current repo maintainer feels the service doesn't fit this repo because the
purpose is explicitly to deal with manipulation of u-boot env variables,
which this service is not involved with.
- https://gerrit.openbmc.org/c/openbmc/phosphor-u-boot-env-mgr/+/71512
+ <https://gerrit.openbmc.org/c/openbmc/phosphor-u-boot-env-mgr/+/71512>
-### Addendum: Rejected D-Bus interfaces for pending device-tree -> D-Bus<br/>daemon
+### Addendum: Rejected D-Bus interfaces for pending device-tree -> D-Bus daemon
-#### Existing interfaces (rejected):
+#### Existing interfaces (rejected)
1. Proposal: xyz.openbmc_project.Decorator.\*
@@ -268,7 +268,7 @@
property).
Discussion @
- https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73260/comment/e0226ae4_d7e514dd/
+ <https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73260/comment/e0226ae4_d7e514dd/>
Follow-up 2: Sticking with Inventory.Decorator.Asset, but removing MAC
address properties to reduce unneeded complexity.
@@ -277,7 +277,7 @@
Rejection: The data is not coming from a FRU device
-#### Proposed interfaces (rejected):
+#### Proposed interfaces (rejected)
1. Proposal: xyz.openbmc_project.DeviceTree
2. Proposal: xyz.openbmc_project.uBootHWID
@@ -319,7 +319,7 @@
MACAddress.." - Patrick Williams
Discussion @
- https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73260/comment/e0226ae4_d7e514dd/
+ <https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/73260/comment/e0226ae4_d7e514dd/>
Follow-up: Landed on interface: xyz.openbmc_project.Inventory.Decorator.Asset
@ path xyz/openbmc_project/MachineContext
@@ -334,7 +334,7 @@
to be no noticeable performance or functional impact to platforms that don't
rely on this service for Entity-Manager HW/config detection.
-## Organizational:
+## Organizational
### Does this design require a new repository?
diff --git a/designs/error-log-handling-for-phal.md b/designs/error-log-handling-for-phal.md
index 32c7000..8441103 100644
--- a/designs/error-log-handling-for-phal.md
+++ b/designs/error-log-handling-for-phal.md
@@ -1,6 +1,6 @@
# Error handling for power Hardware Abstraction Layer (pHAL)
-Author: Devender Rao <devenrao@in.ibm.com> <devenrao>
+Author: Devender Rao <devenrao@in.ibm.com> `devenrao`
Other contributors: None
diff --git a/designs/estoraged.md b/designs/estoraged.md
index fe95982..b4326d5 100644
--- a/designs/estoraged.md
+++ b/designs/estoraged.md
@@ -1,9 +1,12 @@
# eStoraged Design - Encrypted Secondary Storage Management Daemon
-Author: John Wedig (johnwedig@google.com)
+Author: John Wedig <johnwedig@google.com>
-Other contributors: John Broadbent (jebr@google.com) Benjamin Fair
-(benjaminfair@google.com) Nancy Yuenn (yuenn@google.com)
+Other contributors:
+
+- John Broadbent <jebr@google.com>
+- Benjamin Fair <benjaminfair@google.com>
+- Nancy Yuenn <yuenn@google.com>
Created: September 2, 2021
diff --git a/designs/event-logging.md b/designs/event-logging.md
index 7c15526..a54d7e4 100644
--- a/designs/event-logging.md
+++ b/designs/event-logging.md
@@ -86,7 +86,7 @@
logging messages into any application that wants to record these events, tightly
coupling all applications to the Redfish implementation. It has also been
observed that these [strings][app-example], when used, are often out of date
-with the [message registry][registry-example] advertised by `bmcweb`. Some
+with the [message registry][obmc-registry-example] advertised by `bmcweb`. Some
maintainers have rejected adding new Redfish-specific logging messages to their
applications.
@@ -102,7 +102,7 @@
https://github.com/openbmc/docs/blob/master/architecture/redfish-logging-in-bmcweb.md
[app-example]:
https://github.com/openbmc/phosphor-post-code-manager/blob/f2da78deb3a105c7270f74d9d747c77f0feaae2c/src/post_code.cpp#L143
-[registry-example]:
+[obmc-registry-example]:
https://github.com/openbmc/bmcweb/blob/4ba5be51e3fcbeed49a6a312b4e6b2f1ea7447ba/redfish-core/include/registries/openbmc.json#L5
### Existing phosphor-logging implementation
diff --git a/designs/expired-password.md b/designs/expired-password.md
index a2c5dc8..4e07166 100644
--- a/designs/expired-password.md
+++ b/designs/expired-password.md
@@ -1,6 +1,6 @@
# Initial expired passwords
-Author: Joseph Reynolds <josephreynolds1>
+Author: Joseph Reynolds `josephreynolds1`
Other contributors: None
@@ -49,14 +49,14 @@
The meaning of the term "access" varies by context. It could mean:
-1. Access to the BMC's network interfaces.
-2. Access to the BMC's authentication mechanisms together with correct
- credentials, whether or not those credentials have expired and must be
- changed.
-3. Access to the BMC's function via an authenticated interface, for example,
- such as establishing a session after you've changed your initial password.
-4. Access to the BMC's function via an unauthenticated interface such as host
- IPMI or physical control panel (example: power button).
+1. Access to the BMC's network interfaces.
+2. Access to the BMC's authentication mechanisms together with correct
+ credentials, whether or not those credentials have expired and must be
+ changed.
+3. Access to the BMC's function via an authenticated interface, for example,
+ such as establishing a session after you've changed your initial password.
+4. Access to the BMC's function via an unauthenticated interface such as host
+ IPMI or physical control panel (example: power button).
This design uses meanings 3 and 4 except where indicated.
@@ -112,8 +112,8 @@
correct userid and incorrect password, or with an incorrect userid, the
behavior must not change. Note the `/login` URI is deprecated.
- The '/redfish/v1/SessionService/Sessions/<session>' and
- '/redfish/v1/AccountService/Accounts/<account>' resources are enhanced to
+ The `/redfish/v1/SessionService/Sessions/<session>` and
+ `/redfish/v1/AccountService/Accounts/<account>` resources are enhanced to
indicate PasswordChangeRequired per the Redfish spec.
The `ipmitool` command treats an expired password the same as an invalid
@@ -142,12 +142,12 @@
ConfigureSelf privilege which allows it to only change the password and
terminate the session. The usage pattern is:
-1. Create a session.
-2. If the PasswordChangeRequired message is present:
- 1. PATCH the new password into the ManagerAccount object.
- 2. Any other use of the session will get HTTP status code 403 Forbidden.
- 3. DELETE the Session object to terminate the session.
- 4. Create a new session and continue.
+1. Create a session.
+2. If the PasswordChangeRequired message is present:
+ 1. PATCH the new password into the ManagerAccount object.
+ 2. Any other use of the session will get HTTP status code 403 Forbidden.
+ 3. DELETE the Session object to terminate the session.
+ 4. Create a new session and continue.
This design is intended to cover any cause of expired password, including both
the BMC's initial expired password and password expired for another cause such
diff --git a/designs/external-sensor.md b/designs/external-sensor.md
index bc2ffe3..feedab2 100644
--- a/designs/external-sensor.md
+++ b/designs/external-sensor.md
@@ -1,6 +1,6 @@
# ExternalSensor in dbus-sensors
-Author: Josh Lehan[^1]
+Author: Josh Lehan[1]
Other contributors: Ed Tanous, Peter Lundgren, Alex Qiu
@@ -8,7 +8,7 @@
## Introduction
-In OpenBMC, the _dbus-sensors_[^2] package contains a suite of sensor daemons.
+In OpenBMC, the _dbus-sensors_[2] package contains a suite of sensor daemons.
Each daemon monitors a particular type of sensor. This document provides
rationale and motivation for adding _ExternalSensor_, another sensor daemon, and
gives some example usages of it.
@@ -25,15 +25,15 @@
- Essentially all of the existing sensor daemons obtain the sensor values they
publish to D-Bus by reading from local hardware (typically by reading from
- virtual files provided by the _hwmon_[^3] subsystem of the Linux kernel). None
+ virtual files provided by the _hwmon_[3] subsystem of the Linux kernel). None
of the daemons are currently designed with the intention of accepting values
pushed in from an external source. Although there is some debugging
- functionality to add this feature to other sensor daemons[^25], it is not the
+ functionality to add this feature to other sensor daemons[25], it is not the
primary purpose for which they were designed.
- Even if the debugging functionality of an existing daemon were to be used, the
daemon would still need a valid configuration tied to recognized hardware, as
- detected by _entity-manager_[^4], in order for the daemon to properly
+ detected by _entity-manager_[4], in order for the daemon to properly
initialize itself and participate in the OpenBMC software stack.
- For the same reason it is desirable for existing sensor daemons to detect and
@@ -43,30 +43,29 @@
into the architecture of any existing sensor daemon, thus a new daemon is the
correct choice for this behavior.
-For these reasons, _ExternalSensor_ has been added[^5], as the eleventh sensor
+For these reasons, _ExternalSensor_ has been added[5], as the eleventh sensor
daemon in _dbus-sensors_.
## Design
-After some discussion, a proof-of-concept _HostSensor_[^6] was published. This
+After some discussion, a proof-of-concept _HostSensor_[6] was published. This
was a stub, but it revealed the minimal implementation that would still be
capable of fully initializing and participating in the OpenBMC software stack.
_ExternalSensor_ was formed by using this example _HostSensor_, and also one of
-the simplest existing sensor daemons, _HwmonTempSensor_[^7], as references to
+the simplest existing sensor daemons, _HwmonTempSensor_[7], as references to
build upon.
As written, after validating parameters during initialization, there is
essentially no work for _ExternalSensor_ to do. The main loop is mostly idle,
-remaining blocked in the Boost ASIO[^8] library, handling D-Bus requests as they
-come in. This utilizes the functionality in the underlying _Sensor_[^9] class,
+remaining blocked in the Boost ASIO[8] library, handling D-Bus requests as they
+come in. This utilizes the functionality in the underlying _Sensor_[9] class,
which already contains the D-Bus hooks necessary to receive values from the
external source.
-An example external source is the IPMI service[^10], receiving values from the
-host via the IPMI "Set Sensor Reading" command[^11]. _ExternalSensor_ is
-intended to be source-agnostic, so it does not matter if this is IPMI or
-Redfish[^12] or something else in the future, as long as they are received
-similarly over D-Bus.
+An example external source is the IPMI service[10], receiving values from the
+host via the IPMI "Set Sensor Reading" command[11]. _ExternalSensor_ is intended
+to be source-agnostic, so it does not matter if this is IPMI or Redfish[12] or
+something else in the future, as long as they are received similarly over D-Bus.
### Timeout
@@ -76,11 +75,11 @@
will be properly published onto D-Bus, in the usual way done by all sensor
daemons, as a floating-point value.
-A timer is used, the same Boost ASIO[^13] timer mechanism used by other sensor
+A timer is used, the same Boost ASIO[13] timer mechanism used by other sensor
daemons to poll their hardware, but in this case, is used to manage how long it
has been since the last known good external update. When the timer expires, the
sensor value will be deemed stale, and will be replaced with floating-point
-quiet _NaN_[^14].
+quiet _NaN_[14].
### NaN
@@ -93,13 +92,13 @@
possibility of confusion that this will be mistaken for a valid sensor value, as
_NaN_ is literally _not a number_, and thus can not be misparsed as a valid
sensor reading. It thus saves having to add a second field to reliably indicate
-validity, which would break the existing schema[^15].
+validity, which would break the existing schema[15].
An alternative to using _NaN_ for staleness indication would have been to use a
timestamp, which would introduce the complication of having to parse and compare
-timestamps within OpenBMC, and all the subtle difficulties thereof[^16]. What's
+timestamps within OpenBMC, and all the subtle difficulties thereof[16]. What's
more, adding a second field might require a second D-Bus message to update, and
-D-Bus messages are computationally expensive[^17] and should be used sparingly.
+D-Bus messages are computationally expensive[17] and should be used sparingly.
Periodic things like sensors, which send out regular updates, could easily lead
to frequent D-Bus traffic and thus should be kept as minimal as practical. And
finally, changing the Value schema would cause a large blast radius, both in
@@ -109,7 +108,7 @@
### Configuration
Configuring a sensor for use with _ExternalSensor_ should be done in the usual
-way[^18] that is done for use with other sensor daemons, namely, a JSON
+way[18] that is done for use with other sensor daemons, namely, a JSON
dictionary that is an element of the "Exposes" array within a JSON configuration
file to be read by _entity-manager_. In that JSON dictionary, the valid names
are listed below. All of these are mandatory parameters, unless mentioned as
@@ -123,7 +122,7 @@
- "Units": String. This parameter is unique to _ExternalSensor_. As
_ExternalSensor_ is not tied to any particular physical hardware, it can
measure any physical quantity supported by OpenBMC. This string will be
- translated to another string via a lookup table[^19], and forms another
+ translated to another string via a lookup table[19], and forms another
mandatory component of the D-Bus object path.
- "MinValue": Numeric. The minimum valid value for this sensor. Although not
@@ -160,15 +159,15 @@
Here is an example. The sensor created by this stanza will form this object
path: /xyz/openbmc_project/sensors/temperature/HostDevTemp
-```
- {
- "Name": "HostDevTemp",
- "Units": "DegreesC",
- "MinValue": -16.0,
- "MaxValue": 111.5,
- "Timeout": 4.0,
- "Type": "ExternalSensor"
- },
+```json
+{
+ "Name": "HostDevTemp",
+ "Units": "DegreesC",
+ "MinValue": -16.0,
+ "MaxValue": 111.5,
+ "Timeout": 4.0,
+ "Type": "ExternalSensor"
+}
```
There can be multiple _ExternalSensor_ sensors in the configuration. There is no
@@ -177,15 +176,15 @@
## Implementation
-As it stands now, _ExternalSensor_ is up and running[^20]. However, the timeout
+As it stands now, _ExternalSensor_ is up and running[20]. However, the timeout
feature was originally implemented at the IPMI layer. Upon further
investigation, it was found that IPMI was the wrong place for this feature, and
-that it should be moved within _ExternalSensor_ itself[^21]. It was originally
+that it should be moved within _ExternalSensor_ itself[21]. It was originally
thought that the timeout feature would be a useful enhancement available to all
IPMI sensors, however, expected usage of almost all external sensor updates is a
one-shot adjustment (for example, somebody wishes to change a voltage regulator
setting, or fan speed setting). In this case, the timeout feature would not only
-not be necessary, it would get in the way and require additional coding[^22] to
+not be necessary, it would get in the way and require additional coding[22] to
compensate for the unexpected _NaN_ value. Only sensors intended for use with
_ExternalSensor_ are expected to receive continuous periodic updates from an
external source, so it makes sense to move this timeout feature into
@@ -194,75 +193,51 @@
A challenge of generalizing the timeout feature into _ExternalSensor_, however,
was that the existing _Sensor_ base class did not currently allow its existing
-D-Bus setter hook to be customized. This feature was straightforward to
-add[^23]. One limitation was that the existing _Sensor_ class, by design,
-dropped updates that duplicated the existing sensor value. For use with
-_ExternalSensor_, we want to recognize all updates received, even duplicates, as
-they are important to pet the watchdog, to avoid inadvertently triggering the
-timeout feature. However, it is still important to avoid needlessly sending the
-D-Bus _PropertiesChanged_ event for duplicate readings.
+D-Bus setter hook to be customized. This feature was straightforward to add[23].
+One limitation was that the existing _Sensor_ class, by design, dropped updates
+that duplicated the existing sensor value. For use with _ExternalSensor_, we
+want to recognize all updates received, even duplicates, as they are important
+to pet the watchdog, to avoid inadvertently triggering the timeout feature.
+However, it is still important to avoid needlessly sending the D-Bus
+_PropertiesChanged_ event for duplicate readings.
The timeout value was originally a compiled-in constant. If _ExternalSensor_ is
to succeed as a general-purpose tool, this must be configurable. It was
-straightforward to add another configurable parameter[^24] to accept this
-timeout value, as shown in "Parameters" above.
+straightforward to add another configurable parameter[24] to accept this timeout
+value, as shown in "Parameters" above.
The hardest task of all, however, was getting it accepted upstream. If you are
reading this, then most likely, it was successful!
## Footnotes
-[^1]: https://gerrit.openbmc.org/q/owner:krellan%2540google.com
-
-[^2]: https://github.com/openbmc/dbus-sensors/blob/master/README.md
-
-[^3]: https://www.kernel.org/doc/html/latest/hwmon/index.html
-
-[^4]: https://github.com/openbmc/entity-manager/blob/master/README.md
-
-[^5]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/36206
-
-[^6]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/35476
-
-[^7]: https://github.com/openbmc/dbus-sensors/blob/master/src/HwmonTempMain.cpp
-
-[^8]: https://think-async.com/Asio/
-
-[^9]: https://github.com/openbmc/dbus-sensors/blob/master/include/sensor.hpp
-
-[^10]:
- https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md
-
-[^11]:
- https://www.intel.com/content/www/us/en/servers/ipmi/ipmi-intelligent-platform-mgt-interface-spec-2nd-gen-v2-0-spec-update.html
-
-[^12]: https://www.dmtf.org/standards/redfish
-
-[^13]:
- https://www.boost.org/doc/libs/1_75_0/doc/html/boost_asio/overview/timers.html
-
-[^14]: https://anniecherkaev.com/the-secret-life-of-nan
-
-[^15]:
- https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Sensor/Value.interface.yaml
-
-[^16]: https://cr.yp.to/proto/utctai.html
-
-[^17]: https://github.com/openbmc/openbmc/issues/1892
-
-[^18]:
- https://github.com/openbmc/entity-manager/blob/master/docs/my_first_sensors.md
-
-[^19]: https://github.com/openbmc/dbus-sensors/blob/master/src/SensorPaths.cpp
-
-[^20]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/36206
-
-[^21]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/41398
-
-[^22]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/39294
-
-[^23]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/41394
-
-[^24]: https://gerrit.openbmc.org/c/openbmc/entity-manager/+/41397
-
-[^25]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/16177
+[1]: https://gerrit.openbmc.org/q/owner:krellan%2540google.com
+[2]: https://github.com/openbmc/dbus-sensors/blob/master/README.md
+[3]: https://www.kernel.org/doc/html/latest/hwmon/index.html
+[4]: https://github.com/openbmc/entity-manager/blob/master/README.md
+[5]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/36206
+[6]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/35476
+[7]: https://github.com/openbmc/dbus-sensors/blob/master/src/HwmonTempMain.cpp
+[8]: https://think-async.com/Asio/
+[9]: https://github.com/openbmc/dbus-sensors/blob/master/include/sensor.hpp
+[10]:
+ https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md
+[11]:
+ https://www.intel.com/content/www/us/en/servers/ipmi/ipmi-intelligent-platform-mgt-interface-spec-2nd-gen-v2-0-spec-update.html
+[12]: https://www.dmtf.org/standards/redfish
+[13]:
+ https://www.boost.org/doc/libs/1_75_0/doc/html/boost_asio/overview/timers.html
+[14]: https://anniecherkaev.com/the-secret-life-of-nan
+[15]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Sensor/Value.interface.yaml
+[16]: https://cr.yp.to/proto/utctai.html
+[17]: https://github.com/openbmc/openbmc/issues/1892
+[18]:
+ https://github.com/openbmc/entity-manager/blob/master/docs/my_first_sensors.md
+[19]: https://github.com/openbmc/dbus-sensors/blob/master/src/SensorPaths.cpp
+[20]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/36206
+[21]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/41398
+[22]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/39294
+[23]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/41394
+[24]: https://gerrit.openbmc.org/c/openbmc/entity-manager/+/41397
+[25]: https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/16177
diff --git a/designs/fail-boot-on-hw-error.md b/designs/fail-boot-on-hw-error.md
index db66677..bacd3bc 100644
--- a/designs/fail-boot-on-hw-error.md
+++ b/designs/fail-boot-on-hw-error.md
@@ -46,7 +46,7 @@
- The halt must only stop the chassis/host instance that encountered the error
- The halt must allow the host firmware the opportunity to gracefully shut
itself down
- - The halt must stop the host (run obmc-host-stop@X.target) associated with
+ - The halt must stop the host (run `obmc-host-stop@X.target`) associated with
the error and attempt to leave system in the fail state (i.e. chassis power
remains on if it is on)
- The chassis/host instance pair will not be allowed to power on until the log
diff --git a/designs/firmware-update-via-blobs.md b/designs/firmware-update-via-blobs.md
index f786452..f2f91a9 100644
--- a/designs/firmware-update-via-blobs.md
+++ b/designs/firmware-update-via-blobs.md
@@ -21,16 +21,16 @@
In-band here refers to a communications channel that is directly connected
between the host and BMC.
-1. Serial
-1. IPMI over LPC
-1. IPMI over i2c
-1. LPC Memory-Mapped Region
-1. P2A bridge
+1. Serial
+1. IPMI over LPC
+1. IPMI over i2c
+1. LPC Memory-Mapped Region
+1. P2A bridge
## Primer
-Please read the IPMI BLOB protocol design as primer
-[here](https://github.com/openbmc/phosphor-ipmi-blobs/blob/master/README.md).
+Please read the IPMI BLOB protocol design as
+[primer](https://github.com/openbmc/phosphor-ipmi-blobs/blob/master/README.md).
## Requirements
@@ -186,60 +186,60 @@
#### BlockTransfer Sequence
-1. Open (for Image or tarball)
-1. Write
-1. Close
-1. Open (`/flash/hash`)
-1. Write
-1. Close
-1. Open (`/flash/verify`)
-1. Commit
-1. SessionStat (to read back verification status)
-1. Close
-1. Open (`/flash/update`)
-1. Commit
-1. SessionStat (to read back update status)
-1. Close
+1. Open (for Image or tarball)
+1. Write
+1. Close
+1. Open (`/flash/hash`)
+1. Write
+1. Close
+1. Open (`/flash/verify`)
+1. Commit
+1. SessionStat (to read back verification status)
+1. Close
+1. Open (`/flash/update`)
+1. Commit
+1. SessionStat (to read back update status)
+1. Close
#### P2A Sequence
-1. Open (for Image or tarball)
-1. SessionStat (P2A Region for P2A mapping)
-1. Write
-1. Close
-1. Open (`/flash/hash`)
-1. SessionStat (P2A Region)
-1. Write
-1. Close
-1. Open (`/flash/verify`)
-1. Commit
-1. SessionStat (to read back verification status)
-1. Close
-1. Open (`/flash/update`)
-1. Commit
-1. SessionStat (to read back update status)
-1. Close
+1. Open (for Image or tarball)
+1. SessionStat (P2A Region for P2A mapping)
+1. Write
+1. Close
+1. Open (`/flash/hash`)
+1. SessionStat (P2A Region)
+1. Write
+1. Close
+1. Open (`/flash/verify`)
+1. Commit
+1. SessionStat (to read back verification status)
+1. Close
+1. Open (`/flash/update`)
+1. Commit
+1. SessionStat (to read back update status)
+1. Close
#### LPC Sequence
-1. Open (for image or tarball)
-1. WriteMeta (specify region information from host for LPC)
-1. SessionStat (verify the contents from the above)
-1. Write
-1. Close
-1. Open (`/flash/hash`)
-1. WriteMeta (LPC Region)
-1. SessionStat (verify LPC config)
-1. Write
-1. Close
-1. Open (`/flash/verify`)
-1. Commit
-1. SessionStat (to read back verification status)
-1. Close
-1. Open (`/flash/update`)
-1. Commit
-1. SessionStat (to read back update status)
-1. Close
+1. Open (for image or tarball)
+1. WriteMeta (specify region information from host for LPC)
+1. SessionStat (verify the contents from the above)
+1. Write
+1. Close
+1. Open (`/flash/hash`)
+1. WriteMeta (LPC Region)
+1. SessionStat (verify LPC config)
+1. Write
+1. Close
+1. Open (`/flash/verify`)
+1. Commit
+1. SessionStat (to read back verification status)
+1. Close
+1. Open (`/flash/update`)
+1. Commit
+1. SessionStat (to read back update status)
+1. Close
### Stale Images
@@ -265,7 +265,7 @@
used for specifying the transport mechanism. To obtain the list of supported
mechanisms on a platform, see the `Stat` command below.
-```
+```cpp
enum OpenFlags
{
read = (1 << 0),
@@ -314,7 +314,7 @@
The data section of the payload is the following structure:
-```
+```cpp
struct ExtChunkHdr
{
uint32_t length; /* Length of the data queued (little endian). */
@@ -325,7 +325,7 @@
The data section of the payload is the following structure:
-```
+```cpp
struct ExtChunkHdr
{
uint32_t length; /* Length of the data queued (little endian). */
@@ -371,8 +371,8 @@
Aborts any update that's in progress:
-1. Stops the verify_image.service if started.
-1. Deletes any staged files.
+1. Stops the verify_image.service if started.
+1. Deletes any staged files.
In the event the update is already in progress, such as the tarball mechanism is
used and in the middle of updating the files, it cannot be aborted.
@@ -382,7 +382,7 @@
Blob stat on a blob_id (not SessionStat) will return the capabilities of the
blob_id handler.
-```
+```cpp
struct BmcBlobStatRx {
uint16_t crc16;
/* This will have the bits set from the FirmwareUpdateFlags enum. */
@@ -396,7 +396,7 @@
If called pre-commit, it'll return the following information:
-```
+```cpp
struct BmcBlobStatRx {
uint16_t crc16;
uint16_t blob_state; /* OpenFlags::write | (one of the interfaces) */
@@ -409,7 +409,7 @@
address for use to configure the P2A region as part of the metadata portion of
the `BmcBlobStatRx`.
-```
+```cpp
struct BmcBlobStatRx {
uint16_t crc16;
uint16_t blob_state; /* OpenFlags::write | (one of the interfaces) */
@@ -423,7 +423,7 @@
If called post-commit on the verify file session, it'll return:
-```
+```cpp
struct BmcBlobStatRx {
uint16_t crc16;
uint16_t blob_state; /* OPEN_W | (one of the interfaces) */
@@ -443,7 +443,7 @@
If called post-commit on the update file session, it'll return:
-```
+```cpp
struct BmcBlobStatRx {
uint16_t crc16;
uint16_t blob_state; /* OPEN_W | (one of the interfaces) */
@@ -473,7 +473,7 @@
The write meta command's blob will be this structure:
-```
+```cpp
struct LpcRegion
{
uint32_t address; /* Host LPC address where the chunk is to be mapped. */
diff --git a/designs/firmware-update-via-usb.md b/designs/firmware-update-via-usb.md
index a25bbd0..efe6885 100644
--- a/designs/firmware-update-via-usb.md
+++ b/designs/firmware-update-via-usb.md
@@ -56,7 +56,7 @@
The udev rules files for example:
-```
+```udev
SUBSYSTEM=="block", ACTION=="add", ENV{ID_USB_DRIVER}=="usb-storage", ENV{DEVTYPE}=="partition", ENV{SYSTEMD_WANTS}="usb-code-update@%k", TAG+="systemd"
```
diff --git a/designs/gpio-based-cable-presence.md b/designs/gpio-based-cable-presence.md
index 8763a5f..937a7bb 100644
--- a/designs/gpio-based-cable-presence.md
+++ b/designs/gpio-based-cable-presence.md
@@ -1,6 +1,6 @@
-## GPIO-based Cable Presence Detection
+# GPIO-based Cable Presence Detection
-Author: Chu Lin (linchuyuan@google.com)
+Author: Chu Lin <linchuyuan@google.com>
Created: 2021-07-29
@@ -15,8 +15,8 @@
## Background and References
-1. https://www.intel.com/content/www/us/en/products/docs/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html
-2. https://www.dmtf.org/sites/default/files/Redfish_Cable_Management_Proposal_WIP_04-2021.pdf
+1. <https://www.intel.com/content/www/us/en/products/docs/servers/ipmi/ipmi-second-gen-interface-spec-v2-rev1-1.html>
+2. <https://www.dmtf.org/sites/default/files/Redfish_Cable_Management_Proposal_WIP_04-2021.pdf>
## Requirements
@@ -31,7 +31,7 @@
runtime configuration will be provIDed by EntityManager during startup. A
proposed config file looks like the following:
-```
+```json
{
"Exposes": [
{
@@ -39,18 +39,14 @@
"GpioLine": "osfp0",
"Polarity": "active_low",
"Type": "GPIOCableSensing",
- "FaultLedGroup": [
- "attention"
- ]
+ "FaultLedGroup": ["attention"]
},
{
"Name": "cable1",
"GpioLine": "osfp1",
"Polarity": "active_high",
"Type": "GPIOCableSensing",
- "FaultLedGroup": [
- "attention"
- ]
+ "FaultLedGroup": ["attention"]
}
]
}
@@ -69,7 +65,7 @@
On the IPMI sIDe, the presence states will be grouped into fewer SDR IDs in
order to save SDR IDs for ipmi. Given the following example,
-```
+```text
└─/xyz
└─/xyz/openbmc_project
└─/xyz/openbmc_project/inventory
@@ -91,7 +87,7 @@
cable0-13. One is cable[14-19]. If the object path is not indexed by the user,
it will take one SDR ID.
-```
+```text
ipmitool sdr list event
# /xyz/openbmc_project/inventory/item/cdfp0 to
# /xyz/openbmc_project/inventory/item/cdfp3
@@ -106,7 +102,7 @@
try to group it with anything and use 1 SDR ID for its presence state. See the
following for an example output.
-```
+```text
ipmitool sdr list event
cdfp[0-3] | Event-Only | ns
# /xyz/openbmc_project/inventory/item/osfp
@@ -140,7 +136,7 @@
- Instead of having a sleep-poll mechanism, it is better to have a event
listener on the gpio signals. However, the gpio_event_wait api requires all
the lines to come from the same chip. See
- https://github.com/brgl/libgpiod/blob/cc23ef61f66d5a9055b0e9fbdcfe6744c8a637ae/lib/core.c#L993
+ <https://github.com/brgl/libgpiod/blob/cc23ef61f66d5a9055b0e9fbdcfe6744c8a637ae/lib/core.c#L993>
We could spawn threads to listen to each chips but I don't think we should
increase the complexity of such a simple daemon.
diff --git a/designs/guard-on-bmc.md b/designs/guard-on-bmc.md
index 09cd29f..c144cf6 100644
--- a/designs/guard-on-bmc.md
+++ b/designs/guard-on-bmc.md
@@ -150,7 +150,7 @@
#### redfish » v1 » Systems » system » Processors » CPU1
-```
+```json
{
"@odata.type": "#Processor.v1_7_0.Processor",
"Id":view details "CPU1",
@@ -181,7 +181,7 @@
#### >> Entries
-```
+```json
{
"@odata.id": "/redfish/v1/Systems/system/LogServices/IsolatedHardware/Entries",
"@odata.type": "#LogEntryCollection.LogEntryCollection",
diff --git a/designs/hw-fault-monitor.md b/designs/hw-fault-monitor.md
index 2e59a86..6273b3b 100644
--- a/designs/hw-fault-monitor.md
+++ b/designs/hw-fault-monitor.md
@@ -1,9 +1,11 @@
# Hardware Fault Monitor
-Author: Claire Weinan (cweinan@google.com), daylight22)
+Author: Claire Weinan <cweinan@google.com> `daylight22`
-Other contributors: Heinz Boehmer Fiehn (heinzboehmer@google.com) Drew Walton
-(acwalton@google.com)
+Other contributors:
+
+- Heinz Boehmer Fiehn <heinzboehmer@google.com>
+- Drew Walton <acwalton@google.com>
Created: Aug 5, 2021
@@ -31,35 +33,35 @@
- Host Error Monitor logs CPU error information such as CATERR details and takes
appropriate actions such as performing resets and collecting crashdumps:
- https://github.com/openbmc/host-error-monitor
+ <https://github.com/openbmc/host-error-monitor>
- bmcweb implements a Redfish webserver for openbmc:
- https://github.com/openbmc/bmcweb. The Redfish LogService schema is available
- for logging purposes and the EventService schema is available for a Redfish
- server to send event notifications to clients.
+ <https://github.com/openbmc/bmcweb>. The Redfish LogService schema is
+ available for logging purposes and the EventService schema is available for a
+ Redfish server to send event notifications to clients.
- Phosphor Debug Collector (phosphor-debug-collector) collects various debug
dumps and saves them into files:
- https://github.com/openbmc/phosphor-debug-collector
+ <https://github.com/openbmc/phosphor-debug-collector>
- Dbus-sensors reads and saves sensor values and makes them available to other
- modules via D-Bus: https://github.com/openbmc/dbus-sensors
+ modules via D-Bus: <https://github.com/openbmc/dbus-sensors>
- SEL logger logs to the IPMI and Redfish system event logs when certain events
happen, such as sensor readings going beyond their thresholds:
- https://github.com/openbmc/phosphor-sel-logger
+ <https://github.com/openbmc/phosphor-sel-logger>
- FRU fault manager controls the blinking of LEDs when faults occur:
- https://github.com/openbmc/phosphor-led-manager/blob/master/fault-monitor/fru-fault-monitor.hpp
+ <https://github.com/openbmc/phosphor-led-manager/blob/master/fault-monitor/fru-fault-monitor.hpp>
- Guard On BMC records and manages a list of faulty components for isolation.
(Both the host and the BMC may identify faulty components and create guard
records for them):
- https://github.com/openbmc/docs/blob/9c79837a8a20dc8e131cc8f046d1ceb4a731391a/designs/guard-on-bmc.md
+ <https://github.com/openbmc/docs/blob/9c79837a8a20dc8e131cc8f046d1ceb4a731391a/designs/guard-on-bmc.md>
There is an OpenCompute Fault Management Infrastructure proposal that also
recommends delivering error logs from the BMC:
-https://drive.google.com/file/d/1A9Qc7hB3THw0wiEK_dbXYj85_NOJWrb5/
+<https://drive.google.com/file/d/1A9Qc7hB3THw0wiEK_dbXYj85_NOJWrb5/>
## Requirements
diff --git a/designs/management-console/Authorities_List_Management.md b/designs/management-console/Authorities_List_Management.md
index 0f13bea..b95ea6d 100644
--- a/designs/management-console/Authorities_List_Management.md
+++ b/designs/management-console/Authorities_List_Management.md
@@ -1,6 +1,6 @@
# Authorities List Management
-Author: Nan Zhou (nanzhoumails@gmail.com)
+Author: Nan Zhou <nanzhoumails@gmail.com>
Created: 12/01/2021
diff --git a/designs/management-console/VMI_Certificate_Exchange.md b/designs/management-console/VMI_Certificate_Exchange.md
index 7dd7cd5..72ef38e 100644
--- a/designs/management-console/VMI_Certificate_Exchange.md
+++ b/designs/management-console/VMI_Certificate_Exchange.md
@@ -108,7 +108,7 @@
Management console should use the below REST commands to exchange certificates
with VMI
-#### Get Signed certificate:
+#### Get Signed certificate
REST command to get signed client certificate from VMI
@@ -122,14 +122,13 @@
Response: This will return the certificate string which contains signed client
certificate
-```
- {
- “Certificate”: "<certificate string>"
- }
-
+```json
+{
+ "Certificate": "<certificate string>"
+}
```
-#### Get Root certificate:
+#### Get Root certificate
REST command to get VMI root certificate
@@ -142,21 +141,20 @@
Response: This will return the certificate string which contains and root CA
certificate.
-```
- {
- “Certificate”: "<certificate string>"
- }
-
+```json
+{
+ "Certificate": "<certificate string>"
+}
```
This interface returns HTTP error codes 5XX/4XX in failure cases
-## Alternatives considered:
+## Alternatives considered
Have gone through existing BMC certificate management infrastructure if we can
extend for this use case.
-### Current flow for generating and installing Certificates (CSR Based):
+### Current flow for generating and installing Certificates (CSR Based)
- Certificate Signing Request CSR is a message sent from an applicant to a
certificate authority in order to apply for a digital identity certificate.
diff --git a/designs/management-console/service-discovery.md b/designs/management-console/service-discovery.md
index a6598a1..f7a94c1 100644
--- a/designs/management-console/service-discovery.md
+++ b/designs/management-console/service-discovery.md
@@ -6,12 +6,12 @@
Created: 2019-07-12
-# Background and References
+## Background and References
-[1] https://www.engineersgarage.com/Articles/IoT-Service-Discovery-Protocols [2]
-http://www.zeroconf.org/ZeroconfAndUPnP.html : comparison of mDns v/s UPnP. [3]
-https://www.avahi.org/ [4]
-https://github.com/lathiat/avahi/blob/master/avahi-daemon/example.service
+1. <https://www.engineersgarage.com/Articles/IoT-Service-Discovery-Protocols>
+2. <http://www.zeroconf.org/ZeroconfAndUPnP.html> : comparison of mDns v/s UPnP.
+3. <https://www.avahi.org/>
+4. <https://github.com/lathiat/avahi/blob/master/avahi-daemon/example.service>
Apple’s Bonjour uses mDNS and DNS-SD. Linux’s Avahi uses IPv4LL, mDNS, and
DNS-SD. Linux’s systemd uses resolve hostnames on a network via DNS, mDNS, and
@@ -46,8 +46,8 @@
Following commits implements the behaviour.
-https://gerrit.openbmc.org/c/openbmc/meta-phosphor/+/22950
-https://gerrit.openbmc.org/c/openbmc/meta-ibm/+/22951
+- <https://gerrit.openbmc.org/c/openbmc/meta-phosphor/+/22950>
+- <https://gerrit.openbmc.org/c/openbmc/meta-ibm/+/22951>
As part of avahi discovery response, the client receives the following:
@@ -60,7 +60,7 @@
### How to do discovery through avahi
The following command may be used to discover the BMC systems in the network.
-Avahi-browse -rt <service type> e.g. To discover service type :
+`avahi-browse -rt <service type>` e.g. To discover service type :
\_obmc_rest.\_tcp avahi-browse -rt \_obmc_rest.\_tcp Output of the above command
is as follows avahi-browse -rt \_obmc_rest.\_tcp
diff --git a/designs/mctp/mctp-kernel.md b/designs/mctp/mctp-kernel.md
index fc2d914..6f77d0a 100644
--- a/designs/mctp/mctp-kernel.md
+++ b/designs/mctp/mctp-kernel.md
@@ -1,6 +1,6 @@
# OpenBMC in-kernel MCTP
-Author: Jeremy Kerr `<jk@codeconstruct.com.au>`
+Author: Jeremy Kerr <jk@codeconstruct.com.au>
Please refer to the [MCTP Overview](mctp.md) document for general MCTP design
description, background and requirements.
@@ -9,7 +9,7 @@
providing a sockets-based API for MCTP communication within an OpenBMC-based
platform.
-# Requirements for a kernel implementation
+## Requirements for a kernel implementation
- The MCTP messaging API should be an obvious application of the existing POSIX
socket interface
@@ -30,7 +30,7 @@
- customisable routing/bridging configurations within a network.
-# Proposed Design
+## Proposed Design
The design contains several components:
@@ -63,7 +63,7 @@
the namespace for these interfaces is separate from other network interfaces -
such as those for ethernet.
-## Structure: interfaces & networks
+### Structure: interfaces & networks
The kernel models the local MCTP topology through two items: interfaces and
networks.
@@ -85,9 +85,9 @@
If multiple networks are present, each may contain EIDs that are also present on
other networks.
-## Sockets API
+### Sockets API
-### Protocol definitions
+#### Protocol definitions
We define a new address family (and corresponding protocol family) for MCTP:
@@ -152,13 +152,13 @@
#define MCTP_TAG_RSP(x) (x & MCTP_TAG_MASK) /* response to a request: clear TO, keep value */
```
-### Syscall behaviour
+#### Syscall behaviour
The following sections describe the MCTP-specific behaviours of the standard
socket system calls. These behaviours have been chosen to map closely to the
existing sockets APIs.
-#### `bind()`: set local socket address
+##### `bind()`: set local socket address
Sockets that receive incoming request packets will bind to a local address,
using the `bind()` syscall.
@@ -203,7 +203,7 @@
bit is not part of the match). This results in the socket receiving packets with
and without a message integrity check footer.
-#### `connect()`: set remote socket address
+##### `connect()`: set remote socket address
Sockets may specify a socket's remote address with the `connect()` syscall:
@@ -250,7 +250,7 @@
Requesters which connect to a single responder will typically use `connect()` to
specify the peer address and tag for future outgoing messages.
-#### `sendto()`, `sendmsg()`, `send()` & `write()`: transmit an MCTP message
+##### `sendto()`, `sendmsg()`, `send()` & `write()`: transmit an MCTP message
An MCTP message is transmitted using one of the `sendto()`, `sendmsg()`,
`send()` or `write()` syscalls. Using `sendto()` as the primary example:
@@ -318,7 +318,7 @@
Sockets will only receive responses to requests they have sent (with TO=1) and
may only respond (with TO=0) to requests they have received.
-#### `recvfrom()`, `recvmsg()`, `recv()` & `read()`: receive an MCTP message
+##### `recvfrom()`, `recvmsg()`, `recv()` & `read()`: receive an MCTP message
An MCTP message can be received by an application using one of the `recvfrom()`,
`recvmsg()`, `recv()` or `read()` system calls. Using `recvfrom()` as the
@@ -356,7 +356,7 @@
Like the send calls, sockets will only receive responses to requests they have
sent (TO=1) and may only respond (TO=0) to requests they have received.
-#### `getsockname()` & `getpeername()`: query local/remote socket address
+##### `getsockname()` & `getpeername()`: query local/remote socket address
The `getsockname()` system call returns the `struct sockaddr_mctp` value for the
local side of this socket, `getpeername()` for the remote (ie, that used in a
@@ -366,11 +366,11 @@
Calling `getpeername()` on an unconnected socket will result in an error of
`ENOTCONN`.
-#### Socket options
+##### Socket options
The following socket options are defined for MCTP sockets:
-##### `MCTP_ADDR_EXT`: Use extended addressing information in sendmsg/recvmsg
+###### `MCTP_ADDR_EXT`: Use extended addressing information in sendmsg/recvmsg
Enabling this socket option allows an application to specify extended addressing
information on transmitted packets, and access the same on received packets.
@@ -397,14 +397,16 @@
contain this larger structure, then the extended addressing fields are consumed
/ populated respectively.
-##### `MCTP_TAG_CONTROL`: manage outgoing tag allocation behaviour
+###### `MCTP_TAG_CONTROL`: manage outgoing tag allocation behaviour
The set/getsockopt argument is a `mctp_tagctl` structure:
+```c
struct mctp_tagctl {
bool retain;
struct timespec timeout;
};
+```
This allows an application to control the behaviour of allocated tags for
non-connected sockets when transferring messages to multiple different
@@ -431,7 +433,7 @@
- the socket is sending messages with TO=1 (ie, is a requester); and
- messages are sent to multiple different destination EIDs from the one socket.
-#### Syscalls not implemented
+##### Syscalls not implemented
The following system calls are not implemented for MCTP, primarily as they are
not used in `SOCK_DGRAM`-type sockets:
@@ -442,7 +444,7 @@
- `shutdown()`
- `mmap()`
-### Userspace examples
+#### Userspace examples
These examples cover three general use-cases:
@@ -462,7 +464,7 @@
This is similar to a DHCP server.
-#### Requester
+##### Requester
"Client"-side implementation to send requests to a responder, and receive a
response. This uses a (fictitious) message type of `MCTP_TYPE_ECHO`.
@@ -515,7 +517,7 @@
}
```
-#### Responder
+##### Responder
"Server"-side implementation to receive requests and respond. Like the client,
This uses a (fictitious) message type of `MCTP_TYPE_ECHO` in the
@@ -574,7 +576,7 @@
}
```
-#### Broadcast request
+##### Broadcast request
Sends a request to a broadcast EID, and receives (unicast) replies. Typical
control protocol pattern.
@@ -652,9 +654,9 @@
}
```
-### Implementation notes
+#### Implementation notes
-#### Addressing
+##### Addressing
Transmitted messages (through `sendto()` and related system calls) specify their
destination via the `smctp_network` and `smctp_addr` fields of a
@@ -677,7 +679,7 @@
MCTP responders should use the EID and network values of an incoming request to
specify the destination for any responses.
-#### Bridging/routing
+##### Bridging/routing
The network and interface structure allows multiple interfaces to share a common
network. By default, packets are not forwarded between interfaces.
@@ -690,7 +692,7 @@
If the packet is larger than the MTU for the destination interface/route, then
the packet is dropped.
-#### Tag behaviour for transmitted messages
+##### Tag behaviour for transmitted messages
On every message sent with the tag-owner bit set ("TO" in DSP0236), the kernel
must allocate a tag that will uniquely identify responses over a (destination
@@ -739,7 +741,7 @@
use with _any other EID_. Sending to the broadcast address should be avoided; we
expect few applications will need this functionality.
-#### MCTP Control Protocol implementation
+##### MCTP Control Protocol implementation
Aside from the "Resolve endpoint EID" message, the MCTP control protocol
implementation would exist as a userspace process, `mctpd`. This process is
@@ -753,7 +755,7 @@
route table via a netlink interface - the same as that implemented for the
[Utility and configuration interfaces](#utility-and-configuration-interfaces).
-### Neighbour and routing implementation
+#### Neighbour and routing implementation
The packet-transmission behaviour of the MCTP infrastructure relies on a single
routing table to lookup both route and neighbour information. Entries in this
@@ -786,7 +788,7 @@
This is the only kernel-internal usage of MCTP Control Protocol messages.
-## Utility and configuration interfaces
+### Utility and configuration interfaces
A small utility will be developed to control the state of the kernel MCTP stack.
This will be similar in design to the 'iproute2' tools, which perform a similar
@@ -795,7 +797,7 @@
The utility will be invoked as `mctp`, and provide subcommands for managing
different aspects of the kernel stack.
-### `mctp link`: manage interfaces
+#### `mctp link`: manage interfaces
```sh
mctp link set <link> <up|down>
@@ -804,7 +806,7 @@
mctp link set <link> bus-owner <hwaddr>
```
-### `mctp network`: manage networks
+#### `mctp network`: manage networks
```sh
mctp network create <network-id>
@@ -813,14 +815,14 @@
mctp network delete <network-id>
```
-### `mctp address`: manage local EID assignments
+#### `mctp address`: manage local EID assignments
```sh
mctp address add <eid> dev <link>
mctp address del <eid> dev <link>
```
-### `mctp route`: manage routing tables
+#### `mctp route`: manage routing tables
```sh
mctp route add net <network-id> eid <eid|eid-range> via <link> [hwaddr <addr>] [mtu <mtu>] [metric <metric>]
@@ -828,7 +830,7 @@
mctp route show [net <network-id>]
```
-### `mctp stat`: query socket status
+#### `mctp stat`: query socket status
```sh
mctp stat
@@ -837,9 +839,9 @@
A set of netlink message formats will be defined to support these control
functions.
-# Design points & alternatives considered
+## Design points & alternatives considered
-## Including message-type byte in send/receive buffers
+### Including message-type byte in send/receive buffers
This design specifies that message buffers passed to the kernel in send syscalls
and from the kernel in receive syscalls will have the message type byte as the
@@ -859,7 +861,7 @@
Therefore, we transfer the message payload as-is to userspace, without any
modification by the kernel.
-## MCTP message-type specification: using `sockaddr_mctp.smctp_type` rather than protocol
+### MCTP message-type specification: using `sockaddr_mctp.smctp_type` rather than protocol
This design specifies message-types to be passed in the `smctp_type` field of
`struct sockaddr_mctp`. An alternative would be to pass it in the `protocol`
@@ -881,7 +883,7 @@
Future additions that perform protocol-specific message handling, and so alter
the send/receive buffer format, may use a new protocol argument.
-## Networks referenced by index rather than UUID
+### Networks referenced by index rather than UUID
This design proposes referencing networks by an integer index. The MCTP standard
does optionally associate a RFC4122 UUID with a networks; it would be possible
@@ -896,12 +898,12 @@
Instead, the index integer is used instead, in a similar fashion to the integer
index used to reference `struct netdevice`s elsewhere in the network stack.
-## Tag behaviour alternatives
+### Tag behaviour alternatives
We considered _several_ different designs for the tag handling behaviour. A
brief overview of the more-feasible of those, and why they were rejected:
-### Each socket is allocated a unique tag value on creation
+#### Each socket is allocated a unique tag value on creation
We could allocate a tag for each socket on creation, and use that value when a
tag is required. This, however:
@@ -911,7 +913,7 @@
- limits us to 8 sockets per network.
-### Tags only used for message packetisation / reassembly
+#### Tags only used for message packetisation / reassembly
An alternative would be to completely dissociate tag allocation from sockets;
and only allocate a tag for the (short-lived) task of packetising a message, and
@@ -929,7 +931,7 @@
listening on that type, making it trivial to eavesdrop on MCTP data of other
applications
-### Allocate a tag for one request/response pair
+#### Allocate a tag for one request/response pair
Another alternative would be to allocate a tag on each outgoing TO=1 message,
and then release that allocation after the incoming response to that tag (TO=0)
diff --git a/designs/mctp/mctp-userspace.md b/designs/mctp/mctp-userspace.md
index cd09b61..dce74fc 100644
--- a/designs/mctp/mctp-userspace.md
+++ b/designs/mctp/mctp-userspace.md
@@ -1,6 +1,6 @@
# OpenBMC platform communication channel: MCTP & PLDM in userspace
-Author: Jeremy Kerr <jk@ozlabs.org> <jk>
+Author: Jeremy Kerr <jk@ozlabs.org> `jk`
Please refer to the [MCTP Overview](mctp.md) document for general MCTP design
description, background and requirements.
@@ -25,12 +25,12 @@
This daemon has a few components:
-1. the core MCTP stack
+1. the core MCTP stack
-2. one or more binding implementations (eg, MCTP-over-serial), which interact
- with the hardware channel(s).
+2. one or more binding implementations (eg, MCTP-over-serial), which interact
+ with the hardware channel(s).
-3. an interface to handler applications over a unix-domain socket.
+3. an interface to handler applications over a unix-domain socket.
The proposed implementation here is to produce an MCTP "library" which provides
the packetisation and routing functions, between:
@@ -88,7 +88,7 @@
MCTP handlers (ie, clients of the demultiplexer) connect using a unix-domain
socket, at the abstract socket address:
-```
+```text
\0mctp-demux
```
@@ -104,7 +104,7 @@
Each message has a fixed small header:
-```
+```cpp
uint8_t eid
```
diff --git a/designs/mctp/mctp.md b/designs/mctp/mctp.md
index b0e8cf1..3b7801f 100644
--- a/designs/mctp/mctp.md
+++ b/designs/mctp/mctp.md
@@ -1,6 +1,6 @@
# OpenBMC platform communication channel: MCTP & PLDM
-Author: Jeremy Kerr <jk@ozlabs.org> <jk>
+Author: Jeremy Kerr <jk@ozlabs.org> `jk`
## Problem Description
@@ -31,13 +31,13 @@
layer bindings for the actual transport of MCTP packets. These are defined by
the DMTF's Platform Management Working group; standards are available at:
-https://www.dmtf.org/standards/pmci
+<https://www.dmtf.org/standards/pmci>
The following diagram shows how these standards map to the areas of
functionality that we may want to implement for OpenBMC. The DSP numbers
provided are references to DMTF standard documents.
-
+
One of the key concepts here is that separation of transport protocol from the
physical layer bindings; this means that an MCTP "stack" may be using either a
diff --git a/designs/multi-host-postcode.md b/designs/multi-host-postcode.md
index 7529f82..5e546b4 100644
--- a/designs/multi-host-postcode.md
+++ b/designs/multi-host-postcode.md
@@ -25,7 +25,7 @@
|`S:` |D-Bus service name (well-known bus name)| |`R:` |Repository name| |`U:`
|Systemd service unit name| |`A:` |Executable name| |`H:` |HW Module|
-```
+```text
+-----------+
+------+ | 7 segment |
| Host | | display |
@@ -94,11 +94,11 @@
- platform specific OEM handler (fb-ipmi-oem).
- bmcweb (redfish logging service).
-**Interface Diagram**
+### Interface Diagram
Provided below the post code interface diagram with flow sequence
-```
+```text
+---------------------------------------------------+
| BMC |
| |
@@ -143,7 +143,7 @@
+----------------------------------------------------------+
```
-**Postcode Flow:**
+### Postcode Flow
- BMC power-on the host.
- Host starts sending the postcode IPMI message continuously to the BMC.
@@ -178,15 +178,15 @@
- Display the latest postcode of the selected host read through D-Bus on a
7-segment display.
-**D-Bus interface**
+### D-Bus interface
The following D-Bus names need to be created for the multi-host post-code.
- Service name -- xyz.openbmc_project.State.Boot.Raw
-
- Obj path name -- /xyz/openbmc_project/State/Boot/RawX(1,2..N)
-
- Interface name -- xyz.openbmc_project.State.Boot.Raw
+```text
+Service name: xyz.openbmc_project.State.Boot.Raw
+Obj path name: /xyz/openbmc_project/State/Boot/RawX(1,2..N)
+Interface name: xyz.openbmc_project.State.Boot.Raw
+```
## phosphor-post-code-manager
@@ -202,15 +202,15 @@
- Store/retrieve post-code from directory (/var/lib/phosphor-post-code-manager/
hostX(1,2,3..N)) based on event received from phosphor-host-postd.
-**D-Bus interface**
+### D-Bus interface
The following D-Bus names needs to be created for multi-host post-code.
- Service name -- xyz.openbmc_project.State.Boot.PostCodeX(1,2..N)
-
- Obj path name -- /xyz/openbmc_project/State/Boot/PostCodeX(1,2..N)
-
- Interface name -- xyz.openbmc_project.State.Boot.PostCode
+```text
+Service name: xyz.openbmc_project.State.Boot.PostCodeX(1,2..N)
+Obj path name: /xyz/openbmc_project/State/Boot/PostCodeX(1,2..N)
+Interface name: xyz.openbmc_project.State.Boot.PostCode
+```
## bmcweb
@@ -219,7 +219,7 @@
## Alternate design
-**phosphor-post-code-manager single process approach**
+### phosphor-post-code-manager single process approach
This implementation consider single service to handle multi-host postcode. In
this approach, all D-Bus handling will taken care by the single process.
diff --git a/designs/multihost-ipmi-design.md b/designs/multihost-ipmi-design.md
index d2855e4..74ef1a1 100644
--- a/designs/multihost-ipmi-design.md
+++ b/designs/multihost-ipmi-design.md
@@ -26,7 +26,7 @@
IPMI and IPMB System architecture:
-```
+```ascii
+------------------------------------+
| BMC |
| +-----------+ +------------+ | +--------+
@@ -68,11 +68,11 @@
ipmbbridged and ipmid. To address out-of-band IPMI command from the network,the
proposal is captured in section "Changes in netipmid".
-## Issue1: Changes in ipmbbridged:
+## Issue1: Changes in ipmbbridged
ipmbbridged to send the channel details from where the request is received.
-**Change: Sending Host detail as additional parameter**
+### Change: Sending Host detail as additional parameter
While routing the IPMB requests coming from the host channel, We will be adding
new entry in the json config file for the host ID '"devIndex": 0' ipmbbridged
@@ -84,13 +84,40 @@
channel.To ensure existing platforms does not get affected, if the "devIndex"
key is not present in the file ipmbbridged uses default "devIndex" as 0.
-{ "type": "me", "slave-path": "/dev/ipmb-1", "bmc-addr": 32, "remote-addr": 64,
-"devIndex": 0 }, { "type": "ipmb", "slave-path": "/dev/ipmb-2", "bmc-addr": 32,
-"remote-addr": 64, "devIndex": 0 }, { "type": "me", "slave-path": "/dev/ipmb-3",
-"bmc-addr": 32, "remote-addr": 64, "devIndex": 1 }, { "type": "ipmb",
-"slave-path": "/dev/ipmb-4", "bmc-addr": 32, "remote-addr": 64, "devIndex": 1 },
+```json
+[
+ {
+ "type": "me",
+ "slave-path": "/dev/ipmb-1",
+ "bmc-addr": 32,
+ "remote-addr": 64,
+ "devIndex": 0
+ },
+ {
+ "type": "ipmb",
+ "slave-path": "/dev/ipmb-2",
+ "bmc-addr": 32,
+ "remote-addr": 64,
+ "devIndex": 0
+ },
+ {
+ "type": "me",
+ "slave-path": "/dev/ipmb-3",
+ "bmc-addr": 32,
+ "remote-addr": 64,
+ "devIndex": 1
+ },
+ {
+ "type": "ipmb",
+ "slave-path": "/dev/ipmb-4",
+ "bmc-addr": 32,
+ "remote-addr": 64,
+ "devIndex": 1
+ }
+]
+```
-## Issue2: Changes in ipmid:
+## Issue2: Changes in ipmid
Receive the optional parameter sent by the ipmbbridged as host details, while
receiving the parameter in the executionEntry method call the same will be
@@ -103,7 +130,7 @@
order details and respond from the command handler. This is applicable for both
common and oem handlers.
-## Changes in netipmid:
+## Changes in netipmid
The "options" parameter can be used for sending the host information from
netipmid. The changes proposed for ipmbbridged can be used in netipmid as well.
@@ -125,7 +152,7 @@
Example implementation of approach1:Virtual ethernet interface.
-```
+```ascii
+--------------------------------------------+
| BMC |
| +--------+ +-----------+ +------+ | +--------+
@@ -160,14 +187,14 @@
looks to be a simple change but impacts the existing platforms which are already
using it.This may not be a right approach.
-## Approach2:Create multiple ipmid to handle multihost.One ipmid process per host.
+## Approach2:Create multiple ipmid to handle multihost.One ipmid process per host
This is a multi service appoach,one instance of ipmid service shall be spawned
to respond each host.The changes looks simple and no major design change from
the existing design. But many common handlers will be running as duplicate in
multiple instances.
-## Approach3:Using a different IPMI channel for handling multiple host.
+## Approach3:Using a different IPMI channel for handling multiple host
Using a different IPMI channel for handling multiple hosts, in the ipmbbridged
the channel id can be used to identify host. In this approach we will be having
diff --git a/designs/multihost-phosphor-buttons.md b/designs/multihost-phosphor-buttons.md
index 4d2fbca..48bd850 100644
--- a/designs/multihost-phosphor-buttons.md
+++ b/designs/multihost-phosphor-buttons.md
@@ -34,7 +34,7 @@
The front panel of bmc has buttons like power button, reset button in general
the code for monitoring these buttons and triggering actions are supported.
-```
+```text
+----------------------------------------------+
| |
| Front panel |
@@ -57,7 +57,7 @@
example for a multihost platform yosemite-V2 it has host selector switch mux as
additional button in front panel.
-```
+```text
+---------------------------+ +------------+
| | | |
| yv2 front panel | power/ ---------+| host 1 |
@@ -111,7 +111,7 @@
The power/reset button press events are triggered based on the value of host
selector switch position.
-### Example :
+### Example
host selector position value = 0,bmc is mapped to power and reset buttons host
selector position value = 1,host 1 is mapped to power and reset buttons host
@@ -148,7 +148,7 @@
host selector switch value is more than MaxPosition then it should be reset to
zero.
-# Proposed Design
+## Proposed Design
Three high level changes are required in the phosphor button interface class
@@ -193,7 +193,7 @@
This button interface monitors the corresponding gpio lines for debug card host
selection button press and release event via sd-event based loop.
-### OCP Debug card host selector button dbus interface details :
+### OCP Debug card host selector button dbus interface details
1. Released(signal) - This is signal is triggered in the ocp debug card event
handler when the ocp debug card button is pressed and released.
diff --git a/designs/multihost-physical-led.md b/designs/multihost-physical-led.md
index 0b538d7..2acbfce 100644
--- a/designs/multihost-physical-led.md
+++ b/designs/multihost-physical-led.md
@@ -34,8 +34,7 @@
The below diagram represents the overview for current physical LED design.
-```
-
+```ascii
KERNEL META-PHOSPHOR PHOSPHOR-LED-SYSFS SERVICE
+------------+ Event 1 +----------+ LED 1 +-----------------------------+
@@ -78,9 +77,9 @@
triggers the necessary action to generate the dbus object path and interface for
that specified service. It exposes one service per LED.
-**Example**
+### Example
-```
+```text
busctl tree xyz.openbmc_project.LED.Controller.led1
`-/xyz
`-/xyz/openbmc_project
@@ -107,8 +106,7 @@
The below diagram represents the overview for proposed physical LED design.
-```
-
+```ascii
KERNEL PHOSPHOR-LED-SYSFS DAEMON
+------------+ Event 1 +--------+ +---------+ +--------------+
@@ -139,7 +137,7 @@
- Physical Leds are defined in the device tree under "leds" section and
corresponding GPIO pins are configured.
-```
+```dts
leds {
compatible = "gpio-leds";
@@ -154,7 +152,7 @@
**_xyz.openbmc_project.Led.Sysfs.Internal_** interface name to add or remove
the LED, which will be coming from each udev LED event.
-```
+```text
NAME TYPE SIGNATURE RESULT/VALUE FLAGS
xyz.openbmc_project.Led.Sysfs.Internal interface - - -
@@ -185,8 +183,7 @@
**_Example_**
-```
-
+```text
SERVICE xyz.openbmc_project.LED.Controller
INTERFACE xyz.openbmc_project.LED.Physical
@@ -207,7 +204,7 @@
## Alternatives Considered
-**Approach 1**
+### Approach 1
When the udev event is initialized for the LED, it will save those LED names in
a file utilizing the script. Phosphor-led-sysfs will monitor the file using
diff --git a/designs/nmi-dbus-interface.md b/designs/nmi-dbus-interface.md
index ef4ee66..92e3264 100644
--- a/designs/nmi-dbus-interface.md
+++ b/designs/nmi-dbus-interface.md
@@ -16,7 +16,7 @@
## Background and References
There is a situation at customer places/lab where the host goes unresponsive
-causing system hang(https://github.com/ibm-openbmc/dev/issues/457). This means
+causing system hang(<https://github.com/ibm-openbmc/dev/issues/457>). This means
there is no way to figure out what went wrong with the host in a hung state. One
has to recover the system with no relevant debug data captured.
diff --git a/designs/nvmemi-over-smbus.md b/designs/nvmemi-over-smbus.md
index 59b1684..24515a6 100644
--- a/designs/nvmemi-over-smbus.md
+++ b/designs/nvmemi-over-smbus.md
@@ -1,10 +1,10 @@
-### NVMe-MI over SMBus
+# NVMe-MI over SMBus
Author: Tony Lee <tony.lee@quantatw.com>
Created: 3-8-2019
-#### Problem Description
+## Problem Description
Currently, OpenBMC does not support NVMe drive information. NVMe-MI
specification defines a command that can read the NVMe drive information via
@@ -12,7 +12,7 @@
vendor ID, temperature, etc. The aim of this proposal is to allow users to
monitor NVMe drives so appropriate action can be taken.
-#### Background and References
+## Background and References
NVMe-MI specification defines a command called
`NVM Express Basic Management Command` that can read the NVMe drives information
@@ -24,12 +24,14 @@
communicate with NVMe drives. According to different platforms, temperature
sensor, present status, LED and power sequence will be customized.
-[1] NVM Express Management Interface Revision 1.0a April 8, 2017 in Appendix A.
-(https://nvmexpress.org/wp-content/uploads/NVM_Express_Management_Interface_1_0a_2017.04.08_-_gold.pdf)
-[2] System Management Bus (SMBus) Specification Version 3.0 20 Dec 2014
-(http://smbus.org/specs/SMBus_3_0_20141220.pdf)
+[1]:
+ https://nvmexpress.org/wp-content/uploads/NVM_Express_Management_Interface_1_0a_2017.04.08_-_gold.pdf
+ "NVM Express Management Interface Revision 1.0a April 8, 2017 in Appendix A."
+[2]:
+ http://smbus.org/specs/SMBus_3_0_20141220.pdf
+ "System Management Bus (SMBus) Specification Version 3.0 20 Dec 2014"
-#### Requirements
+## Requirements
The implementation should:
@@ -41,7 +43,7 @@
- Ability to turn the fault LED on/off for each drive by SmartWarnings if the
object path of fault LED is defined in the configuration file.
-#### Proposed Design
+## Proposed Design
Create a D-bus service "xyz.openbmc_project.nvme.manager" with object paths for
each NVMe sensor: "/xyz/openbmc_project/sensors/temperature/nvme0",
@@ -70,7 +72,7 @@
Under the D-bus named "xyz.openbmc_project.nvme.manager":
-```
+```text
/xyz/openbmc_project
└─/xyz/openbmc_project/sensors
└─/xyz/openbmc_project/sensors/temperature/nvme0
@@ -84,7 +86,7 @@
Under the D-bus named "xyz.openbmc_project.Inventory.Manager":
-```
+```text
/xyz/openbmc_project
└─/xyz/openbmc_project/inventory
└─/xyz/openbmc_project/inventory/system
@@ -142,7 +144,7 @@
| BuildDate | bool | The date of item manufacture in YYYYMMDD format |
| Model | bool | The model of the item |
-##### xyz.openbmc_project.nvme.manager.service
+### xyz.openbmc_project.nvme.manager.service
This service has several steps:
@@ -165,12 +167,12 @@
This service will run automatically and look up NVMe drives every second.
-##### Fault LED
+### Fault LED
When the value obtained from the command corresponds to one of the warning
types, it will trigger the fault LED of corresponding device and issue events.
-##### Add SEL related to NVMe
+### Add SEL related to NVMe
The events `TemperatureFault`, `BackupdrivesFault`, `CapacityFault`,
`DegradesFault` and `MediaFault` will be generated for the NVMe errors.
@@ -181,7 +183,7 @@
- Degrades Fault log : when the property `DegradesFault` set to true
- Media Fault log: when the property `MediaFault` set to true
-#### Alternatives Considered
+## Alternatives Considered
NVMe-MI specification defines multiple commands that can communicate with NVMe
drives over MCTP protocol. The NVMe-MI over MCTP has the following key
@@ -196,12 +198,12 @@
For monitoring NVMe drives, using NVM Express Basic Management Command over
SMBus directly is much simpler than NVMe-MI over MCTP protocol.
-#### Impacts
+## Impacts
This application is monitoring NVMe drives via SMbus and set values to D-bus.
The impacts should be small in the system.
-#### Testing
+## Testing
This implementation is to use NVMe-MI-Basic command over SMBus and then set the
response data to D-bus. Testing will send SMBus command to the drives to get the
diff --git a/designs/oem/google/root_of_trust.md b/designs/oem/google/root_of_trust.md
index 456b355..35e4326 100644
--- a/designs/oem/google/root_of_trust.md
+++ b/designs/oem/google/root_of_trust.md
@@ -44,7 +44,7 @@
This new API is designed to forward calls to RoT devices and avoid and
inspections of data. An example call would be:
-```
+```json
{
"#RootOfTrust.Mailbox": {
"target": "/redfish/v1/RootsOfTrust/0/Actions.Mailbox",
@@ -57,21 +57,21 @@
This new service root is very similar to `/ibm/v1`. This would require a new
dbus interface to service this API:
-```
+```yaml
description: >
- Forward bytes to Google RoT devices.
+ Forward bytes to Google RoT devices.
methods:
- - name: Mailbox
- description: >
- A method to forward bytes to RoT device.
- parameters:
- - name: rawRequest
- type: array[byte]
- description: >
- Value to be updated for the keyword.
- errors:
- - xyz.openbmc_project.Common.Error.InvalidArgument
- - xyz.openbmc_project.Common.Error.InternalFailure
+ - name: Mailbox
+ description: >
+ A method to forward bytes to RoT device.
+ parameters:
+ - name: rawRequest
+ type: array[byte]
+ description: >
+ Value to be updated for the keyword.
+ errors:
+ - xyz.openbmc_project.Common.Error.InvalidArgument
+ - xyz.openbmc_project.Common.Error.InternalFailure
```
## Alternatives Considered
diff --git a/designs/oem/ibm/system-power-mode.md b/designs/oem/ibm/system-power-mode.md
index 65a019a..6909b0d 100644
--- a/designs/oem/ibm/system-power-mode.md
+++ b/designs/oem/ibm/system-power-mode.md
@@ -35,7 +35,7 @@
the OCC.
PowerMode was added to version 2021.1 Redfish Schema Supplement:
-https://www.dmtf.org/sites/default/files/standards/documents/DSP0268_2021.1.pdf
+<https://www.dmtf.org/sites/default/files/standards/documents/DSP0268_2021.1.pdf>
Current Customer Settable System Power Modes that will be sent to the OCCs:
@@ -73,7 +73,7 @@
When initiated, the new code will send a SET_MODE_AND_STATE command (0x20) to
the OCC and a SET_CONFIG_DATA (0x21) command with the Idle Power Saver
parameters. These commands are defined in the OCC Interface Spec:
-https://github.com/open-power/docs/blob/master/occ/OCC_P9_FW_Interfaces.pdf
+<https://github.com/open-power/docs/blob/master/occ/OCC_P9_FW_Interfaces.pdf>
Default values will also be defined for Power Mode and Idle Power Saver
parameters for the system. If the customer has not yet set any of these
diff --git a/designs/phosphor-audit.md b/designs/phosphor-audit.md
index 86464ac..399d50f 100644
--- a/designs/phosphor-audit.md
+++ b/designs/phosphor-audit.md
@@ -1,10 +1,11 @@
# phosphor-audit
-Author: Ivan Mikhaylov, [i.mikhaylov@yadro.com](mailto:i.mikhaylov@yadro.com)
+Author: Ivan Mikhaylov [i.mikhaylov@yadro.com](mailto:i.mikhaylov@yadro.com)
-Other contributors: Alexander Amelkin,
-[a.amelkin@yadro.com](mailto:a.amelkin@yadro.com) Alexander Filippov,
-[a.filippov@yadro.com](mailto:a.filippov@yadro.com)
+Other contributors:
+
+- Alexander Amelkin [a.amelkin@yadro.com](mailto:a.amelkin@yadro.com)
+- Alexander Filippov [a.filippov@yadro.com](mailto:a.filippov@yadro.com)
Created: 2019-07-23
@@ -104,7 +105,7 @@
possible to just store logs, run arbitrary command or notify someone in handler
or we can do all of the above and all of this can be optional.
-**Audit event call**
+### Audit event call
Audit event call performs preprocessing of incoming data at application side
before sending it to the audit service, if the request is filtered out, it will
@@ -133,15 +134,18 @@
Pseudocode for example:
+```cpp
audit_event(NET_IPMI, "access denied"(rc=-1), "ipmi cmd", "qwerty223",
"192.168.0.1", <some additional data if needed>)
audit_event(REST, "login successful"(rc=200), "rest login",
"qwerty223", "192.168.0.1", NULL)
audit_event(HOST_IPMI, "shutting down the host"(rc=0), "host poweroff",
NULL, NULL, NULL)
+```
`audit_event(blob_data)` Blob can be described as structure:
+```cpp
struct blob_audit
{
uint8_t type;
@@ -151,6 +155,7 @@
sockaddr_in6 *addr;
struct iovec *data;
}
+```
When the call reaches the server destination via D-Bus, the server already knows
that the call should be processed via predefined list of actions which are set
@@ -169,18 +174,17 @@
How the checks will be processed at client's layer:
-1. check the status of service and cache that value
-2. check the list of possible actions which should be logged and cache them
- also
-3. listen on 'propertiesChanged' event in case of changing list or status of
- service
+1. check the status of service and cache that value
+2. check the list of possible actions which should be logged and cache them also
+3. listen on 'propertiesChanged' event in case of changing list or status of
+ service
## Service configuration
The configuration structure can be described as tree with set of options, as
example of structure:
-```
+```text
[IPMI]
[Enabled]
[Whitelist]
diff --git a/designs/phosphor-hwmon-io-uring.md b/designs/phosphor-hwmon-io-uring.md
index 4e61bf8..4cbab70 100644
--- a/designs/phosphor-hwmon-io-uring.md
+++ b/designs/phosphor-hwmon-io-uring.md
@@ -71,7 +71,7 @@
used to store the read results, which will be the main access point for
obtaining sensor reads in mainloop.cpp.
-```
+```ascii
Interface Layer
+--------------------------------------------+
| |
diff --git a/designs/physical-topology.md b/designs/physical-topology.md
index bf2ba3f..9f2bc20 100644
--- a/designs/physical-topology.md
+++ b/designs/physical-topology.md
@@ -1,8 +1,8 @@
# Physical Topology for Inventory Items
-Author: Benjamin Fair <benjaminfair>
+Author: Benjamin Fair `benjaminfair`
-Other contributors: Ed Tanous <edtanous>
+Other contributors: Ed Tanous `edtanous`
Created: June 1, 2022
@@ -89,34 +89,34 @@
superchassis.json
-```
+```json
{
- "Exposes": [
- {
- "Name": "MyPort",
- "Type": "BackplanePort"
- }
- ],
- "Name": "Superchassis",
- "Probe": "TRUE",
- "Type": "Chassis"
+ "Exposes": [
+ {
+ "Name": "MyPort",
+ "Type": "BackplanePort"
+ }
+ ],
+ "Name": "Superchassis",
+ "Probe": "TRUE",
+ "Type": "Chassis"
}
```
subchassis.json:
-```
+```json
{
- "Exposes": [
- {
- "ConnectsToType": "BackplanePort",
- "Name": "MyDownstreamPort",
- "Type": "DownstreamPort"
- }
- ],
- "Name": "Subchassis",
- "Probe": "TRUE",
- "Type": "Chassis"
+ "Exposes": [
+ {
+ "ConnectsToType": "BackplanePort",
+ "Name": "MyDownstreamPort",
+ "Type": "DownstreamPort"
+ }
+ ],
+ "Name": "Subchassis",
+ "Probe": "TRUE",
+ "Type": "Chassis"
}
```
@@ -134,7 +134,7 @@
Example `busctl` calls:
-```
+```text
$ busctl get-property xyz.openbmc_project.ObjectMapper \
/xyz/openbmc_project/inventory/system/chassis/Superchassis/containing \
xyz.openbmc_project.Association endpoints
diff --git a/designs/pldm-stack.md b/designs/pldm-stack.md
index daebfa9..47ce5b2 100644
--- a/designs/pldm-stack.md
+++ b/designs/pldm-stack.md
@@ -1,6 +1,6 @@
# PLDM stack on OpenBMC
-Author: Deepak Kodihalli <dkodihal@linux.vnet.ibm.com> <dkodihal>
+Author: Deepak Kodihalli <dkodihal@linux.vnet.ibm.com> `dkodihal`
Created: 2019-01-22
@@ -40,7 +40,7 @@
associated IDs and states specs), BIOS, FRU, Platform monitoring and control,
Firmware Update and SMBIOS. All these specifications are available at:
-https://www.dmtf.org/standards/pmci
+<https://www.dmtf.org/standards/pmci>
Some of the reasons PLDM sounds promising (some of these are advantages over
IPMI):
@@ -223,7 +223,7 @@
a) With blocking API
-```
+```text
+---------------+ +----------------+ +----------------+ +-----------------+
|BMC requester/ | |PLDM requester | |PLDM responder | |PLDM Daemon |
|client app | |lib (part of | | | | |
@@ -277,7 +277,7 @@
b) With non-blocking API
-```
+```text
+---------------+ +----------------+ +----------------+ +---------------+
|BMC requester/ | |PLDM requester | |PLDM responder | |PLDM daemon |
|client app | |lib (part of | | | | |
@@ -335,7 +335,7 @@
a) Define D-Bus interfaces to send and receive PLDM messages :
-```
+```python
method sendPLDM(uint8 mctp_eid, uint8 msg[])
signal recvPLDM(uint8 mctp_eid, uint8 pldm_instance_id, uint8 msg[])
@@ -376,8 +376,8 @@
by sending it the PLDM GetFRURecordTable command. The pldmd should send this
command if the host indicates support for the PLDM FRU spec. The pldmd
receives a PLDM FRU record table from the host firmware (
- www.dmtf.org/sites/default/files/standards/documents/DSP0257_1.0.0.pdf). The
- daemon parses the FRU record table and hosts the PLDM FRU information on
+ <https://www.dmtf.org/sites/default/files/standards/documents/DSP0257_1.0.0.pdf>).
+ The daemon parses the FRU record table and hosts the PLDM FRU information on
D-Bus.
- Pldmd will also host the FRU inventory D-Bus from the xyz.openbmc_project.
@@ -517,7 +517,7 @@
After doing the discovery of PLDM sensors, `pldmd` should initialize all found
sensors by necessary commands (e.g., `SetNumericSensorEnable`,
-`SetSensorThresholds`, `SetSensorHysteresis and `InitNumericSensor`) and then
+`SetSensorThresholds`, `SetSensorHysteresis` and `InitNumericSensor`) and then
start to update the sensor status to D-bus objects by polling or async event
method depending on the capability of PLDM terminus.
diff --git a/designs/power-recovery.md b/designs/power-recovery.md
index 3465b0d..4154dbe 100644
--- a/designs/power-recovery.md
+++ b/designs/power-recovery.md
@@ -288,7 +288,7 @@
The control of this policy can already bet set via the Redfish API.
-```
+```bash
# Power Restore Policy
curl -k -H "Content-Type: application/json" -X PATCH -d '{"PowerRestorePolicy":"AlwaysOn"}' https://${bmc}/redfish/v1/Systems/system
curl -k -H "Content-Type: application/json" -X PATCH -d '{"PowerRestorePolicy":"AlwaysOff"}' https://${bmc}/redfish/v1/Systems/system
diff --git a/designs/power-systems-memory-preserving-reboot.md b/designs/power-systems-memory-preserving-reboot.md
index 9834671..cc86179 100644
--- a/designs/power-systems-memory-preserving-reboot.md
+++ b/designs/power-systems-memory-preserving-reboot.md
@@ -1,4 +1,4 @@
-# Memory preserving reboot and System Dump extraction flow on POWER Systems.
+# Memory preserving reboot and System Dump extraction flow on POWER Systems
Author: Dhruvaraj S <dhruvaraj@in.ibm.com>
@@ -131,7 +131,7 @@
systems, an additional s0 interrupt will be sent to SBE to stop the cores
immediately.
-#### 2 - Analyze the error data.
+#### 2 - Analyze the error data
The attention listener on the BMC calls a chip-op to analyze the reason for the
attention.
@@ -192,12 +192,12 @@
Hypervisor sends down offload complete message to BMC and BMC sends it to HMC.
The NBD endpoints are cleared.
-#### 12 - HMC verifies dump and send dump DELETE to BMC.
+#### 12 - HMC verifies dump and send dump DELETE to BMC
HMC verifies the dump and send dump delete request to BMC BMC sends the dump
delete message to hypervisor Hypervisor deletes dump in host memory.
-### Memory preserve reboot sequence.
+### Memory preserve reboot sequence
diff --git a/designs/psu-firmware-update.md b/designs/psu-firmware-update.md
index 9c43313..d4344db 100644
--- a/designs/psu-firmware-update.md
+++ b/designs/psu-firmware-update.md
@@ -1,8 +1,11 @@
# PSU firmware update
-Author: Lei YU <mine260309@gmail.com> <LeiYU>
+Author: Lei YU <mine260309@gmail.com> `LeiYU`
-Other contributors: Su Xiao <suxiao@inspur.com> Derek Howard <derekh@us.ibm.com>
+Other contributors:
+
+- Su Xiao <suxiao@inspur.com>
+- Derek Howard <derekh@us.ibm.com>
Created: 2019-06-03
diff --git a/designs/redfish-authorization.md b/designs/redfish-authorization.md
index 5f9e4db..21f97c1 100644
--- a/designs/redfish-authorization.md
+++ b/designs/redfish-authorization.md
@@ -1,6 +1,6 @@
# Dynamic Redfish Authorization
-Author: Nan Zhou (nanzhoumails@gmail.com)
+Author: Nan Zhou <nanzhoumails@gmail.com>
Created: 08/08/2022
@@ -50,10 +50,10 @@
References:
-1. https://redfish.dmtf.org/schemas/DSP0266_1.15.1.html#privilege-model
-2. https://redfish.dmtf.org/schemas/DSP0266_1.15.1.html#redfish-service-operation-to-privilege-mapping
-3. https://redfish.dmtf.org/schemas/DSP0266_1.15.1.html#roles
-4. https://redfish.dmtf.org/registries/v1/Redfish_1.3.0_PrivilegeRegistry.json
+1. <https://redfish.dmtf.org/schemas/DSP0266_1.15.1.html#privilege-model>
+2. <https://redfish.dmtf.org/schemas/DSP0266_1.15.1.html#redfish-service-operation-to-privilege-mapping>
+3. <https://redfish.dmtf.org/schemas/DSP0266_1.15.1.html#roles>
+4. <https://redfish.dmtf.org/registries/v1/Redfish_1.3.0_PrivilegeRegistry.json>
### Phosphor-user-manager
@@ -71,11 +71,11 @@
References:
-1. https://github.com/openbmc/docs/blob/master/architecture/user-management.md
-2. https://github.com/openbmc/phosphor-user-manager
-3. https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/User
-4. https://linux.die.net/man/8/nslcd
-5. https://linux.die.net/man/8/nscd
+1. <https://github.com/openbmc/docs/blob/master/architecture/user-management.md>
+2. <https://github.com/openbmc/phosphor-user-manager>
+3. <https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/User>
+4. <https://linux.die.net/man/8/nslcd>
+5. <https://linux.die.net/man/8/nscd>
### BMCWeb
@@ -121,9 +121,9 @@
References:
-1. https://github.com/openbmc/bmcweb/blob/d9f6c621036162e9071ce3c3a333b4544c6db870/include/authentication.hpp
-2. https://github.com/openbmc/bmcweb/blob/d9f6c621036162e9071ce3c3a333b4544c6db870/http/http_connection.hpp
-3. https://github.com/openbmc/bmcweb/blob/d9f6c621036162e9071ce3c3a333b4544c6db870/redfish-core/lib/roles.hpp
+1. <https://github.com/openbmc/bmcweb/blob/d9f6c621036162e9071ce3c3a333b4544c6db870/include/authentication.hpp>
+2. <https://github.com/openbmc/bmcweb/blob/d9f6c621036162e9071ce3c3a333b4544c6db870/http/http_connection.hpp>
+3. <https://github.com/openbmc/bmcweb/blob/d9f6c621036162e9071ce3c3a333b4544c6db870/redfish-core/lib/roles.hpp>
### Gaps
@@ -256,7 +256,7 @@
The following diagram shows how assigned privileges of a power control service
with identity (username in PAM, or CN/SAN in TLS) "power-service" is resolved.
-```
+```ascii
+-----------------+
| power service |
| |
@@ -360,7 +360,7 @@
Redfish role which is assigned a new set of OEM Redfish Privileges is mapped out
below.
-```
+```ascii
Root User BMCWeb Phosphor-User-Manager Linux
| PATCH PrivilegeRegistry | | |
|-------------------------->| DBus: createGroup | |
@@ -475,7 +475,7 @@
A example execution flow for a read operation is mapped out below.
-```
+```ascii
+---------------+
| BMCWeb | Get
| routing | /redfish/v1/Managers/${ManagerId}/EthernetInterfaces/
@@ -538,7 +538,7 @@
Entity EthernetInterface so that users with "OemEthernetManager" can also send
GET to EthernetInterface.
-```
+```json
{
Entity": "EthernetInterface",
"OperationMap": {
diff --git a/designs/redfish-eventservice.md b/designs/redfish-eventservice.md
index f29f311..b54c544 100644
--- a/designs/redfish-eventservice.md
+++ b/designs/redfish-eventservice.md
@@ -109,9 +109,7 @@
- Server Sent-Events (Section 12.5)
- Security (Section 12 & 13.2.8)
-**BLOCK DIAGRAM**
-
-```
+```text
+------------------------------------------------------------------------------------+
| CLIENT |
| EVENT LISTENER |
@@ -161,7 +159,7 @@
Push style events(HTTPS) flow diagram:
-```
+```text
+-------------+ +------------+ +-------------------------------------+ +-----------------+
| | | CLIENT | | BMCWEB | | EVENT LOG/ |
| CLIENT | | LISTENERS | |RESOURCE SENDER FORMATTER MONITOR | |TELEMETRY SERVICE|
@@ -301,7 +299,7 @@
SSE flow diagram:
-```
+```text
+-------------+ +------------+ +-------------------------------------+ +-----------------+
| | | CLIENT | | BMCWEB | | EVENT LOG/ |
| CLIENT | | LISTENERS | |RESOURCE SENDER FORMATTER MONITOR | |TELEMETRY SERVICE|
@@ -465,44 +463,40 @@
This document doesn't cover below component design.
-1. Redfish Event Logs: This is existing implementation. In OpenBMC, All events
- will be logged to Journal control logs and RSyslog service, monitors event
- logs associated with "REDFISH_MESSAGE_ID" and write the required information
- to "/var/log/redfish" for persisting the event logs.
+1. Redfish Event Logs: This is existing implementation. In OpenBMC, All events
+ will be logged to Journal control logs and RSyslog service, monitors event
+ logs associated with "REDFISH_MESSAGE_ID" and write the required information
+ to "/var/log/redfish" for persisting the event logs.
- So EventService design is hooked to Redfish Event Logs majorly for below
- two reasons.
+ So EventService design is hooked to Redfish Event Logs majorly for below two
+ reasons.
- - Get the notification whenever new event is logged to Redfish event
- Logs.
- - Way to read the Redfish event log information.
+ - Get the notification whenever new event is logged to Redfish event Logs.
+ - Way to read the Redfish event log information.
- This document covers one example Redfish Event Log implementation covered
- under below design. As part of it, it uses inotify for getting
- notification about new event log and read the log information by accessing
- the redfish event log file.
+ This document covers one example Redfish Event Log implementation covered
+ under below design. As part of it, it uses inotify for getting notification
+ about new event log and read the log information by accessing the redfish
+ event log file.
- Refer below link for more information on same.
+ Refer below link for more information on same.
+ [Redfish Logging](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md)
- [link](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md)
+ If other OEM's has different implementation for Redfish EventLogs, they can
+ satisfy above mentioned two requirement and can hook it to EventService
+ design specified here. For example, If xyz OEM uses D-Bus based Redfish Event
+ logs, They can use 'signal' for notifying the new redfish event log and event
+ log information. They can replace 'inotify' with 'signal' and hook their OEM
+ specific Redfish event log to this Redfish EventService design.
- If other OEM's has different implementation for Redfish EventLogs, they
- can satisfy above mentioned two requirement and can hook it to
- EventService design specified here.
- For example, If xyz OEM uses D-Bus based Redfish Event logs, They can
- use 'signal' for notifying the new redfish event log and event log
- information. They can replace 'inotify' with 'signal' and hook their
- OEM specific Redfish event log to this Redfish EventService design.
+2. Telemetry service: Redfish telemetry service is used to gather all the
+ metrics reports associated with different resources such as Power metrics,
+ thermal metrics, memory metrics, processor metrics etc... Monitoring service
+ in telemetry supports different modes along with aggregated
+ operations(Single, average, max, min, sum etc..).
-2. Telemetry service: Redfish telemetry service is used to gather all the
- metrics reports associated with different resources such as Power metrics,
- thermal metrics, memory metrics, processor metrics etc... Monitoring service
- in telemetry supports different modes along with aggregated
- operations(Single, average, max, min, sum etc..).
-
- Refer below link for design document of telemetry service.
-
- [link](https://gerrit.openbmc.org/#/c/openbmc/docs/+/24357/)
+ Refer below link for design document of telemetry service.
+ [Telemetry Service](https://gerrit.openbmc.org/#/c/openbmc/docs/+/24357/)
### Redfish resource schema's
@@ -516,10 +510,8 @@
bmcweb webserver and synced with config json file for restoring and persisting
the data.
-**EventService**
-
-Contains the attributes of the service such as Service Enabled, status, delivery
-retry attempts, Event Types, Subscriptions, Actions URI etc.
+**EventService** Contains the attributes of the service such as Service Enabled,
+status, delivery retry attempts, Event Types, Subscriptions, Actions URI etc.
- URI : `/redfish/v1/EventService`
- SCHEMA :
@@ -567,7 +559,7 @@
The "Event service sender" is common entity for both type of resources. The
formatter and monitor entities are different for each type of resources.
-**Event log monitor**
+#### Event log monitor
In OpenBMC, all the redfish event logs are currently logged to persistent area
of BMC filesystem("/var/log/redfish"). The "Event log monitor" service under
@@ -580,7 +572,7 @@
It monitors the live events for sending asynchronously and does not send the
events logged before bmcweb service start.
-**Event log formatter**
+#### Event log formatter
It is used to format the request body by reading event logs passed from 'Event
log monitor' and filter the data by reading subscription information. It will
@@ -592,7 +584,7 @@
Refer Tested section for example request body.
-**MetricReport monitor**
+#### MetricReport monitor
Telemetry monitoring service ( Not covered in this document) is responsible for
gathering metrics from D-Bus sensors and exposing them as D-Bus objects.
@@ -612,13 +604,13 @@
to communicate the subscriptions data whenever user creates or updates or delete
subscription.
-**MetricReport formatter**
+#### MetricReport formatter
The 'MetricReport formatter' is responsible for formatting the data which comes
from 'MetricReport monitor/agent' by checking subscriptions information such as
HttpHeaders, Custom text strings along with Telemetry report data.
-**Event service sender**
+#### Event service sender
The "Event service sender" is used to send the formatted request body which is
passed from 'Event log formatter' or 'Telemetry formatter' to all filtered
@@ -631,14 +623,14 @@
interoperable networking libraries by providing low-level HTTP/1, WebSocket, and
networking protocol vocabulary types and algorithms using the consistent
asynchronous model of Boost.Asio. For more information on beast, refer
-[link](https://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/introduction.html)
+[Beast](https://www.boost.org/doc/libs/develop/libs/beast/doc/html/beast/introduction.html)
1. PUSH style eventing: BMC uses the boost::beast for asynchronously sending
events to the subscribed clients. Here is the Beast client Examples for
sending the synchronous and asynchronous requests over encrypted and
un-encrypted channels.
- [link](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async/)
- [link](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async-ssl/)
+ [Beast Async](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async/)
+ [Beast AsyncSSL](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async-ssl/)
2. Server-Sent Events (SSE): The EventDestination resource of the subscription
data shall contains the opaque of opened client SSE stream connection. After
@@ -734,7 +726,7 @@
- Subscription structure: It holds the data associated with each
EventDestination schema properties along with established connection handle.
-### Server-Sent Events (SSE):
+### Server-Sent Events (SSE)
Server-Sent Events (SSE) is a server push technology enabling a browser to
receive automatic updates from a server via HTTP connection. The Server-Sent
@@ -753,7 +745,7 @@
until the client closes the socket. The bmcweb service should sent the response
to GET URI with following headers.
-```
+```text
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
'Connection': 'keep-alive'
@@ -764,7 +756,7 @@
postfix "\n" on each line. For representing the end of data, it should end with
"\n\n". Example sending json response should look like
-```
+```text
data: {\n
data: "msg": "hello world",\n
data: "id": 12345\n
@@ -776,9 +768,9 @@
collection. Once bmcweb receives the SSE stream request, the open connection
will be upgraded to WebSocket by checking the request Content-Type
header(matches to 'text/event-stream') and keep the connection alive till the
-client/server closes the connection. Please refer
-[link](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/13948/) for details on
-how to upgrade the connection for SSE. The "Context" property in the
+client/server closes the connection. Please refer to
+[code review](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/13948/) for
+details on how to upgrade the connection for SSE. The "Context" property in the
EventDestination resource shall be an opaque string generated by the service.
Note: since its GET operation on existing open connection(which is authenticated
@@ -824,10 +816,10 @@
Example for subscribing SSE with filters:
-```
+```text
MessageId based filter:
METHOD: GET
-URi: https://<BMCIP>/redfish/v1/EventService/SSE?MessageId='Alert.1.0.LanDisconnect'
+URI: https://<BMCIP>/redfish/v1/EventService/SSE?MessageId='Alert.1.0.LanDisconnect'
RegistryPrefix based filter:
https://sseuri?$filter=(RegistryPrefix eq Resource) or (RegistryPrefix eq
@@ -862,7 +854,7 @@
threshold limit. If SSL negotiation fails, it will not retry for connection
establishment. Users can upload new certificates. More details about certificate
can be found at
-[link](https://github.com/openbmc/docs/blob/master/designs/redfish-tls-user-authentication.md)
+[TLS design](https://github.com/openbmc/docs/blob/master/designs/redfish-tls-user-authentication.md)
Example for created Push style event is documented in testing section of same
document.
@@ -883,19 +875,19 @@
Example POST Request body:
-```
+```json
{
"Message": "Test Event for validation",
"MessageArgs": [],
"EventId": "OpenBMC.0.1.TestEvent",
- "EventGroupId" : "",
+ "EventGroupId": "",
"Severity": "OK"
}
```
## Alternatives considered
-**HTTP POLLING**
+### HTTP POLLING
Polling is a traditional technique where client repeatedly polls a server for
data. The client makes a request and waits for the server to respond with data.
@@ -908,7 +900,7 @@
polling and send the data/events when it happens on server side to the
subscribed clients.
-**WEBSOCKET**
+### WEBSOCKET
WebSocket provides a richer protocol to perform bi-directional, full-duplex
communication. Having a two-way channel is more attractive for some case but in
@@ -920,7 +912,7 @@
WebSocket on the other hand, require full-duplex connections and new Web Socket
servers to handle the protocol.
-**IPMI PEF**
+### IPMI PEF
Platform Event Filtering (PEF) provides a mechanism for configuring the BMC to
take selected actions on event messages that it receives. This mechanism is IPMI
@@ -931,7 +923,7 @@
- Direct journal logs vs Redfish event log file using inotify
-Considered reading direct journald logs using sd*journal*<xyz> api's but that
+Considered reading direct journald logs using `sd*journal*<xyz>` api's but that
seems to be in-efficient because
1. sdjournal has multiple logs currently( not just event logs) and so this
@@ -1025,120 +1017,120 @@
should not create any subscription or open any http connection.
- Max limit check: Creates max supported event subscriptions and validate.
-** Push style events: **
+### Push style events
1. EventListner: Client should configure the web service for listening the
- events (Example: http://192.168.1.2/Events).
+ events (Example: `http://192.168.1.2/Events`).
2. Subscription: Client can subscribe for events on BMC using below
-```
-URI: /redfish/v1/EventService/Subscriptions
-METHOD: POST
-REQUEST BODY:
-{
- "Destination":"http://192.168.1.2/Events",
- "Context":"CustomText",
- "Protocol":"Redfish",
-}
-```
+ ```text
+ URI: /redfish/v1/EventService/Subscriptions
+ METHOD: POST
+ REQUEST BODY:
+ {
+ "Destination":"http://192.168.1.2/Events",
+ "Context":"CustomText",
+ "Protocol":"Redfish",
+ }
+ ```
- On successful event subscription client will receive 201(Created) http
- status code along with created subscription ID. At this point onwards,
- client will receive events associated with subscribed data.
+ On successful event subscription client will receive 201(Created) http status
+ code along with created subscription ID. At this point onwards, client will
+ receive events associated with subscribed data.
- Client can use "SubmitTestEvent" (Documented above) to test the working
- state.
+ Client can use "SubmitTestEvent" (Documented above) to test the working
+ state.
3. ViewSubscription: Client can get the subscriptions details using
-```
-URI: /redfish/v1/EventService/Subscriptions/<ID>
-METHOD: GET
-```
+ ```text
+ URI: /redfish/v1/EventService/Subscriptions/<ID>
+ METHOD: GET
+ ```
4. UpdateSubscription: At any point client can update the subscription
information.
-```
-URI: /redfish/v1/EventService/Subscriptions/<ID>
-METHOD: PATCH
-REQUEST BODY:
-{
- "Destination":"http://192.168.1.2/Events",
- "Context":"Changed Custom Text",
- "RegistryPrefix": "OpenBMC.0.2"
-}
-```
+ ```text
+ URI: /redfish/v1/EventService/Subscriptions/<ID>
+ METHOD: PATCH
+ REQUEST BODY:
+ {
+ "Destination":"http://192.168.1.2/Events",
+ "Context":"Changed Custom Text",
+ "RegistryPrefix": "OpenBMC.0.2"
+ }
+ ```
5. DeleteSubscription: Client can unsubscribe and stop receiving events by
deleting the subscription.
-```
-URI: /redfish/v1/EventService/Subscriptions/<ID>
-METHOD: DELETE
-```
+ ```text
+ URI: /redfish/v1/EventService/Subscriptions/<ID>
+ METHOD: DELETE
+ ```
-** Server-Sent events subscription: **
+### Server-Sent events subscription
1. EventListner and Subscription: Client can open latest browser (chrome) and
fire GET URI on "ServerSentEventUri" along with filters.
-```
-URI: /redfish/v1/EventService/SSE?RegistryPrefix='OpenBMC.0.2'&MessageId='OpenBMC.0.2.xyz"
-METHOD: GET
-```
+ ```text
+ URI: /redfish/v1/EventService/SSE?RegistryPrefix='OpenBMC.0.2'&MessageId='OpenBMC.0.2.xyz"
+ METHOD: GET
+ ```
- On successful event subscription client will receive 200(Created) http
- status code, subscription id along with below response headers for
- streaming.
+ On successful event subscription client will receive 200(Created) http status
+ code, subscription id along with below response headers for streaming.
-```
-'Content-Type': 'text/event-stream',
-'Cache-Control': 'no-cache',
-'Connection': 'keep-alive'
-```
+ ```text
+ 'Content-Type': 'text/event-stream',
+ 'Cache-Control': 'no-cache',
+ 'Connection': 'keep-alive'
+ ```
- At this point onwards, client browser will receive events associated with
- subscribed data.
+ At this point onwards, client browser will receive events associated with
+ subscribed data.
- Client can use "SubmitTestEvent" (Documented above) to test the working
- state.
+ Client can use "SubmitTestEvent" (Documented above) to test the working
+ state.
2. ViewSubscription: Client can get the subscriptions details using
-```
-URI: /redfish/v1/EventService/Subscriptions/<ID>
-METHOD: GET
-```
+ ```text
+ URI: /redfish/v1/EventService/Subscriptions/<ID>
+ METHOD: GET
+ ```
3. UpdateSubscription: At any point client can update the subscription
information. Note Client can't change the destination as that is opaque
associated with opened SSE connection.
-```
-URI: /redfish/v1/EventService/Subscriptions/<ID>
-METHOD: PATCH
-REQUEST BODY:
-{
- "Context":"Changed Custom Text",
- "RegistryPrefix": "OpenBMC.0.2"
-}
-```
+ ```text
+ URI: /redfish/v1/EventService/Subscriptions/<ID>
+ METHOD: PATCH
+ REQUEST BODY:
+ {
+ "Context":"Changed Custom Text",
+ "RegistryPrefix": "OpenBMC.0.2"
+ }
+ ```
4. DeleteSubscription: There are two ways to close the connection from client.
+
- Client can close the browser directly which will close the SSE http
connection and so bmcweb service can close and delete the subscription
data.
- Client can also unsubscribe and stop receiving events by deleting the
subscription.
-```
-URI: /redfish/v1/EventService/Subscriptions/<ID>
-METHOD: DELETE
-```
+ ```text
+ URI: /redfish/v1/EventService/Subscriptions/<ID>
+ METHOD: DELETE
+ ```
-** EventListner **
+### EventListner
Push style Events:
@@ -1149,22 +1141,26 @@
There are multiple EventListners exist and here is simple node js server, which
can be run using "node server.js".
-```
+```js
// server.js
const http = require("http");
var displayResponse;
-http.createServer((request, response) => {
+http
+ .createServer((request, response) => {
console.log("Requested url: " + request.url);
const { headers, method, url } = request;
- if ((method.toLowerCase() == "post") && (url.toLowerCase() === "/events")) {
- let body = [];
- request.on('error', (err) => {
+ if (method.toLowerCase() == "post" && url.toLowerCase() === "/events") {
+ let body = [];
+ request
+ .on("error", (err) => {
console.error(err);
- }).on('data', (chunk) => {
+ })
+ .on("data", (chunk) => {
body.push(chunk);
- }).on('end', () => {
+ })
+ .on("end", () => {
body = Buffer.concat(body).toString();
console.log(body);
@@ -1173,13 +1169,16 @@
response.statusCode = 200;
response.end();
- })
- } else if ((method.toLowerCase() == "get") && (url.toLowerCase() === "/display_events")) {
+ });
+ } else if (
+ method.toLowerCase() == "get" &&
+ url.toLowerCase() === "/display_events"
+ ) {
response.writeHead(200, {
Connection: "keep-alive",
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache",
- "Access-Control-Allow-Origin": "*"
+ "Access-Control-Allow-Origin": "*",
});
displayResponse = response;
@@ -1187,8 +1186,11 @@
response.writeHead(404);
response.end();
}
- }).listen(5000, () => {
- console.log("Use 'http://<IP>:5000/events' as destination to subscribe for BMC events");
+ })
+ .listen(5000, () => {
+ console.log(
+ "Use 'http://<IP>:5000/events' as destination to subscribe for BMC events",
+ );
console.log("Open 'http://<IP>:5000/display_events' URL on browser\n");
});
```
@@ -1202,12 +1204,12 @@
listening events.
You can also refer below link for details on Server-Sent events.
-(https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)
+<https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events>
Another simple python script for testing SSE using EventSource. Run it using
"python sse-client.py".
-```
+```python
// sse-client.py
import requests, json, sys, time, re, os
import sseclient
@@ -1238,28 +1240,28 @@
print("\nERROR: Error in subscribing the SSE events\n")
```
-**EventService**
+#### EventService
Supported properties:
-| PROPERTY NAME | TYPE | DESCRIPTION |
-| ---------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| ServiceEnabled | Boolean | This indicates whether event service is enabled. Default: True |
-| DeliveryRetryAttempts | Integer | This is the number of attempts an event posting is retried before the subscription is terminated. Default: 3 |
-| DeliveryRetryIntervalSeconds | Integer | This represents the number of seconds between retry attempts for sending any given Event. Default: 30 |
-| EventFormatTypes | Array(string) | Indicates the content types of the message that this service can send to the event destination. ** Event: ** Resource types of 'Event' sent to subscribed destination. This is default value if nothing is specified. ** MetricReport: ** Resource types of 'MetricReport' only sent to subscribed destination. |
-| RegistryPrefixes | Array(string) | A list of the Prefixes of the Message Registries that can be used for the RegistryPrefix property on a subscription. If this property is absent or contains an empty array, the service does not support RegistryPrefix-based subscriptions. |
-| ResourceTypes | Array(string) | A list of the Prefixes of the message registries that can be used for the RegistryPrefix property on a subscription. If this property is absent or contains an empty array, the service does not support RegistryPrefix-based subscriptions |
-| ServerSentEventUri | String | The value of this property shall be a URI that specifies an HTML5 Server-Sent Event conformant endpoint. URI: /redfish/v1/EventService/SSE |
-| Subscriptions | Object | The value of this property shall contain the link to a collection of type EventDestinationCollection. |
-| Actions | Object | This action shall add a test event to the event service with the event data specified in the action parameters. More details on TestEvents captured below. |
+| PROPERTY NAME | TYPE | DESCRIPTION |
+| ---------------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ServiceEnabled | Boolean | This indicates whether event service is enabled. Default: True |
+| DeliveryRetryAttempts | Integer | This is the number of attempts an event posting is retried before the subscription is terminated. Default: 3 |
+| DeliveryRetryIntervalSeconds | Integer | This represents the number of seconds between retry attempts for sending any given Event. Default: 30 |
+| EventFormatTypes | Array(string) | Indicates the content types of the message that this service can send to the event destination. **Event:** Resource types of 'Event' sent to subscribed destination. This is default value if nothing is specified. **MetricReport:** Resource types of 'MetricReport' only sent to subscribed destination. |
+| RegistryPrefixes | Array(string) | A list of the Prefixes of the Message Registries that can be used for the RegistryPrefix property on a subscription. If this property is absent or contains an empty array, the service does not support RegistryPrefix-based subscriptions. |
+| ResourceTypes | Array(string) | A list of the Prefixes of the message registries that can be used for the RegistryPrefix property on a subscription. If this property is absent or contains an empty array, the service does not support RegistryPrefix-based subscriptions |
+| ServerSentEventUri | String | The value of this property shall be a URI that specifies an HTML5 Server-Sent Event conformant endpoint. URI: /redfish/v1/EventService/SSE |
+| Subscriptions | Object | The value of this property shall contain the link to a collection of type EventDestinationCollection. |
+| Actions | Object | This action shall add a test event to the event service with the event data specified in the action parameters. More details on TestEvents captured below. |
Note: EventService.v1_3_0 was created to deprecate the EventTypesForSubscription
and SSEFilterPropertiesSupported\EventType properties.
Example GET Response:
-```
+```json
{
"@odata.context": "/redfish/v1/$metadata#EventService.EventService",
"@odata.id": "/redfish/v1/EventService",
@@ -1271,15 +1273,10 @@
},
"DeliveryRetryAttempts": 3,
"DeliveryRetryIntervalSeconds": 30,
- "EventFormatTypes": [
- "Event"
- ],
+ "EventFormatTypes": ["Event"],
"Id": "EventService",
"Name": "Event Service",
- "RegistryPrefixes": [
- "Base",
- "OpenBMC"
- ],
+ "RegistryPrefixes": ["Base", "OpenBMC"],
"ServerSentEventUri": "/redfish/v1/EventService/SSE",
"ServiceEnabled": true,
"Subscriptions": {
@@ -1288,11 +1285,11 @@
}
```
-**Subscription Collections**
+#### Subscription Collections
Example GET output:
-```
+```json
{
"@odata.type":"#EventDestinationCollection.EventDestinationCollection",
"@odata.context":"/redfish/v1/$metadata#EventDestinationCollection.EventDestinationCollection",
@@ -1309,7 +1306,7 @@
}
```
-**Subscriptions**
+#### Subscriptions
Supported properties:
@@ -1325,37 +1322,27 @@
Example GET Request:
-```
+```json
{
"@odata.context": "/redfish/v1/$metadata#EventDestination.EventDestination",
"@odata.id": "/redfish/v1/EventService/Subscriptions/1",
"@odata.type": "#EventDestination.v1_5_0.EventDestination",
"Context": "143TestString",
"Destination": "http://test3.domain.com/EventListener",
- "EventFormatTypes": [
- "Event"
- ],
- "HttpHeaders": [
- "X-Auth-Token:XYZABCDEDF"
- ],
+ "EventFormatTypes": ["Event"],
+ "HttpHeaders": ["X-Auth-Token:XYZABCDEDF"],
"Id": "1",
- "MessageIds": [
- "InventoryAdded",
- "InventoryRemoved"
- ],
+ "MessageIds": ["InventoryAdded", "InventoryRemoved"],
"Name": "EventSubscription 1",
"Protocol": "Redfish",
- "RegistryPrefixes": [
- "Base",
- "OpenBMC"
- ],
+ "RegistryPrefixes": ["Base", "OpenBMC"],
"SubscriptionType": "Event"
}
```
- Event log formatted response body looks like:
-```
+```text
id: 1
data:{
data: "@odata.type": "#Event.v1_1_0.Event",
@@ -1384,7 +1371,7 @@
- Configuration structure pseudo code:
-```
+```cpp
struct EventSrvConfig
{
bool enabled;
@@ -1395,7 +1382,7 @@
- Subscription structure pseudo code:
-```
+```cpp
struct EventSrvSubscription
{
std::string destinationUri;
diff --git a/designs/redfish-pcie.md b/designs/redfish-pcie.md
index 9555d26..e714ac4 100644
--- a/designs/redfish-pcie.md
+++ b/designs/redfish-pcie.md
@@ -36,7 +36,7 @@
the Redfish PCIe resources.
The proposed D-Bus interface can be found here:
-https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/19768
+<https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/19768>
The proposed producer will be a new D-Bus daemon that will be responsible for
gathering and caching PCIe hardware data and maintaining the D-Bus interfaces
diff --git a/designs/redfish-postcodes.md b/designs/redfish-postcodes.md
index 0e4e329..6305ae4 100644
--- a/designs/redfish-postcodes.md
+++ b/designs/redfish-postcodes.md
@@ -20,7 +20,7 @@
Sample [LogService](https://redfish.dmtf.org/schemas/LogService_v1.xml) entry:
-```
+```json
https://obmc/redfish/v1/Systems/system/LogServices/PostCodes
{
"@odata.context": "/redfish/v1/$metadata#LogService.LogService",
@@ -44,7 +44,7 @@
Events will be exposed using the
[LogEntry](https://redfish.dmtf.org/schemas/LogEntry_v1.xml) schema.
-```
+```json
https://obmc/redfish/v1/Systems/system/LogServices/PostCodes/Entries
{
"@odata.context": "/redfish/v1/$metadata#LogEntryCollection.LogEntryCollection",
@@ -79,7 +79,7 @@
A new [MessageRegistry](https://redfish.dmtf.org/schemas/MessageRegistry_v1.xml)
schema entry defines the format for the message.
-```
+```json
https://obmc/redfish/v1/Registries/OpenBMC/OpenBMC
{
"@Redfish.Copyright": "Copyright 2018 OpenBMC. All rights reserved.",
@@ -123,7 +123,7 @@
xyz.openbmc_project.State.Boot.PostCode service. The existing interface tracks
POST codes for the past 100 host boot events and the current boot cycle index.
-```
+```json
xyz.openbmc_project.State.Boot.PostCode
GetPostCodes(q undefined) → [uint64] undefined
CurrentBootCycleIndex = 1
@@ -133,23 +133,12 @@
The GetPostCodes method is called using the boot cycle index to retrieve the
codes for the boot cycle.
-```
+```json
{
"call": "GetPostCodes",
"interface": "xyz.openbmc_project.State.Boot.PostCode",
"obj": "/xyz/openbmc_project/State/Boot/PostCode",
- "result": [
- 1,
- 2,
- 3,
- 4,
- 5,
- 6,
- 17,
- 50,
- 4,
- 173
- ],
+ "result": [1, 2, 3, 4, 5, 6, 17, 50, 4, 173],
"status": "ok"
}
```
@@ -158,7 +147,7 @@
new method GetPostCodesTS will be added to include an ISO formatted time stamp
with micro-second resolution along with each POST code.
-```
+```json
{
"call": "GetPostCodesTS",
"interface": "xyz.openbmc_project.State.Boot.PostCode",
@@ -182,7 +171,7 @@
The DBus DeleteAll interface will be implemented to remove entries. The Redfish
ClearLog action will call the DBus DeleteAll interface.
-```
+```json
{
"call": "DeleteAll",
"interface": "xyz.openbmc_project.Collection.DeleteAll",
diff --git a/designs/redfish-resource-supplement-for-pfr.md b/designs/redfish-resource-supplement-for-pfr.md
index c6c7daf..11068e4 100644
--- a/designs/redfish-resource-supplement-for-pfr.md
+++ b/designs/redfish-resource-supplement-for-pfr.md
@@ -85,13 +85,13 @@
it can not be re-provisioned.
New OemComputerSystem schema can be found at
-[link](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/24253/)
+[in review](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/24253/).
PFR in OpenBMC must support logging of resiliency error detection and
correction. Below are two metadata entries in redfish message registry for
redfish event logging capability. For more details on how to log redfish events
can be found at document
-[Redfish logging in bmcweb ](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md).
+[Redfish logging in bmcweb](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md).
Below type of events should be logged as part of PFR or provisioning. These
redfish events are created for basic firmware components BIOS, BMC, CPLD and ME
@@ -147,7 +147,7 @@
Event logs associated with BMC component is specified here as example.
-```
+```text
MessageEntry{"BMCFirmwareResiliencyError",
{
"Indicates BMC firmware encountered resilience error",
@@ -199,7 +199,7 @@
Method. Intel uses "Intel PFR" design (via BIOS) to provision and lock the PFR
provisioning status.
-```
+```text
URI: /redfish/v1/Systems/system
METHOD: GET
RESPONSE:
@@ -230,14 +230,14 @@
Few examples to attack Firmware components and validate PFR:
- 1. Corrupt the BMC/BIOS etc... firmware and check Panic events and recovery
- actions events.
+ 1. Corrupt the BMC/BIOS etc... firmware and check Panic events and recovery
+ actions events.
- 2. Induce hardware watchdog trigger using known methods and check. etc..
+ 2. Induce hardware watchdog trigger using known methods and check. etc..
- 3. Corrupt the security key's by directly mocking hardware and validate.
+ 3. Corrupt the security key's by directly mocking hardware and validate.
-```
+```text
URI: /redfish/v1/Systems/system/LogServices/EventLog/Entries
METHOD: GET
```
diff --git a/designs/redfish-spdm-attestation.md b/designs/redfish-spdm-attestation.md
index 3bcb844..6120c0c 100644
--- a/designs/redfish-spdm-attestation.md
+++ b/designs/redfish-spdm-attestation.md
@@ -50,11 +50,11 @@
There are three type of information we will need from an attestation daemon on
D-Bus:
-1. Basic information, like attestation protocol, enablement status, update
- timestamp, etc.
-2. Identity information, e.g., device identity certificates.
-3. Measurements information, e.g., measurements of the component firmware,
- hardware configuration, etc.
+1. Basic information, like attestation protocol, enablement status, update
+ timestamp, etc.
+2. Identity information, e.g., device identity certificates.
+3. Measurements information, e.g., measurements of the component firmware,
+ hardware configuration, etc.
So far, phosphor-dbus-interfaces lacks interfaces defined for attestation
purpose. Thus, we propose three new interfaces:
@@ -145,10 +145,10 @@
path. It is up to the vendor to do the association.
For MCTP devices detection, the community has been working on `mctpreactor`
-daemon in dbus-sensors to handle the configuration. The link to implementation
-is [here](https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/69111), the
-related PR discussion is [here](https://github.com/CodeConstruct/mctp/pull/17).
-SPDM daemon will monitor `mctpd` for `InterfacesAdded` signals providing the
+daemon in dbus-sensors to handle the configuration. The proposed
+[implementation](https://gerrit.openbmc.org/c/openbmc/dbus-sensors/+/69111); the
+related [PR discussion](https://github.com/CodeConstruct/mctp/pull/17). SPDM
+daemon will monitor `mctpd` for `InterfacesAdded` signals providing the
`xyz.openbmc_project.MCTP.Endpoint` interface, which exposes the message types
supported by the endpoint in the `SupportedMessageTypes` member. SPDM daemon set
up a connection with the SPDM-capable endpoints to get certificates and
@@ -158,7 +158,7 @@
Below is a high-level diagram showing the relationship between different
components.
-```
+```ascii
+------+ +---------+
|Client| |Inventory|
+--+---+ |Manager |
@@ -292,8 +292,8 @@
addition, the following repositories are expected to be modified to execute this
design:
-- https://github.com/openbmc/bmcweb
-- https://github.com/openbmc/phosphor-dbus-interfaces
+- <https://github.com/openbmc/bmcweb>
+- <https://github.com/openbmc/phosphor-dbus-interfaces>
## Testing
diff --git a/designs/redfish-tls-user-authentication.md b/designs/redfish-tls-user-authentication.md
index dfde1d6..a794786 100644
--- a/designs/redfish-tls-user-authentication.md
+++ b/designs/redfish-tls-user-authentication.md
@@ -50,7 +50,7 @@
proper `user`'s certificate from `CA`. After this certificate is acquired,
`User` can use this certificate when initializing HTTPS sessions.
-```
+```text
┌──┐ ┌────┐ ┌───────┐
│CA│ │User│ │Redfish│
└┬─┘ └─┬──┘ └───┬───┘
@@ -135,7 +135,7 @@
#### Authentication Process
-```
+```text
+-+
+++
|
@@ -199,8 +199,8 @@
```
Certificate based authentication has the highest priority, because of the design
-of _Boost.Beast/Boost.ASIO/OpenSSL_ as the certificate verification is being
-done at the very beginning of HTTPS request processing. _OpenSSL_ library is
+of `Boost.Beast/Boost.ASIO/OpenSSL` as the certificate verification is being
+done at the very beginning of HTTPS request processing. `OpenSSL` library is
responsible for determining whether certificate is valid or not. For certificate
to be marked as valid, it (and every certificate in chain) has to meet these
conditions:
@@ -216,9 +216,9 @@
- certificate cannot be self-signed
- issuer name has to match CA's subject name
-After these checks a callback is invoked providing result of user<->CA matching
-status. There, in case of success Redfish extracts username from `CommonName`
-and verifies if user does exist in the system.
+After these checks a callback is invoked providing result of `user<->CA`
+matching status. There, in case of success Redfish extracts username from
+`CommonName` and verifies if user does exist in the system.
As can be seen on the flow diagram, Redfish will use **the first valid**
credentials according to processing sequence. It is recommended for user to use
@@ -268,8 +268,8 @@
As for TLS auth itself:
-1. Flow described in [Process overview](###process-overview) should be tested,
- to confirm that after going through it, everything works as expected.
+1. Flow described in [Process overview](#process-overview) should be tested, to
+ confirm that after going through it, everything works as expected.
2. Validity period tests - to confirm that certificates that are not-yet-valid
and expired ones are not accepted, by both - changing validity periods in
certificates themselves, as well as modifying time on BMC itself
diff --git a/designs/remote-bios-configuration.md b/designs/remote-bios-configuration.md
index 77bab9f..f814590 100644
--- a/designs/remote-bios-configuration.md
+++ b/designs/remote-bios-configuration.md
@@ -18,10 +18,9 @@
## Background and References
-[1]
-https://www.dmtf.org/sites/default/files/standards/documents/DSP0247_1.0.0.pdf
-[2] https://redfish.dmtf.org/schemas/v1/Bios.v1_1_0.json [3]
-https://redfish.dmtf.org/schemas/v1/AttributeRegistry.v1_3_2.json
+1. <https://www.dmtf.org/sites/default/files/standards/documents/DSP0247_1.0.0.pdf>
+2. <https://redfish.dmtf.org/schemas/v1/Bios.v1_1_0.json>
+3. <https://redfish.dmtf.org/schemas/v1/AttributeRegistry.v1_3_2.json>
## Requirements
@@ -48,7 +47,7 @@
## Proposed Design
-```
+```text
+----------------------------------------------------------------------------------------------------------------+
| Remote BIOS configuration (RBC) via BMC |
| |
@@ -84,7 +83,7 @@
+----------------------------------------------------------------------------------------------------------------+
```
-##Intel uses the following logic
+## Intel uses the following logic
BIOS send data in as Proprietary format to the BMC via IPMI interface. There are
two types of proprietary XML format files in BIOS configuration. Type-0 contain
@@ -115,7 +114,7 @@
non-volatile storage. Pending attributes list will be cleared whenever new
attributes data received.
-```
+```text
#Intel uses the following logic for BIOS first boot
+---------------------------------------------------------------------------------------------------------------------+
| |
@@ -152,7 +151,7 @@
+---------------------------------------+-----------------------------------------------------------------------------+
```
-```
+```text
#Intel uses the following logic for BIOS reset
+---------------------------------------------------------------------------------------------------------------------+
| |
@@ -189,7 +188,7 @@
+---------------------------------------+-----------------------------------------------------------------------------+
```
-```
+```text
#Intel uses the following logic for BIOS reset and BMC have new values
+---------------------------------------------------------------------------------------------------------------------+
| |
@@ -234,7 +233,7 @@
```
-##BIOS send the data in BIOS configuration PLDM via MCTP
+## BIOS send the data in BIOS configuration PLDM via MCTP
BIOS should update the BIOS settings via Set BIOS table PLDM command- BIOS
string table, Attribute name table, Attribute value table via MCTP.
@@ -253,9 +252,9 @@
non-volatile storage. PLDM daemon should preserve BIOS tables in non-volatile
storage. RBC and PLDM should restored the data whenever BMC reset.
-#BIOS first boot
+## BIOS first boot
-```
+```text
+--------------------------------------------------------------------------------------------------------------------+
| +-----------------------+ +---------------------------------------------------------------------------+|
@@ -322,9 +321,9 @@
```
-##Complete BIOS BMC flow for BIOS configuration in deferred update model
+## Complete BIOS BMC flow for BIOS configuration in deferred update model
-```
+```text
+----------------------------------------+ +----------------------------------------+
| BIOS | | BMC |
| | | |
@@ -368,9 +367,9 @@
+----------------------------------------+ +----------------------------------------+
```
-##Complete BIOS BMC flow for BIOS configuration in immediate update model
+## Complete BIOS BMC flow for BIOS configuration in immediate update model
-```
+```text
+----------------------------------------+ +----------------------------------------+
| BIOS | | BMC |
| | | |
@@ -415,9 +414,9 @@
clear the Pending Attributes list whenever new AllBaseBIOSTables received from
BIOS.
-#Redfish interfaces for remote Bios configuration
+## Redfish interfaces for remote Bios configuration
-```
+```text
+-----------------------------------------------------------------------------------------------------------+
| +-------------------------+ +----------------------------------------------------------------+|
| | RBC Web tool - POSTMAN | | BMC ||
@@ -452,34 +451,32 @@
1. Get Current Attributes name and value list: Get the current BIOS settings
attribute name and value pair list. GET Method -
- "https://<BMC IP address>/redfish/v1/Systems/system/Bios"
+ `https://<BMC>/redfish/v1/Systems/system/Bios`
2. Get Attribute Registry: Get the detailed information about Bios Attribute
like current value, supported value, description, Menupath, Default value.
- GET Method - "https://<BMC IP address>/redfish/v1/Registries/Bios"
+ GET Method - `https://<BMC>/redfish/v1/Registries/Bios`
3. Change BIOS password: ACTION -
- "https://<BMC IP address>/redfish/v1/Systems/system/Bios/Actions/Bios.ChangePassword"
+ `https://<BMC>/redfish/v1/Systems/system/Bios/Actions/Bios.ChangePassword`
4. Reset To default settings: ACTION -
- "https://<BMC IP address>/redfish/v1/Systems/system/Bios/Actions/Bios.ResetBios"
+ `https://<BMC>/redfish/v1/Systems/system/Bios/Actions/Bios.ResetBios`
5. Update new BIOS settings (single attribute): Use to send the new value for
particular attribute or list of attributes. PATCH Method -
- "https://<BMC IP address>/redfish/v1/Systems/system/Bios/Settings" Ex:
- Attribute name and new value : { "DdrFreqLimit" : 2400}
+ `https://<BMC>/redfish/v1/Systems/system/Bios/Settings` Ex: Attribute name
+ and new value : `{ "DdrFreqLimit" : 2400 }`
6. Get the new pending value list: Use to get the new pending attributes list.
- GET Method -
- "https://<BMC IP address>/redfish/v1/Systems/system/Bios/Settings" -Valid
+ GET Method - `https://<BMC>/redfish/v1/Systems/system/Bios/Settings` - Valid
only in deferred model. For immediate update model, It will be empty. Ex:
- Attribute name and new value : { "DdrFreqLimit" : 2400,"QuietBoot",0x1 }
+ Attribute name and new value : `{ "DdrFreqLimit" : 2400, "QuietBoot", 0x1 }`
7. Update new BIOS settings (multiple attributes): Use to send the new value for
particular attribute or list of attributes. PATCH Method -
- "https://<BMC IP address>/redfish/v1/Systems/system/Bios/Settings" Ex:
- Attribute name and new value list : { "DdrFreqLimit" : 2400},"QuietBoot",0x1
- }
+ `https://<BMC>/redfish/v1/Systems/system/Bios/Settings` Ex: Attribute name
+ and new value list : `{ "DdrFreqLimit" : 2400, "QuietBoot", 0x1 }`
## Alternatives Considered
diff --git a/designs/state-management-and-external-interfaces.md b/designs/state-management-and-external-interfaces.md
index 072e63d..d0335e2 100644
--- a/designs/state-management-and-external-interfaces.md
+++ b/designs/state-management-and-external-interfaces.md
@@ -43,7 +43,7 @@
The Redfish [ResetType][1] has the following operations associated with it:
-```
+```json
"ResetType": {
"enum": [
"On",
@@ -180,4 +180,3 @@
[1]: http://redfish.dmtf.org/schemas/v1/Resource.json#/definitions/ResetType
[2]: https://github.com/openbmc/phosphor-state-manager
[3]: https://github.com/openbmc/bmcweb
-[4]: https://gerrit.openbmc.org/c/openbmc/docs/+/22358
diff --git a/designs/target-fail-monitoring.md b/designs/target-fail-monitoring.md
index e598ca8..e4dcede 100644
--- a/designs/target-fail-monitoring.md
+++ b/designs/target-fail-monitoring.md
@@ -41,7 +41,7 @@
completed unit. See the JobNew()/JobRemoved() section in the [systemd dbus
API][3]. The six different results are:
-```
+```text
done, canceled, timeout, failed, dependency, skipped
```
@@ -73,7 +73,7 @@
status that failed (i.e. canceled, timeout, ...)
- Example:
-```
+```text
xyz.openbmc_project.State.BMC.Error.MultiUserTargetFailure
STATUS=timeout
```
@@ -82,10 +82,10 @@
targets
- Critical systemd targets are ones used by phosphor-state-manager
- BMC: multi-user.target
- - Chassis: obmc-chassis-poweron@0.target, obmc-chassis-poweroff@0.target
- - Host: obmc-host-start@0.target, obmc-host-startmin@0.target,
- obmc-host-shutdown@0.target, obmc-host-stop@0.target,
- obmc-host-reboot@0.target
+ - Chassis: `obmc-chassis-poweron@0.target, obmc-chassis-poweroff@0.target`
+ - Host: `obmc-host-start@0.target, obmc-host-startmin@0.target`,
+ `obmc-host-shutdown@0.target`, `obmc-host-stop@0.target`,
+ `obmc-host-reboot@0.target`
- The errors for these must be defined in phosphor-dbus-interfaces
- Limitations:
- Fully qualified target name must be input (i.e. no templated / wild card
@@ -108,31 +108,31 @@
The json file(s) would have the following format for targets:
-```
+```json
{
- "targets" : [
- {
- "name": "multi-user.target",
- "errorsToMonitor": ["default"],
- "errorToLog": "xyz.openbmc_project.State.BMC.Error.MultiUserTargetFailure",
- },
- {
- "name": "obmc-chassis-poweron@0.target",
- "errorsToMonitor": ["timeout", "failed"],
- "errorToLog": "xyz.openbmc_project.State.Chassis.Error.PowerOnTargetFailure",
- }
- ]
+ "targets": [
+ {
+ "name": "multi-user.target",
+ "errorsToMonitor": ["default"],
+ "errorToLog": "xyz.openbmc_project.State.BMC.Error.MultiUserTargetFailure"
+ },
+ {
+ "name": "obmc-chassis-poweron@0.target",
+ "errorsToMonitor": ["timeout", "failed"],
+ "errorToLog": "xyz.openbmc_project.State.Chassis.Error.PowerOnTargetFailure"
+ }
+ ]
}
```
The json (files) would have the following format for services:
-```
+```json
{
- "services" : [
- "xyz.openbmc_project.biosconfig_manager.service",
- "xyz.openbmc_project.Dump.Manager.service"
- ]
+ "services": [
+ "xyz.openbmc_project.biosconfig_manager.service",
+ "xyz.openbmc_project.Dump.Manager.service"
+ ]
}
```
diff --git a/designs/telemetry.md b/designs/telemetry.md
index 7a646c2..88254df 100644
--- a/designs/telemetry.md
+++ b/designs/telemetry.md
@@ -2,8 +2,10 @@
Author: Piotr Matuszczak <piotr.matuszczak@intel.com>
-Other contributors: Pawel Rapkiewicz <pawel.rapkiewicz@intel.com> <pawelr>,
-Kamil Kowalski <kamil.kowalski@intel.com>
+Other contributors:
+
+- Pawel Rapkiewicz <pawel.rapkiewicz@intel.com> `pawelr`
+- Kamil Kowalski <kamil.kowalski@intel.com>
Created: 2019-08-07
@@ -272,13 +274,13 @@
additional sensor readings because it already has the latest values, since they
are updated on PropertiesChanged signal from the D-Bus sensors.
-**Telemetry service on [D-Bus][4]**
+### Telemetry service on [D-Bus][4]
Telemetry service exposes specific interfaces on D-Bus. One of them will be used
for reading report management. The second one will be used for triggers
management.
-**Reading report management**
+### Reading report management
The reading report management D-Bus object:
@@ -307,7 +309,7 @@
this metric. Each report has also the property that stores update interval (for
periodically updated reports).
-**Trigger management**
+### Trigger management
The trigger management D-Bus object:
@@ -415,7 +417,7 @@
| string | Unique metric Id |
| object path | D-Bus path of existing reading report. This is required when trigger's action is to update metric report. This path shall point to existing reading report within the Telemetry service. |
-**Trigger operations**
+### Trigger operations\*\*
Triggers support three types of operation: Log, Event and Update. For each,
there is a different way of proceeding.
@@ -425,33 +427,33 @@
Redfish log service shall then retrieve the data by reading system journal.
All is shown on the diagram below.
-```ascii
-+---------------------------+
-|bmcweb| | +----------------------+
-+------/ +-----------+-+ | |Telemetry| |
-| |Redfish | | | +---------/ |
-| |log service| | | | |
-| +-----------/ | | | |
-| | | | | |
-| | | | | |
-| +------^------+ | +-----------+----------+
-+---------------------------+ |
- | |
- +----collect----+ event
- journal entry | (write to journal)
- | |
- +------------------------------------+ |
- |systemd| | | |
- +-------/ +----------+ +---+------+ | |
- | |journal| | |libjournal| | |
- | +-------/ <--> <-------+
- | | | +----------+ |
- | | | |
- | | | |
- | +----------+ |
- | |
- +------------------------------------+
-```
+ ```ascii
+ +---------------------------+
+ |bmcweb| | +----------------------+
+ +------/ +-----------+-+ | |Telemetry| |
+ | |Redfish | | | +---------/ |
+ | |log service| | | | |
+ | +-----------/ | | | |
+ | | | | | |
+ | | | | | |
+ | +------^------+ | +-----------+----------+
+ +---------------------------+ |
+ | |
+ +----collect----+ event
+ journal entry | (write to journal)
+ | |
+ +------------------------------------+ |
+ |systemd| | | |
+ +-------/ +----------+ +---+------+ | |
+ | |journal| | |libjournal| | |
+ | +-------/ <--> <-------+
+ | | | +----------+ |
+ | | | |
+ | | | |
+ | +----------+ |
+ | |
+ +------------------------------------+
+ ```
2. For action Event, the Telemetry service shall send event using the [Redfish
Event Service][6] either as push-style event or SSE.
@@ -462,7 +464,7 @@
signal. This will cause Redfish Metric Report to be streamed out if it was
configured to do so.
-**Redfish Telemetry Service API**
+### Redfish Telemetry Service API
Redfish Telemetry Service shall support 2019.1 Redfish schemas for telemetry
resources. Metric report definitions determines which metrics are to be include
@@ -661,7 +663,7 @@
}
```
-**Performance tests**
+### Performance tests
Performance test were conducted on the AST2500 system with 64 MB flash and 512
MB RAM. Flash consumption by the Telemetry service is 197.5 kB. The runtime
@@ -769,7 +771,7 @@
- Functional tests
- Performance tests
-**Unit tests**
+### Unit tests
The Telemetry's code shall be covered by the unit tests. The preferred framework
is the [GTest/GMock][7]. The unit tests shall be ran before code change is to be
@@ -778,7 +780,7 @@
according to test-driven development principle. Unit tests shall be also
carefully reviewed.
-**Functional tests**
+### Functional tests
Functional tests will be divided into two steps.
@@ -796,7 +798,7 @@
scenarios with sending metric report as an event, triggering metric report
update and logging events.
-**Performance tests**
+### Performance tests
Performance tests shall be done using full OpenBMC configuration with all the
required set of features. The tests shall create a lot of metric reports (up to
diff --git a/designs/thermal-control-modes.md b/designs/thermal-control-modes.md
index 163784f..8a65724 100644
--- a/designs/thermal-control-modes.md
+++ b/designs/thermal-control-modes.md
@@ -32,7 +32,7 @@
overall power dissipation.
Mathematical calculations to logically estimate exit air temps:
-https://github.com/openbmc/dbus-sensors/blob/master/src/ExitAirTempSensor.cpp
+<https://github.com/openbmc/dbus-sensors/blob/master/src/ExitAirTempSensor.cpp>
## Requirements
diff --git a/designs/uart-mux-support.md b/designs/uart-mux-support.md
index d71a6d9..1bf0e27 100644
--- a/designs/uart-mux-support.md
+++ b/designs/uart-mux-support.md
@@ -216,7 +216,7 @@
Example:
-```
+```bash
busctl set-property xyz.openbmc_project.Console.host1 \
/xyz/openbmc_project/console/host2 \
xyz.openbmc_project.Console.Access Connect ""
@@ -227,7 +227,7 @@
Unified Tree:
-```
+```text
busctl tree --user xyz.openbmc_project.Console.host1
└─/xyz
└─/xyz/openbmc_project
@@ -238,7 +238,7 @@
Split Tree:
-```
+```text
busctl tree --user xyz.openbmc_project.Console.host1
└─/xyz
└─/xyz/openbmc_project
@@ -392,7 +392,7 @@
Below is a block diagram of the relationships between the software and hardware
components:
-```
+```text
+--------------------+
| server.conf |
+--------------------+
@@ -434,7 +434,7 @@
The initial format of these messages will be something like:
-```
+```text
[obmc-console] %Y-%m-%d %H:%M:%S UTC CONNECTED
[obmc-console] %Y-%m-%d %H:%M:%S UTC DISCONNECTED
```
diff --git a/designs/unique-hostname.md b/designs/unique-hostname.md
index 14e5c22..a919f35 100644
--- a/designs/unique-hostname.md
+++ b/designs/unique-hostname.md
@@ -18,9 +18,9 @@
The detailed issue regarding the hostname and service name conflicts is
described in the following links.
-https://github.com/openbmc/openbmc/issues/1741.
-https://lists.freedesktop.org/archives/avahi/2018-January/002492.html
-https://github.com/lathiat/avahi/issues/117
+- <https://github.com/openbmc/openbmc/issues/1741.>
+- <https://lists.freedesktop.org/archives/avahi/2018-January/002492.html>
+- <https://github.com/lathiat/avahi/issues/117>
## Requirements
diff --git a/designs/virtual-media.md b/designs/virtual-media.md
index f858267..683b9b1 100644
--- a/designs/virtual-media.md
+++ b/designs/virtual-media.md
@@ -1,10 +1,11 @@
# Virtual Media (a.k.a. Remote Media)
-Author: Pawel Rapkiewicz <pawel.rapkiewicz@intel.com> <pawelr>
+Author: Pawel Rapkiewicz <pawel.rapkiewicz@intel.com> `pawelr`
-Other contributors: Przemyslaw Czarnowski
-<przemyslaw.hawrylewicz.czarnowski@intel.com> Anna Platash
-<anna.platash@intel.com>
+Other contributors:
+
+- Przemyslaw Czarnowski <przemyslaw.hawrylewicz.czarnowski@intel.com>
+- Anna Platash <anna.platash@intel.com>
Created: 6/4/2019
@@ -291,14 +292,14 @@
Schema will look similar for both Proxy and Legacy Mode. Some key differences as
follows:
-| Field Name | Proxy Mode | Legacy Mode | Comment |
-| -------------------- | ---------- | -------------------------------- | --------------------------------------------------------------- |
-| InsertMedia | N/A | action as described by DMTF spec | Action can return Task object if<br> process is time consumming |
-| Image | N/A | image location | |
-| ImageName | N/A | image name | |
-| ConnectedVia | "Applet" | as described by DMTF spec | applies only for connected media |
-| TransferMethod | "Stream" | "Stream" | "upload" is not supported by design |
-| TransferProtocolType | "OEM" | as described by DMTF spec | |
+| Field Name | Proxy Mode | Legacy Mode | Comment |
+| -------------------- | ---------- | -------------------------------- | ---------------------------------------------------------- |
+| InsertMedia | N/A | action as described by DMTF spec | Action can return Task object if process is time consuming |
+| Image | N/A | image location | |
+| ImageName | N/A | image name | |
+| ConnectedVia | "Applet" | as described by DMTF spec | applies only for connected media |
+| TransferMethod | "Stream" | "Stream" | "upload" is not supported by design |
+| TransferProtocolType | "OEM" | as described by DMTF spec | |
#### Virtual Media OEM Extension
@@ -306,7 +307,7 @@
directly via Redfish action and whole connection is processed between service
and web server.
-For [Proxy Mode](#Proxy-Mode) nbd data is served by client web browser. Having
+For [Proxy Mode](#proxy-mode) nbd data is served by client web browser. Having
multiple connections, in order to setup connection, client needs the information
about the location of websocket created by web server. This value is exposed as
OEM `WebSocketEndpoint` property for each item.
diff --git a/designs/virtual-sensors.md b/designs/virtual-sensors.md
index bda4f8c..2f33a94 100644
--- a/designs/virtual-sensors.md
+++ b/designs/virtual-sensors.md
@@ -1,4 +1,4 @@
-### Virtual sensors
+# Virtual sensors
Author: Vijay Khemka <vijaykhemka@fb.com>; <vijay!>
diff --git a/designs/vpd-collection.md b/designs/vpd-collection.md
index 1e52b63..96e086c 100644
--- a/designs/vpd-collection.md
+++ b/designs/vpd-collection.md
@@ -158,7 +158,7 @@
containing keywords SN, FN and CCIN, the representation in D-Bus would look
like:
-```
+```text
Interface: com.ibm.ipzvpd.VINI
Properties:
SN
@@ -222,9 +222,9 @@
### Build upon the entity manager
-Using the entity manager: https://github.com/openbmc/entity-manager. The Entity
-manager has an application called the FruDevice, which probes /dev/i2c/ for
-EEPROMs, reads (IPMI format) VPD and stores it on DBUS.
+Using the entity manager: <https://github.com/openbmc/entity-manager>. The
+Entity manager has an application called the FruDevice, which probes /dev/i2c/
+for EEPROMs, reads (IPMI format) VPD and stores it on DBUS.
The application could be enhanced to:
diff --git a/development/add-new-system.md b/development/add-new-system.md
index 4f433e8..4b4368f 100644
--- a/development/add-new-system.md
+++ b/development/add-new-system.md
@@ -67,7 +67,7 @@
within `meta-ibm/meta-romulus/`. The Romulus layer is defined within the `conf`
subdirectory. Under `conf` you will see a layout like this:
-```
+```bash
meta-ibm/meta-romulus/conf/
├── bblayers.conf.sample
├── conf-notes.txt
@@ -80,7 +80,7 @@
To create our new romulus-prime system we are going to start out by copying our
romulus layer.
-```
+```bash
cp -R meta-ibm/meta-romulus meta-ibm/meta-romulus-prime
```
@@ -154,7 +154,7 @@
the conf file for your build. You can manually copy in the new files or just
remove it and let BitBake do it for you:
- ```
+ ```bash
cd ..
rm -r ./build/conf
. setup romulus-prime
@@ -179,7 +179,7 @@
Create a config files as follows:
- ```
+ ```bash
cp meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-config.bb meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb
vi meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb
@@ -192,15 +192,15 @@
#Use Romulus config
do_make_setup() {
- cp ${S}/Romulus.py \
- ${S}/obmc_system_config.py
- cat <<EOF > ${S}/setup.py
+ cp ${S}/Romulus.py \
+ ${S}/obmc_system_config.py
+ cat <<EOF > ${S}/setup.py
from distutils.core import setup
setup(name='${BPN}',
- version='${PR}',
- py_modules=['obmc_system_config'],
- )
+ version='${PR}',
+ py_modules=['obmc_system_config'],
+ )
EOF
}
@@ -215,7 +215,7 @@
romulus-prime to use the romulus.cfg file. We just need to add the `-prime`
to the prepend path.
- ```
+ ```bash
vi ./meta-ibm/meta-romulus-prime/recipes-kernel/linux/linux-aspeed_%.bbappend
FILESEXTRAPATHS_prepend_romulus-prime := "${THISDIR}/${PN}:"
@@ -234,7 +234,7 @@
is an example of this process. Upstreaming to the kernel is a lesson in
itself. For this lesson, we will simply use the Romulus kernel config files.
- ```
+ ```bash
vi ./meta-ibm/meta-romulus-prime/conf/machine/romulus-prime.conf
# Replace the ${MACHINE} variable in the KERNEL_DEVICETREE
@@ -252,7 +252,7 @@
Your new image will be in the following location from where you ran your
"bitbake" command:
-```
+```bash
./tmp/deploy/images/romulus-prime/obmc-phosphor-image-romulus-prime.static.mtd
```
@@ -262,7 +262,7 @@
Once booted, you should see the following for the login:
-```
+```text
romulus-prime login:
```
@@ -278,9 +278,9 @@
This section describes how you can make changes to the kernel to port OpenBMC to
a new machine. The device tree is in
-https://github.com/openbmc/linux/tree/dev-4.13/arch/arm/boot/dts. For examples,
-see [aspeed-bmc-opp-romulus.dts][1] or a similar machine. Complete the following
-steps to make kernel changes:
+<https://github.com/openbmc/linux/tree/dev-4.13/arch/arm/boot/dts>. For
+examples, see [aspeed-bmc-opp-romulus.dts][1] or a similar machine. Complete the
+following steps to make kernel changes:
1. Add the new machine device tree:
- Describe the GPIOs, e.g. LED, FSI, gpio-keys, etc. You should get such info
@@ -387,21 +387,25 @@
- [w83773g@4c.conf][8] defines the `w83773` temperature sensor containing 3
temperatures:
- ```
+
+```bash
LABEL_temp1 = "outlet"
...
LABEL_temp2 = "inlet_cpu"
...
LABEL_temp3 = "inlet_io"
- ```
- This device is defined in its device tree as [w83773g@4c][9]. When BMC starts,
- the udev rule will start `phosphor-hwmon` and it will create temperature
- sensors on below DBus objects based on its sysfs attributes.
- ```
+```
+
+This device is defined in its device tree as [w83773g@4c][9]. When BMC starts,
+the udev rule will start `phosphor-hwmon` and it will create temperature sensors
+on below DBus objects based on its sysfs attributes.
+
+```bash
/xyz/openbmc_project/sensors/temperature/outlet
/xyz/openbmc_project/sensors/temperature/inlet_cpu
/xyz/openbmc_project/sensors/temperature/inlet_io
- ```
+```
+
- [pwm-tacho-controller@1e786000.conf][10] defines the fans and the config is
similar as above, the difference is that it creates `fan_tach` sensors.
- [occ-hwmon.1.conf][11] defines the occ hwmon sensor for master CPU. This
@@ -409,7 +413,8 @@
label instead of directly getting the index of the sensor, because CPU cores
and DIMMs could be dynamic, e.g. CPU cores could be disabled, DIMMs could be
pulled out.
- ```
+
+```bash
MODE_temp1 = "label"
MODE_temp2 = "label"
...
@@ -422,21 +427,22 @@
LABEL_temp34 = "dimm7_temp"
LABEL_power2 = "p0_power"
...
- ```
- - The `MODE_temp* = "label"` tells that if it sees `tempX`, it shall read the
- label which is the sensor id.
- - And `LABEL_temp* = "xxx"` tells the sensor name for the corresponding sensor
- id.
- - For example, if `temp1_input` is 37000 and `temp1_label` is 91 in sysfs,
- `phosphor-hwmon` knows `temp1_input` is for sensor id 91, which is
- `p0_core0_temp`, so it creates
- `/xyz/openbmc_project/sensors/temperature/p0_core0_temp` with sensor
- value 37000.
- - For Romulus, the power sensors do not need to read label since all powers
- are available on a system.
- - For Witherspoon, the power sensors are similar to temperature sensors, that
- it shall tell hwmon to read the `function_id` instead of directly getting
- the index of the sensor.
+```
+
+- The `MODE_temp* = "label"` tells that if it sees `tempX`, it shall read the
+ label which is the sensor id.
+- And `LABEL_temp* = "xxx"` tells the sensor name for the corresponding sensor
+ id.
+- For example, if `temp1_input` is 37000 and `temp1_label` is 91 in sysfs,
+ `phosphor-hwmon` knows `temp1_input` is for sensor id 91, which is
+ `p0_core0_temp`, so it creates
+ `/xyz/openbmc_project/sensors/temperature/p0_core0_temp` with sensor
+ value 37000.
+- For Romulus, the power sensors do not need to read label since all powers are
+ available on a system.
+- For Witherspoon, the power sensors are similar to temperature sensors, that it
+ shall tell hwmon to read the `function_id` instead of directly getting the
+ index of the sensor.
### LEDs
@@ -445,54 +451,59 @@
1. In kernel dts, LEDs shall be described, e.g. [romulus dts][12] describes 3
LEDs, `fault`, `identify` and `power`.
- ```
- leds {
- compatible = "gpio-leds";
+ ```dts
+ leds {
+ compatible = "gpio-leds";
- fault {
- gpios = <&gpio ASPEED_GPIO(N, 2) GPIO_ACTIVE_LOW>;
- };
+ fault {
+ gpios = <&gpio ASPEED_GPIO(N, 2) GPIO_ACTIVE_LOW>;
+ };
- identify {
- gpios = <&gpio ASPEED_GPIO(N, 4) GPIO_ACTIVE_HIGH>;
- };
+ identify {
+ gpios = <&gpio ASPEED_GPIO(N, 4) GPIO_ACTIVE_HIGH>;
+ };
- power {
- gpios = <&gpio ASPEED_GPIO(R, 5) GPIO_ACTIVE_LOW>;
- };
- };
+ power {
+ gpios = <&gpio ASPEED_GPIO(R, 5) GPIO_ACTIVE_LOW>;
+ };
+ };
```
2. In machine layer, LEDs shall be configured via yaml to describe how it
functions, e.g. [Romulus led yaml][28]:
- ```
+
+ ```yaml
bmc_booted:
- power:
- Action: 'Blink'
- DutyOn: 50
- Period: 1000
- Priority: 'On'
+ power:
+ Action: "Blink"
+ DutyOn: 50
+ Period: 1000
+ Priority: "On"
power_on:
- power:
- Action: 'On'
- DutyOn: 50
- Period: 0
- Priority: 'On'
- ...
+ power:
+ Action: "On"
+ DutyOn: 50
+ Period: 0
+ Priority: "On"
```
+
It tells the LED manager to set the `power` LED to blink when BMC is ready
- and booted, and set it on when host is powered on.
-3. At runtime, LED manager automatically set LEDs on/off/blink based on the
- above yaml config.
-4. LED can be accessed manually via /xyz/openbmc_project/led/, e.g.
- - Get identify LED state:
- ```
- curl -b cjar -k https://$bmc/xyz/openbmc_project/led/physical/identify
- ```
- - Set identify LED to blink:
- ```
- curl -b cjar -k -X PUT -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.Led.Physical.Action.Blink" }' https://$bmc/xyz/openbmc_project/led/physical/identify/attr/State
- ```
+ and booted, and set it on when host is powered on. 3. At runtime, LED manager
+ automatically set LEDs on/off/blink based on the above yaml config. 4. LED
+ can be accessed manually via /xyz/openbmc_project/led/, e.g.
+
+3. Get identify LED state:
+
+ ```bash
+ curl -b cjar -k https://$bmc/xyz/openbmc_project/led/physical/identify
+ ```
+
+4. Set identify LED to blink:
+
+ ```bash
+ curl -b cjar -k -X PUT -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.Led.Physical.Action.Blink" }' https://$bmc/xyz/openbmc_project/led/physical/identify/attr/State
+ ```
+
5. When an error related to a FRU occurs, an event log is created in logging
with a CALLOUT path. [phosphor-fru-fault-monitor][29] monitors the logs:
- Assert the related fault LED group when a log with the CALLOUT path is
@@ -522,7 +533,7 @@
For ipmi-sensor-inventory, the sensors from IPMI are different between systems,
so you need to define your own sensors, e.g.
-```
+```yaml
0x08:
sensorType: 0x07
path: /org/open_power/control/occ0
@@ -566,7 +577,7 @@
Romulus has no GPIO detection for fans, so it checks fan tach sensor:
-```
+```yaml
- name: fan0
path: /system/chassis/motherboard/fan0
methods:
@@ -587,17 +598,17 @@
and the fan speed ranges from 0 to about 7000. So it needs a factor and offset
to mapping the pwm to fan speed:
-```
- - inventory: /system/chassis/motherboard/fan0
- allowed_out_of_range_time: 30
- deviation: 15
- num_sensors_nonfunc_for_fan_nonfunc: 1
- sensors:
- - name: fan0
- has_target: true
- target_interface: xyz.openbmc_project.Control.FanPwm
- factor: 21
- offset: 1600
+```yaml
+- inventory: /system/chassis/motherboard/fan0
+ allowed_out_of_range_time: 30
+ deviation: 15
+ num_sensors_nonfunc_for_fan_nonfunc: 1
+ sensors:
+ - name: fan0
+ has_target: true
+ target_interface: xyz.openbmc_project.Control.FanPwm
+ factor: 21
+ offset: 1600
```
The yaml config tells that:
@@ -614,7 +625,8 @@
- `zone-condition` defines the cooling zone conditions. Romulus is always
air-cooled, so this config is as simple as defining an `air_cooled_chassis`
condition based on the cooling type property.
- ```
+
+```yaml
- name: air_cooled_chassis
type: getProperty
properties:
@@ -623,65 +635,74 @@
path: /xyz/openbmc_project/inventory/system/chassis
type: bool
value: false
- ```
+```
+
- `zone-config` defines the cooling zones. Romulus has only one zone:
- ```
- zones:
- - zone: 0
- full_speed: 255
- default_floor: 195
- increase_delay: 5
- decrease_interval: 30
- ```
- It defines that the zone full speed and default floor speed for the fans, so
- the fan pwm will be set to 255 if it is in full speed, and set to 195 if fans
- are in default floor speed.
+
+```yaml
+zones:
+ - zone: 0
+ full_speed: 255
+ default_floor: 195
+ increase_delay: 5
+ decrease_interval: 30
+```
+
+It defines that the zone full speed and default floor speed for the fans, so the
+fan pwm will be set to 255 if it is in full speed, and set to 195 if fans are in
+default floor speed.
+
- `fan-config` defines which fans are controlled in which zone and which target
interface shall be used, e.g. below yaml config defines fan0 shall be
controlled in zone0 and it shall use `FanPwm` interface.
- ```
+
+```yaml
- inventory: /system/chassis/motherboard/fan0
cooling_zone: 0
sensors:
- fan0
target_interface: xyz.openbmc_project.Control.FanPwm
...
- ```
+```
+
- `events-config` defines the various events and its handlers, e.g. which fan
targets shall be set in which temperature. This config is a bit complicated,
the [example event yaml][17] provides documents and examples. Romulus example:
- ```
- - name: set_air_cooled_speed_boundaries_based_on_ambient
- groups:
- - name: zone0_ambient
- interface: xyz.openbmc_project.Sensor.Value
- property:
- name: Value
- type: int64_t
- matches:
- - name: propertiesChanged
- actions:
- - name: set_floor_from_average_sensor_value
- map:
- value:
- - 27000: 85
- - 32000: 112
- - 37000: 126
- - 40000: 141
- type: std::map<int64_t, uint64_t>
- - name: set_ceiling_from_average_sensor_value
- map:
- value:
- - 25000: 175
- - 27000: 255
- type: std::map<int64_t, uint64_t>
- ```
- The above yaml config defines the fan floor and ceiling speed in
- `zone0_ambient`'s different temperatures. E.g.
- 1. When the temperature is lower than 27 degreesC, the floor speed (pwm)
- shall be set to 85.
- 2. When the temperature is between 27 and 32 degrees C, the floor speed (pwm)
- shall be set to 112, etc.
+
+```yaml
+- name: set_air_cooled_speed_boundaries_based_on_ambient
+ groups:
+ - name: zone0_ambient
+ interface: xyz.openbmc_project.Sensor.Value
+ property:
+ name: Value
+ type: int64_t
+ matches:
+ - name: propertiesChanged
+ actions:
+ - name: set_floor_from_average_sensor_value
+ map:
+ value:
+ - 27000: 85
+ - 32000: 112
+ - 37000: 126
+ - 40000: 141
+ type: std::map<int64_t, uint64_t>
+ - name: set_ceiling_from_average_sensor_value
+ map:
+ value:
+ - 25000: 175
+ - 27000: 255
+ type: std::map<int64_t, uint64_t>
+```
+
+The above yaml config defines the fan floor and ceiling speed in
+`zone0_ambient`'s different temperatures. E.g.
+
+1. When the temperature is lower than 27 degreesC, the floor speed (pwm) shall
+ be set to 85.
+2. When the temperature is between 27 and 32 degrees C, the floor speed (pwm)
+ shall be set to 112, etc.
With above configs, phosphor-fan will run the fan presence/monitor/control logic
as configured specifically for the machine.
@@ -710,9 +731,10 @@
All the GPIOs to be monitored shall be described in the device tree. E.g.
-```
+```dts
gpio-keys {
compatible = "gpio-keys";
+
checkstop {
label = "checkstop";
gpios = <&gpio ASPEED_GPIO(J, 2) GPIO_ACTIVE_LOW>;
@@ -729,7 +751,7 @@
The following code describes two GPIO keys, one for `checkstop` and the other
for `id-button`, where the key code is calculated from [aspeed-gpio.h][24]:
-```
+```bash
#define ASPEED_GPIO_PORT_A 0
#define ASPEED_GPIO_PORT_B 1
...
@@ -747,24 +769,29 @@
Witherspoon and Zaius have examples for gpio presence.
- [Witherspoon][19]:
- ```
- INVENTORY=/system/chassis/motherboard/powersupply0
- DEVPATH=/dev/input/by-path/platform-gpio-keys-event
- KEY=104
- NAME=powersupply0
- DRIVERS=/sys/bus/i2c/drivers/ibm-cffps,3-0069
- ```
- It checks GPIO key 104 for `powersupply0`'s presence, creates the inventory
- object and bind or unbind the driver.
+
+```bash
+INVENTORY=/system/chassis/motherboard/powersupply0
+DEVPATH=/dev/input/by-path/platform-gpio-keys-event
+KEY=104
+NAME=powersupply0
+DRIVERS=/sys/bus/i2c/drivers/ibm-cffps,3-0069
+```
+
+It checks GPIO key 104 for `powersupply0`'s presence, creates the inventory
+object and bind or unbind the driver.
+
- [Zaius][20]:
- ```
- INVENTORY=/system/chassis/pcie_card_e2b
- DEVPATH=/dev/input/by-path/platform-gpio-keys-event
- KEY=39
- NAME=pcie_card_e2b
- ```
- It checks GPIO key 39 for `pcie_card_e2b`'s presence, and creates the
- inventory object.
+
+```bash
+INVENTORY=/system/chassis/pcie_card_e2b
+DEVPATH=/dev/input/by-path/platform-gpio-keys-event
+KEY=39
+NAME=pcie_card_e2b
+```
+
+It checks GPIO key 39 for `pcie_card_e2b`'s presence, and creates the inventory
+object.
#### GPIO monitor
@@ -772,32 +799,36 @@
or button presses.
- [checkstop monitor][21] is a common service for OpenPOWER machines.
- ```
- DEVPATH=/dev/input/by-path/platform-gpio-keys-event
- KEY=74
- POLARITY=1
- TARGET=obmc-host-crash@0.target
- ```
- By default it monitors GPIO key 74, and if it is triggered, it tells systemd
- to start `obmc-host-crash@0.target`. For systems using a different GPIO pin
- for checkstop, it simply overrides the default one by specifying its own
- config file in meta-machine layer. E.g. [Zaius's checkstop config][22].
- **Note**: when the key is pressed, `phosphor-gpio-monitor` starts the target
- unit and exits.
+
+```bash
+DEVPATH=/dev/input/by-path/platform-gpio-keys-event
+KEY=74
+POLARITY=1
+TARGET=obmc-host-crash@0.target
+```
+
+By default it monitors GPIO key 74, and if it is triggered, it tells systemd to
+start `obmc-host-crash@0.target`. For systems using a different GPIO pin for
+checkstop, it simply overrides the default one by specifying its own config file
+in meta-machine layer. E.g. [Zaius's checkstop config][22]. **Note**: when the
+key is pressed, `phosphor-gpio-monitor` starts the target unit and exits.
+
- [id-button monitor][23] is an example service on Romulus to monitor ID button
press.
- ```
- DEVPATH=/dev/input/by-path/platform-gpio-keys-event
- KEY=135
- POLARITY=1
- TARGET=id-button-pressed.service
- EXTRA_ARGS=--continue
- ```
- It monitors GPIO key 135 for the button press and starts
- `id-button-pressed.service`, that handles the event by setting the identify
- LED group's `Assert` property. **Note**: It has an extra argument,
- `--continue`, that tells `phosphor-gpio-monitor` to not exit and continue
- running when the key is pressed.
+
+```bash
+DEVPATH=/dev/input/by-path/platform-gpio-keys-event
+KEY=135
+POLARITY=1
+TARGET=id-button-pressed.service
+EXTRA_ARGS=--continue
+```
+
+It monitors GPIO key 135 for the button press and starts
+`id-button-pressed.service`, that handles the event by setting the identify LED
+group's `Assert` property. **Note**: It has an extra argument, `--continue`,
+that tells `phosphor-gpio-monitor` to not exit and continue running when the key
+is pressed.
[1]:
https://github.com/openbmc/linux/blob/dev-4.13/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts
@@ -842,7 +873,6 @@
https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/gpio
[24]:
https://github.com/openbmc/linux/blob/dev-4.13/include/dt-bindings/gpio/aspeed-gpio.h
-[25]: https://github.com/openbmc/docs/blob/master/development/add-new-system.md
[26]:
https://github.com/openbmc/openbmc/commit/e0e69beab7c268e4ad98972016c78b0d7d5769ac
[27]:
@@ -850,6 +880,5 @@
[28]:
https://github.com/openbmc/openbmc/blob/3cce45a96f0416b4c3d8f2b698cb830662a29227/meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config/led.yaml
[29]: https://github.com/openbmc/phosphor-led-manager/tree/master/fault-monitor
-[30]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md
[31]: https://github.com/openbmc/docs/blob/master/kernel-development.md
[32]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md
diff --git a/development/dev-environment.md b/development/dev-environment.md
index a62ed0b..69d56b0 100644
--- a/development/dev-environment.md
+++ b/development/dev-environment.md
@@ -81,21 +81,21 @@
Note this section will take you through the process of building a Romulus
OpenBMC image. Future tutorials will build on this by having you customize the
image. If you would like to skip the building and just try out OpenBMC and QEMU
-then you can download the latest Romulus image from
-[here](https://jenkins.openbmc.org/job/latest-master/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/openbmc/build/tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd)
+then you can download the latest Romulus image from the
+[OpenBMC Jenkins](https://jenkins.openbmc.org/job/latest-master/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/openbmc/build/tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd)
and skip to the
[Download and Start QEMU Session](#download-and-start-qemu-session) section.
1. Clone OpenBMC
- ```
+ ```bash
git clone https://github.com/openbmc/openbmc.git
```
2. Build the Romulus OpenBMC Image (note this will take 30 - 120 minutes
depending on your hardware)
- ```
+ ```bash
. setup romulus
bitbake obmc-phosphor-image
```
@@ -108,7 +108,7 @@
1. Download latest openbmc/qemu fork of QEMU application
- ```
+ ```bash
wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm
chmod u+x qemu-system-arm
@@ -116,7 +116,7 @@
2. Copy the image generated by the build to your current directory
- ```
+ ```bash
cp ./tmp/deploy/images/romulus/obmc-phosphor-image-romulus.static.mtd ./
```
@@ -127,21 +127,24 @@
session. In this example, it just uses 2222, 2443, 2623. You can use whatever
you prefer.
- ```
+ ```bash
./qemu-system-arm -m 256 -M romulus-bmc -nographic \
- -drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
- -net nic \
- -net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostfwd=udp:127.0.0.1:2623-:623,hostname=qemu
+ -drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
+ -net nic \
+ -net user,hostfwd=:127.0.0.1:2222-:22,hostfwd=:127.0.0.1:2443-:443,hostfwd=udp:127.0.0.1:2623-:623,hostname=qemu
```
If you are running within a virtual environment where you can use the real
ports, then you would start QEMU with the following.
- ```
+ ```bash
+
./qemu-system-arm -m 256 -machine romulus-bmc -nographic \
- -drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
- -net nic \
- -net user,hostfwd=:127.0.0.1:22-:22,hostfwd=:127.0.0.1:443-:443,hostfwd=tcp:127.0.0.1:80-:80,hostfwd=tcp:127.0.0.1:2200-:2200,hostfwd=udp:127.0.0.1:623-:623,hostfwd=udp:127.0.0.1:664-:664,hostname=qemu
+ -drive file=./obmc-phosphor-image-romulus.static.mtd,format=raw,if=mtd \
+ -net nic \
+ -net
+ user,hostfwd=:127.0.0.1:22-:22,hostfwd=:127.0.0.1:443-:443,hostfwd=tcp:127.0.0.1:80-:80,hostfwd=tcp:127.0.0.1:2200-:2200,hostfwd=udp:127.0.0.1:623-:623,hostfwd=udp:127.0.0.1:664-:664,hostname=qemu
+
```
4. Wait for your QEMU-based BMC to boot
@@ -154,7 +157,7 @@
the obmcutil tool to check the state of the OpenBMC state services. When you
see the following then you have successfully booted to "Ready" state.
- ```
+ ```bash
root@openbmc:~# obmcutil state
CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready
CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off
@@ -167,7 +170,7 @@
Run these from the system you started QEMU on
- ```
+ ```bash
ssh root@localhost -p 2222
```
@@ -190,31 +193,31 @@
- set up a bmc build environment
-```
+```bash
source setup romulus myBuild/build
```
- add the qemu x86 open embedded machine for testing
-```
+```bash
MACHINE ??= "qemux86"
```
- Make the changes to the build (ie devtool modify bmcweb, devtool add gdb)
-```
+```bash
devtool modify bmcweb myNewLocalbmcweb/
```
- build open bmc for the qemu x86 machine
-```
+```bash
MACHINE=qemux86 bitbake obmc-phosphor-image
```
- run qemu they way yocto provides
-```
+```bash
runqemu myBuild/build/tmp/deploy/images/qemux86/ nographic \
qemuparams="-m 2048"
```
diff --git a/development/devtool-hello-world.md b/development/devtool-hello-world.md
index 89403dc..c6d4501 100644
--- a/development/devtool-hello-world.md
+++ b/development/devtool-hello-world.md
@@ -21,7 +21,7 @@
1. Use devtool to extract source code
- ```
+ ```bash
devtool modify phosphor-state-manager
```
@@ -29,25 +29,25 @@
2. Modify a source file and add a cout
- ```
+ ```bash
vi workspace/sources/phosphor-state-manager/bmc_state_manager_main.cpp
```
Your diff should look something like this:
- ```
+ ```bash
+#include <iostream>
int main(int argc, char**)
{
@@ -17,6 +18,8 @@ int main(int argc, char**)
- bus.request_name(BMC_BUSNAME);
+ bus.request_name(BMC_BUSNAME);
+ std::cout<<"Hello World" <<std::endl;
+
- while (true)
- {
+ while (true)
+ {
```
3. Rebuild the flash image which will now include your change
@@ -55,7 +55,7 @@
This will be a much faster build as bitbake will utilize all of the cache
from your previous build, only building what is new.
- ```
+ ```bash
bitbake obmc-phosphor-image
```
@@ -66,13 +66,13 @@
After you login to your QEMU session, verify the message is in the journal
- ```
+ ```bash
journalctl | grep "Hello World"
```
You should see something like this:
- ```
+ ```bash
<date> romulus phosphor-bmc-state-manager[1089]: Hello World
```
@@ -87,7 +87,7 @@
1. Modify your hello world
- ```
+ ```bash
vi workspace/sources/phosphor-state-manager/bmc_state_manager_main.cpp
```
@@ -99,7 +99,7 @@
that you are interested in. In this case, we'll just rebuild the
phosphor-state-manager repo to pick up your new hello world change.
- ```
+ ```bash
bitbake phosphor-state-manager
```
@@ -121,7 +121,7 @@
no more bricking the system. Log in to the QEMU instance and run these
commands.
- ```
+ ```bash
mkdir -p /tmp/persist/usr
mkdir -p /tmp/persist/work/usr
mount -t overlay -o lowerdir=/usr,upperdir=/tmp/persist/usr,workdir=/tmp/persist/work/usr overlay /usr
@@ -133,7 +133,7 @@
to run from your phosphor-state-manager directory. If you chose your own port
then substitute that here for the 2222.
- ```
+ ```bash
scp -P 2222 ./workspace/sources/phosphor-state-manager/oe-workdir/package/usr/bin/phosphor-bmc-state-manager root@127.0.0.1:/usr/bin/
```
@@ -141,13 +141,13 @@
1. Stop the BMC state manager service
- ```
+ ```bash
systemctl stop xyz.openbmc_project.State.BMC.service
```
2. Run the application in your QEMU session:
- ```
+ ```bash
phosphor-bmc-state-manager
```
@@ -161,7 +161,7 @@
tutorials on this, but for now just run the following to restart the BMC
state service and have it pick up your new application:
- ```
+ ```bash
systemctl restart xyz.openbmc_project.State.BMC.service
```
@@ -169,13 +169,13 @@
output to the console, but it will be in the journal. Later tutorials will
discuss the journal but for now just run:
- ```
+ ```bash
journalctl | tail
```
You should see something like this in one of the journal entries:
- ```
+ ```bash
<date> romulus phosphor-bmc-state-manager[1089]: Hello World Again
```
@@ -186,6 +186,6 @@
## Advanced Workflow
Once you've got a good handle on the above, there are some more advanced tools
-and wrappers you can utilize to optimize this flow. See this
-[link](https://amboar.github.io/notes/2022/01/13/openbmc-development-workflow.html)
+and wrappers you can utilize to optimize this flow. See the
+[workflow document](https://amboar.github.io/notes/2022/01/13/openbmc-development-workflow.html)
for more information.
diff --git a/development/gerrit-setup.md b/development/gerrit-setup.md
index fdb9ece..903eb40 100644
--- a/development/gerrit-setup.md
+++ b/development/gerrit-setup.md
@@ -9,14 +9,14 @@
## Initial Setup
-##### Update Git Identity
+### Update Git Identity
- `git config --global --add user.name "Your name" (eg. John Smith)`
- `git config --global --add user.email "youremail@your-domain" (eg. jsmith@somedomain.com)`
- (Optional)
`git config --global --add diff.tool "preferred diff tool" (eg. gvimdiff or meld)`
-##### Setup SSH Keys
+### Setup SSH Keys
Create keys: `ssh-keygen -t ed25519 -C "your_email@your-domain"`
@@ -43,21 +43,21 @@
- Click on "ADD NEW SSH KEY"
- If succesfull you should see your public key added and with the status "Valid"
-##### Add e-mail to Gerrit
+### Add e-mail to Gerrit
- Login to [Gerrit](https://gerrit.openbmc.org/)
- Enter e-mail in Settings -> Contact Information -> Register New E-Mail
- Check e-mail for confirmation and click the link to confirm
-##### Add full name to Gerrit
+### Add full name to Gerrit
- Enter your full name in Settings -> Profile -> Full name
-##### Add SSH config entry
+### Add SSH config entry
Add the following to `~/.ssh/config`:
-```
+```bash
Host openbmc.gerrit
Hostname gerrit.openbmc.org
Port 29418
@@ -70,7 +70,7 @@
Username
- Ensure proper permissions for for your .ssh directory: `chmod 600 ~/.ssh/*`
-##### Confirm Setup Success
+### Confirm Setup Success
Test connectivity to Gerrit by attempting to clone a repo
@@ -78,11 +78,11 @@
- If successful you should see something like:
`Checking out files: 100% (45/45), done.`
-##### Add Hooks
+### Add Hooks
Inside the repo you just cloned, enter the following commands:
-```
+```bash
gitdir=$(git rev-parse --git-dir)
curl https://gerrit.openbmc.org/tools/hooks/commit-msg -o ${gitdir}/hooks/commit-msg
chmod +x ${gitdir}/hooks/commit-msg
@@ -91,7 +91,7 @@
This will enhance the `git commit` command to add a `Change-Id` to your commit
message which Gerrit uses to track the review.
-##### Push Code Change to Gerrit
+### Push Code Change to Gerrit
Now that your workstation and Gerrit are configured, you are ready to make code
changes and push them to Gerrit for code review. Here is what the basic workflow
@@ -108,7 +108,7 @@
- Go to [Gerrit web interface](https://gerrit.openbmc.org/), click on your new
review, and add reviewers based on `OWNERS` file in the repo.
-##### Conclusion
+## Conclusion
If you've completed all of the above steps successfully, that's it! You have now
set up Gerrit and know how to submit your code changes for review!
diff --git a/development/web-ui.md b/development/web-ui.md
index 7ae1df8..ae428c2 100644
--- a/development/web-ui.md
+++ b/development/web-ui.md
@@ -6,7 +6,7 @@
**Prerequisites:** Current Linux, Mac, or Windows system
-# Webui-vue
+## Webui-vue
The [webui-vue](https://github.com/openbmc/webui-vue) repository will replace
phosphor-webui once it is deprecated. Webui-vue uses the
@@ -41,7 +41,7 @@
- State Store
- Theming
-## Load Web UI against QEMU
+### Load Web UI against QEMU
Connect to Web UI in QEMU
@@ -50,7 +50,7 @@
[dev-environment](https://github.com/openbmc/docs/blob/master/development/dev-environment.md).
2. Assuming you used the default of 2443 for the HTTPS port in your QEMU
- session, you will point your web browser to https://localhost:2443.
+ session, you will point your web browser to <https://localhost:2443>.
3. Login with default username and password and verify basic Web UI features are
working as expected.
@@ -58,10 +58,10 @@
**Note** You will need to approve the security exception in your browser to
connect. OpenBMC is running with a self-signed SSL certificate.
-# Phosphor-webui
+## Phosphor-webui
-The [phosphor-webui](https://github.com/openbmc/phosphor-webui) repository
-provides a web-based interface for an OpenBMC. It uses the
+The [phosphor-webui](https://github.com/openbmc/webui-vue) repository provides a
+web-based interface for an OpenBMC. It uses the
[AngularJS](https://angularjs.org/) framework to interact with the BMC via REST
API calls. It allows users to view hardware information, update firmware, set
network settings, and much more.
@@ -72,11 +72,11 @@
Phosphor-webui was built on AngularJS and AngularJS goes End of Life June
30, 2021.
-## Customize Phosphor-webui
+### Customize Phosphor-webui
1. Clone the repository
- ```
+ ```bash
git clone https://github.com/openbmc/phosphor-webui.git
```
@@ -96,19 +96,19 @@
will use to represent your customized version of OpenBMC. Feel free to use
any .png you wish for this step.
- ```
+ ```bash
wget http://www.pngmart.com/files/3/Free-PNG-Transparent-Image.png
```
Copy your new .png into the appropriate directory
- ```
+ ```bash
cp Free-PNG-Transparent-Image.png app/assets/images/
```
Point to that new image in the web UI HTML
- ```
+ ```bash
vi app/login/controllers/login-controller.html
# Replace the logo.svg near the top with Free-PNG-Transparent-Image.png
<img src="../../assets/images/Free-PNG-Transparent-Image.png" class="login__logo" alt="OpenBMC logo" role="img"/>
@@ -116,11 +116,11 @@
Start up the server with your change
- ```
+ ```bash
npm run-script server
```
- Load web browser at https://localhost:8080 and verify your new image is on
+ Load web browser at <https://localhost:8080> and verify your new image is on
the login screen.
Kill your npm run using Ctrl^C.
@@ -131,7 +131,7 @@
Similar to the previous step, modify the appropriate HTML for the header:
- ```
+ ```bash
vi app/common/directives/app-header.html
# Replace logo.svg with Free-PNG-Transparent-Image.png again
<div class="logo__wrapper"><img src="../../assets/images/Free-PNG-Transparent-Image.png" class="header__logo" alt="company logo"/></div>
@@ -139,11 +139,12 @@
Start up the server with your change
- ```
+ ```bash
npm run-script server
```
- Browse to https://localhost:8080 and verify your new image is on the header.
+ Browse to `https://localhost:8080` and verify your new image is on the
+ header.
Note that you will need to log in to view the header. Point the web UI to
your QEMU session by typing the QEMU session (e.g. localhost:2443) in the
@@ -154,5 +155,5 @@
your logo is also something you can easily do to customize your creation of
an OpenBMC system.
- And that's it! You've downloaded, customized, and run the OpenBMC
- phosphor-webui code!
+And that's it! You've downloaded, customized, and run the OpenBMC phosphor-webui
+code!
diff --git a/features.md b/features.md
index 6963e1d..d500b2b 100644
--- a/features.md
+++ b/features.md
@@ -58,8 +58,6 @@
https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md
[hardware diagnostics]:
https://github.com/openbmc/openpower-hw-diags/blob/master/README.md
-[host management]:
- https://github.com/openbmc/docs/blob/master/host-management.md
[host management rest apis]:
https://github.com/openbmc/docs/blob/master/host-management.md
[ipmi in band]:
diff --git a/host-management.md b/host-management.md
index 74fcf93..d339c58 100644
--- a/host-management.md
+++ b/host-management.md
@@ -10,10 +10,10 @@
This document uses token based authentication method:
-```
-$ export bmc=xx.xx.xx.xx
-$ export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
-$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
+```bash
+export bmc=xx.xx.xx.xx
+export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
```
## Inventory
@@ -41,11 +41,15 @@
structure to be accessed. For example, to enumerate all inventory items and
their properties:
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/enumerate
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/enumerate
+```
To list the properties of one item:
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system/chassis/motherboard
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system/chassis/motherboard
+```
## Sensors
@@ -77,7 +81,8 @@
A temperature sensor might look like:
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/temperature/ocp_zone
+```bash
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/temperature/ocp_zone
{
"data": {
"CriticalAlarmHigh": false,
@@ -98,6 +103,7 @@
"message": "200 OK",
"status": "ok"
}
+```
Note the value of this sensor is 34.625C (34625 \* 10^-3).
@@ -106,11 +112,15 @@
To enumerate all sensors in the system:
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/enumerate
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/enumerate
+```
List properties of one inventory item:
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/temperature/outlet
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/sensors/temperature/outlet
+```
## Event Logs
@@ -133,7 +143,8 @@
To list all reported event logs:
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/logging/entry
+```bash
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/logging/entry
{
"data": [
"/xyz/openbmc_project/logging/entry/3",
@@ -147,10 +158,12 @@
"message": "200 OK",
"status": "ok"
}
+```
To read a specific event log:
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/logging/entry/1
+```bash
+ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/logging/entry/1
{
"data": {
"AdditionalData": [
@@ -168,15 +181,20 @@
"message": "200 OK",
"status": "ok"
}
+```
To delete an event log (log 1 in this example), call the `Delete` method on the
event:
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data" : []}' https://${bmc}/xyz/openbmc_project/logging/entry/1/action/Delete
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data" : []}' https://${bmc}/xyz/openbmc_project/logging/entry/1/action/Delete
+```
To clear all event logs, call the top-level `DeleteAll` method:
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data" : []}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data" : []}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
+```
## Host Boot Options
@@ -189,21 +207,21 @@
- Set boot mode:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootMode -d '{"data": "xyz.openbmc_project.Control.Boot.Mode.Modes.Regular"}'
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootMode -d '{"data": "xyz.openbmc_project.Control.Boot.Mode.Modes.Regular"}'
+```
- Set boot source:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootSource -d '{"data": "xyz.openbmc_project.Control.Boot.Source.Sources.Default"}'
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootSource -d '{"data": "xyz.openbmc_project.Control.Boot.Source.Sources.Default"}'
+```
- Set boot type (valid only if host is based on the x86 CPU):
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootType -d '{"data": "xyz.openbmc_project.Control.Boot.Type.Types.EFI"}'
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/BootType -d '{"data": "xyz.openbmc_project.Control.Boot.Type.Types.EFI"}'
+```
Also there are boolean
[`Enable`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Object/Enable.interface.yaml)
@@ -212,15 +230,15 @@
- Set boot override one-time flag:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/one_time/attr/Enabled -d '{"data": "true"}'
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/one_time/attr/Enabled -d '{"data": "true"}'
+```
- Enable boot override:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/Enabled -d '{"data": "true"}'
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT https://${bmc}/xyz/openbmc_project/control/host0/boot/attr/Enabled -d '{"data": "true"}'
+```
## Host State Control
@@ -230,30 +248,30 @@
Assuming you have logged in, the following will power on the host:
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
```
To power off the host:
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.Off"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.State.Host.Transition.Off"}' -X PUT https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
```
To issue a hard power off (accomplished by powering off the chassis):
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Chassis.Transition.Off"}' https://${bmc}//xyz/openbmc_project/state/chassis0/attr/RequestedPowerTransition
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Chassis.Transition.Off"}' https://${bmc}//xyz/openbmc_project/state/chassis0/attr/RequestedPowerTransition
```
To reboot the host:
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Host.Transition.Reboot"}' https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data":"xyz.openbmc_project.State.Host.Transition.Reboot"}' https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
```
More information about Host State Management can be found here:
-https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/State
+<https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/State>
## Host Clear GARD
@@ -266,19 +284,19 @@
- Method 1: From the BMC command line:
- ```
+```bash
busctl call org.open_power.Software.Host.Updater \
/org/open_power/control/gard \
xyz.openbmc_project.Common.FactoryReset Reset
- ```
+```
- Method 2: Using the REST API:
- ```
- $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data":[]}' https://${bmc}/org/open_power/control/gard/action/Reset
+```
-Implementation: https://github.com/openbmc/openpower-pnor-code-mgmt
+Implementation: <https://github.com/openbmc/openpower-pnor-code-mgmt>
## Host Watchdog
@@ -294,8 +312,10 @@
host watchdog service provides 2 files as configuration options into
phosphor-watchdog:
+```text
/lib/systemd/system/phosphor-watchdog@poweron.service.d/poweron.conf
/etc/default/obmc/watchdog/poweron
+```
`poweron.conf` contains the "Conflicts" relationships to ensure the watchdog
service is stopped at the correct times. `poweron` contains the required
@@ -304,8 +324,10 @@
The 2 service files involved with the host watchdog are:
+```text
phosphor-watchdog@poweron.service
obmc-enable-host-watchdog@0.service
+```
`phosphor-watchdog@poweron` starts the host watchdog service and
`obmc-enable-host-watchdog` starts the watchdog timer. Both are run as a part of
diff --git a/kernel-development.md b/kernel-development.md
index ed092f2..6056320 100644
--- a/kernel-development.md
+++ b/kernel-development.md
@@ -5,7 +5,7 @@
requirement, not a hard requirement, and exceptions will be made on a
case-by-case basis. If in doubt, start a discussion on the mailing list.
-The OpenBMC kernel tree is hosted at https://github.com/openbmc/linux and
+The OpenBMC kernel tree is hosted at <https://github.com/openbmc/linux> and
contains the set of patches that we carry. Ideally there would be no patches
carried, as everything should be upstream.
@@ -88,16 +88,16 @@
Before submitting patches it is recommended you boot test on at least the Qemu
platforms, and whatever hardware you have available.
-# Tips and Tricks
+## Tips and Tricks
Some general hints for kernel development
-## Out-of-tree builds
+### Out-of-tree builds
You can build a kernel out of the yocto environment, by using the initramfs
(from a pre-existing yocto build) directly:
-```
+```sh
make ARCH=arm \
O=obj \
CROSS_COMPILE=arm-linux-gnueabihf- \
@@ -111,15 +111,15 @@
The cpio can be found in the following yocto output directory:
-```
+```sh
build/tmp/deploy/images/palmetto/
```
-## Building a uImage
+### Building a uImage
To build a uImage (for example, to netboot):
-```
+```sh
# build a zImage using the obmc rootfs
make ARCH=arm \
O=obj \
diff --git a/maintainer-workflow.md b/maintainer-workflow.md
index cdd92ea..93fe5be 100644
--- a/maintainer-workflow.md
+++ b/maintainer-workflow.md
@@ -8,14 +8,14 @@
on an existing CCLA (corporate).
- Executed CLAs can be found [in the CLA repository][1].
- If you were not added to the appropriate CLA repository ACL send an email to
- openbmc@lists.ozlabs.org with a request to be added.
+ `openbmc@lists.ozlabs.org` with a request to be added.
- If a CLA for the contributor is found, accept the patch(1).
- If a CLA is not found, request that the contributor execute one and send it to
- manager@lfprojects.org.
+ `manager@lfprojects.org`.
- Do not accept the patch(1) until a signed CLA (individual _or_ corporate)
has been uploaded to the CLA repository.
- - The CCLA form can be found [here][2].
- - The ICLA form can be found [here][3].
+ - The CCLA form can be found at [CCLA template][2].
+ - The ICLA form can be found at [ICLA template][3].
An executed OpenBMC CLA is _not_ required to accept contributions to OpenBMC
forks of upstream projects, like the Linux kernel or U-Boot.
diff --git a/meta-layer-guidelines.md b/meta-layer-guidelines.md
index 9323386..d074714 100644
--- a/meta-layer-guidelines.md
+++ b/meta-layer-guidelines.md
@@ -106,9 +106,7 @@
community through the mailing list or discord whether or not the OpenBMC
community would be willing to adopt support and maintenance of said project.
-## Meta layers should not point to OpenBMC specific repositories outside of
-
-https://github.com/openbmc
+## Meta layers should not point to OpenBMC specific repositories outside of <https://github.com/openbmc>
**What defines an OpenBMC specific repository?**
diff --git a/rest-api.md b/rest-api.md
index 39e9de7..8cad489 100644
--- a/rest-api.md
+++ b/rest-api.md
@@ -18,10 +18,10 @@
This tutorial uses token based authentication method:
-```
-$ export bmc=xx.xx.xx.xx
-$ export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
-$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
+```bash
+export bmc=xx.xx.xx.xx
+export token=`curl -k -H "Content-Type: application/json" -X POST https://${bmc}/login -d '{"username" : "root", "password" : "0penBmc"}' | grep token | awk '{print $2;}' | tr -d '"'`
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/...
```
## HTTP GET operations & URL structure
@@ -32,131 +32,145 @@
- To query the attributes of an object, perform a GET request on the object
name, with no trailing slash. For example:
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system
- {
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system
+```
+
+```json
+{
"data": {
- "AssetTag": "",
- "BuildDate": "",
- "Cached": true,
- "FieldReplaceable": true,
- "Manufacturer": "",
- "Model": "",
- "PartNumber": "",
- "Present": true,
- "PrettyName": "",
- "SerialNumber": ""
- },
- "message": "200 OK",
- "status": "ok"
- }
- ```
+ "AssetTag": "",
+ "BuildDate": "",
+ "Cached": true,
+ "FieldReplaceable": true,
+ "Manufacturer": "",
+ "Model": "",
+ "PartNumber": "",
+ "Present": true,
+ "PrettyName": "",
+ "SerialNumber": ""
+ },
+ "message": "200 OK",
+ "status": "ok"
+}
+```
- To query a single attribute, use the `attr/<name>` path. Using the `system`
object from above, we can query just the `Name` value:
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system/attr/Cached
- {
- "data": true,
- "message": "200 OK",
- "status": "ok"
- }
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system/attr/Cached
+```
+
+```json
+{
+ "data": true,
+ "message": "200 OK",
+ "status": "ok"
+}
+```
- When a path has a trailing-slash, the response will list the sub objects of
the URL. For example, using the same object path as above, but adding a slash:
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/
- {
- "data": [
- "/xyz/openbmc_project/Chassis",
- "/xyz/openbmc_project/Hiomapd",
- "/xyz/openbmc_project/Ipmi",
- "/xyz/openbmc_project/certs",
- "/xyz/openbmc_project/console",
- "/xyz/openbmc_project/control",
- "/xyz/openbmc_project/dump",
- "/xyz/openbmc_project/events",
- "/xyz/openbmc_project/inventory",
- "/xyz/openbmc_project/ipmi",
- "/xyz/openbmc_project/led",
- "/xyz/openbmc_project/logging",
- "/xyz/openbmc_project/network",
- "/xyz/openbmc_project/object_mapper",
- "/xyz/openbmc_project/sensors",
- "/xyz/openbmc_project/software",
- "/xyz/openbmc_project/state",
- "/xyz/openbmc_project/time",
- "/xyz/openbmc_project/user"
- ],
- "message": "200 OK",
- "status": "ok"
- }
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/
+```
- This shows that there are 19 children of the `openbmc_project/` object:
- `dump`, `software`, `control`, `network`, `logging`,etc. This can be used with
- the base REST URL (ie., `http://${bmc}/`), to discover all objects in the
- hierarchy.
+```json
+{
+ "data": [
+ "/xyz/openbmc_project/Chassis",
+ "/xyz/openbmc_project/Hiomapd",
+ "/xyz/openbmc_project/Ipmi",
+ "/xyz/openbmc_project/certs",
+ "/xyz/openbmc_project/console",
+ "/xyz/openbmc_project/control",
+ "/xyz/openbmc_project/dump",
+ "/xyz/openbmc_project/events",
+ "/xyz/openbmc_project/inventory",
+ "/xyz/openbmc_project/ipmi",
+ "/xyz/openbmc_project/led",
+ "/xyz/openbmc_project/logging",
+ "/xyz/openbmc_project/network",
+ "/xyz/openbmc_project/object_mapper",
+ "/xyz/openbmc_project/sensors",
+ "/xyz/openbmc_project/software",
+ "/xyz/openbmc_project/state",
+ "/xyz/openbmc_project/time",
+ "/xyz/openbmc_project/user"
+ ],
+ "message": "200 OK",
+ "status": "ok"
+}
+```
+
+This shows that there are 19 children of the `openbmc_project/` object: `dump`,
+`software`, `control`, `network`, `logging`,etc. This can be used with the base
+REST URL (ie., `http://${bmc}/`), to discover all objects in the hierarchy.
- Performing the same query with `/list` will list the child objects
_recursively_.
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/network/list
- {
- "data": [
- "/xyz/openbmc_project/network/config",
- "/xyz/openbmc_project/network/config/dhcp",
- "/xyz/openbmc_project/network/eth0",
- "/xyz/openbmc_project/network/eth0/ipv4",
- "/xyz/openbmc_project/network/eth0/ipv4/3b9faa36",
- "/xyz/openbmc_project/network/eth0/ipv6",
- "/xyz/openbmc_project/network/eth0/ipv6/ff81b6d6",
- "/xyz/openbmc_project/network/eth1",
- "/xyz/openbmc_project/network/eth1/ipv4",
- "/xyz/openbmc_project/network/eth1/ipv4/3b9faa36",
- "/xyz/openbmc_project/network/eth1/ipv4/66e63348",
- "/xyz/openbmc_project/network/eth1/ipv6",
- "/xyz/openbmc_project/network/eth1/ipv6/ff81b6d6",
- "/xyz/openbmc_project/network/host0",
- "/xyz/openbmc_project/network/host0/intf",
- "/xyz/openbmc_project/network/host0/intf/addr",
- "/xyz/openbmc_project/network/sit0",
- "/xyz/openbmc_project/network/snmp",
- "/xyz/openbmc_project/network/snmp/manager"
- ],
- "message": "200 OK",
- "status": "ok"
- }
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/network/list
+```
+
+```json
+{
+ "data": [
+ "/xyz/openbmc_project/network/config",
+ "/xyz/openbmc_project/network/config/dhcp",
+ "/xyz/openbmc_project/network/eth0",
+ "/xyz/openbmc_project/network/eth0/ipv4",
+ "/xyz/openbmc_project/network/eth0/ipv4/3b9faa36",
+ "/xyz/openbmc_project/network/eth0/ipv6",
+ "/xyz/openbmc_project/network/eth0/ipv6/ff81b6d6",
+ "/xyz/openbmc_project/network/eth1",
+ "/xyz/openbmc_project/network/eth1/ipv4",
+ "/xyz/openbmc_project/network/eth1/ipv4/3b9faa36",
+ "/xyz/openbmc_project/network/eth1/ipv4/66e63348",
+ "/xyz/openbmc_project/network/eth1/ipv6",
+ "/xyz/openbmc_project/network/eth1/ipv6/ff81b6d6",
+ "/xyz/openbmc_project/network/host0",
+ "/xyz/openbmc_project/network/host0/intf",
+ "/xyz/openbmc_project/network/host0/intf/addr",
+ "/xyz/openbmc_project/network/sit0",
+ "/xyz/openbmc_project/network/snmp",
+ "/xyz/openbmc_project/network/snmp/manager"
+ ],
+ "message": "200 OK",
+ "status": "ok"
+}
+```
- Adding `/enumerate` instead of `/list` will also include the attributes of the
listed objects.
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/time/enumerate
- {
- "data": {
- "/xyz/openbmc_project/time/bmc": {
- "Elapsed": 1563209492098739
- },
- "/xyz/openbmc_project/time/host": {
- "Elapsed": 1563209492101678
- },
- "/xyz/openbmc_project/time/owner": {
- "TimeOwner": "xyz.openbmc_project.Time.Owner.Owners.BMC"
- },
- "/xyz/openbmc_project/time/sync_method": {
- "TimeSyncMethod": "xyz.openbmc_project.Time.Synchronization.Method.NTP"
- }
- },
- "message": "200 OK",
- "status": "ok"
- }
- ```
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/time/enumerate
+```
+
+```json
+{
+ "data": {
+ "/xyz/openbmc_project/time/bmc": {
+ "Elapsed": 1563209492098739
+ },
+ "/xyz/openbmc_project/time/host": {
+ "Elapsed": 1563209492101678
+ },
+ "/xyz/openbmc_project/time/owner": {
+ "TimeOwner": "xyz.openbmc_project.Time.Owner.Owners.BMC"
+ },
+ "/xyz/openbmc_project/time/sync_method": {
+ "TimeSyncMethod": "xyz.openbmc_project.Time.Synchronization.Method.NTP"
+ }
+ },
+ "message": "200 OK",
+ "status": "ok"
+}
+```
## HTTP PUT operations
@@ -164,9 +178,12 @@
for creating a new resource when the client already knows where to put it. These
require a json formatted payload. To get an example of what that looks like:
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/host0 > host.json
+cat host.json
```
-$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/host0 > host.json
-$ cat host.json
+
+```json
{
"data": {
"AttemptsLeft": 3,
@@ -182,9 +199,12 @@
or
+```bash
+curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition > requested_host.json
+cat requested_host.json
```
-$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition > requested_host.json
-$ cat requested_host.json
+
+```json
{
"data": "xyz.openbmc_project.State.Host.Transition.Off",
"message": "200 OK",
@@ -198,8 +218,8 @@
To make curl use the correct content type header use the -H option to specify
that we're sending JSON data:
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d <json> <url>
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d <json> <url>
```
A PUT operation on an object requires a complete object. For partial updates
@@ -208,7 +228,7 @@
For example, make changes to the requested_host.json file and do a PUT (upload):
-```
+```bash
$ cat requested_host.json
{"data": "xyz.openbmc_project.State.Host.Transition.Off"}
$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -T requested_host.json https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
@@ -216,8 +236,8 @@
Alternatively specify the json inline with -d:
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PUT -d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' https://${bmc}/xyz/openbmc_project/state/host0/attr/RequestedHostTransition
```
When using '-d' just remember that json requires quoting.
@@ -230,14 +250,14 @@
HTTP 403 (Forbidden). These also require a json formatted payload. To delete
logging entries:
-```
-$ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
+```bash
+curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/logging/action/DeleteAll
```
To invoke a method without parameters (Factory Reset of BMC and Host):
-```
-$ curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset
+```bash
+curl -k -H "X-Auth-Token: $token" -H 'Content-Type: application/json' -X POST -d '{"data":[]}' https://${bmc}/xyz/openbmc_project/software/action/Reset
```
## HTTP DELETE operations
@@ -252,14 +272,14 @@
Display logging entries:
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate
```
Then delete the event record with ID 1:
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/1
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X DELETE https://${bmc}/xyz/openbmc_project/logging/entry/1
```
## Uploading images
@@ -270,15 +290,15 @@
For example, to upload an image:(the `<file_to_upload>` must be a tar ball)
-```
-$ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -X POST -T <file_to_upload> https://${bmc}/upload/image
+```bash
+curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -X POST -T <file_to_upload> https://${bmc}/upload/image
```
In above example, the filename on the BMC will be chosen by the REST server.
It is possible for the user to choose the uploaded file's remote name:
-```
+```bash
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -X PUT -T foo https://${bmc}/upload/image/bar
```
@@ -287,7 +307,7 @@
The operation will either return the version id (hash) of the uploaded file on
success:
-```
+```json
{
"data": "afb92384",
"message": "200 OK",
@@ -297,18 +317,18 @@
or an error message
-```
+```json
{
- "data": {
- "description": "Version already exists or failed to be extracted"
- },
- "message": "400 Bad Request",
- "status": "error"
+ "data": {
+ "description": "Version already exists or failed to be extracted"
+ },
+ "message": "400 Bad Request",
+ "status": "error"
}
```
For more details on uploading and updating software, see:
-https://github.com/openbmc/docs/tree/master/architecture/code-update
+<https://github.com/openbmc/docs/tree/master/architecture/code-update>
## Event subscription protocol
@@ -321,14 +341,16 @@
Following is a description of the event subscription protocol, with example JS
code snippets denoting client-side code.
-a) The client needs to have logged on to the BMC. b) The client needs to open a
-secure websocket with the URL <BMC IP>/subscribe.
+a. The client needs to have logged on to the BMC.
-```
- var ws = new WebSocket("wss://<BMC IP>/subscribe")
+b. The client needs to open a secure websocket with the URL
+`<BMC IP>/subscribe`.
+
+```javascript
+var ws = new WebSocket("wss://<BMC IP>/subscribe");
```
-c) The client needs to send, over the websocket, a JSON dictionary, comprising
+c. The client needs to send, over the websocket, a JSON dictionary, comprising
of key-value pairs. This dictionary serves as the "events filter". All the keys
are optional, so the dictionary can be empty if no filtering is desired. The
filters represented by each of the key-value pairs are ORed.
@@ -345,54 +367,55 @@
All of the following are valid:
-```
-var data = JSON.stringify(
-{
- "paths": ["/xyz/openbmc_project/logging", "/xyz/openbmc_project/sensors"],
- "interfaces": ["xyz.openbmc_project.Logging.Entry", "xyz.openbmc_project.Sensor.Value"]
+```javascript
+var data = JSON.stringify({
+ paths: ["/xyz/openbmc_project/logging", "/xyz/openbmc_project/sensors"],
+ interfaces: [
+ "xyz.openbmc_project.Logging.Entry",
+ "xyz.openbmc_project.Sensor.Value",
+ ],
});
-ws.onopen = function() {
- ws.send(data);
+ws.onopen = function () {
+ ws.send(data);
};
```
-```
-var data = JSON.stringify(
-{
- "paths": ["/xyz/openbmc_project/logging", "/xyz/openbmc_project/sensors"],
+```javascript
+var data = JSON.stringify({
+ paths: ["/xyz/openbmc_project/logging", "/xyz/openbmc_project/sensors"],
});
-ws.onopen = function() {
- ws.send(data);
+ws.onopen = function () {
+ ws.send(data);
};
```
-```
-var data = JSON.stringify(
-{
- "interfaces": ["xyz.openbmc_project.Logging.Entry", "xyz.openbmc_project.Sensor.Value"]
+```javascript
+var data = JSON.stringify({
+ interfaces: [
+ "xyz.openbmc_project.Logging.Entry",
+ "xyz.openbmc_project.Sensor.Value",
+ ],
});
-ws.onopen = function() {
- ws.send(data);
+ws.onopen = function () {
+ ws.send(data);
};
```
-```
-var data = JSON.stringify(
-{
-});
-ws.onopen = function() {
- ws.send(data);
+```javascript
+var data = JSON.stringify({});
+ws.onopen = function () {
+ ws.send(data);
};
```
-d) The rest server on the BMC will respond over the websocket when a D-Bus event
+d. The rest server on the BMC will respond over the websocket when a D-Bus event
occurs, considering the client supplied filters. The rest servers notifies about
InterfacesAdded and PropertiesChanged events. The response is a JSON dictionary
as follows :
InterfacesAdded
-```
+```text
"event": InterfacesAdded
"path": <string : new D-Bus path that was created>
"interfaces": <dict : a dictionary of interfaces> (similar to org.freedesktop.DBus.ObjectManager.InterfacesAdded )
@@ -400,7 +423,7 @@
PropertiesChanged
-```
+```text
"event": PropertiesChanged
"path": <string : D-Bus path whose property changed>
"interface": <string : D-Bus interface to which the changed property belongs>
diff --git a/security/TLS-configuration.md b/security/TLS-configuration.md
index b75258b..5e8e2ba 100644
--- a/security/TLS-configuration.md
+++ b/security/TLS-configuration.md
@@ -33,8 +33,8 @@
- issuer name has to match the fully qualified domain name of your OpenBMC host
If you already have certificates you can skip to
-[Enable TLS authentication ](#Enable-TLS-authentication) or go to
-[Verify certificates](#Verify-certificates) and check if they meet the above
+[Enable TLS authentication](#enable-tls-authentication) or go to
+[Verify certificates](#verify-certificates) and check if they meet the above
requirements.
### Prepare configuration files
@@ -49,7 +49,7 @@
at `/etc/ssl/openssl.cnf`. For Cygwin it might be
`/etc/defaults/etc/pki/tls/openssl.cnf` or `/etc/pki/tls/openssl.cnf`.
-```
+```bash
mkdir ~/ca
cd ~/ca
cp /usr/lib/ssl/openssl.cnf openssl-client.cnf
@@ -58,13 +58,13 @@
Then open the client `~/ca/openssl-client.cnf` file in your favorite editor, for
example `vi`.
-```
+```bash
vi ~/ca/openssl-client.cnf
```
Find the sections listed below and add or choose the presented values.
-```
+```bash
[ req ]
req_extensions = v3_req
@@ -79,13 +79,13 @@
Now create a server configuration `openssl-server.cnf` by copying the client
file
-```
+```bash
cp ~/ca/openssl-client.cnf openssl-server.cnf
```
and changing values presented in the sections listed below.
-```
+```bash
[ usr_cert ]
extendedKeyUsage = serverAuth
@@ -97,7 +97,7 @@
`myext-server.cnf` for the client and server certificates respectively. Without
these files no extensions are added to the certificate.
-```
+```bash
cat << END > myext-client.cnf
[ my_ext_section ]
keyUsage = digitalSignature, keyAgreement
@@ -106,7 +106,7 @@
END
```
-```
+```bash
cat << END > myext-server.cnf
[ my_ext_section ]
keyUsage = digitalSignature, keyAgreement
@@ -119,7 +119,7 @@
First we need to create a private key to sign the CA certificate.
-```
+```bash
openssl genrsa -out CA-key.pem 2048
```
@@ -127,7 +127,7 @@
be prompted for information which will be incorporated into the certificate,
such as Country, City, Company Name, etc.
-```
+```bash
openssl req -new -config openssl-client.cnf -key CA-key.pem -x509 -days 1000 -out CA-cert.pem
```
@@ -138,7 +138,7 @@
Generate a new key that will be used to sign the certificate signing request:
-```
+```bash
openssl genrsa -out client-key.pem 2048
```
@@ -148,14 +148,14 @@
provide **the OpenBMC system user name** for the `CommonName` attribute of this
certificate. In this example, use **root**.
-```
+```bash
openssl req -new -config openssl-client.cnf -key client-key.pem -out signingReqClient.csr
```
Sign the certificate using your `CA-cert.pem` certificate with following
command:
-```
+```bash
openssl x509 -req -extensions my_ext_section -extfile myext-client.cnf -days 365 -in signingReqClient.csr -CA CA-cert.pem -CAkey CA-key.pem -CAcreateserial -out client-cert.pem
```
@@ -164,13 +164,13 @@
### Create server certificate signed by given CA certificate
For convenience we will use the same CA generated in paragraph
-[Create a new CA certificate](#Create-a-new-CA-certificate), although a
+[Create a new CA certificate](#create-a-new-ca-certificate), although a
different one could be used.
Generate a new key that will be used to sign the server certificate signing
request:
-```
+```bash
openssl genrsa -out server-key.pem 2048
```
@@ -179,17 +179,17 @@
name of your OpenBMC server** for the `CommonName` attribute of this
certificate. In this example it will be `bmc.example.com`. A wildcard can be
used to protect multiple host, for example a certificate configured for
-`*.example.com` will secure www.example.com, as well as mail.example.com,
+`*.example.com` will secure `www.example.com`, as well as `mail.example.com`,
blog.example.com, and others.
-```
+```bash
openssl req -new -config openssl-server.cnf -key server-key.pem -out signingReqServer.csr
```
Sign the certificate using your `CA-cert.pem` certificate with following
command:
-```
+```bash
openssl x509 -req -extensions my_ext_section -extfile myext-server.cnf -days 365 -in signingReqServer.csr -CA CA-cert.pem -CAkey CA-key.pem -CAcreateserial -out server-cert.pem
```
@@ -200,7 +200,7 @@
To verify the signing request and both certificates you can use following
commands.
-```
+```bash
openssl x509 -in CA-cert.pem -text -noout
openssl x509 -in client-cert.pem -text -noout
openssl x509 -in server-cert.pem -text -noout
@@ -219,12 +219,12 @@
- `Subject` CN in `client-cert.pem`, it should match existing OpemBMC user name.
In this example it is **root**.
- `Subject` CN in `server-cert.pem`, it should match OpemBMC host name. In this
- example it is **bmc.example.com **. (see rfc 3280 4.2.1.11 for name
+ example it is **bmc.example.com**. (see rfc 3280 4.2.1.11 for name
constraints)
Below are fragments of generated certificates that you can compare with.
-```
+```text
CA-cert.pem
Data:
Version: 3 (0x2)
@@ -259,7 +259,7 @@
ee:d3:78:84
```
-```
+```text
client-cert.pem
Data:
Version: 3 (0x2)
@@ -294,7 +294,7 @@
56:57:4c:6a
```
-```
+```text
server-cert.pem
Data:
Version: 3 (0x2)
@@ -338,7 +338,7 @@
endings as `\n`. The command below prepares a whole POST body and puts it into a
file named: `install_ca.json`.
-```
+```bash
cat << END > install_ca.json
{
"CertificateString":"$(cat CA-cert.pem | sed -n -e '1h;1!H;${x;s/\n/\\n/g;p;}')",
@@ -353,7 +353,7 @@
Where `${bmc}` should be `bmc.example.com`. It is convenient to export it as an
environment variable.
-```
+```bash
curl --user root:0penBmc -d @install_ca.json -k -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Managers/bmc/Truststore/Certificates
```
@@ -364,7 +364,7 @@
After successful certificate installation you should get positive HTTP response
and a new certificate should be available under this resource collection.
-```
+```bash
curl --user root:0penBmc -k https://${bmc}/redfish/v1/Managers/bmc/Truststore/Certificates
```
@@ -374,7 +374,7 @@
Additionally we must upload to OpenBMC the private key that was used to sign the
server certificate. A proper message mody can be prepared the with this command:
-```
+```bash
cat << END > replace_cert.json
{
"CertificateString":"$(cat server-key.pem server-cert.pem | sed -n -e '1h;1!H;${x;s/\n/\\n/g;p;}')",
@@ -390,7 +390,7 @@
To replace the server certificate on the OpenBMC server post the content of
`replace_cert.json` with this command:
-```
+```bash
curl --user root:0penBmc -d @replace_cert.json -k -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate/
```
@@ -399,7 +399,7 @@
To check current state of the TLS authentication method use this command:
-```
+```bash
curl --user root:0penBmc -k https://${bmc}/redfish/v1/AccountService
```
@@ -407,13 +407,13 @@
To enable TLS authentication use this command:
-```
+```bash
curl --user root:0penBmc -k -X PATCH -H "Content-Type: application/json" --data '{"Oem": {"OpenBMC": {"AuthMethods": { "TLS": true} } } }' https://${bmc}/redfish/v1/AccountService
```
To disable TLS authentication use this command:
-```
+```bash
curl --user root:0penBmc -k -X PATCH -H "Content-Type: application/json" --data '{"Oem": {"OpenBMC": {"AuthMethods": { "TLS": false} } } }' https://${bmc}/redfish/v1/AccountService
```
@@ -428,7 +428,7 @@
was replaced it should be possible to execute curl requests using only client
certificate, key, and CA like below.
-```
+```bash
curl --cert client-cert.pem --key client-key.pem -vvv --cacert CA-cert.pem https://${bmc}/redfish/v1/SessionService/Sessions
```
@@ -441,7 +441,7 @@
when TLS is disabled or certificates are invalid.
- Certificates do not meet the requirements. See paragraphs
- [Verify certificates](#Verify-certificates).
+ [Verify certificates](#verify-certificates).
- Attempting to load the same certificate twice will end up with an error.
diff --git a/security/how-to-report-a-security-vulnerability.md b/security/how-to-report-a-security-vulnerability.md
index 3bc3589..b5bf04e 100644
--- a/security/how-to-report-a-security-vulnerability.md
+++ b/security/how-to-report-a-security-vulnerability.md
@@ -50,7 +50,7 @@
- Coordinate announcement details with you, such as timing or how you want to be
credited.
- At the agreed time, publish the OpenBMC security advisory, reveal the fix, and
- publish the CVE.
+ publish the [CVE][].
Please refer to the [CERT Guide to Coordinated Vulnerability Disclosure][],
(SPECIAL REPORT CMU/SEI-2017-SR-022) for additional considerations.
diff --git a/security/network-security-considerations.md b/security/network-security-considerations.md
index e9ebff3..2360732 100644
--- a/security/network-security-considerations.md
+++ b/security/network-security-considerations.md
@@ -106,12 +106,11 @@
surface. For example, a large scale data center may not need a Web interface.
Services can be disabled in several ways:
-1. Configure OpenBMC recipes to build the unwanted feature out of the BMC's
- firmware image. This gives the BMC the advantage of a smaller attack
- surface.
-2. Implement something like the [Redfish ManagerNetworkProtocol][] properties
- for IPMI, SSH, and other BMC services, possibly by using shell commands like
- 'systemctl disable ipmid' and 'systemctl stop ipmid'.
+1. Configure OpenBMC recipes to build the unwanted feature out of the BMC's
+ firmware image. This gives the BMC the advantage of a smaller attack surface.
+2. Implement something like the [Redfish ManagerNetworkProtocol][] properties
+ for IPMI, SSH, and other BMC services, possibly by using shell commands like
+ 'systemctl disable ipmid' and 'systemctl stop ipmid'.
[redfish managernetworkprotocol]:
https://redfish.dmtf.org/schemas/ManagerNetworkProtocol.v1_4_0.json
@@ -168,12 +167,12 @@
BMCWeb controls which HTTPS transport layer security (TLS) ciphers it offers via
compile-time header file `include/ssl_key_handler.hpp` in the
-https://github.com/openbmc/bmcweb repository. The implementation is provided by
-OpenSSL.
+<https://github.com/openbmc/bmcweb> repository. The implementation is provided
+by OpenSSL.
BMCWeb provides appropriate HTTP response headers, for example, in header file
`include/security_headers_middleware.hpp` and `crow/include/crow/websocket.h` in
-the https://github.com/openbmc/bmcweb repository.
+the <https://github.com/openbmc/bmcweb> repository.
[bmcweb configuration]: https://github.com/openbmc/bmcweb#configuration
[owasp application security]:
@@ -183,14 +182,13 @@
BMCWeb offers three authentication methods:
-1. The Redfish SessionService, which takes a username and password and provides
- an X-Auth token.
-2. The Phosphor D-Bus REST interface '/login' URI, which takes a username and
- password and provides a session cookie. This method is deprecated in
- OpenBMC.
-3. Basic Access Authentication, which takes a username and password (often URL
- encoded like https://user:pass@host/...) in an "Authorization" request
- header, and returns no credentials. This method is deprecated by RFC 3986.
+1. The Redfish SessionService, which takes a username and password and provides
+ an X-Auth token.
+2. The Phosphor D-Bus REST interface '/login' URI, which takes a username and
+ password and provides a session cookie. This method is deprecated in OpenBMC.
+3. Basic Access Authentication, which takes a username and password (often URL
+ encoded like `https://user:pass@host/...`) in an "Authorization" request
+ header, and returns no credentials. This method is deprecated by RFC 3986.
The username and password are presented to phosphor-user-manager for
authentication.
@@ -201,11 +199,11 @@
tokens are required to use POST, PUT, PATCH, or DELETE methods.
General security considerations for REST APIs apply:
-https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/REST_Security_Cheat_Sheet.md
+<https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/REST_Security_Cheat_Sheet.md>
Redfish provides security considerations in the "Security Detail" section of the
"Redfish Specification" (document ID DSP0266) available from
-https://www.dmtf.org/standards/redfish.
+<https://www.dmtf.org/standards/redfish>.
#### The webui-vue Web application
@@ -235,7 +233,7 @@
### TCP and UDP ports 5355 - mDNS service discovery
General security considerations for service discovery apply. For example,
-described here: https://attack.mitre.org/techniques/T1046/
+described here: <https://attack.mitre.org/techniques/T1046/>
### UDP port 427 - SLP, Avahi
@@ -244,13 +242,13 @@
### UDP port 623 - IPMI RCMP
The IPMI network-facing design is described here:
-https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md
+<https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md>
and the implementation is described here:
-https://github.com/openbmc/phosphor-net-ipmid. Note that host IPMI is outside
+<https://github.com/openbmc/phosphor-net-ipmid>. Note that host IPMI is outside
the scope of this document.
General security considerations for IPMI apply. For example, described here:
-https://www.us-cert.gov/ncas/alerts/TA13-207A
+<https://www.us-cert.gov/ncas/alerts/TA13-207A>
OpenBMC implements RCMP+ and IPMI 2.0. The phosphor-user-manager provides the
underlying authentication mechanism.
diff --git a/security/obmc-github-security-advisory-template.md b/security/obmc-github-security-advisory-template.md
index 76a8448..49f55e5 100644
--- a/security/obmc-github-security-advisory-template.md
+++ b/security/obmc-github-security-advisory-template.md
@@ -9,10 +9,12 @@
[security response team guidelines]: ./obmc-security-response-team-guidelines.md
-### Affected Product
+## Affected Product
-Ecosystem: Other OpenBMC Package name: <TBD> Affected versions: 2.9 Patched
-versions: <TBD>
+- Ecosystem: Other
+- OpenBMC Package name: `TBD`
+- Affected versions: 2.9
+- Patched versions: `TBD`
## Severity
@@ -20,7 +22,7 @@
## CWE
-<TBD>
+`TBD`
## CVE identifier
diff --git a/security/obmc-security-response-team-guidelines.md b/security/obmc-security-response-team-guidelines.md
index 2a3f615..2f1367d 100644
--- a/security/obmc-security-response-team-guidelines.md
+++ b/security/obmc-security-response-team-guidelines.md
@@ -57,9 +57,10 @@
- Privately engage an OpenBMC maintainer or subject matter expert.
3. For OpenBMC problems.
- 1. Determine if this is a high severity problem. Example using CVSS metrics:
- a remotely exploitable or low complexity attack that has high impact to
- the BMC's confidentiality, integrity, or availability.
+ 1. Determine if this is a high severity problem. Example using [CVSS
+ metrics](cvss metrics): a remotely exploitable or low complexity attack
+ that has high impact to the BMC's confidentiality, integrity, or
+ availability.
2. Avoid pre-announcing problems. Be especially careful with high severity
problems. When fixing the problem, use the contribution process but limit
the details in the issue or use a private channel to discuss.
@@ -76,7 +77,7 @@
Repository maintainer process steps: 1. Create a private gerrit code review and
oversee development of the fix. 2. Create a draft advisory under
-github.com/openbmc/<REPO>/security/advisories. Please follow guidance in the
+`github.com/openbmc/<REPO>/security/advisories`. Please follow guidance in the
[OpenBMC Security Advisory Template][]. Add the openbmc security-response group
and other stakeholders to the advisory. 3. Review the security bulletin with
stakeholders to get it ready to publish. 4. Work with the SRT to identify CVEs.
@@ -119,7 +120,7 @@
## Template: OpenBMC Security Advisory
-```
+```text
OpenBMC Security Advisory
Title: ...
@@ -143,7 +144,7 @@
When the Security Advisory is created, inform the OpenBMC community by sending
email like this:
-```
+```text
TO: openbmc-security@lists.ozlabs.org, openbmc@lists.ozlabs.org
SUBJECT: [Security Advisory] ${subject}
@@ -160,9 +161,9 @@
Some of these guidelines were collected from:
-- https://bestpractices.coreinfrastructure.org/en/projects/34
-- https://www.kernel.org/doc/html/v4.16/admin-guide/security-bugs.html
-- https://oss-security.openwall.org/wiki/mailing-lists/distros
+- <https://bestpractices.coreinfrastructure.org/en/projects/34>
+- <https://www.kernel.org/doc/html/v4.16/admin-guide/security-bugs.html>
+- <https://oss-security.openwall.org/wiki/mailing-lists/distros>
- [ISO/IEC 29147:2018 vulnerability disclosure](https://www.iso.org/standard/72311.html)
## Team composition and email maintenance
@@ -207,11 +208,11 @@
This email list is for privately reporting OpenBMC security vulnerabilities.
List membership is limited to the OpenBMC security response team. For more
information, see
-https://github.com/openbmc/docs/blob/master/security/how-to-report-a-security-vulnerability.md
+<https://github.com/openbmc/docs/blob/master/security/how-to-report-a-security-vulnerability.md>
Sample response for denying list membership:
-```
+```text
Thanks for your interest in OpenBMC security. Subscriptions to the
openbmc-security@lists.ozlabs.org email list are by invitation only
and are typically extended only to security response team members.
diff --git a/security/obmc-security-response-team.md b/security/obmc-security-response-team.md
index d2605a9..f6b339f 100644
--- a/security/obmc-security-response-team.md
+++ b/security/obmc-security-response-team.md
@@ -13,16 +13,16 @@
The basic workflow is:
-1. A community member reports a problem privately to the security response team
- (and to the repository maintainers if known).
-2. The responders (including the security response team, the repository
- maintainers, and the problem submitter) work to understand the problem.
-3. The repository maintainer creates an OpenBMC security advisory which
- explains the problem, its severity, and how to protect your systems that
- were built on OpenBMC.
-4. The responders privately engage community members to create workarounds and
- fixes and to negotiate disclosure dates.
-5. The OpenBMC security advisory is published along with any accompanying CVEs.
+1. A community member reports a problem privately to the security response team
+ (and to the repository maintainers if known).
+2. The responders (including the security response team, the repository
+ maintainers, and the problem submitter) work to understand the problem.
+3. The repository maintainer creates an OpenBMC security advisory which explains
+ the problem, its severity, and how to protect your systems that were built on
+ OpenBMC.
+4. The responders privately engage community members to create workarounds and
+ fixes and to negotiate disclosure dates.
+5. The OpenBMC security advisory is published along with any accompanying CVEs.
Note that the OpenBMC security response team is distinct from the OpenBMC
security working group which remains completely open.
diff --git a/testing/local-ci-build.md b/testing/local-ci-build.md
index 08fdfd4..65b3e2d 100644
--- a/testing/local-ci-build.md
+++ b/testing/local-ci-build.md
@@ -108,7 +108,7 @@
find where we call `docker run`, way down at the bottom. Add an additional
argument, remembering to escape the newline ('\'):
-```
+```bash
PHOSPHOR_IPMI_HOST_PATH="/my/dir/for/phosphor-host-ipmid"
docker run --blah-blah-existing-flags \
@@ -143,7 +143,7 @@
# Now run the Docker container normally
```
-#### Interactive Docker Session
+### Interactive Docker Session
To use an interactive session, you can pass the flag `INTERACTIVE=true` to
`run-unit-test-docker.sh` which will drop you into a bash shell with a default
diff --git a/testing/run-test-docker.md b/testing/run-test-docker.md
index b87ac30..04e0302 100644
--- a/testing/run-test-docker.md
+++ b/testing/run-test-docker.md
@@ -30,11 +30,12 @@
`./scripts/build-qemu-robot-docker.sh`
- ###### _Note: When your Docker is behind a proxy, add the following parameters to the build command (use proper IP and PORT values.)_
+**Note:** When your Docker is behind a proxy, add the following parameters to
+the build command (use proper IP and PORT values.)
- ```
+```bash
--build-arg http_proxy=<IP>:<PORT> --build-arg https_proxy=<IP>:<PORT>
- ```
+```
## Code update process using robot test code
@@ -48,39 +49,40 @@
3. Execute docker run to initiate BMC code update.
- ###### _Note: Download BMC fw image file (_.all.tar) before executing this. BMC_IMG_PATH below points to this downloaded file.
+ **Note:** Download BMC fw image file (`_.all.tar`) before executing this.
+ `BMC\*IMG_PATH` below points to this downloaded file.
- ```
+ ```bash
docker run --user root \
- --env HOME=${HOME} \
- --workdir ${HOME} \
- --volume ${HOME}/OpenBMC_Automation:${HOME} \
- --tty openbmc/ubuntu-robot-qemu python -m robot \
- -v OPENBMC_HOST:<BMC IP> \
- -v FILE_PATH:<BMC_IMG_PATH> \
- -i Initiate_Code_Update_BMC \
- ${HOME}/openbmc-test-automation/extended/code_update/update_bmc.robot
+ --env HOME=${HOME} \
+ --workdir ${HOME} \
+ --volume ${HOME}/OpenBMC_Automation:${HOME} \
+ --tty openbmc/ubuntu-robot-qemu python -m robot \
+ -v OPENBMC_HOST:<BMC IP> \
+ -v FILE_PATH:<BMC_IMG_PATH> \
+ -i Initiate_Code_Update_BMC \
+ ${HOME}/openbmc-test-automation/extended/code_update/update_bmc.robot
```
Example to run BMC code update using witherspoon-20170614071422.all.tar image
file from HOME directory of the system where docker run command is executed:
- ```
+ ```bash
docker run --user root \
- --env HOME=${HOME} \
- --workdir ${HOME} \
- --volume ${HOME}/OpenBMC_Automation:${HOME} \
- --tty openbmc/ubuntu-robot-qemu python -m robot \
- -v OPENBMC_HOST:1.11.222.333 \
- -v FILE_PATH:/home/witherspoon-20170614071422.all.tar \
- -i Initiate_Code_Update_BMC \
- ${HOME}/openbmc-test-automation/extended/code_update/update_bmc.robot
+ --env HOME=${HOME} \
+ --workdir ${HOME} \
+ --volume ${HOME}/OpenBMC_Automation:${HOME} \
+ --tty openbmc/ubuntu-robot-qemu python -m robot \
+ -v OPENBMC_HOST:1.11.222.333 \
+ -v FILE_PATH:/home/witherspoon-20170614071422.all.tar \
+ -i Initiate_Code_Update_BMC \
+ ${HOME}/openbmc-test-automation/extended/code_update/update_bmc.robot
```
4. On code update completion, logs generated from robot framework execution will
be available in the following location:
- ```
+ ```bash
${HOME}/OpenBMC_Automation/log.html
${HOME}/OpenBMC_Automation/report.html
${HOME}/OpenBMC_Automation/output.xml
@@ -90,41 +92,42 @@
1. Execute docker run to execute OpenBMC automation test cases.
- ###### _Note: This runs a Docker container using openbmc/ubuntu-robot-qemu image._
+ **Note:** This runs a Docker container using openbmc/ubuntu-robot-qemu image.
- ###### _Robot test code is extracted and ran on this container using run-robot.sh script._
+ Robot test code is extracted and ran on this container using run-robot.sh
+ script.
- ```
+ ```bash
docker run --user root \
- --env HOME=${HOME} \
- --env IP_ADDR=<BMC IP> \
- --env SSH_PORT=22 \
- --env HTTPS_PORT=443 \
- --env ROBOT_TEST_CMD="tox -e <System Type> -- <Robot Cmd>" \
- --workdir ${HOME} \
- --volume ${WORKSPACE}:${HOME} \
- --tty openbmc/ubuntu-robot-qemu \
- ${HOME}/openbmc-build-scripts/scripts/run-robot.sh
+ --env HOME=${HOME} \
+ --env IP_ADDR=<BMC IP> \
+ --env SSH_PORT=22 \
+ --env HTTPS_PORT=443 \
+ --env ROBOT_TEST_CMD="tox -e <System Type> -- <Robot Cmd>" \
+ --workdir ${HOME} \
+ --volume ${WORKSPACE}:${HOME} \
+ --tty openbmc/ubuntu-robot-qemu \
+ ${HOME}/openbmc-build-scripts/scripts/run-robot.sh
```
Example to run entire test suite:
- ```
+ ```bash
docker run --user root \
- --env HOME=${HOME} \
- --env IP_ADDR=1.11.222.333 \
- --env SSH_PORT=22 \
- --env HTTPS_PORT=443 \
- --env ROBOT_TEST_CMD="tox -e witherspoon -- tests" \
- --workdir ${HOME} \
- --volume ${HOME}/OpenBMC_Automation:${HOME} \
- --tty openbmc/ubuntu-robot-qemu \
- ${HOME}/openbmc-build-scripts/scripts/run-robot.sh
+ --env HOME=${HOME} \
+ --env IP_ADDR=1.11.222.333 \
+ --env SSH_PORT=22 \
+ --env HTTPS_PORT=443 \
+ --env ROBOT_TEST_CMD="tox -e witherspoon -- tests" \
+ --workdir ${HOME} \
+ --volume ${HOME}/OpenBMC_Automation:${HOME} \
+ --tty openbmc/ubuntu-robot-qemu \
+ ${HOME}/openbmc-build-scripts/scripts/run-robot.sh
```
2. After the execution, test results will be available in below files.
- ```
+ ```bash
${HOME}/OpenBMC_Automation/log.html
${HOME}/OpenBMC_Automation/report.html
${HOME}/OpenBMC_Automation/output.xml`
diff --git a/tof/contract.md b/tof/contract.md
index fedde9a..bdf0a8d 100644
--- a/tof/contract.md
+++ b/tof/contract.md
@@ -42,8 +42,9 @@
## Current members
-The current TOF members and terms are maintained
-[here](https://github.com/openbmc/docs/blob/master/tof/membership-and-voting.md#terms-and-elections).
+The current TOF members and terms are maintained in the
+[TOF membership](https://github.com/openbmc/docs/blob/master/tof/membership-and-voting.md#terms-and-elections)
+doc.
The TOF shall have a minimum of 5 and maximum of 9 members at any given time.
diff --git a/yocto-development.md b/yocto-development.md
index 9cf2040..28d81bb 100644
--- a/yocto-development.md
+++ b/yocto-development.md
@@ -58,7 +58,7 @@
Run the devtool command to add your repo to the workspace. In my example I have
a repo out on GitHub that contains my code.
-```
+```bash
devtool add welcome https://github.com/causten/hello.git
```
@@ -68,8 +68,8 @@
Add/Modify these lines.
-```
-do_install () {
+```bash
+do_install() {
install -m 0755 -d ${D}${bindir} ${D}${datadir}/welcome
install -m 0644 ${S}/hello ${D}${bindir}
install -m 0644 ${S}/README.md ${D}${datadir}/welcome/
@@ -82,7 +82,7 @@
The Final Step is to tell BitBake that you need the `welcome` recipe
-```
+```bash
vim conf/local.conf
IMAGE_INSTALL_append = " welcome"
```
@@ -98,14 +98,14 @@
In my example to check if README.md was going to be added just do...
-```
+```bash
ls build/tmp/work/${MACHINE}-openbmc-linux-gnueabi/obmc-phosphor-image/1.0-r0/rootfs/usr/share/welcome/README.md
```
NXP wrote a few examples of [useful](https://community.nxp.com/docs/DOC-94953)
commands with BitBake that find the file too
-```
+```bash
bitbake -g obmc-phosphor-image && cat pn-depends.dot |grep welcome
```