prettier: re-format
Prettier is enabled in openbmc-build-scripts on Markdown, JSON, and YAML
files to have consistent formatting for these file types. Re-run the
formatter on the whole repository.
Change-Id: I35ec9c19ae581e4dd00b515c1bba3a9c1862eeb1
Signed-off-by: Patrick Williams <patrick@stwcx.xyz>
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 153f371..ab6b8fa 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,5 +1,4 @@
-Contributing to OpenBMC
-=======================
+# Contributing to OpenBMC
First off, thanks for taking the time to contribute! The following is a set of
guidelines for contributing to an OpenBMC repository which are hosted in the
@@ -16,12 +15,11 @@
## Inclusive Naming
OpenBMC relies on the Open Compute Project to provide guidelines on inclusive
-naming. The OCP guidelines can be found here:
+naming. The OCP guidelines can be found here:
https://www.opencompute.org/documents/ocp-terminology-guidelines-for-inclusion-and-openness
-Structure
----------
+## Structure
OpenBMC has quite a modular structure, consisting of small daemons with a
limited set of responsibilities. These communicate over D-Bus with other
@@ -30,25 +28,24 @@
The BMC's interfaces to the external world are typically through a separate
daemon, which then translates those requests to D-Bus messages.
-These separate projects are then compiled into the final system by the
-overall 'openbmc' build infrastructure.
+These separate projects are then compiled into the final system by the overall
+'openbmc' build infrastructure.
For future development, keep this design in mind. Components' functionality
-should be logically grouped, and keep related parts together where it
-makes sense.
+should be logically grouped, and keep related parts together where it makes
+sense.
-Starting out
-------------
+## Starting out
Before you make a contribution, execute one of the OpenBMC Contributor License
Agreements, _One time only_:
-* [Individual CLA](https://drive.google.com/file/d/1k3fc7JPgzKdItEfyIoLxMCVbPUhTwooY)
-* [Corporate CLA](https://drive.google.com/file/d/1d-2M8ng_Dl2j1odsvZ8o1QHAdHB-pNSH)
+- [Individual CLA](https://drive.google.com/file/d/1k3fc7JPgzKdItEfyIoLxMCVbPUhTwooY)
+- [Corporate CLA](https://drive.google.com/file/d/1d-2M8ng_Dl2j1odsvZ8o1QHAdHB-pNSH)
-If you work for someone, consider asking them to execute the corporate CLA.
-This 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.
+If you work for someone, consider asking them to execute the corporate CLA. This
+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.
@@ -63,46 +60,48 @@
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 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 review comment.
+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
+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
+review comment.
-Coding style
-------------
+## Coding style
-Components of the OpenBMC sources should have a consistent style. If the
-source is coming from another project, we choose to follow the existing style
-of the upstream project. Otherwise, conventions are chosen based on the
-language.
+Components of the OpenBMC sources should have a consistent style. If the source
+is coming from another project, we choose to follow the existing style of the
+upstream project. Otherwise, conventions are chosen based on the language.
### Python
-Python source should all conform to PEP8. This style is well established
-within the Python community and can be verified with the 'pycodestyle' tool.
+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/
### Python Formatting
-If a repository has a setup.cfg file present in its root directory,
-then CI will automatically verify the Python code meets the [pycodestyle](http://pycodestyle.pycqa.org/en/latest/intro.html)
-requirements. This enforces PEP 8 standards on all Python code.
+If a repository has a setup.cfg file present in its root directory, then CI will
+automatically verify the Python code meets the
+[pycodestyle](http://pycodestyle.pycqa.org/en/latest/intro.html) requirements.
+This enforces PEP 8 standards on all Python code.
OpenBMC standards for Python match with PEP 8 so in general, a blank setup.cfg
-file is all that's needed. If so desired, enforcement of 80
-(vs. the default 79) chars is fine as well:
+file is all that's needed. If so desired, enforcement of 80 (vs. the default 79)
+chars is fine as well:
+
```
[pycodestyle]
max-line-length = 80
```
+
By default, pycodestyle does not enforce the following rules: E121, E123, E126,
E133, E226, E241, E242, E704, W503, and W504. These rules are ignored because
they are not unanimously accepted and PEP 8 does not enforce them. It is at the
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:
+
```
[pycodestyle]
ignore= NONE
@@ -124,15 +123,15 @@
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:
- - Indent with tabs instead of spaces, set at 8 columns
+- Indent with tabs instead of spaces, set at 8 columns
- - 80-column lines
+- 80-column lines
- - Opening braces on the end of a line, except for functions
+- Opening braces on the end of a line, except for functions
This style can mostly be verified with 'astyle' as follows:
@@ -142,23 +141,21 @@
See [C++ Style and Conventions](./cpp-style-and-conventions.md).
-Planning changes
-----------------
+## Planning changes
-If you are making a nontrivial change, you should plan how to
-introduce it to the OpenBMC development community.
+If you are making a nontrivial change, you should plan how to introduce it to
+the OpenBMC development community.
-If you are planning a new function, you should get agreement that your
-change will be accepted. As early as you can, introduce the change
-via the OpenBMC Discord server or email list to start
-the discussion. You may find a better way to do what you need.
+If you are planning a new function, you should get agreement that your change
+will be accepted. As early as you can, introduce the change via the OpenBMC
+Discord server or email list to start the discussion. You may find a better way
+to do what you need.
-If the feedback seems favorable or requests more details, continue
-by submitting the design to gerrit starting with a copy of the
+If the feedback seems favorable or requests more details, continue by submitting
+the design to gerrit starting with a copy of the
[design_template](https://github.com/openbmc/docs/blob/master/designs/design-template.md).
-Submitting changes
-------------------
+## Submitting changes
We use git for almost everything. Most projects in OpenBMC use Gerrit to review
patches. Changes to an upstream project (e.g. Yocto Project, systemd, or the
@@ -168,33 +165,35 @@
A good commit does exactly one thing. We prefer many small, atomic commits to
one large commit which makes many functional changes.
- - Too large: "convert foo to new API; also fix CVE 1234 in bar"
- - Too small: "move abc.h to top of include list" and "move xyz.h to bottom of
- include list"
- - Just right: "convert foo to new API" and "convert foo from tab to space"
+
+- Too large: "convert foo to new API; also fix CVE 1234 in bar"
+- Too small: "move abc.h to top of include list" and "move xyz.h to bottom of
+ include list"
+- Just right: "convert foo to new API" and "convert foo from tab to space"
Other commit tips:
- - If your change has a specification, sketch out your ideas first
- and work to get that accepted before completing the details.
- - Work at most a few days before seeking review.
- - Commit and review header files before writing code.
- - Commit and review each implementation module separately.
+
+- If your change has a specification, sketch out your ideas first and work to
+ get that accepted before completing the details.
+- Work at most a few days before seeking review.
+- Commit and review header files before writing code.
+- Commit and review each implementation module separately.
Often, creating small commits this way results in many commits that are
dependent on prior commits; Gerrit handles this situation well, so feel free to
push commits which are based on your change still in review. However, when
possible, your commit should stand alone on top of master - "Fix whitespace in
bar()" does not need to depend on "refactor foo()". Said differently, ensure
-that topics that are not related to each other semantically are also not
-related to each other in Git until they are merged into master.
+that topics that are not related to each other semantically are also not related
+to each other in Git until they are merged into master.
When pushing a stack of patches, these commits will show up with that same
relationship in Gerrit. This means that each patch must be merged in order of
that relationship. So if one of the patches in the middle needs to be changed,
all the patches from that point on would need to be pushed to maintain the
-relationship. This will effectively rebase the unchanged patches, which would
-in turn trigger a new CI build. Ideally, changes from the entire patchset could
-be done all in one go to reduce unnecessary rebasing.
+relationship. This will effectively rebase the unchanged patches, which would in
+turn trigger a new CI build. Ideally, changes from the entire patchset could be
+done all in one go to reduce unnecessary rebasing.
When someone makes a comment on your commit in Gerrit, modify that commit and
send it again to Gerrit. This typically involves `git rebase --interactive` or
@@ -211,19 +210,19 @@
[testing documentation](https://github.com/openbmc/docs/blob/master/testing/local-ci-build.md)
for help writing tests, as well as best practices.
-Ensure that your patch doesn't change unrelated areas. Be careful of
-accidental whitespace changes - this makes review unnecessarily difficult.
+Ensure that your patch doesn't change unrelated areas. Be careful of accidental
+whitespace changes - this makes review unnecessarily difficult.
### Formatting Commit Messages
Your commit message should explain:
- - Concisely, *what* change are you making? e.g. "libpldm: Add APIs to enable
- PLDM Requester" This first line of your commit message is the subject line.
- - Comprehensively, *why* are you making that change? In some cases, like a
- small refactor, the why is fairly obvious. But in cases like the inclusion of
- a new feature, you should explain why the feature is needed.
- - Concisely, *how* did you test? (see below).
+- Concisely, _what_ change are you making? e.g. "libpldm: Add APIs to enable
+ PLDM Requester" This first line of your commit message is the subject line.
+- Comprehensively, _why_ are you making that change? In some cases, like a small
+ refactor, the why is fairly obvious. But in cases like the inclusion of a new
+ feature, you should explain why the feature is needed.
+- Concisely, _how_ did you test? (see below).
Try to include the component you are changing at the front of your subject line;
this typically comes in the form of the class, module, handler, or directory you
@@ -236,37 +235,36 @@
Exceptions to this are allowed in the form of links, which can be represented in
the form of:
-'''
-This implements [1]
+''' 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 below). This line must include the full name you commonly use, often a
-given name and a family name or surname. (ok: Sam Samuelsson, Robert A.
-Heinlein; not ok: xXthorXx, Sam, RAH)
+you the contributor have agreed to the Developer Certificate of Origin (see
+below). This line must include the full name you commonly use, often a given
+name and a family name or surname. (ok: Sam Samuelsson, Robert A. Heinlein; not
+ok: xXthorXx, Sam, RAH)
### Testing
Each commit is expected to be tested. The expectation of testing may vary from
subproject to subproject, but will typically include running all applicable
automated tests and performing manual testing. Each commit should be tested
-separately, even if they are submitted together (an exception is when commits
-to different projects depend on each other).
+separately, even if they are submitted together (an exception is when commits to
+different projects depend on each other).
Commit messages should include a "Tested" field describing how you tested the
code changes in the patch. Example:
+
```
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.
```
If the change required manual testing, describe what you did and what happened;
-if it used to do something else before your change, describe that too. If the
+if it used to do something else before your change, describe that too. If the
change can be validated entirely by running unit tests, say so in the "Tested:"
field.
@@ -280,26 +278,25 @@
Your contribution will generally need to be reviewed before being accepted.
-
-Submitting changes via Gerrit server to OpenBMC
------------------------------------------------
+## Submitting changes via Gerrit server to OpenBMC
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:
+
```
Host openbmc.gerrit
Hostname gerrit.openbmc.org
@@ -312,110 +309,103 @@
phosphor-state-manager, and 'openbmc.gerrit' is the name of the Host previously
added:
- `git remote add gerrit ssh://openbmc.gerrit/openbmc/openbmc_repo`
+`git remote add gerrit ssh://openbmc.gerrit/openbmc/openbmc_repo`
Alternatively, you can encode all the data in the URL:
- `git remote add gerrit ssh://your_github_id@gerrit.openbmc.org:29418/openbmc/openbmc_repo`
+`git remote add gerrit ssh://your_github_id@gerrit.openbmc.org:29418/openbmc/openbmc_repo`
Then add the default branch for pushes to this remote:
- `git config remote.gerrit.push HEAD:refs/for/master`
+`git config remote.gerrit.push HEAD:refs/for/master`
-Gerrit uses [Change-Ids](https://gerrit-review.googlesource.com/Documentation/user-changeid.html) to identify commits that belong to the same
-review. Configure your git repository to automatically add a
-Change-Id to your commit messages. The steps are:
+Gerrit uses
+[Change-Ids](https://gerrit-review.googlesource.com/Documentation/user-changeid.html)
+to identify commits that belong to the same review. Configure your git
+repository to automatically add a Change-Id to your commit messages. The steps
+are:
- `gitdir=$(git rev-parse --git-dir)`
+`gitdir=$(git rev-parse --git-dir)`
- `scp -p -P 29418 openbmc.gerrit:hooks/commit-msg ${gitdir}/hooks`
+`scp -p -P 29418 openbmc.gerrit:hooks/commit-msg ${gitdir}/hooks`
To submit a change set, commit your changes, and push to the Gerrit server,
where 'gerrit' is the name of the remote added with the git remote add command:
- `git push gerrit`
+`git push gerrit`
-Sometimes you need to specify a topic (especially when working on a
-feature that spans across few projects) or (un)mark the change as
-Work-in-Progress. For that refer to [Gerrit
-documentation](https://gerrit-review.googlesource.com/Documentation/intro-user.html#topics).
+Sometimes you need to specify a topic (especially when working on a feature that
+spans across few projects) or (un)mark the change as Work-in-Progress. For that
+refer to
+[Gerrit documentation](https://gerrit-review.googlesource.com/Documentation/intro-user.html#topics).
-Gerrit will show you the URL link to your review. You can also find
-your reviews from the [OpenBMC Gerrit server](https://gerrit.openbmc.org) search bar
-or menu (All > Open, or My > Changes).
+Gerrit will show you the URL link to your review. You can also find your reviews
+from the [OpenBMC Gerrit server](https://gerrit.openbmc.org) search bar or menu
+(All > Open, or My > Changes).
-Invite reviewers to review your changes. Each OpenBMC repository has
-an `OWNERS` file that lists required reviewers who are subject matter
-experts. Those reviewers may add additional reviewers. To add
-reviewers from the Gerrit web page, click the "add reviewers" icon by
-the list of reviewers.
+Invite reviewers to review your changes. Each OpenBMC repository has an `OWNERS`
+file that lists required reviewers who are subject matter experts. Those
+reviewers may add additional reviewers. To add reviewers from the Gerrit web
+page, click the "add reviewers" icon by the list of reviewers.
-You are expected to respond to all comments. And remember to use the
-"reply" button to publish your replies for others to see.
+You are expected to respond to all comments. And remember to use the "reply"
+button to publish your replies for others to see.
-The review results in the proposed change being accepted, rejected for
-rework, or abandoned. When you re-work your change, remember to use
-`git commit --amend` so Gerrit handles the update as a new patch of
-the same review.
+The review results in the proposed change being accepted, rejected for rework,
+or abandoned. When you re-work your change, remember to use `git commit --amend`
+so Gerrit handles the update as a new patch of the same review.
-Each repository is governed by a small group of maintainers who are
-leaders with expertise in their area. They are responsible for
-reviewing changes and maintaining the quality of the code. You'll
-need a maintainer to accept your change, and they will look to the
-other reviewers for guidance. When accepted, your change will merge
-into the OpenBMC project.
+Each repository is governed by a small group of maintainers who are leaders with
+expertise in their area. They are responsible for reviewing changes and
+maintaining the quality of the code. You'll need a maintainer to accept your
+change, and they will look to the other reviewers for guidance. When accepted,
+your change will merge into the OpenBMC project.
+## References to non-public resources
-References to non-public resources
-----------------------------------------
+Code and commit messages shall not refer to companies' internal documents or
+systems (including bug trackers). Other developers may not have access to these,
+making future maintenance difficult.
-Code and commit messages shall not refer to companies' internal documents
-or systems (including bug trackers). Other developers may not have access to
-these, making future maintenance difficult.
+Code contributed to OpenBMC must build from the publicly available sources, with
+no dependencies on non-public resources (URLs, repositories, etc).
-Code contributed to OpenBMC must build from the publicly available sources,
-with no dependencies on non-public resources (URLs, repositories, etc).
+## Best practices for D-Bus interfaces
-Best practices for D-Bus interfaces
-----------------------------------
+- New D-Bus interfaces should be reusable
- * New D-Bus interfaces should be reusable
+- Type signatures should and use the simplest types possible, appropriate for
+ the data passed. For example, don't pass numbers as ASCII strings.
- * Type signatures should and use the simplest types possible, appropriate
- for the data passed. For example, don't pass numbers as ASCII strings.
+- D-Bus interfaces are defined in the `phosphor-dbus-interfaces` repository at:
- * 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
-
-Best practices for C
---------------------
+## Best practices for C
There are numerous resources available elsewhere, but a few items that are
relevant to OpenBMC work:
- * Do not use `system(<some shell pipeline>)`. Reading and writing from
- files should be done with the appropriate system calls.
+- Do not use `system(<some shell pipeline>)`. Reading and writing from files
+ should be done with the appropriate system calls.
- Generally, it's much better to use `fork(); execve()` if you do need to
- spawn a process, especially if you need to provide variable arguments.
+ Generally, it's much better to use `fork(); execve()` if you do need to spawn
+ a process, especially if you need to provide variable arguments.
- * Use the `stdint` types (eg, `uint32_t`, `int8_t`) for data that needs to be
- a certain size. Use the `PRIxx` macros for printf, if necessary.
+- Use the `stdint` types (eg, `uint32_t`, `int8_t`) for data that needs to be a
+ certain size. Use the `PRIxx` macros for printf, if necessary.
- * Don't assume that `char` is signed or unsigned.
+- Don't assume that `char` is signed or unsigned.
- * Beware of endian considerations when reading to & writing from
- C types
+- Beware of endian considerations when reading to & writing from C types
- * Declare internal-only functions as `static`, declare read-only data
- as `const` where possible.
+- Declare internal-only functions as `static`, declare read-only data as `const`
+ where possible.
- * Ensure that your code compiles without warnings, especially for changes
- to the kernel.
+- Ensure that your code compiles without warnings, especially for changes to the
+ kernel.
## Pace of Review
@@ -423,15 +413,15 @@
company, or who are not used to code reviews at all, are sometimes surprised by
the pace of code reviews in open source projects. Try to keep in mind that those
reviewing your patch may be contributing to OpenBMC in a volunteer or
-partial-time capacity, may be in a timezone far from your own, and may
-have very deep review queues already of patches which have been waiting longer
-than yours. Do everything you can to make it easy for the reviewer to review
-your contribution.
+partial-time capacity, may be in a timezone far from your own, and may have very
+deep review queues already of patches which have been waiting longer than yours.
+Do everything you can to make it easy for the reviewer to review your
+contribution.
-If you feel your patch has been missed entirely, of course, it's
-alright to email the maintainers (addresses available in OWNERS file) or
-ping them on Discord - but a reasonable timeframe to do so is on the order of a
-week, not on the order of hours.
+If you feel your patch has been missed entirely, of course, it's alright to
+email the maintainers (addresses available in OWNERS file) or ping them on
+Discord - but a reasonable timeframe to do so is on the order of a week, not on
+the order of hours.
The maintainers' job is to ensure that incoming patches are as correct and easy
to maintain as possible. Part of the nature of open source is attrition -
@@ -442,8 +432,7 @@
is trying to collaborate with you to build a patch that will benefit the project
on its own.
-Developer's Certificate of Origin 1.1
--------------------------------------
+## Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
diff --git a/IPMITOOL-cheatsheet.md b/IPMITOOL-cheatsheet.md
index da02651..22729a8 100644
--- a/IPMITOOL-cheatsheet.md
+++ b/IPMITOOL-cheatsheet.md
@@ -85,7 +85,7 @@
$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" user enable <userid>
```
-## Field-replaceable Unit (FRU)
+## Field-replaceable Unit (FRU)
#### 1. View FRU information
@@ -181,6 +181,7 @@
## Chassis
#### 1. Display information about the high-level status of the system rack and
+
#### power subsystem.
```
@@ -247,7 +248,9 @@
##
-If you want to make your override persistent over reboots use the `persistent` option:
+If you want to make your override persistent over reboots use the `persistent`
+option:
+
```
$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device> options=persistent
```
@@ -255,13 +258,15 @@
##
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:
+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
```
You can combine options with a help of `,`:
+
```
$ ipmitool -C 17 -H "$BMC_IP" -I lanplus -U "$BMC_USER" -P "$BMC_PASSWD" chassis bootdev <device> options=persistent,efiboot
```
@@ -269,6 +274,7 @@
##
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
```
@@ -341,6 +347,7 @@
## Serial Over Lan (SOL)
#### 1. Retrieve Serial-Over-LAN configuration information for the specified
+
#### channel.
```
diff --git a/README.md b/README.md
index ed81cbc..9b569bf 100644
--- a/README.md
+++ b/README.md
@@ -6,8 +6,8 @@
for OpenBMC as a whole. There may be component-specific documentation in the
repository for each component.
-The [features](features.md) document lists the project's major features
-with links to more information.
+The [features](features.md) document lists the project's major features with
+links to more information.
## Contact
@@ -19,34 +19,34 @@
These documents contain details on developing OpenBMC code itself
- - [cheatsheet.md](cheatsheet.md): Quick reference for some common
- development tasks
+- [cheatsheet.md](cheatsheet.md): Quick reference for some common development
+ tasks
- - [CONTRIBUTING.md](CONTRIBUTING.md): Guidelines for contributing to
- OpenBMC
+- [CONTRIBUTING.md](CONTRIBUTING.md): Guidelines for contributing to OpenBMC
-- [development tutorials](development/README.md): Tutorials for getting up to
- speed on OpenBMC development
+- [development tutorials](development/README.md): Tutorials for getting up to
+ speed on OpenBMC development
- - [kernel-development.md](kernel-development.md): Reference for common
- kernel development tasks
+- [kernel-development.md](kernel-development.md): Reference for common kernel
+ development tasks
## OpenBMC Usage
These documents describe how to use OpenBMC, including using the programmatic
interfaces to an OpenBMC system.
- - [code-update](architecture/code-update): Updating OpenBMC and host platform firmware
+- [code-update](architecture/code-update): Updating OpenBMC and host platform
+ firmware
- - [console.md](console.md): Using the host console
+- [console.md](console.md): Using the host console
- - [host-management.md](host-management.md): Performing host management tasks
- with OpenBMC
+- [host-management.md](host-management.md): Performing host management tasks
+ with OpenBMC
- - [rest-api.md](rest-api.md): Introduction to using the OpenBMC REST API
+- [rest-api.md](rest-api.md): Introduction to using the OpenBMC REST API
- - [REDFISH-cheatsheet.md](REDFISH-cheatsheet.md): Quick reference for some
- common OpenBMC Redfish commands
+- [REDFISH-cheatsheet.md](REDFISH-cheatsheet.md): Quick reference for some
+ common OpenBMC Redfish commands
- - [REST-cheatsheet.md](REST-cheatsheet.md): Quick reference for some common
- OpenBMC REST API commands
+- [REST-cheatsheet.md](REST-cheatsheet.md): Quick reference for some common
+ OpenBMC REST API commands
diff --git a/REDFISH-cheatsheet.md b/REDFISH-cheatsheet.md
index 78e36be..e039c4e 100644
--- a/REDFISH-cheatsheet.md
+++ b/REDFISH-cheatsheet.md
@@ -1,13 +1,14 @@
# Redfish cheat sheet
+
This document is intended to provide a set of example [Redfish][1] client
-commands for OpenBMC usage. This document uses cURL.
-This document assumes several ids, such as ManagerId, "bmc", and
-ComputerSystemId, "system". Assuming an id is not correct and any software
-written to use the Redfish API should not. From the Redfish Specification,
-DSP0266, "Clients shall not make assumptions about the URIs for the members of a
-resource collection."
+commands for OpenBMC usage. This document uses cURL. This document assumes
+several ids, such as ManagerId, "bmc", and ComputerSystemId, "system". Assuming
+an id is not correct and any software written to use the Redfish API should not.
+From the Redfish Specification, DSP0266, "Clients shall not make assumptions
+about the URIs for the members of a resource collection."
## Query Redfish Service Root
+
```
export bmc=xx.xx.xx.xx
curl -k https://${bmc}/redfish/v1
@@ -16,29 +17,35 @@
---
## Establish Redfish connection session
+
##### Method 1
+
```
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"}'
```
-A file, headers.txt, will be created. Find the `"X-Auth-Token"`
-in that file. Save it away in an env variable like so:
+
+A file, headers.txt, will be created. Find the `"X-Auth-Token"` in that file.
+Save it away in an env variable like so:
```
export bmc_token=<token>
```
-##### Method 2
+##### Method 2
+
```
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/...
```
+
Note: Method 2 is used in this document.
---
## View Redfish Objects
+
```
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
@@ -48,6 +55,7 @@
---
## View sessions
+
```
curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/SessionService/Sessions
```
@@ -55,22 +63,27 @@
---
## Host power
+
Host soft power off:
+
```
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:
+
```
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:
+
```
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:
+
```
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"}'
```
@@ -78,6 +91,7 @@
---
## BMC reboot
+
```
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"}'
```
@@ -85,7 +99,9 @@
---
## BMC factory reset
+
Proceed with caution:
+
```
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST https://${bmc}/redfish/v1/Managers/bmc/Actions/Manager.ResetToDefaults -d '{"ResetToDefaultsType": "ResetAll"}'
```
@@ -93,12 +109,15 @@
---
## Log entry
+
Display logging entries:
+
```
curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/redfish/v1/Systems/system/LogServices/EventLog/Entries
```
Delete logging entries:
+
```
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
```
@@ -106,6 +125,7 @@
---
## Firmware ApplyTime:
+
```
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH -d '{"HttpPushUriOptions":{"HttpPushUriApplyTime":{"ApplyTime":"Immediate"}}}' https://${bmc}/redfish/v1/UpdateService
```
@@ -119,8 +139,8 @@
---
## Firmware update
-Firmware update:
-Note the `<image file path>` must be a tarball.
+
+Firmware update: Note the `<image file path>` must be a tarball.
```
uri=$(curl -k -H "X-Auth-Token: $token" https://${bmc}/redfish/v1/UpdateService | jq -r ' .HttpPushUri')
@@ -128,13 +148,16 @@
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/octet-stream" -X POST -T <image file path> https://${bmc}${uri}
```
-TFTP Firmware update using TransferProtocol:
-Note: The `<image file path>` contains the address of the TFTP service: `xx.xx.xx.xx/obmc-phosphor-xxxxx-xxxxxxxxx.static.mtd.tar`
+TFTP Firmware update using TransferProtocol: Note: The `<image file path>`
+contains the address of the TFTP service:
+`xx.xx.xx.xx/obmc-phosphor-xxxxx-xxxxxxxxx.static.mtd.tar`
```
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:
+
```
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>"}'
```
@@ -142,7 +165,9 @@
---
## Update "root" password
+
Change password to "0penBmc1":
+
```
curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X PATCH -d '{"Password": "0penBmc1"}' https://${bmc}/redfish/v1/AccountService/Accounts/root
```
@@ -150,17 +175,21 @@
---
## BIOS firmware boot control
+
Enter into BIOS setup on boot
+
```
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
+
```
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)
+
```
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"}}'
```
@@ -168,12 +197,15 @@
---
## Enable NTP
+
Add a NTP Server
+
```
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
+
```
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}}'
```
@@ -181,9 +213,9 @@
---
## Disable IPMI
+
```
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}}'
```
-
[1]: https://www.dmtf.org/standards/redfish
diff --git a/REST-cheatsheet.md b/REST-cheatsheet.md
index a6315f9..18b6643 100644
--- a/REST-cheatsheet.md
+++ b/REST-cheatsheet.md
@@ -1,234 +1,277 @@
# OpenBMC REST cheat sheet
-This document is intended to provide a set of REST client commands for OpenBMC usage.
+This document is intended to provide a set of REST client commands for OpenBMC
+usage.
## Using CURL commands
### 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 use the same cookie jar files for read-only REST methods like GET, but
-requires either an authentication token or the username and password passed in
-as part of the URL for non-read-only methods.
+authentication handled by the curl cookie jar files. The bmcweb REST server can
+use the same cookie jar files for read-only REST methods like GET, but requires
+either an authentication token or the username and password passed in as part of
+the URL for non-read-only methods.
Starting with the 2.7 OpenBMC release (August 2019), bmcweb is the default REST
server.
### 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\" ] }"
- ```
-* If passing in the username/password as part of the URL, no unique login call
- is required. The URL format is:
- ```
- <username>:<password>@<hostname>/<path>...
- ```
+- 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\" ] }"
+ ```
+- If passing in the username/password as part of the URL, no unique login call
+ is required. The URL format is:
+
+ ```
+ <username>:<password>@<hostname>/<path>...
+ ```
+
For example:
- ```
- $ 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/...
- ```
+ ```
+ $ export bmc=xx.xx.xx.xx
+ $ curl -k -X GET https://root:0penBmc@${bmc}/xyz/openbmc_project/list
+ ```
- The third method is recommended.
+- 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/...
+ ```
+
+ The third method is recommended.
### Commands
+
Note: To keep the syntax below common between the phosphor-rest and bmcweb
- implementations as described above, this assumes that if bmcweb
- is used it is using the 'Token based' login method as described above:
+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/...
- ```
+```
+$ 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
- ```
+- List and 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/
- ```
+ ```
+ $ 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
+ ```
-* 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
- ```
+- List sub-objects:
-* 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
- ```
+ ```
+ $ 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 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
- ```
+- Host soft power off:
-* 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
- ```
+ ```
+ $ 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
+ ```
-* 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
- ```
+- Host hard power off:
-* 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
- ```
+ ```
+ $ 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
+ ```
-* 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
- ```
+- Host power on:
-* 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
- ```
+ ```
+ $ 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
+ ```
-* Delete images from system:
+- Reboot Host:
- - 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
- ```
+ ```
+ $ 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
+ ```
- - 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
- ```
+- Reboot BMC:
-* 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
- ```
+ ```
+ $ 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
+ ```
-* Control boot source override:
+- Display logging entries:
- - Read current boot source override settings:
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/control/host0/boot/enumerate
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X GET https://${bmc}/xyz/openbmc_project/logging/entry/enumerate
+ ```
- - 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"}'
- ```
+- Delete logging entries:
- - 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"}'
- ```
+ ```
+ $ 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
+ ```
- - 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"}'
- ```
+- Delete dump entries:
- - 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"}'
- ```
+ ```
+ $ 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
+ ```
- - 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"}'
- ```
+- Delete images from system:
-* Set NTP and Nameserver:
+ - Delete image:
- Examples using public server.
- - 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
- ```
+ ```
+ $ 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
+ ```
- - 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
- ```
+ - Delete all non-running images:
-* Configure time ownership and time sync method:
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -H "Content-Type: application/json" -X POST -d '{"data": []}' https://${bmc}/xyz/openbmc_project/software/action/DeleteAll
+ ```
- The introduction about time setting is here:
- https://github.com/openbmc/phosphor-time-manager
+- Clear gard records:
- Note: Starting from OpenBMC 2.6 (with systemd v239), systemd's timedated introduces a new beahvior that it checks the NTP services' status during setting time, instead of checking the NTP setting:
+ ```
+ $ 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
+ ```
- -When NTP server is set to disabled, and the NTP service is stopping but not stopped, setting time will get an error.
+- Control boot source override:
- Before OpenBMC 2.4 (with systemd v236), the above will always succeed.
- This results in [openbmc/openbmc#3459](https://github.com/openbmc/openbmc/issues/3459), and the related test cases are updated to cooperate with this behavior change.
+ - Read current boot source override settings:
- * 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
- ```
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/control/host0/boot/enumerate
+ ```
- * Write:
+ - Set boot source:
- 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
- ```
+ ```
+ $ 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"}'
+ ```
- 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
- ```
+ - Set boot mode:
-* Power Supply Redundancy:
+ ```
+ $ 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"}'
+ ```
- - Read:
- ```
- $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy
- ```
+ - Set boot type (valid only if host is based on the x86 CPU):
- - 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}'
- ```
+ ```
+ $ 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"}'
+ ```
-* Factory Reset:
+ - Set boot source override persistent:
- - 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
- ```
+ ```
+ $ 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"}'
+ ```
- - 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
- ```
+ - Enable boot source override:
- - 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
- ```
- and then reboot BMC.
+ ```
+ $ 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:
+
+ Examples using public server.
+
+ - 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
+ ```
+
+ - 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
+ ```
+
+- Configure time ownership and time sync method:
+
+ The introduction about time setting is here:
+ 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
+ setting time, instead of checking the NTP setting:
+
+ -When NTP server is set to disabled, and the NTP service is stopping but not
+ stopped, setting time will get an error.
+
+ Before OpenBMC 2.4 (with systemd v236), the above will always succeed. This
+ results in
+ [openbmc/openbmc#3459](https://github.com/openbmc/openbmc/issues/3459), and
+ the related test cases are updated to cooperate with this behavior change.
+
+ - 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
+ ```
+
+ - Write:
+
+ 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
+ ```
+
+ 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
+ ```
+
+- Power Supply Redundancy:
+
+ - Read:
+
+ ```
+ $ curl -k -H "X-Auth-Token: $token" -X GET https://${bmc}/xyz/openbmc_project/control/power_supply_redundancy
+ ```
+
+ - 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}'
+ ```
+
+- 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
+ ```
+
+ - 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
+ ```
+
+ - 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
+ ```
+
+ and then reboot BMC.
diff --git a/SECURITY.md b/SECURITY.md
index 54e473c..fc658ff 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -1,55 +1,59 @@
# Security Policy
-
## How to report a security vulnerability
-This describes how you can report an OpenBMC security vulnerability
-privately to give the project time to address the problem before
-public disclosure.
+This describes how you can report an OpenBMC security vulnerability privately to
+give the project time to address the problem before public disclosure.
The main ideas are:
- - You have information about a security problem which is not yet
- publicly available.
- - You want the problem fixed before public disclosure and
- you are willing to help make that happen.
- - You understand the problem will eventually be publicly disclosed.
+
+- You have information about a security problem which is not yet publicly
+ available.
+- You want the problem fixed before public disclosure and you are willing to
+ help make that happen.
+- You understand the problem will eventually be publicly disclosed.
To begin the process:
- - Send an email to `openbmc-security at lists.ozlabs.org` with details
- about the security problem such as:
- - the version and configuration of OpenBMC the problem appears in
- - how to reproduce the problem
- - what are the symptoms
- - As the problem reporter, you will be included in the email thread
- for the problem.
-The OpenBMC security response team (SRT) will respond to you and work to
-address the problem. Activities may include:
- - Privately engage community members to understand and address the
- problem. Anyone brought onboard should be given a link to the
- OpenBMC [security response team guidelines][].
- - Work to determine the scope and severity of the problem,
- such as [CVSS metrics][].
- - Work to create or identify an existing [CVE][].
- - Coordinate workarounds and fixes with you and the community.
- - Coordinate announcement details with you, such as timing or
- how you want to be credited.
- - Create an OpenBMC security advisory.
+- Send an email to `openbmc-security at lists.ozlabs.org` with details about the
+ security problem such as:
+ - the version and configuration of OpenBMC the problem appears in
+ - how to reproduce the problem
+ - what are the symptoms
+- As the problem reporter, you will be included in the email thread for the
+ problem.
+
+The OpenBMC security response team (SRT) will respond to you and work to address
+the problem. Activities may include:
+
+- Privately engage community members to understand and address the problem.
+ Anyone brought onboard should be given a link to the OpenBMC [security
+ response team guidelines][].
+- Work to determine the scope and severity of the problem, such as [CVSS
+ metrics][].
+- Work to create or identify an existing [CVE][].
+- Coordinate workarounds and fixes with you and the community.
+- Coordinate announcement details with you, such as timing or how you want to be
+ credited.
+- Create an OpenBMC security advisory.
Please refer to the [CERT Guide to Coordinated Vulnerability Disclosure][],
(SPECIAL REPORT CMU/SEI-2017-SR-022) for additional considerations.
Alternatives to this process:
- - If the problem is not severe, please write an issue to the affected
- repository or email the list.
- - Join the OpenBMC community and fix the problem yourself.
- - If you are unsure if the error is in OpenBMC (contrasted with
- upstream projects such as the Linux kernel or downstream projects
- such as a customized version of OpenBMC), please report it and we
- will help you route it to the correct area.
- - Discuss your topic in other [OpenBMC communication channels](https://github.com/openbmc/openbmc).
+
+- If the problem is not severe, please write an issue to the affected repository
+ or email the list.
+- Join the OpenBMC community and fix the problem yourself.
+- If you are unsure if the error is in OpenBMC (contrasted with upstream
+ projects such as the Linux kernel or downstream projects such as a customized
+ version of OpenBMC), please report it and we will help you route it to the
+ correct area.
+- Discuss your topic in other
+ [OpenBMC communication channels](https://github.com/openbmc/openbmc).
[security response team guidelines]: ./obmc-security-response-team-guidelines.md
-[CVSS metrics]: https://www.first.org/cvss/calculator/3.0
-[CVE]: http://cve.mitre.org/about/index.html
-[CERT Guide to Coordinated Vulnerability Disclosure]: https://resources.sei.cmu.edu/asset_files/SpecialReport/2017_003_001_503340.pdf
+[cvss metrics]: https://www.first.org/cvss/calculator/3.0
+[cve]: http://cve.mitre.org/about/index.html
+[cert guide to coordinated vulnerability disclosure]:
+ https://resources.sei.cmu.edu/asset_files/SpecialReport/2017_003_001_503340.pdf
diff --git a/anti-patterns.md b/anti-patterns.md
index 71616b2..cb9a0ed 100644
--- a/anti-patterns.md
+++ b/anti-patterns.md
@@ -2,41 +2,41 @@
From [Wikipedia](https://en.wikipedia.org/wiki/Anti-pattern):
-
"An anti-pattern is a common response to a recurring problem that is usually
ineffective and risks being highly counterproductive."
-
The developers of OpenBMC do not get 100% of decisions right 100% of the time.
That, combined with the fact that software development is often an exercise in
copying and pasting, results in mistakes happening over and over again.
-
This page aims to document some of the anti-patterns that exist in OpenBMC to
-ease the job of those reviewing code. If an anti-pattern is spotted, rather
-that repeating the same explanations over and over, a link to this document can
-be provided.
-
+ease the job of those reviewing code. If an anti-pattern is spotted, rather that
+repeating the same explanations over and over, a link to this document can be
+provided.
<!-- begin copy/paste on next line -->
## Anti-pattern template [one line description]
### Identification
+
(1 paragraph) Describe how to spot the anti-pattern.
### Description
+
(1 paragraph) Describe the negative effects of the anti-pattern.
### Background
-(1 paragraph) Describe why the anti-pattern exists. If you don't know, try
+
+(1 paragraph) Describe why the anti-pattern exists. If you don't know, try
running git blame and look at who wrote the code originally, and ask them on the
-mailing list or in Discord what their original intent was, so it can be documented
-here (and you may possibly discover it isn't as much of an anti-pattern as you
-thought). If you are unable to determine why the anti-pattern exists, put:
-"Unknown" here.
+mailing list or in Discord what their original intent was, so it can be
+documented here (and you may possibly discover it isn't as much of an
+anti-pattern as you thought). If you are unable to determine why the
+anti-pattern exists, put: "Unknown" here.
### Resolution
+
(1 paragraph) Describe the preferred way to solve the problem solved by the
anti-pattern and the positive effects of solving it in the manner described.
@@ -46,16 +46,16 @@
### Identification
-The ArgumentParser object is typically present to wrap calls to get options.
-It abstracts away the parsing and provides a `[]` operator to access the
+The ArgumentParser object is typically present to wrap calls to get options. It
+abstracts away the parsing and provides a `[]` operator to access the
parameters.
### Description
Writing a custom ArgumentParser object creates nearly duplicate code in a
-repository. The ArgumentParser itself is the same, however, the options
-provided differ. Writing a custom argument parser re-invents the wheel on
-c++ command line argument parsing.
+repository. The ArgumentParser itself is the same, however, the options provided
+differ. Writing a custom argument parser re-invents the wheel on c++ command
+line argument parsing.
### Background
@@ -65,12 +65,13 @@
### Resolution
The CLI11 library was designed and implemented specifically to support modern
-argument parsing. It handles the cases seen in OpenBMC daemons and has some
+argument parsing. It handles the cases seen in OpenBMC daemons and has some
handy built-in validators, and allows easy customizations to validation.
## Explicit AC_MSG_ERROR on PKG_CHECK_MODULES failure
### Identification
+
```
PKG_CHECK_MODULES(
[PHOSPHOR_LOGGING],
@@ -81,14 +82,13 @@
### Description
-The autotools PKG_CHECK_MODULES macro provides the ability to specify an
-"if found" and "if not found" behavior. By default, the "if not found"
-behavior will list the package not found. In many cases, this is sufficient
-to a developer to know what package is missing. In most cases, it's another
-OpenBMC package.
+The autotools PKG_CHECK_MODULES macro provides the ability to specify an "if
+found" and "if not found" behavior. By default, the "if not found" behavior will
+list the package not found. In many cases, this is sufficient to a developer to
+know what package is missing. In most cases, it's another OpenBMC package.
-If the library sought's name isn't related to the package providing it, then
-the failure message should be set to something more useful to the developer.
+If the library sought's name isn't related to the package providing it, then the
+failure message should be set to something more useful to the developer.
### Resolution
@@ -102,14 +102,16 @@
## Explicit listing of shared library packages in RDEPENDS in bitbake metadata
### Identification
+
```
RDEPENDS_${PN} = "libsystemd"
```
### Description
+
Out of the box bitbake examines built applications, automatically adds runtime
dependencies and thus ensures any library packages dependencies are
-automatically added to images, sdks, etc. There is no need to list them
+automatically added to images, sdks, etc. There is no need to list them
explicitly in a recipe.
Dependencies change over time, and listing them explicitly is likely prone to
@@ -121,19 +123,23 @@
for information on when to use explicit runtime dependencies.
### Background
-The initial bitbake metadata author for OpenBMC was not aware that bitbake
-added these dependencies automatically. Initial bitbake metadata therefore
-listed shared library dependencies explicitly, and was subsequently copy pasted.
+
+The initial bitbake metadata author for OpenBMC was not aware that bitbake added
+these dependencies automatically. Initial bitbake metadata therefore listed
+shared library dependencies explicitly, and was subsequently copy pasted.
### Resolution
-Do not list shared library packages in RDEPENDS. This eliminates the
-possibility of installing unnecessary shared library packages due to
-unmaintained library dependency lists in bitbake metadata.
+
+Do not list shared library packages in RDEPENDS. This eliminates the possibility
+of installing unnecessary shared library packages due to unmaintained library
+dependency lists in bitbake metadata.
## Use of /usr/bin/env in systemd service files
### Identification
+
In systemd unit files:
+
```
[Service]
@@ -141,15 +147,17 @@
```
### Description
+
Outside of OpenBMC, most applications that provide systemd unit files don't
-launch applications in this way. So if nothing else, this just looks strange
-and violates the [princple of least
-astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment).
+launch applications in this way. So if nothing else, this just looks strange and
+violates the
+[princple of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment).
### Background
+
This anti-pattern exists because a requirement exists to enable live patching of
-applications on read-only filesystems. Launching applications in this way was
-part of the implementation that satisfied the live patch requirement. For
+applications on read-only filesystems. Launching applications in this way was
+part of the implementation that satisfied the live patch requirement. For
example:
```
@@ -165,7 +173,8 @@
on a writeable /usr/local filesystem.
### Resolution
-The /usr/bin/env method only enables live patching of applications. A method
+
+The /usr/bin/env method only enables live patching of applications. A method
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:
@@ -174,14 +183,15 @@
mkdir -p /var/persist/work/usr
mount -t overlay -o lowerdir=/usr,upperdir=/var/persist/usr,workdir=/var/persist/work/usr overlay /usr
```
+
can enable live system patching without any additional requirements on how
-applications are launched from systemd service files. This is the preferred
+applications are launched from systemd service files. This is the preferred
method for enabling live system patching as it allows OpenBMC developers to
write systemd service files in the same way as most other projects.
To undo existing instances of this anti-pattern remove /usr/bin/env from systemd
service files and replace with the fully qualified path to the application being
-launched. For example, given an application in /usr/bin:
+launched. For example, given an application in /usr/bin:
```
sed -i s,/usr/bin/env ,/usr/bin/, foo.service
@@ -190,13 +200,16 @@
## Incorrect placement of executables in /sbin, /usr/sbin or /bin, /usr/bin
### Identification
-OpenBMC executables that are installed in `/usr/sbin`. `$sbindir` in bitbake
-metadata, makefiles or configure scripts. systemd service files pointing to
+
+OpenBMC executables that are installed in `/usr/sbin`. `$sbindir` in bitbake
+metadata, makefiles or configure scripts. systemd service files pointing to
`/bin` or `/usr/bin` executables.
### Description
+
Installing OpenBMC applications in incorrect locations violates the
-[principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment) and more importantly violates the
+[principle of least astonishment](https://en.wikipedia.org/wiki/Principle_of_least_astonishment)
+and more importantly violates the
[FHS](https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard).
### Background
@@ -204,16 +217,16 @@
There are typically two types of executables:
1. Long-running daemons started by, for instance, systemd service files and
- *NOT* intended to be directly executed by users.
+ _NOT_ intended to be directly executed by users.
2. Utilities intended to be used by a user as a CLI.
-Executables of type 1 should not be placed anywhere in `${PATH}` because it
-is confusing and error-prone to users, but should instead be placed in a
+Executables of type 1 should not be placed anywhere in `${PATH}` because it is
+confusing and error-prone to users, but should instead be placed in a
`/usr/libexec/<package>` subdirectory.
Executables of type 2 should be placed in `/usr/bin` because they are intended
-to be used by users and should be in `${PATH}` (also, `sbin` is inappropriate
-as we transition to having non-root access).
+to be used by users and should be in `${PATH}` (also, `sbin` is inappropriate as
+we transition to having non-root access).
The sbin anti-pattern exists because the FHS was misinterpreted at an early
point in OpenBMC project history, and has proliferated ever since.
@@ -235,7 +248,7 @@
The FHS description for `/usr/sbin` refers to "system administration" but the
de-facto interpretation of the system being administered refers to the OS
-installation and not a system in the OpenBMC sense of managed system. As such
+installation and not a system in the OpenBMC sense of managed system. As such
OpenBMC applications should be installed in `/usr/bin`.
It is becoming common practice in Linux for daemons to now be moved to `libexec`
@@ -243,16 +256,19 @@
that controls their launch.
### Resolution
+
Install OpenBMC applications in `/usr/libexec` or `/usr/bin/` as appropriate.
## Handling unexpected error codes and exceptions
### Identification
+
The anti-pattern is for an application to continue processing after it
encounters unexpected conditions in the form of error codes and exceptions and
not capturing the data needed to resolve the problem.
Example C++ code:
+
```
using InternalFailure = sdbusplus::xyz::openbmc_project::Common::Error::InternalFailure;
try
@@ -266,6 +282,7 @@
```
### Description
+
Suppressing unexpected errors can lead an application to incorrect or erratic
behavior which can affect the service it provides and the overall system.
@@ -274,117 +291,124 @@
investigate problems and the system's reliability does not improve over time.
### Background
-Programmers want their application to continue processing when it encounters
-conditions it can recover from. Sometimes they try too hard and continue when
-it is not appropriate.
-Programmers also want to log what is happening in the application, so they
-write log entries that give debug data when something goes wrong, typically
-targeted for their use. They don't consider how the log entry is consumed
-by the BMC administrator or automated service tools.
+Programmers want their application to continue processing when it encounters
+conditions it can recover from. Sometimes they try too hard and continue when it
+is not appropriate.
+
+Programmers also want to log what is happening in the application, so they write
+log entries that give debug data when something goes wrong, typically targeted
+for their use. They don't consider how the log entry is consumed by the BMC
+administrator or automated service tools.
The `InternalFailure` in the [Phosphor logging README][] is overused.
-[Phosphor logging README]: https://github.com/openbmc/phosphor-logging/blob/master/README.md
+[phosphor logging readme]:
+ https://github.com/openbmc/phosphor-logging/blob/master/README.md
### Resolution
Several items are needed:
-1. Check all places where a return code or errno value is given. Strongly
- consider that a default error handler should throw an exception, for
- example `std::system_error`.
-2. Have a good reason to handle specific error codes. See below.
-3. Have a good reason to handle specific exceptions. Allow other exceptions
- to propagate.
+
+1. Check all places where a return code or errno value is given. Strongly
+ consider that a default error handler should throw an exception, for example
+ `std::system_error`.
+2. Have a good reason to handle specific error codes. See below.
+3. Have a good reason to handle specific exceptions. Allow other exceptions to
+ propagate.
4. Document (in terms of impacts to other services) what happens when this
- service fails, stops, or is restarted. Use that to inform the recovery
+ service fails, stops, or is restarted. Use that to inform the recovery
strategy.
In the error handler:
-1. Consider what data (if any) should be logged. Determine who will consume
- the log entry: BMC developers, administrator, or an analysis tool. Usually
- the answer is more than one of these.
+1. Consider what data (if any) should be logged. Determine who will consume the
+ log entry: BMC developers, administrator, or an analysis tool. Usually the
+ answer is more than one of these.
The following example log entries use an IPMI request to set network access
on, but the user input is invalid.
- - BMC Developer: Reference internal applications, services, pids, etc.
- the developer would be familiar with.
+ - BMC Developer: Reference internal applications, services, pids, etc. the
+ developer would be familiar with.
- Example: `ipmid service successfully processed a network setting packet,
- however the user input of USB0 is not a valid network interface to
- configure.`
+ Example:
+ `ipmid service successfully processed a network setting packet, however the user input of USB0 is not a valid network interface to configure.`
- - Administrator: Reference the external interfaces of the BMC such as the
- REST API. They can respond to feedback about invalid input, or a need
- to restart the BMC.
+ - Administrator: Reference the external interfaces of the BMC such as the
+ REST API. They can respond to feedback about invalid input, or a need to
+ restart the BMC.
- Example: `The network interface of USB0 is not a valid option. Retry the
- IPMI command with a valid interface.`
+ Example:
+ `The network interface of USB0 is not a valid option. Retry the IPMI command with a valid interface.`
- - 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 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.
+ - 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
+ 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.
- Example: `[UserInput][IPMI][Network][Config][Warning] Interface USB0 not
- valid.`
+ Example:
+ `[UserInput][IPMI][Network][Config][Warning] Interface USB0 not valid.`
-2. Determine if the application can fully recover from the condition. If not,
- don't continue. Allow the system to determine if it writes a core dump or
- restarts the service. If there are severe impacts when the service fails,
+2. Determine if the application can fully recover from the condition. If not,
+ don't continue. Allow the system to determine if it writes a core dump or
+ restarts the service. If there are severe impacts when the service fails,
consider using a better error recovery mechanism.
## Non-standard debug application options and logging
### Identification
-An application uses non-standard methods on startup to indicate verbose
-logging and/or does not utilize standard systemd-journald debug levels for
-logging.
+
+An application uses non-standard methods on startup to indicate verbose logging
+and/or does not utilize standard systemd-journald debug levels for logging.
### Description
-When debugging issues within OpenBMC that cross multiple applications, it's
-very difficult to enable the appropriate debug when different applications
-have different mechanisms for enabling debug. For example, different OpenBMC
+
+When debugging issues within OpenBMC that cross multiple applications, it's very
+difficult to enable the appropriate debug when different applications have
+different mechanisms for enabling debug. For example, different OpenBMC
applications take the following as command line parameters to enable extra
debug:
+
- 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 causes other issues when trying to compare debug data across
-different applications that may be having their buffers flushed at different
-times (and picked up by journald).
+of writing debug data. They use std::cout, printf, fprintf, ... Doing this
+causes other issues when trying to compare debug data across different
+applications that may be having their buffers flushed at different times (and
+picked up by journald).
### Background
-Everyone has their own ways to debug. There was no real standard within
-OpenBMC on how to do it so everyone came up with whatever they were familiar
-with.
+
+Everyone has their own ways to debug. There was no real standard within OpenBMC
+on how to do it so everyone came up with whatever they were familiar with.
### Resolution
+
If an OpenBMC application is to support enhanced debug via a command line then
it will support the standard "-v,--verbose" option.
In general, OpenBMC developers should utilize the "debug" journald level for
-debug messages. This can be enabled/disabled globally and would apply to
-all applications. If a developer believes this would cause too much debug
-data in certain cases then they can protect these journald debug calls around
-a --verbose command line option.
+debug messages. This can be enabled/disabled globally and would apply to all
+applications. If a developer believes this would cause too much debug data in
+certain cases then they can protect these journald debug calls around a
+--verbose command line option.
## DBus interface representing GPIOs
### Identification
+
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
+
Platform functionality selected by GPIOs might equally be selected by other
means with a shift in system design philosophy. As such, GPIOs are a (hardware)
implementation detail. Exposing the implementation on DBus forces the
@@ -395,11 +419,13 @@
[coupling]: https://en.wikipedia.org/wiki/Coupling_%28computer_programming%29
### Background
+
GPIOs are often used to select functionality that might be hard to generalise,
-and therefore hard to abstract. If this is the case, then the functionality
-in question is probably best wrapped up as an implementation detail of a
-behaviour that is more generally applicable (e.g. host power-on procedures).
+and therefore hard to abstract. If this is the case, then the functionality in
+question is probably best wrapped up as an implementation detail of a behaviour
+that is more generally applicable (e.g. host power-on procedures).
### Resolution
+
Consider what functionality the GPIO provides and design or exploit an existing
interface to expose that behaviour instead.
diff --git a/architecture/LED-architecture.md b/architecture/LED-architecture.md
index 3653fbc..2f7e5a9 100644
--- a/architecture/LED-architecture.md
+++ b/architecture/LED-architecture.md
@@ -1,7 +1,7 @@
# LED Support for OpenBMC
This document describes how to add LED support for your machine based upon the
-OpenBMC [LED Architecture][LED D-Bus README] document. LED group management is
+OpenBMC [LED Architecture][led d-bus readme] document. LED group management is
done automatically for machines that support the use of the MRW and is beyond
the scope of this document.
@@ -22,8 +22,9 @@
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...
+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
@@ -32,43 +33,52 @@
## REDFISH
### Resource identify Operation
-Starting with Redfish v2020.3, Redfish resources have **LocationIndicatorActive**
-property, which is used to identify a particular resource. This is for LED
-Identify operation only.
-All applicable Inventory D-Bus objects would have a forward association
-mapping to LED Group D-Bus object, namely:
+Starting with Redfish v2020.3, Redfish resources have
+**LocationIndicatorActive** property, which is used to identify a particular
+resource. This is for LED Identify operation only.
+
+All applicable Inventory D-Bus objects would have a forward association mapping
+to LED Group D-Bus object, namely:
+
```
- identify_led_group
```
+
All applicable LED Group D-Bus objects would have an association mapping to
inventory D-Bus object, namely:
+
```
- identify_inventory_object
```
When a `LocationIndicatorActive` GET operation is performed on the resource,
bmcweb does below operations:
+
- Look for an association `identify_led_group` on the Inventory D-Bus object
- If found, read the `asserted` property from the D-Bus object that is pointed
to by `identify_led_group`
When a `LocationIndicatorActive` PATCH operation is performed on the resource,
bmcweb does below operations:
+
- Look for an association `identify_led_group` on the Inventory D-Bus object
-- If found, set the `asserted` property on the D-Bus object that is pointed
- to by `identify_led_group`
+- If found, set the `asserted` property on the D-Bus object that is pointed to
+ by `identify_led_group`
### Representing resource faults
+
For representing the fault status of a resource, Redfish `Health` property is
-used.
-All applicable Inventory D-Bus objects would have a forward association mapping
-to LED Group D-Bus object, namely;
+used. All applicable Inventory D-Bus objects would have a forward association
+mapping to LED Group D-Bus object, namely;
+
```
- fault_led_group
```
+
All applicable LED Group D-Bus objects would have an association mapping to
inventory D-Bus object, namely:
+
```
- fault_inventory_object
```
@@ -78,28 +88,29 @@
on the Inventory D-Bus object.
When LED manager gets PropertyChanged signal, it does the following:
+
- Look for an association `fault_led_group` on the Inventory D-Bus object
-- Turn on/off the fault LED group depending on the value of `Functional`
- `false` would mean turn ON the LED group
- `true` would mean turn OFF the LED group
+- Turn on/off the fault LED group depending on the value of `Functional` `false`
+ would mean turn ON the LED group `true` would mean turn OFF the LED group
- bmcweb already has a design to look for `Functional` property and set the
`Health` property.
## Development Details
-There are two significant layers for LED operations. The physical and the
-logical. The LED Group Manager communicates with the physical LED Manager to
-drive the physical LEDs. The logical groups are defined in the machine's
-led.yaml file. LED Group manager consumes this and creates D-Bus/REST
-interfaces for the individual LEDs that are part of the group.
+
+There are two significant layers for LED operations. The physical and the
+logical. The LED Group Manager communicates with the physical LED Manager to
+drive the physical LEDs. The logical groups are defined in the machine's
+led.yaml file. LED Group manager consumes this and creates D-Bus/REST interfaces
+for the individual LEDs that are part of the group.
### Defining the physical LED
-Physical LED wiring is defined in the `leds` section of the machine's
-[device tree][Kernel ARM DTS]. See the [Palmetto DTS][Palmetto DTS LED]
-as an example.
+Physical LED wiring is defined in the `leds` section of the machine's [device
+tree][kernel arm dts]. See the [Palmetto DTS][palmetto dts led] as an example.
_Add a fault LED to the device tree with a corresponding gpio pin..._
+
```
leds {
compatible = "gpio-leds";
@@ -125,8 +136,9 @@
```
### Defining Groups
+
An LED Group can contain zero or more LEDs and is defined in the machines
-[led.yaml][LED YAML]. The default one will likely need to be tailored to your
+[led.yaml][led yaml]. The default one will likely need to be tailored to your
machines layout. Customized yaml files are placed into the machines specific
Yocto location. As an example:
@@ -134,15 +146,15 @@
meta-ibm/meta-palmetto/recipes-phosphor/leds/palmetto-led-manager-config/led.yaml
```
-The parent properties in the yaml file will be created below `/xyz/openbmc_project/led/groups/`.
-The children properties need to map to an LED name in `/sys/class/leds`.
+The parent properties in the yaml file will be created below
+`/xyz/openbmc_project/led/groups/`. The children properties need to map to an
+LED name in `/sys/class/leds`.
In the example, below two URIs would be created:
`/xyz/openbmc_project/led/groups/enclosure_fault` and
-`/xyz/openbmc_project/led/groups/lamp_test`. Both act on the same physical
-LED `fault` but do so differently. The lamp_test would also drive a blink
-signal to the physical `power` LED if one was created.
-
+`/xyz/openbmc_project/led/groups/lamp_test`. Both act on the same physical LED
+`fault` but do so differently. The lamp_test would also drive a blink signal to
+the physical `power` LED if one was created.
```
EnclosureFault:
@@ -163,14 +175,17 @@
```
### Required Groups
-OpenBMC Architecture requires specific LED Groups to be created and are
-documented in the [D-Bus interface][LED D-Bus README].
+OpenBMC Architecture requires specific LED Groups to be created and are
+documented in the [D-Bus interface][led d-bus readme].
## Yocto packaging
+
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"
@@ -191,14 +206,18 @@
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`
- ```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
-[LED YAML]: https://github.com/openbmc/phosphor-led-manager/blob/master/led.yaml
-[Kernel ARM DTS]: https://github.com/openbmc/linux/tree/dev-4.19/arch/arm/boot/dts
-[Palmetto DTS LED]: https://github.com/openbmc/linux/blob/dev-4.19/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dts#L45
+[led d-bus readme]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/README.md
+[led yaml]: https://github.com/openbmc/phosphor-led-manager/blob/master/led.yaml
+[kernel arm dts]:
+ https://github.com/openbmc/linux/tree/dev-4.19/arch/arm/boot/dts
+[palmetto dts led]:
+ https://github.com/openbmc/linux/blob/dev-4.19/arch/arm/boot/dts/aspeed-bmc-opp-palmetto.dts#L45
diff --git a/architecture/code-update/code-update-deprecated.md b/architecture/code-update/code-update-deprecated.md
index 3947ebc..9babbff 100644
--- a/architecture/code-update/code-update-deprecated.md
+++ b/architecture/code-update/code-update-deprecated.md
@@ -1,11 +1,10 @@
-OpenBMC Code Update
-===================
+# OpenBMC Code Update
**Important Note:**
-* The REST APIs described below are deprecated.
- Please follow [code-update.md](code-update.md) for the new APIs to do code
- update.
-* The rest part of this document is still valid.
+
+- The REST APIs described below are deprecated. Please follow
+ [code-update.md](code-update.md) for the new APIs to do code update.
+- The rest part of this document is still valid.
The host code update can be found here:
[host-code-update.md](host-code-update.md)
@@ -14,69 +13,66 @@
`tmp/deploy/images/<platform>/`. The `image-*` symlinks correspond to components
that can be updated on the BMC:
- * `image-bmc` → `obmc-phosphor-image-<platform>-<timestamp>.static.mtd`
+- `image-bmc` → `obmc-phosphor-image-<platform>-<timestamp>.static.mtd`
- The complete flash image for the BMC
+ The complete flash image for the BMC
- * `image-kernel` → `fitImage-obmc-phosphor-initramfs-<platform>.bin`
+- `image-kernel` → `fitImage-obmc-phosphor-initramfs-<platform>.bin`
- The OpenBMC kernel FIT image (including the kernel, device tree, and initramfs)
+ The OpenBMC kernel FIT image (including the kernel, device tree, and
+ initramfs)
- * `image-rofs` → `obmc-phosphor-image-<platform>.squashfs-xz`
+- `image-rofs` → `obmc-phosphor-image-<platform>.squashfs-xz`
- The read-only OpenBMC filesystem
+ The read-only OpenBMC filesystem
- * `image-rwfs` → `rwfs.jffs2`
+- `image-rwfs` → `rwfs.jffs2`
- The read-write filesystem for persistent changes to the OpenBMC filesystem
+ The read-write filesystem for persistent changes to the OpenBMC filesystem
- * `image-u-boot` → `u-boot.bin`
+- `image-u-boot` → `u-boot.bin`
- The OpenBMC bootloader
+ The OpenBMC bootloader
-Additionally, there are two tarballs created that can be deployed and unpacked by REST:
+Additionally, there are two tarballs created that can be deployed and unpacked
+by REST:
- * `<platform>-<timestamp>.all.tar`
+- `<platform>-<timestamp>.all.tar`
- The complete BMC flash content: A single file (`image-bmc`) wrapped in a
- tar archive.
+ The complete BMC flash content: A single file (`image-bmc`) wrapped in a tar
+ archive.
- * `<platform>-<timestamp>.tar`
+- `<platform>-<timestamp>.tar`
- Partitioned BMC flash content: Multiple files wrapped in a tar archive,
- one for each of the u-boot, kernel, ro and rw partitions.
+ Partitioned BMC flash content: Multiple files wrapped in a tar archive, one
+ for each of the u-boot, kernel, ro and rw partitions.
-Preparing for BMC code Update
------------------------------
+## Preparing for BMC code Update
-The BMC normally runs with the read-write and read-only file systems
-mounted, which means these images may be read (and written, for the
-read-write filesystem) at any time. Because the updates are distributed
-as complete file system images, these filesystems have to be unmounted
-to replace them with new images. To unmount these file systems all
-applications must be stopped.
+The BMC normally runs with the read-write and read-only file systems mounted,
+which means these images may be read (and written, for the read-write
+filesystem) at any time. Because the updates are distributed as complete file
+system images, these filesystems have to be unmounted to replace them with new
+images. To unmount these file systems all applications must be stopped.
-By default, an orderly `reboot` will stop all applications and unmount
-the root filesystem, and the images copied into the `/run/initramfs`
-directory will be applied at that point before restarting. This also
-applied to the `shutdown` and `halt` commands -- they will write the
-flash before stopping.
+By default, an orderly `reboot` will stop all applications and unmount the root
+filesystem, and the images copied into the `/run/initramfs` directory will be
+applied at that point before restarting. This also applied to the `shutdown` and
+`halt` commands -- they will write the flash before stopping.
-As an alternative, an option can be parsed by the `init` script in
-the initramfs to copy the required contents of these filesystems into
-RAM so the images can be applied while the rest of the application stack
-is running and progress can be monitored over the network. The
-`update` script can then be called to write the images while the
-system is operational and its progress output monitored.
+As an alternative, an option can be parsed by the `init` script in the initramfs
+to copy the required contents of these filesystems into RAM so the images can be
+applied while the rest of the application stack is running and progress can be
+monitored over the network. The `update` script can then be called to write the
+images while the system is operational and its progress output monitored.
-Update from the OpenBMC shell
------------------------------
+## Update from the OpenBMC shell
To update from the OpenBMC shell, follow the steps in this section.
-It is recommended that the BMC be prepared for update (note that the
-environment variable needs to be set twice for initramfs be able to
-read it due to the U-Boot redundant environments):
+It is recommended that the BMC be prepared for update (note that the environment
+variable needs to be set twice for initramfs be able to read it due to the
+U-Boot redundant environments):
fw_setenv openbmconce copy-files-to-ram copy-base-filesystem-to-ram
fw_setenv openbmconce copy-files-to-ram copy-base-filesystem-to-ram
@@ -94,50 +90,51 @@
reboot
-During the reboot process, the `update` script will be invoked after
-the file systems are unmounted to complete the update process.
+During the reboot process, the `update` script will be invoked after the file
+systems are unmounted to complete the update process.
Some optional features are available, see the help for more details:
/run/initramfs/update --help
-Update via REST
----------------
+## Update via REST
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
-Perform a POST to invoke the `PrepareForUpdate` method of the `/flash/bmc` object:
+Perform a POST to invoke the `PrepareForUpdate` method of the `/flash/bmc`
+object:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": []}' \
https://${bmc}/org/openbmc/control/flash/bmc/action/prepareForUpdate
-This will setup the u-boot environment and reboot the BMC. If no other
-images were pending the BMC should return in about 2 minutes.
-
+This will setup the u-boot environment and reboot the BMC. If no other images
+were pending the BMC should return in about 2 minutes.
### Configure update settings
There are a few settings available to control the update process:
- * `preserve_network_settings`: Preserve network settings, only needed if updating the whole flash
- * `restore_application_defaults`: update (clear) the read-write file system
- * `update_kernel_and_apps`: update kernel and initramfs.
- If the partitioned tarball will be used for update then this option
- must be set. Otherwise, if the complete tarball will be used then
- this option must not be set.
- * `clear_persistent_files`: ignore the persistent file list when resetting applications defaults
- * `auto_apply`: Attempt to write the images by invoking the `Apply` method after the images are unpacked.
+- `preserve_network_settings`: Preserve network settings, only needed if
+ updating the whole flash
+- `restore_application_defaults`: update (clear) the read-write file system
+- `update_kernel_and_apps`: update kernel and initramfs. If the partitioned
+ tarball will be used for update then this option must be set. Otherwise, if
+ the complete tarball will be used then this option must not be set.
+- `clear_persistent_files`: ignore the persistent file list when resetting
+ applications defaults
+- `auto_apply`: Attempt to write the images by invoking the `Apply` method after
+ the images are unpacked.
To configure the update settings, perform a REST PUT to
`/control/flash/bmc/attr/<setting>`. For example:
@@ -158,12 +155,13 @@
### Check flash status
-You can query the progress of the download and image verification with
-a simple GET request:
+You can query the progress of the download and image verification with a simple
+GET request:
curl -b cjar -k https://${bmc}/org/openbmc/control/flash/bmc
-Or perform a POST to invoke the `GetUpdateProgress` method of the `/flash/bmc` object:
+Or perform a POST to invoke the `GetUpdateProgress` method of the `/flash/bmc`
+object:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": []}' \
@@ -171,29 +169,31 @@
Note:
- * During downloading the tarball, the progress status is `Downloading`
- * After the tarball is downloaded and verified, the progress status becomes `Image ready to apply`.
+- During downloading the tarball, the progress status is `Downloading`
+- After the tarball is downloaded and verified, the progress status becomes
+ `Image ready to apply`.
### Apply update
-If the status is `Image ready to apply.` then you can either initiate
-a reboot or call the Apply method to start the process of writing the
-flash:
+
+If the status is `Image ready to apply.` then you can either initiate a reboot
+or call the Apply method to start the process of writing the flash:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": []}' \
https://${bmc}/org/openbmc/control/flash/bmc/action/Apply
-Now the image is being flashed, you can check the progress with above steps command as well.
+Now the image is being flashed, you can check the progress with above steps
+command as well.
-* During flashing the image, the status becomes `Writing images to flash`
-* After it's flashed and verified, the status becomes `Apply Complete. Reboot to take effect.`
+- During flashing the image, the status becomes `Writing images to flash`
+- After it's flashed and verified, the status becomes
+ `Apply Complete. Reboot to take effect.`
### Reboot the BMC
-To start using the new images, reboot the BMC using the warmReset method
-of the BMC control object:
+To start using the new images, reboot the BMC using the warmReset method of the
+BMC control object:
curl -b cjar -k -H "Content-Type: application/json" -X POST \
-d '{"data": []}' \
https://${bmc}/org/openbmc/control/bmc0/action/warmReset
-
diff --git a/architecture/code-update/code-update-diagrams.md b/architecture/code-update/code-update-diagrams.md
index 1d6078e..a00609a 100644
--- a/architecture/code-update/code-update-diagrams.md
+++ b/architecture/code-update/code-update-diagrams.md
@@ -57,7 +57,10 @@
image
```
-- [1] [Software D-Bus Object](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Software)
+
+- [1]
+ [Software D-Bus Object](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Software)
- [*] In a static layout configuration, the images are stored in RAM and the
- content is written to flash during BMC reboot. Reference the update and
- shutdown scripts provided by [initrdscripts](https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/initrdscripts)
+ content is written to flash during BMC reboot. Reference the update and
+ shutdown scripts provided by
+ [initrdscripts](https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/initrdscripts)
diff --git a/architecture/code-update/code-update.md b/architecture/code-update/code-update.md
index 8ce7175..789ee08 100644
--- a/architecture/code-update/code-update.md
+++ b/architecture/code-update/code-update.md
@@ -1,10 +1,9 @@
-OpenBMC Code Update
-==============
+# OpenBMC Code Update
Two BMC Code layouts are available:
- * Static, non-UBI layout
- * UBI layout - enabled via `obmc-ubi-fs` distro feature
+- Static, non-UBI layout
+- UBI layout - enabled via `obmc-ubi-fs` distro feature
This document describes the code update that supports both layouts.
@@ -12,21 +11,21 @@
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`
+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 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 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
+
```
purpose=xyz.openbmc_project.Software.Version.VersionPurpose.BMC
version=2.7.0-dev
@@ -35,123 +34,122 @@
MachineName=tiogapass
```
-2. Transfer the generated BMC image to the BMC via one of the following
-methods:
- * Method 1: Via scp: Copy the generated BMC image to the `/tmp/images/`
- directory on the BMC.
- * Method 2: Via REST Upload:
+2. Transfer the generated BMC image to the BMC via one of the following methods:
+
+- Method 1: Via scp: Copy the generated BMC 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 3: Via TFTP: Perform a POST request to call the `DownloadViaTFTP`
+ method of `/xyz/openbmc_project/software`.
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:
+ 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
- ```
+ ```
+ # 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",
- ```
+ ```
+ $ 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
- ```
-
+ ```
+ 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:
+ 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
+ ```
+ 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
- ```
+ ```
+ 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:
+ 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 xyz.openbmc_project.Software.BMC.Updater \
- /xyz/openbmc_project/software/<id> \
- xyz.openbmc_project.Software.ActivationProgress Progress
- ```
+ ```
+ busctl get-property xyz.openbmc_project.Software.BMC.Updater \
+ /xyz/openbmc_project/software/<id> \
+ xyz.openbmc_project.Software.ActivationProgress 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
- ```
+ ```
+ 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:
+ 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 xyz.openbmc_project.Software.BMC.Updater \
- /xyz/openbmc_project/software/<id> \
- xyz.openbmc_project.Software.Activation Activation
- ```
+ ```
+ busctl get-property xyz.openbmc_project.Software.BMC.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>
- ```
+ ```
+ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>
+ ```
7. Reboot the BMC for the image to take effect.
- * Method 1: From the BMC command line:
+- Method 1: From the BMC command line:
- ```
- reboot
- ```
+ ```
+ reboot
+ ```
- * Method 2: Using the REST API:
+- Method 2: 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
- ```
+ ```
+ 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
@@ -176,11 +174,11 @@
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 \
@@ -199,8 +197,8 @@
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 \
@@ -221,11 +219,12 @@
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.
+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:
+
```
# busctl call xyz.openbmc_project.ObjectMapper \
/xyz/openbmc_project/software/updatable org.freedesktop.DBus.Properties \
@@ -236,8 +235,8 @@
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.
+ `/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 \
@@ -274,28 +273,27 @@
A file named "MANIFEST" must be included in any image tar uploaded, downloaded
via TFTP, or copied to the BMC.
-The MANIFEST file format must be key=value (e.g. version=v1.99.10).
-It should include the following fields:
+The MANIFEST file format must be key=value (e.g. version=v1.99.10). It should
+include the following fields:
-* version - The version of the image
-* purpose - The image's purpose (e.g.
-xyz.openbmc_project.Software.Version.VersionPurpose.BMC or
-xyz.openbmc_project.Software.Version.VersionPurpose.Host). Accepted purpose
-values can be found at
-[Version interface](https://github.com/openbmc/phosphor-dbus-interfaces/blob/6f69ae5b33ee224358cb4c2061f4ad44c6b36d70/xyz/openbmc_project/Software/Version.interface.yaml)
-under "VersionPurpose" values.
-* MachineName - The name of machine (platform) for which this image is
- built for. This value will be compared against
- OPENBMC_TARGET_MACHINE value defined in os-release file
- of running image. Image will not be upgraded if this
- check fails. For backward compatibility this check
- skips failure if MachineName is not defined for current
- released images but it will be made mandatory field
- from 2.9 onward releases.
+- version - The version of the image
+- purpose - The image's purpose (e.g.
+ xyz.openbmc_project.Software.Version.VersionPurpose.BMC or
+ xyz.openbmc_project.Software.Version.VersionPurpose.Host). Accepted purpose
+ values can be found at
+ [Version interface](https://github.com/openbmc/phosphor-dbus-interfaces/blob/6f69ae5b33ee224358cb4c2061f4ad44c6b36d70/xyz/openbmc_project/Software/Version.interface.yaml)
+ under "VersionPurpose" values.
+- MachineName - The name of machine (platform) for which this image is built
+ for. This value will be compared against OPENBMC_TARGET_MACHINE value defined
+ in os-release file of running image. Image will not be upgraded if this check
+ fails. For backward compatibility this check skips failure if MachineName is
+ not defined for current released images but it will be made mandatory field
+ from 2.9 onward releases.
Other optional fields are:
-* extended_version - A more detailed version, which could include versions of
-different components in the image.
+
+- extended_version - A more detailed version, which could include versions of
+ different components in the image.
### Deleting an Image
@@ -319,13 +317,13 @@
### 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 loaded on the system by accident. The software implementation of the field
-mode interface disables patching of the BMC by not mounting `/usr/local`, which
-in turn disables host patching at `/usr/local/share/pnor/`.
-Enabling field mode is intended to be a one-way operation which means that once
-enabled, there is no REST API provided to disable it.
+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
+loaded on the system by accident. The software implementation of the field mode
+interface disables patching of the BMC by not mounting `/usr/local`, which in
+turn disables host patching at `/usr/local/share/pnor/`. Enabling field mode is
+intended to be a one-way operation which means that once enabled, there is no
+REST API provided to disable it.
Field mode can be enabled by running the following command:
@@ -335,8 +333,8 @@
```
-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:
+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:
```
fw_setenv fieldmode
@@ -351,9 +349,9 @@
### 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:
+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:
```
curl -b cjar -k -H 'Content-Type: application/json' -X POST -d '{"data":[]}' \
@@ -361,10 +359,10 @@
```
-The factory reset on the BMC side will clear `/var`, `/home`, and `/etc`.
-On the host side, the factory reset will clear the read/write volume for each
-host image on the system, clear the shared preserve host volume, pnor-prsv, and
-clear any host patches located in `/usr/local/share/pnor/`.
+The factory reset on the BMC side will clear `/var`, `/home`, and `/etc`. On the
+host side, the factory reset will clear the read/write volume for each host
+image on the system, clear the shared preserve host volume, pnor-prsv, and clear
+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
@@ -383,12 +381,12 @@
#### 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 BMC chip
-can also be used to store images. This is determined by "BMC_RO_MTD". Using both
-the alternate BMC chip and the BMC chip allows for multiple BMC images to be
-stored. By default, only the BMC chip is used. To use both, set "BMC_RO_MTD" to
-"alt-bmc+bmc".
+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
+BMC chip can also be used to store images. This is determined by "BMC_RO_MTD".
+Using both the alternate BMC chip and the BMC chip allows for multiple BMC
+images to be stored. By default, only the BMC chip is used. To use both, set
+"BMC_RO_MTD" to "alt-bmc+bmc".
### Implementation
diff --git a/architecture/code-update/emmc-storage-design.md b/architecture/code-update/emmc-storage-design.md
index 5eea020..875f2a7 100644
--- a/architecture/code-update/emmc-storage-design.md
+++ b/architecture/code-update/emmc-storage-design.md
@@ -2,34 +2,37 @@
Author: Adriana Kobylak < anoo! >
-Other contributors: Joel Stanley < shenki! >,
- Milton Miller
+Other contributors: Joel Stanley < shenki! >, Milton Miller
Created: 2019-06-20
## Problem Description
+
Proposal to define an initial storage design for an eMMC device. This includes
filesystem type, partitioning, volume management, boot options and
initialization, etc.
## Background and References
+
OpenBMC currently supports raw flash such as the SPI NOR found in the systems
based on AST2400 and AST2500, but there is no design for managed NAND.
## Requirements
-- Security: Ability to enforce read-only, verification of official/signed
- images for production.
+
+- Security: Ability to enforce read-only, verification of official/signed images
+ for production.
- Updatable: Ensure that the filesystem design allows for an effective and
simple update mechanism to be implemented.
-- Simplicity: Make the system easy to understand, so that it is easy to
- develop, test, use, and recover.
+- Simplicity: Make the system easy to understand, so that it is easy to develop,
+ test, use, and recover.
- Code reuse: Try to use something that already exists instead of re-inventing
the wheel.
## Proposed Design
+
- The eMMC image layout and characteristics are specified in a meta layer. This
allows OpenBMC to support different layouts and configurations. The tarball to
perform a code update is still built by image_types_phosphor, so a separate
@@ -78,6 +81,7 @@
as it currently does for NOR chips.
## Alternatives Considered
+
- Store U-Boot and the Linux kernel in a separate SPI NOR flash device, since
SOCs such as the AST2500 do not support executing U-Boot from an eMMC. In
addition, having the Linux kernel on the NOR saves from requiring U-Boot
@@ -89,11 +93,11 @@
Format the NOR as it is currently done for a system that supports UBI: a fixed
MTD partition for U-Boot, one for its environment, and a UBI volume spanning
- the remaining of the flash. Store the dual kernel volumes in the UBI partition.
- This approach allows the re-use of the existing code update interfaces, since
- the static approach does not currently support storing two kernel images.
- Selection of the desired kernel image would be done with the existing U-Boot
- environment approach.
+ the remaining of the flash. Store the dual kernel volumes in the UBI
+ partition. This approach allows the re-use of the existing code update
+ interfaces, since the static approach does not currently support storing two
+ kernel images. Selection of the desired kernel image would be done with the
+ existing U-Boot environment approach.
Static MTD partitions could be created to store the kernel images, but
additional work would be required to introduce a new method to select the
@@ -190,18 +194,18 @@
the same paths as to prevent changes to the applications that rely on the
location of that data.
- - Provisioning: Since the LVM userspace tools don't offer an offline
- mode, it's not straightforward to assemble an LVM disk image from a bitbake
- task. Therefore, have the initramfs create the LVM volume and fetch the
- rootfs file into tmpfs from an external source to flash the volume. The
- rootfs file can be fetched using DHCP, UART, USB key, etc. An alternative
- option include to build the image from QEMU, this would require booting QEMU
- as part of the build process to setup the LVM volume and create the image
- file.
+ - Provisioning: Since the LVM userspace tools don't offer an offline mode,
+ it's not straightforward to assemble an LVM disk image from a bitbake task.
+ Therefore, have the initramfs create the LVM volume and fetch the rootfs
+ file into tmpfs from an external source to flash the volume. The rootfs file
+ can be fetched using DHCP, UART, USB key, etc. An alternative option include
+ to build the image from QEMU, this would require booting QEMU as part of the
+ build process to setup the LVM volume and create the image file.
## Impacts
-This design would impact the OpenBMC build process and code update
-internal implementations but should not affect the external interfaces.
+
+This design would impact the OpenBMC build process and code update internal
+implementations but should not affect the external interfaces.
- openbmc/linux: Kernel changes to support the eMMC chip and its filesystem.
- openbmc/openbmc: Changes to create an eMMC image.
@@ -211,7 +215,9 @@
filesystem.
## Testing
+
Verify OpenBMC functionality in a system containing an eMMC. This system could
be added to the CI pool.
-[pre-init script]: https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/preinit-mounts/preinit-mounts/init
+[pre-init script]:
+ https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/preinit-mounts/preinit-mounts/init
diff --git a/architecture/code-update/firmware-update-over-redfish.md b/architecture/code-update/firmware-update-over-redfish.md
index 7892fa0..2a56398 100644
--- a/architecture/code-update/firmware-update-over-redfish.md
+++ b/architecture/code-update/firmware-update-over-redfish.md
@@ -5,6 +5,7 @@
Created: 2019-02-11
## Problem Description
+
OpenBMC is moving to [Redfish][1] as its standard for out of band management.
Redfish has its own API's and methods for updating firmware on a system and
implementing those is going to require some changes (and potential upstream work
@@ -14,32 +15,34 @@
OpenBMC's existing firmware update implementation over to Redfish.
## 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 [here][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
+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:
+
- Redfish has a single upload and update API. OpenBMC has a concept of uploading
an image with one API and then activating with another.
- Redfish does not support multiple firmware images being associated with the
same target. OpenBMC does have support for this concept (for example when a
target like the BMC has multiple flash chips associated with it). A discussion
has been started with the DMTF on this within [Issue 3357][10]
- - OpenBMC has the concept of a priority that allows a user to chose an
- image associated with a target for activation. This allows a user to easily
- switch back and forth between multiple images for a single target without
- uploading each image every time.
+ - OpenBMC has the concept of a priority that allows a user to chose an image
+ associated with a target for activation. This allows a user to easily switch
+ back and forth between multiple images for a single target without uploading
+ each image every time.
- Redfish does not support deleting a firmware image (this happens by default
when a new image is uploaded)
- Redfish does support the ability to update multiple targets with the same
image with the same command. OpenBMC does not support this currently.
-- Redfish has support via a SimpleUpdate action which allows the user to
- pass in a variety of remote locations to retrieve a file from
- (FTP, HTTP, SCP, ...). Existing OpenBMC only has support for TFTP.
+- Redfish has support via a SimpleUpdate action which allows the user to pass in
+ a variety of remote locations to retrieve a file from (FTP, HTTP, SCP, ...).
+ Existing OpenBMC only has support for TFTP.
- Redfish has the ability to schedule when a firmware update is applied
(Immediate, OnReset, AtMaintenanceWindowStart...). Existing OpenBMC firmware
has no concept of this.
@@ -58,6 +61,7 @@
with what the existing OpenBMC REST api's provide.
### 2.7 Requirements
+
- Support FirmwareInventory definition for BMC and BIOS under UpdateService
- Support FirmwareVersion under Managers/BMC
- Support BiosVersion under Systems/system
@@ -75,16 +79,15 @@
### Future Requirements
-**Note:** TODO: The goal of this section is to document at a high
-level what will be required post 2.7 release. An update to this design document
-will be required before these requirements are implemented. They are here to
-ensure nothing in the base design would inhibit the ability to implement these
-later.
+**Note:** TODO: The goal of this section is to document at a high level what
+will be required post 2.7 release. An update to this design document will be
+required before these requirements are implemented. They are here to ensure
+nothing in the base design would inhibit the ability to implement these later.
- Support new concept defined in [PR 3420][12] to be able to support multiple
firmware images for a single target.
-- Support new UpdateService firmware update implementation defined in
- [Issue 3296][11]
+- Support new UpdateService firmware update implementation defined in [Issue
+ 3296][11]
- Support firmware update for other targets (power supplies, voltage regulators,
...)
- Support to update multiple targets with the same firmware image at once
@@ -102,6 +105,7 @@
### Update An Image
The pseudo flow for an update is:
+
```
Discover UpdateService location
HttpPushUri = GET https://${bmc}/redfish/v1/UpdateService
@@ -110,29 +114,31 @@
(Immediate or OnReset)
POST <image> https://${bmc}/${HttpPushUri}
```
+
This will cause the following on the back-end:
+
- Receive the image
- Copy it internally to the required location in the filesystem (/tmp/images)
- Wait for the InterfacesAdded signal from /xyz/openbmc_project/software
- Activate the new image
- If ApplyTime is Immediate, reboot the BMC or Host
- If ApplyTime is OnReset, do nothing (user will need to initiate host or bmc
- reboot to apply image)
+ reboot to apply image)
Note that the ApplyTime property will be processed by the software management
-stack at the end of the activation.
-Note that the ApplyTime property is global to all firmware update packages and
-will be used for all subsequent firmware update packages.
+stack at the end of the activation. Note that the ApplyTime property is global
+to all firmware update packages and will be used for all subsequent firmware
+update packages.
### Status of an Image
-The user needs to know the status of their firmware images, especially during
-an update. The Task concept is still being defined within the DMTF and will
-provide the full status of an image during upload and activate.
-Using the Status object associated with the software inventory items will be
-used as a mechanism to provide status of inventory items back to the user.
-Here is the mapping of [phosphor activation states][13] to
-[Redfish Status States][14].
+The user needs to know the status of their firmware images, especially during an
+update. The Task concept is still being defined within the DMTF and will provide
+the full status of an image during upload and activate. Using the Status object
+associated with the software inventory items will be used as a mechanism to
+provide status of inventory items back to the user. Here is the mapping of
+[phosphor activation states][13] to [Redfish Status States][14].
+
```
NotReady -> Disabled
Invalid -> Disabled
@@ -159,7 +165,7 @@
window. After setting the priority to 0, the software manager automatically
updates the priority of the other images as needed.
-### Remote Image Download Based Update ###
+### Remote Image Download Based Update
As noted above, Redfish supports a SimpleUpdate object under the UpdateService.
The SimpleUpdate schema supports a variety of transfer protocols (CIFS, FTP,
@@ -172,6 +178,7 @@
file name so there will be some parsing required.
The pseudo flow for an update is:
+
```
# Discover SimpleUpdate URI Action location
GET https://${bmc}/redfish/v1/UpdateService
@@ -197,6 +204,7 @@
bmcweb repository for details).
### Delete an Image
+
No support for deleting an image will be provided (until the DMTF provides it).
When new images are uploaded, they by default have no priority. When they are
activated, they are given the highest priority and all other images have their
@@ -205,15 +213,17 @@
activated.
## Alternatives Considered
+
Could simply create Redfish OEM api's that look like OpenBMC's current custom
-REST api's. The porting would be minimal but then OpenBMC would not conform
-to any standard Redfish API's. Other vendors have done this but the Redfish
-DMTF is making strides towards enhancing the UpdateService to contain the
-features required to make an enterprise based firmware update API. OpenBMC
-should just stay at the forefront of these DMTF changes and ensure they are
-implemented as they are released.
+REST api's. The porting would be minimal but then OpenBMC would not conform to
+any standard Redfish API's. Other vendors have done this but the Redfish DMTF is
+making strides towards enhancing the UpdateService to contain the features
+required to make an enterprise based firmware update API. OpenBMC should just
+stay at the forefront of these DMTF changes and ensure they are implemented as
+they are released.
## Impacts
+
This will be using the existing D-Bus API's for firmware update internally so
there should be minimal impact between the previous REST implementation.
@@ -222,21 +232,28 @@
the D-Bus API's behind the [Software Version Management][8] implementation.
## Testing
+
End to end [tests][9] are being written for the firmware update of BMC and BIOS
firmware, these must pass. Also unit tests must be written with the required
D-Bus API's mocked to ensure proper code coverage.
[1]: https://redfish.dmtf.org/
-[2]: https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md#steps-to-update
+[2]:
+ https://github.com/openbmc/docs/blob/master/architecture/code-update/code-update.md#steps-to-update
[3]: http://redfish.dmtf.org/schemas/v1/UpdateService.json
-[4]: http://redfish.dmtf.org/schemas/v1/UpdateService.v1_4_0.json#/definitions/UpdateService
+[4]:
+ http://redfish.dmtf.org/schemas/v1/UpdateService.v1_4_0.json#/definitions/UpdateService
[5]: https://www.supermicro.com/manuals/other/RedfishRefGuide.pdf
-[6]: https://github.com/dell/iDRAC-Redfish-Scripting/blob/master/Redfish%20Python/DeviceFirmwareDellUpdateServiceREDFISH.py
-[7]: https://github.com/openbmc/bmcweb/blob/master/redfish-core/lib/update_service.hpp
-[8]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/README.md
+[6]:
+ https://github.com/dell/iDRAC-Redfish-Scripting/blob/master/Redfish%20Python/DeviceFirmwareDellUpdateServiceREDFISH.py
+[7]:
+ https://github.com/openbmc/bmcweb/blob/master/redfish-core/lib/update_service.hpp
+[8]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/README.md
[9]: https://github.com/openbmc/openbmc-test-automation
[10]: https://github.com/DMTF/Redfish/issues/3357
[11]: https://github.com/DMTF/Redfish/pull/3296
[12]: https://github.com/DMTF/Redfish/pull/3420
-[13]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/Activation.interface.yaml
+[13]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/Activation.interface.yaml
[14]: http://redfish.dmtf.org/schemas/v1/Resource.json#/definitions/Status
diff --git a/architecture/code-update/flash-layout.md b/architecture/code-update/flash-layout.md
index 0258182..b47f957 100644
--- a/architecture/code-update/flash-layout.md
+++ b/architecture/code-update/flash-layout.md
@@ -1,4 +1,5 @@
# OpenBMC Flash Layout and Filesystem Documentation
+
This file is focused on providing information about the flash setup that the
code update application requires to be supported out-of-the-box, which includes
how the Linux filesystem is setup, filesystem layouts, overlays, boot options,
@@ -6,7 +7,9 @@
[code-update.md](code-update.md) for details about code update interfaces.
## Design considerations
+
### Boot loading and init
+
For system initialization and bootstrap, [Das U-Boot][] was selected as the
bootloader.
@@ -19,6 +22,7 @@
line embedded in the tree.
### Runtime management
+
For runtime management, the [systemd][] system and service manager was chosen
for its configuration, dependency, and triggered action support, as well as its
robust recovery.
@@ -28,6 +32,7 @@
starting systemd. Reference the [systemd File Hierarchy Requirements][].
### Root filesystem
+
For storage of the root filesystem, a read-only volume was selected. This allows
the majority of the filesystem content, including all executables and static
data files, to be stored in a read-only filesystem image. Replacing read-only
@@ -54,12 +59,14 @@
section below.
## Supported Filesystem Choices
+
OpenBMC supports code update for the following types of filesystems. Additional
information is given for each filesystem such as how the filesystem is stored on
flash, how the filesystem is instantiated during system boot/init, and how code
update handles the filesystem.
### Writable Filesystem Options
+
#### JFFS2 on MTD partition
The majority of the filesystem is stored in a read-only squashfs in an MTD
@@ -116,19 +123,25 @@
This is a work in progress. See the [eMMC Design Document][].
### Auxiliary Filesystems
-A tmpfs is used for /tmp, /run, and similar, while /dev, /proc, and
-/sys are supported by their normal kernel special filesystems, as specified by
-the FHS.
+
+A tmpfs is used for /tmp, /run, and similar, while /dev, /proc, and /sys are
+supported by their normal kernel special filesystems, as specified by the FHS.
## Other
+
Additional Bitbake layer configurations exist for Raspberry Pi and x86 QEMU
machines, but are provided primarily for code development and exploration. Code
update for these environments is not supported.
-[Das U-Boot]: https://www.denx.de/wiki/U-Boot
-[systemd]: https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md
-[systemd File Hierarchy Requirements]: https://www.freedesktop.org/wiki/Software/systemd/FileHierarchy/
-[FHS]: https://refspecs.linuxfoundation.org/fhs.shtml
-[obmc-phosphor-initfs]: https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/initrdscripts/obmc-phosphor-initfs.bb
-[preinit-mounts]: https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/preinit-mounts
-[eMMC Design Document]: https://github.com/openbmc/docs/blob/master/architecture/code-update/emmc-storage-design.md
+[das u-boot]: https://www.denx.de/wiki/U-Boot
+[systemd]:
+ https://github.com/openbmc/docs/blob/master/architecture/openbmc-systemd.md
+[systemd file hierarchy requirements]:
+ https://www.freedesktop.org/wiki/Software/systemd/FileHierarchy/
+[fhs]: https://refspecs.linuxfoundation.org/fhs.shtml
+[obmc-phosphor-initfs]:
+ https://github.com/openbmc/openbmc/blob/master/meta-phosphor/recipes-phosphor/initrdscripts/obmc-phosphor-initfs.bb
+[preinit-mounts]:
+ https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/preinit-mounts
+[emmc design document]:
+ https://github.com/openbmc/docs/blob/master/architecture/code-update/emmc-storage-design.md
diff --git a/architecture/code-update/host-code-update.md b/architecture/code-update/host-code-update.md
index 90f9056..57f4413 100644
--- a/architecture/code-update/host-code-update.md
+++ b/architecture/code-update/host-code-update.md
@@ -1,5 +1,4 @@
-Host Code Update
-================
+# Host Code Update
Reference:
https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software
@@ -8,116 +7,118 @@
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`.
+ methods:
- ```
- 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
- ```
+- 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
+ ```
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:
+ 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
- ```
+ ```
+ # 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",
- ```
+ ```
+ $ 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
- ```
+ ```
+ 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:
+ 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
+ ```
+ 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
- ```
+ ```
+ 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:
+ 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
- ```
+ ```
+ 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
- ```
+ ```
+ 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:
+ 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
- ```
+ ```
+ 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>
- ```
+ ```
+ curl -b cjar -k https://${bmc}/xyz/openbmc_project/software/<id>
+ ```
### Patching the host firmware
diff --git a/architecture/interface-overview.md b/architecture/interface-overview.md
index 2b7902e..ebc38db 100644
--- a/architecture/interface-overview.md
+++ b/architecture/interface-overview.md
@@ -1,57 +1,58 @@
# OpenBMC interfaces
-Purpose: This introduces a simplified view of the BMC's primary interfaces.
-It is intended to provide a reference suitable for a wide audience:
- - Engineers provide domain expertise in specific areas and learn about use
- cases and threats their interfaces poses.
- - Give BMC administrators and system integrators a simplified view of the
- BMC's system interfaces. For example, to understand which interfaces can
- be disabled.
- - Management and security folks need everything to work and play together
- nicely. For example, to understand the BMC's attack surfaces.
+Purpose: This introduces a simplified view of the BMC's primary interfaces. It
+is intended to provide a reference suitable for a wide audience:
+
+- Engineers provide domain expertise in specific areas and learn about use cases
+ and threats their interfaces poses.
+- Give BMC administrators and system integrators a simplified view of the BMC's
+ system interfaces. For example, to understand which interfaces can be
+ disabled.
+- Management and security folks need everything to work and play together
+ nicely. For example, to understand the BMC's attack surfaces.
## Introduction to the interfaces and services
-This section shows the BMC's primary interfaces and how they are related. It
-begins with the BMC's physical interfaces and moves toward abstractions such
-as network services. The intent is to show the interfaces essential to the
-OpenBMC project in a framework to reason about which interfaces are present,
-how they are related. This provides a foundation to reason about which can be
-disabled, how they are secured, etc. The appendix provides details about each
-interface and service shown.
+This section shows the BMC's primary interfaces and how they are related. It
+begins with the BMC's physical interfaces and moves toward abstractions such as
+network services. The intent is to show the interfaces essential to the OpenBMC
+project in a framework to reason about which interfaces are present, how they
+are related. This provides a foundation to reason about which can be disabled,
+how they are secured, etc. The appendix provides details about each interface
+and service shown.
-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 details from the unit file may be shown, such as the
-program which implements a service.
+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
+details from the unit file may be shown, such as the program which implements a
+service.
-The OpenBMC [Service Management][] interface can control `systemd` services.
-For example, disabling a BMC service will disable the corresponding external
+The OpenBMC [Service Management][] interface can control `systemd` services. For
+example, disabling a BMC service will disable the corresponding external
interface.
-[systemd concepts]: https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts
-[Service Management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Service/README.md
+[systemd concepts]:
+ https://www.freedesktop.org/software/systemd/man/systemd.html#Concepts
+[service management]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Service/README.md
-Diagrams are included to help visualize relationships. The diagrams show
-management agents on the left side, the BMC in the center, and host elements
-on the right side. The diagrams are simplified and are not intended to be
-complete.
+Diagrams are included to help visualize relationships. The diagrams show
+management agents on the left side, the BMC in the center, and host elements on
+the right side. The diagrams are simplified and are not intended to be complete.
### Physical interfaces
This shows the BMC's physical connections including network, USB, UART serial,
-and connections to its host platform. This uses a simplified view of the host
-which shows only the host interfaces that connect directly to the BMC. A
-typical host would have additional connections for console, network, etc.
+and connections to its host platform. This uses a simplified view of the host
+which shows only the host interfaces that connect directly to the BMC. A typical
+host would have additional connections for console, network, etc.
-Interfaces between the BMC and its host platform vary considerably based on
-BMC and host platform implementation. The information presented in this
-section and its subsections is intended to illustrate common elements, not to
-represent any particular system. This section is intended to be referenced by
-additional documentation which gives details for specific BMC and host
-implementations.
+Interfaces between the BMC and its host platform vary considerably based on BMC
+and host platform implementation. The information presented in this section and
+its subsections is intended to illustrate common elements, not to represent any
+particular system. This section is intended to be referenced by additional
+documentation which gives details for specific BMC and host implementations.
```
+----------------+ +----------------+
@@ -74,26 +75,29 @@
#### Host-BMC physical interface transport protocols
This lists protocols that operate over the BMC-host physical interfaces:
- - Host IPMI.
- - [MCTP][]. OpenBMC offers MCTP over LPC, PCIe, UART.
- - Custom OEM solution.
- - SMBus.
-[MCTP]: https://www.dmtf.org/sites/default/files/standards/documents/DSP0236_1.3.0.pdf
+- Host IPMI.
+- [MCTP][]. OpenBMC offers MCTP over LPC, PCIe, UART.
+- Custom OEM solution.
+- SMBus.
+
+[mctp]:
+ https://www.dmtf.org/sites/default/files/standards/documents/DSP0236_1.3.0.pdf
#### Host-BMC data models
This lists specifications for the data which flows over the BMC-host transport
protocols:
- - Host IPMI.
- - PLDM (DMTF document DSP0240).
- - Custom OEM solution.
+
+- Host IPMI.
+- PLDM (DMTF document DSP0240).
+- Custom OEM solution.
### Network services provided
-OpenBMC provides services via its management network. The default services
-are listed here by port number. More information about each service is given
-in sections below or in the appendix.
+OpenBMC provides services via its management network. The default services are
+listed here by port number. More information about each service is given in
+sections below or in the appendix.
```
+----------------------------------+
@@ -117,28 +121,33 @@
```
Services provided to connected clients may use ports for:
- - Active SSH sessions.
- - Active KVM-IP sessions.
- - Active virtual media sessions.
+
+- Active SSH sessions.
+- Active KVM-IP sessions.
+- Active virtual media sessions.
### Network services consumed
-This section lists network services used by OpenBMC systems. OpenBMC uses the
-typical services in the usual way, such as NTP, DNS, and DHCP. In addition,
+This section lists network services used by OpenBMC systems. OpenBMC uses the
+typical services in the usual way, such as NTP, DNS, and DHCP. In addition,
OpenBMC uses:
- - TFTP (disabled by default, when invoked by BMC operator) - Trivial FTP
- client to fetch firmware images for [code update][].
- - SNMP manager to catch [SNMP traps][] (when enabled).
-[code update]: https://github.com/openbmc/docs/blob/master/code-update/code-update.md
-[SNMP traps]: https://github.com/openbmc/phosphor-snmp/blob/master/docs/snmp-configuration.md
+- TFTP (disabled by default, when invoked by BMC operator) - Trivial FTP client
+ to fetch firmware images for [code update][].
+- SNMP manager to catch [SNMP traps][] (when enabled).
+
+[code update]:
+ https://github.com/openbmc/docs/blob/master/code-update/code-update.md
+[snmp traps]:
+ https://github.com/openbmc/phosphor-snmp/blob/master/docs/snmp-configuration.md
### Host console
OpenBMC provides access to its host's serial console in various ways:
- - Client access via network IPMI.
- - Client access via ssh port 2200.
- - The hostlogger facility.
+
+- Client access via network IPMI.
+- Client access via ssh port 2200.
+- The hostlogger facility.
```
+---------------------------+ +-----------------+
@@ -183,22 +192,22 @@
```
In the diagram, the arrowheads represent the flow of control from web agents to
-BMCWeb APIs, some of which set up Websockets which give the network agent
-direct communication with the desired interface (not via BMCWeb).
+BMCWeb APIs, some of which set up Websockets which give the network agent direct
+communication with the desired interface (not via BMCWeb).
-Note that [BMCWeb is configurable][] at compile time. This section describes
-the default configuration (which serves the HTTP application protocol over the
-HTTPS transport protocol on TCP port 443).
+Note that [BMCWeb is configurable][] at compile time. This section describes the
+default configuration (which serves the HTTP application protocol over the HTTPS
+transport protocol on TCP port 443).
-[BMCWeb is configurable]: https://github.com/openbmc/bmcweb#configuration
+[bmcweb is configurable]: https://github.com/openbmc/bmcweb#configuration
Services provided:
- - Web application (webui-vue) and other static content
- - REST APIs including custom phosphor-rest and Redfish APIs
- - KVM-IP (Keyboard, Video, Mouse over IP)
- - Virtual media via USB-IP (Universal Serial Bus over IP)
- - others
+- Web application (webui-vue) and other static content
+- REST APIs including custom phosphor-rest and Redfish APIs
+- KVM-IP (Keyboard, Video, Mouse over IP)
+- Virtual media via USB-IP (Universal Serial Bus over IP)
+- others
### Host IPMI services
@@ -214,16 +223,17 @@
```
The IPMI firmware firewall (which aims to control which host commands and
-channels can be used) is not implemented in OpenBMC. There is support for a
+channels can be used) is not implemented in OpenBMC. There is support for a
[Phosphor host IPMI whitelist][] scheme.
-[Phosphor host IPMI whitelist]: https://github.com/openbmc/openbmc/blob/master/meta-phosphor/classes/phosphor-ipmi-host-whitelist.bbclass
+[phosphor host ipmi whitelist]:
+ https://github.com/openbmc/openbmc/blob/master/meta-phosphor/classes/phosphor-ipmi-host-whitelist.bbclass
### D-Bus interfaces
OpenBMC uses D-Bus interfaces as the primary way to communicate (inter-process
-communication) between OpenBMC applications. Note that other methods are
-used, for example Unix domain sockets.
+communication) between OpenBMC applications. Note that other methods are used,
+for example Unix domain sockets.
```
+--------------------------------------------------+
@@ -242,26 +252,27 @@
+--------------------------------------------------+
```
-To learn more, read the [Phosphor D-Bus interface docs][] and search for
-README files in various subdirectories under the xyz/openbmc_project path.
+To learn more, read the [Phosphor D-Bus interface docs][] and search for README
+files in various subdirectories under the xyz/openbmc_project path.
-[Phosphor D-Bus interface docs]: https://github.com/openbmc/phosphor-dbus-interfaces
-
+[phosphor d-bus interface docs]:
+ https://github.com/openbmc/phosphor-dbus-interfaces
## Interfaces and services
-This section lists each interface and service shown in this document. The
-intent is to give the relevance of each item and how to locate details in the
-source code.
+This section lists each interface and service shown in this document. The intent
+is to give the relevance of each item and how to locate details in the source
+code.
### BMC network
This sections shows variations in the operational environment of the BMC's
management network.
-The BMC may be connected to a network used to manage the BMC. This is dubbed
-the "management network" to distinguish it from the payload network the host
-system is connected to. These are typically separate networks.
+The BMC may be connected to a network used to manage the BMC. This is dubbed the
+"management network" to distinguish it from the payload network the host system
+is connected to. These are typically separate networks.
+
```
+-----------+ +----------------+
| BMC | | Host |
@@ -273,6 +284,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:
+
```
+-----------+ +----------------+
| BMC | | Host |
@@ -292,6 +304,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:
+
```
+-----------+ +----------------+
| BMC | | Host |
@@ -306,6 +319,7 @@
```
The BMC's management network may be connected to USB (LAN over USB):
+
```
+-----------+ +----------------+
| BMC | | Host |
@@ -329,73 +343,74 @@
### Secure Shell (SSH)
This refers to the SSH protocol which provides both secure shell (ssh) and
-secure copy (scp) access to the BMC. OpenBMC uses the Dropbear SSH
-implementation. Note that port 22 connects to the BMC's shell, while port 2200
+secure copy (scp) access to the BMC. OpenBMC uses the Dropbear SSH
+implementation. Note that port 22 connects to the BMC's shell, while port 2200
connects to the host console.
### HTTP and HTTPS
OpenBMC supports the HTTP application protocol over HTTPS, both handled by the
-BMCWeb server. The "http" URI scheme is disabled by default but can be
-enabled at compile time by BMCWeb configuration options.
+BMCWeb server. The "http" URI scheme is disabled by default but can be enabled
+at compile time by BMCWeb configuration options.
### Host serial console
Refers to the BMC's access to its host's serial connection which typically
-accesses the host system's console. See also `obmc-console-server` which
-provides host serial access to various internal BMC services. Contrast with
+accesses the host system's console. See also `obmc-console-server` which
+provides host serial access to various internal BMC services. Contrast with
access to the BMC's serial connection which provides access to the BMC's
console.
### Service discovery
-Refers to the multicast discovery service (mDNS). For example, you can find
-the BMC via the `avahi-browse -rt _obmc_rest._tcp` command.
+Refers to the multicast discovery service (mDNS). For example, you can find the
+BMC via the `avahi-browse -rt _obmc_rest._tcp` command.
### Service Location Protocol (SLP)
-Refers to the unicast service discovery protocol provided by `slpd`. For
-example, you can find the BMC via the `slptool -u ${ip} findsrvtypes or
-findsrvs` command.
+Refers to the unicast service discovery protocol provided by `slpd`. For
+example, you can find the BMC via the
+`slptool -u ${ip} findsrvtypes or findsrvs` command.
### RMCP+, IPMI, and ipmitool
-Refers to the RMCP+ protocol and IPMI implementation provided by `netipmid`
-with source here: `https://github.com/openbmc/phosphor-net-ipmid` and some
-details provided by [IPMI Session management][]. Network IPMI provides access
-to many resources including host IPMI access, SOL (access to the host
-console), and more. Also known as out of band IPMI. Contrast with host-IPMI
-which interacts with the host and with Redfish which provides alternate
-function.
+Refers to the RMCP+ protocol and IPMI implementation provided by `netipmid` with
+source here: `https://github.com/openbmc/phosphor-net-ipmid` and some details
+provided by [IPMI Session management][]. Network IPMI provides access to many
+resources including host IPMI access, SOL (access to the host console), and
+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][]` external command.
+The BMC's RMCP+ IPMI interface is designed to be operated by the `[ipmitool][]`
+external command.
-[IPMI Session management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Ipmi/SESSION_README.md
+[ipmi session management]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Ipmi/SESSION_README.md
[ipmitool]: https://github.com/ipmitool/ipmitool
### Host IPMI
Refers to the host-facing IPMI service provided by the `ipmid` program with
-source here: `https://github.com/openbmc/phosphor-host-ipmid`. The systemd
-service is `phosphor-ipmi-host` implemented by the `ipmid` program. Also
-known as in-band IPMI. Contrast with RMCP+ which faces the network and with
-PLDM which provides alternate function.
+source here: `https://github.com/openbmc/phosphor-host-ipmid`. The systemd
+service is `phosphor-ipmi-host` implemented by the `ipmid` program. Also known
+as in-band IPMI. Contrast with RMCP+ which faces the network and with PLDM which
+provides alternate function.
### BMC shell
This refers to the BMC's command line interface which defaults to the `bash`
-program provided via the `/bin/sh` path on the BMC's file system. Note that
-the shell (together with its utility programs) provides access to many of the
-BMC's internal and external interfaces.
+program provided via the `/bin/sh` path on the BMC's file system. Note that the
+shell (together with its utility programs) provides access to many of the BMC's
+internal and external interfaces.
### obmc-console
This refers to support for multiple independent consoles in
https://github.com/openbmc/obmc-console and two applications:
- - The `obmc-console-server` abstracts the host console (UART) connection as a
- Unix domain socket.
- - The `obmc-console-client` can connect a console to an SSH session.
+
+- The `obmc-console-server` abstracts the host console (UART) connection as a
+ Unix domain socket.
+- The `obmc-console-client` can connect a console to an SSH session.
Other applications use the console server.
@@ -403,49 +418,48 @@
Refers to the BMC service provided by the `hostlogger` program here:
https://github.com/openbmc/phosphor-hostlogger which listens to the
-`obmc-console-server` and logs host console messages into the BMC's file
-system.
+`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 control which interfaces it provides. For example, there are
-configurations options to:
- - enable downloading firmware images from a TFTP server
- - enable the "http" URI scheme
- - others
+https://github.com/openbmc/bmcweb#configuration with build-time options to
+control which interfaces it provides. For example, there are configurations
+options to:
+
+- enable downloading firmware images from a TFTP server
+- enable the "http" URI scheme
+- others
The webserver also sets up Secure Websockets for services such as KVM-IP,
Virtual-USB, and more.
### 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
+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
### 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
+Refers to the legacy REST APIs optionally served by the BMCWeb server. Docs:
+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
-Also known as IPKvm. Do not confuse with Kernel Virtual Machine (the other
-KVM).
+(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
-Also known as USB-over-IP, and helps implement virtual media. Contrast with
-the BMC and host physical USB ports.
+Also known as USB-over-IP, and helps implement virtual media. Contrast with the
+BMC and host physical USB ports.
diff --git a/architecture/ipmi-architecture.md b/architecture/ipmi-architecture.md
index eb13f90..5f38989 100644
--- a/architecture/ipmi-architecture.md
+++ b/architecture/ipmi-architecture.md
@@ -1,7 +1,7 @@
# IPMI Architecture
-IPMI is made up of commands and channels. Commands are provided by providers
-and channels are processes called bridges. Commands are received from external
+IPMI is made up of commands and channels. Commands are provided by providers and
+channels are processes called bridges. Commands are received from external
sources (system admin users) via the bridges and routed to the providers'
command handlers via the main IPMI daemon.
@@ -11,9 +11,8 @@
transporting the data, each with a slightly different protocol and transport
layer, but ultimately, the highest level data is a raw IPMI command consisting
of a NetFn/LUN, Command, and optional data. Each response is likewise a
-Completion Code and optional data. So the first step is to break apart
-channels and the IPMI queue.
-
+Completion Code and optional data. So the first step is to break apart channels
+and the IPMI queue.
```
/------------------\
@@ -70,27 +69,26 @@
array<byte>:data - optional response data
```
-A channel bridge, upon receiving a new IPMI command, will extract the
-necessary fields from whatever transport format (RMCP+, IPMB, KCS, etc.)
-For session-based channels (RMCP+) the bridge is responsible for establishing
-the session with credentials and determining the maximum privilege available
-for this session. The bridge then takes the extracted command, data, and
-possibly user and privilge information, and encodes them in a D-Bus method call
-to send to the IPMI daemon, ipmid. The daemon will take the message, and
-attempt to find an appropriate handler in its handler tables. If a handler is
-found, it will attempt to extract the required parameters for the handler and
-pass them along. The handler will return a tuple of response parameters, which
-will get packed back into a D-Bus response message and sent back to the calling
-channel's bridge. The bridge will then re-package the response into its
-transport protocol and send it off.
+A channel bridge, upon receiving a new IPMI command, will extract the necessary
+fields from whatever transport format (RMCP+, IPMB, KCS, etc.) For session-based
+channels (RMCP+) the bridge is responsible for establishing the session with
+credentials and determining the maximum privilege available for this session.
+The bridge then takes the extracted command, data, and possibly user and
+privilge information, and encodes them in a D-Bus method call to send to the
+IPMI daemon, ipmid. The daemon will take the message, and attempt to find an
+appropriate handler in its handler tables. If a handler is found, it will
+attempt to extract the required parameters for the handler and pass them along.
+The handler will return a tuple of response parameters, which will get packed
+back into a D-Bus response message and sent back to the calling channel's
+bridge. The bridge will then re-package the response into its transport protocol
+and send it off.
-The next part is to provide a higher-level, strongly-typed, modern C++
-mechanism for registering handlers. Each handler will specify exactly what
-arguments are needed for the command and what types will be returned in the
-response. This way, the ipmid queue can unpack requests and pack responses in a
-safe manner. Because the handler packing and unpacking code is templated, it
-is written mostly in headers.
-
+The next part is to provide a higher-level, strongly-typed, modern C++ mechanism
+for registering handlers. Each handler will specify exactly what arguments are
+needed for the command and what types will be returned in the response. This
+way, the ipmid queue can unpack requests and pack responses in a safe manner.
+Because the handler packing and unpacking code is templated, it is written
+mostly in headers.
## Details and Implementation
@@ -106,21 +104,21 @@
these checks fail, ipmid returns with _Insufficient Privilege_.
At this point, the IPMI command is run through the filter hooks. The default
-hook is ACCEPT, where the command just passes onto the execution phase. But
-OEMs and providers can register hooks that would ultimately block IPMI commands
-from executing, much like the IPMI 2.0 Spec's Firmware Firewall. The hook would
-be passed in the context of the IPMI call and the raw content of the call and
-has the opportunity to return any valid IPMI completion code. Any non-zero
+hook is ACCEPT, where the command just passes onto the execution phase. But OEMs
+and providers can register hooks that would ultimately block IPMI commands from
+executing, much like the IPMI 2.0 Spec's Firmware Firewall. The hook would be
+passed in the context of the IPMI call and the raw content of the call and has
+the opportunity to return any valid IPMI completion code. Any non-zero
completion code would prevent the command from executing and would be returned
to the caller.
The network channel bridges (netipmid), executing one process per interface,
-handle session (RMCP+) and SOL commands and responses to those commands.
-Get/Set SOL configuration, Get session info, close session commands can also be
+handle session (RMCP+) and SOL commands and responses to those commands. Get/Set
+SOL configuration, Get session info, close session commands can also be
requested through KCS/BT interface, ipmid daemon must also need details about
-session and SOL. In order to maintain sync between ipmid and netipmid
-daemon, session and SOL are exposed in D-Bus, which ipmid can query and respond
-to commands issued through host interface (KCS/BT).
+session and SOL. In order to maintain sync between ipmid and netipmid daemon,
+session and SOL are exposed in D-Bus, which ipmid can query and respond to
+commands issued through host interface (KCS/BT).
The next phase is parameter unpacking and validation. This is done by
compiler-generated code with variadic templates at handler registration time.
@@ -129,6 +127,7 @@
unpacked.
This is done in the core IPMI library (from a high level) like this:
+
```cpp
template <typename Handler>
class IpmiHandler
@@ -174,7 +173,9 @@
};
}
```
+
While some IPMI handlers would look like this:
+
```cpp
ipmi::RspType<> setUserAccess(
std::shared_ptr<ipmi::Context> context,
@@ -231,46 +232,46 @@
}
```
-
Ipmid providers are all executed as boost::asio::coroutines. This means that
they can take advantage of any of the boost::asio async method calls in a way
that looks like synchronous code, but will execute asynchronously by yielding
-control of the processor to the run loop via the yield_context object. Use
-the yield_context object by passing it as a 'callback' which will then cause
-the calling coroutine to yield the processor until its IO is ready, at which
-point it will 'return' much like a synchronous call.
+control of the processor to the run loop via the yield_context object. Use the
+yield_context object by passing it as a 'callback' which will then cause the
+calling coroutine to yield the processor until its IO is ready, at which point
+it will 'return' much like a synchronous call.
Ideally, all handlers would take advantage of the asynchronous capabilities of
ipmid via the boost::asio::yield_context. This means that the queue could have
multiple in-flight calls that are waiting on another D-Bus call to return. With
-asynchronous calls, this will not block the rest of the queue's operation,
-The sdbusplus::asio::connection that is available to all providers via the
-getSdBus() function provides yield_method_call() which is an asynchronous
-D-Bus call mechanism that 'looks' like a synchronous call. It is important that
-any global data that an asynchronous handler uses is protected as if the
-handler is multi-threaded. Since many of the resources used in IPMI handlers
-are actually D-Bus objects, this is not likely a common issue because of the
-serialization that happens via the D-Bus calls.
+asynchronous calls, this will not block the rest of the queue's operation, The
+sdbusplus::asio::connection that is available to all providers via the
+getSdBus() function provides yield_method_call() which is an asynchronous D-Bus
+call mechanism that 'looks' like a synchronous call. It is important that any
+global data that an asynchronous handler uses is protected as if the handler is
+multi-threaded. Since many of the resources used in IPMI handlers are actually
+D-Bus objects, this is not likely a common issue because of the serialization
+that happens via the D-Bus calls.
-Using templates, it is possible to extract the return type and argument types
-of the handlers and use that to unpack (and validate) the arguments from the
+Using templates, it is possible to extract the return type and argument types of
+the handlers and use that to unpack (and validate) the arguments from the
incoming request and then pack the result back into a vector of bytes to send
back to the caller. The deserializer will keep track of the number of bits it
has unpacked and then compare it with the total number of bits that the method
is requesting. In the example, we are assuming that the non-full-byte integers
are packed bits in the message in most-significant-bit first order (same order
-the specification describes them in). Optional arguments can be used easily
-with C++17's std::optional.
+the specification describes them in). Optional arguments can be used easily with
+C++17's std::optional.
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
-* any additional types can be created by making a pack/unpack template
+
+- 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
+- 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
extracted first. While this is opposite of the order the IPMI specification is
@@ -284,6 +285,7 @@
test/message/unpack.cpp.
As an example this is how a bitset is unpacked
+
```cpp
/** @brief Specialization of UnpackSingle for std::bitset<N>
*/
@@ -308,10 +310,10 @@
};
```
-If a handler needs to unpack a variable payload, it is possible to request
-the Payload parameter. When the Payload parameter is present, any remaining,
-unpacked bytes are available for inspection. Using the same unpacking calls
-that were used to unpack the other parameters, the remaining parameters can
-be manually unpacked. This is helpful for multi-function commands like Set
-LAN Configuration Parameters, where the first two bytes are fixed, but the
-remaining 3:N bytes vary based on the selected parameter.
+If a handler needs to unpack a variable payload, it is possible to request the
+Payload parameter. When the Payload parameter is present, any remaining,
+unpacked bytes are available for inspection. Using the same unpacking calls that
+were used to unpack the other parameters, the remaining parameters can be
+manually unpacked. This is helpful for multi-function commands like Set LAN
+Configuration Parameters, where the first two bytes are fixed, but the remaining
+3:N bytes vary based on the selected parameter.
diff --git a/architecture/object-mapper.md b/architecture/object-mapper.md
index 7887b1d..eb1130a 100644
--- a/architecture/object-mapper.md
+++ b/architecture/object-mapper.md
@@ -1,14 +1,14 @@
# The ObjectMapper
-The `xyz.openbmc_project.ObjectMapper` service, commonly referred to as just
-the mapper, is an OpenBMC application that attempts to ease the pain of using
-D-Bus by providing APIs that help in discovering and associating other D-Bus
-objects.
+The `xyz.openbmc_project.ObjectMapper` service, commonly referred to as just the
+mapper, is an OpenBMC application that attempts to ease the pain of using D-Bus
+by providing APIs that help in discovering and associating other D-Bus objects.
The mapper has two major pieces of functionality:
- [Methods](#methods) - Provides D-Bus discovery related functionality.
-- [Associations](#associations) - Associates two different objects with each other.
+- [Associations](#associations) - Associates two different objects with each
+ other.
## Methods
@@ -16,16 +16,18 @@
### GetObject
-Use this method to find the services, with their interfaces, that implement
-a certain object path. The output is a map of service names to their
-implemented interfaces. An optional list of interfaces may also be passed in
-to constrain the output to services that implement those specific interfaces.
+Use this method to find the services, with their interfaces, that implement a
+certain object path. The output is a map of service names to their implemented
+interfaces. An optional list of interfaces may also be passed in to constrain
+the output to services that implement those specific interfaces.
Inputs:
+
- path: object path
- param: interfaces - an optional list of interfaces to constrain the search to
Output:
+
- Map of service names to their interfaces
```
@@ -48,22 +50,26 @@
```
#### Example Use Case
+
Find the service name that has the desired object path so it can be passed into
a get property call.
### GetSubTree
Use this method to find the objects, services, and interfaces in the specified
-subtree that implement a certain interface. If no interfaces are passed in,
-then all objects/services/interfaces in the subtree are returned. If interfaces
-are passed in, then only those interfaces are returned in the output.
+subtree that implement a certain interface. If no interfaces are passed in, then
+all objects/services/interfaces in the subtree are returned. If interfaces are
+passed in, then only those interfaces are returned in the output.
Inputs:
-- param: subtree - the root of the tree. Using "/" will search the whole tree
-- param: depth - the maximum depth of the tree past the root to search. Use 0 to search all
+
+- param: subtree - the root of the tree. Using "/" will search the whole tree
+- param: depth - the maximum depth of the tree past the root to search. Use 0 to
+ search all
- param: interfaces - an optional list of interfaces to constrain the search to
Output:
+
- Map of object paths to a map of service names to their interfaces
```
@@ -105,17 +111,22 @@
```
#### Example Use Case
+
Find all object paths and services that implement a specific interface.
### GetSubTreePaths
+
This is the same as GetSubTree, but only returns object paths
Inputs:
-- param: subtree - the root of the tree. Using "/" will search the whole tree
-- param: depth - the maximum depth of the tree past the root to search. Use 0 to search all
+
+- param: subtree - the root of the tree. Using "/" will search the whole tree
+- param: depth - the maximum depth of the tree past the root to search. Use 0 to
+ search all
- param: interfaces - an optional list of interfaces to constrain the search to
Output:
+
- array of object paths in that subtree
```
@@ -134,18 +145,22 @@
```
#### Example Use Case
+
Find all object paths that implement a specific interface.
### GetAncestors
+
Use this method to find all ancestors of an object that implement a specific
-interface. If no interfaces are passed in, then all ancestor
+interface. If no interfaces are passed in, then all ancestor
paths/services/interfaces are returned.
Inputs:
+
- param: path - the object path to find the ancestors of
- param: interfaces - an optional list of interfaces to constrain the search to
Output:
+
- A map of object paths to a map of services names to their interfaces
```
@@ -195,51 +210,56 @@
```
#### Example Use Case
+
Find a parent object that implements a specific interface.
## Associations
Associations are special D-Bus objects created by the mapper to associate two
-objects with each other. For this to occur, some application must implement
-the `xyz.openbmc_project.Association.Definitions` interface, and then when an
+objects with each other. For this to occur, some application must implement the
+`xyz.openbmc_project.Association.Definitions` interface, and then when an
association is desired, the `Associations` property on that interface needs to
be written.
This `Associations` property is an array of tuples of the form:
+
```
[forward, reverse, object path]
```
+
- forward: this is the name of the forward association object
- reverse: this is the name of the reverse association object
- object path: this is the other object to associate with
-When an object with, for example, an object path of `pathA` uses
-the following values:
+When an object with, for example, an object path of `pathA` uses the following
+values:
+
```
["foo", "bar", "pathB"]
```
+
The mapper will create 2 new objects:
1. `pathA/foo`
2. `pathB/bar`
On each of these objects, the interface `xyz.openbmc_project.Association` will
-be implemented, which has a single `endpoints` property. This property is
-an array that holds the object paths to the other end of the association.
+be implemented, which has a single `endpoints` property. This property is an
+array that holds the object paths to the other end of the association.
-So, `pathA/foo->endpoints` will contain `pathB`, and `pathB/bar->endpoints`
-will contain `pathA`.
+So, `pathA/foo->endpoints` will contain `pathB`, and `pathB/bar->endpoints` will
+contain `pathA`.
If another object, say `pathC`, also has an association to `pathB`, then a
second entry, `pathC`, will be added into `pathB`\'s endpoints property.
-These new objects will match the lifetime of the associated objects.
-For example, if `pathA` is deleted, then `pathA/foo` will also be deleted,
-and `pathA` will be removed from the endpoints property of `pathB/bar`. If
-that was the last entry in that property, then `pathB/bar` will also be deleted.
-In addition, if the endpoint path is removed from D-Bus, in this case `pathB`,
-then the mapper will remove the 2 association paths until `pathB` shows back
-up again.
+These new objects will match the lifetime of the associated objects. For
+example, if `pathA` is deleted, then `pathA/foo` will also be deleted, and
+`pathA` will be removed from the endpoints property of `pathB/bar`. If that was
+the last entry in that property, then `pathB/bar` will also be deleted. In
+addition, if the endpoint path is removed from D-Bus, in this case `pathB`, then
+the mapper will remove the 2 association paths until `pathB` shows back up
+again.
Note: The original name of the association definition interface was
`org.openbmc.Associations`. While the mapper still supports this interface as
@@ -277,4 +297,6 @@
}
```
-[1]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/ObjectMapper.interface.yaml
+
+[1]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/ObjectMapper.interface.yaml
diff --git a/architecture/openbmc-systemd.md b/architecture/openbmc-systemd.md
index bda20ad..fc5c261 100644
--- a/architecture/openbmc-systemd.md
+++ b/architecture/openbmc-systemd.md
@@ -1,10 +1,10 @@
-OpenBMC & Systemd
-===================
+# OpenBMC & Systemd
+
OpenBMC uses [systemd](https://www.freedesktop.org/wiki/Software/systemd/) to
-manage all processes. It has its own set of target and service units to
-control which processes are started. There is a lot of documentation on systemd
-and to do OpenBMC state work, you're going to have to read some of it. Here's
-the highlights:
+manage all processes. It has its own set of target and service units to control
+which processes are started. There is a lot of documentation on systemd and to
+do OpenBMC state work, you're going to have to read some of it. Here's the
+highlights:
[Unit](https://www.freedesktop.org/software/systemd/man/systemd.unit.html#) -
Units are the basic framework of all systemd work.
@@ -17,23 +17,27 @@
2. Define the services that get run for a given target.
On an OpenBMC system, you can go to /lib/systemd/system/ and see all of the
-systemd units on the system. You can easily cat these files to start looking at
-the relationships among them. Service files can also be found in
+systemd units on the system. You can easily cat these files to start looking at
+the relationships among them. Service files can also be found in
/etc/systemd/system and /run/systemd/system as well.
[systemctl](https://www.freedesktop.org/software/systemd/man/systemctl.html) is
the main tool you use to interact with systemd and its units.
-----------
+---
+
## Initial Power
+
When an OpenBMC system first has power applied, it starts the "default.target"
-unless an alternate target is specified on the kernel command line. In
-Phosphor OpenBMC, there is a link from `default.target` to `multi-user.target`.
+unless an alternate target is specified on the kernel command line. In Phosphor
+OpenBMC, there is a link from `default.target` to `multi-user.target`.
You'll find all the phosphor services associated with `multi-user.target`.
## Server Power On
-When OpenBMC is used within a server, the [obmc-host-start@.target](https://github.com/openbmc/phosphor-state-manager/blob/master/target_files/obmc-host-start%40.target)
+
+When OpenBMC is used within a server, the
+[obmc-host-start@.target](https://github.com/openbmc/phosphor-state-manager/blob/master/target_files/obmc-host-start%40.target)
is what drives the boot of the system.
To start it you would run `systemctl start obmc-host-start@0.target`.
@@ -46,7 +50,9 @@
obmc-host-startmin@0.target
phosphor-reset-host-reboot-attempts@0.service
```
-The [obmc-host-startmin@.target](https://github.com/openbmc/phosphor-state-manager/blob/master/target_files/obmc-host-startmin%40.target)
+
+The
+[obmc-host-startmin@.target](https://github.com/openbmc/phosphor-state-manager/blob/master/target_files/obmc-host-startmin%40.target)
represents the bare minimum of services and targets required to start the host.
This target is also utilized in host reboot scenarios. This distinction of a
host-start and a host-startmin target allows the user to put services in the
@@ -56,6 +62,7 @@
host boot attempt.
Next if we look at the `obmc-host-startmin@0.target`, we see this:
+
```
ls -1 /lib/systemd/system/obmc-host-startmin@0.target.requires/
obmc-chassis-poweron@0.target
@@ -68,6 +75,7 @@
The `obmc-chassis-poweron@0.target` has corresponding services associated with
it:
+
```
ls -1 /lib/systemd/system/obmc-chassis-poweron@0.target.requires/
op-power-start@0.service
@@ -79,33 +87,37 @@
The services have dependencies within them that control the execution of each
service (for example, the op-power-start.service will run prior to the
-op-wait-power-on.service). These dependencies are set using targets and the
+op-wait-power-on.service). These dependencies are set using targets and the
Wants,Before,After keywords.
## Server Power Off (Soft)
+
The soft server power off function is encapsulated in the
-`obmc-host-shutdown@.target`. This target is soft in that it notifies the host
+`obmc-host-shutdown@.target`. This target is soft in that it notifies the host
of the power off request and gives it a certain amount of time to shut itself
down.
## Server Power Off (Hard)
+
The hard server power off is encapsulated in the
-`obmc-chassis-hard-poweroff@.target`. This target will force the stopping
-of the soft power off service if running, and immediately cut power to the
-system.
+`obmc-chassis-hard-poweroff@.target`. This target will force the stopping of the
+soft power off service if running, and immediately cut power to the system.
## Server Reboot
-The reboot of the server is encapsulated in the `obmc-host-reboot@.target`.
-This target will utilize the soft power off target and then, once that
-completes, start the host power on target.
+
+The reboot of the server is encapsulated in the `obmc-host-reboot@.target`. This
+target will utilize the soft power off target and then, once that completes,
+start the host power on target.
## Server Quiesce
+
The `obmc-host-quiesce@.target` is utilized in host error scenarios. When the
`obmc-host-quiesce@0.target` is entered, it puts the host state D-Bus
-[object][https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Host.interface.yaml]
+[object][https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/state/host.interface.yaml]
in a `Quiesced` state.
## Server Emergency Power Off due to Error
+
The `obmc-chassis-emergency-poweroff@.target` is a wrapper target around the
`obmc-chassis-hard-poweroff@.target` and `obmc-host-quiesce@.target`. It is
utilized by applications that have detected critical thermal or power errors
@@ -115,35 +127,38 @@
most critical services are run in this path.
Automated error recovery (i.e. host reboot) will not be done if this target is
-started. User intervention is required to exit from it. The user could request
-a power on if they wished or a host stop / power off if they wanted to get out
-of quiesce.
+started. User intervention is required to exit from it. The user could request a
+power on if they wished or a host stop / power off if they wanted to get out of
+quiesce.
## Systemd Control in OpenBMC
+
There are a collection of services within OpenBMC that interact with systemd and
its unit files, providing somewhat of an abstraction layer from the user of the
-OpenBMC system and systemd. See the [state](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/State)
+OpenBMC system and systemd. See the
+[state](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/State)
interfaces for more information on this function.
For example, if you wanted to execute the server power on function, you would do
the following:
-> busctl set-property xyz.openbmc_project.State.Host /xyz/openbmc_project/state/host0
-xyz.openbmc_project.State.Host RequestedHostTransition s
-xyz.openbmc_project.State.Host.Transition.On
+> busctl set-property xyz.openbmc_project.State.Host
+> /xyz/openbmc_project/state/host0 xyz.openbmc_project.State.Host
+> RequestedHostTransition s xyz.openbmc_project.State.Host.Transition.On
Underneath the covers, this is calling systemd with the server power on target.
## Systemd Services or Monitoring Applications
-A common question when creating new OpenBMC applications which need to
-execute some logic in the context of systemd targets is whether they should
-be triggered by systemd services or by monitoring for the appropriate
-D-Bus signal indicating the start/stop of the target they are interested in.
+
+A common question when creating new OpenBMC applications which need to execute
+some logic in the context of systemd targets is whether they should be triggered
+by systemd services or by monitoring for the appropriate D-Bus signal indicating
+the start/stop of the target they are interested in.
The basic guidelines for when to create a systemd service are the following:
-- If your application logic depends on other systemd based services then
- make it a systemd service and utilize the Wants/After/Before service
- capabilities.
+
+- If your application logic depends on other systemd based services then make it
+ a systemd service and utilize the Wants/After/Before service capabilities.
- If other applications depend on your application logic then it should be a
systemd service.
- If your application failing during the target start could impact targets or
@@ -151,8 +166,9 @@
dependent targets are not started if your application fails.
## Error Handling of Systemd
-With great numbers of targets and services, come great chances for failures.
-To make OpenBMC a robust and productive system, it needs to be sure to have an
+
+With great numbers of targets and services, come great chances for failures. To
+make OpenBMC a robust and productive system, it needs to be sure to have an
error handling policy for when services and their targets fail.
When a failure occurs, the OpenBMC software needs to notify the users of the
@@ -163,65 +179,65 @@
There are two main failure scenarios when it comes to OpenBMC and systemd usage:
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
+ host checkstop detected)
-Within OpenBMC, there is a host quiesce target. This is the target that other
+- 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
OpenBMC can then monitor for the entry into this quiesce target and will handle
the halt vs. automatic reboot functionality.
Targets which are not host related, will need special thought in regards to
-their error handling. For example, the target responsible for applying chassis
+their error handling. For example, the target responsible for applying chassis
power, `obmc-chassis-poweron@0.target`, will have a
-`OnFailure=obmc-chassis-poweroff@%i.target` error path. That is, if the
-chassis power on target fails then power off the chassis.
+`OnFailure=obmc-chassis-poweroff@%i.target` error path. That is, if the chassis
+power on target fails then power off the chassis.
-The above info sets up some general **guidelines** for our host related
-targets and services:
+The above info sets up some general **guidelines** for our host related targets
+and services:
- All targets should have a `OnFailure=obmc-quiesce-host@.target`
-- All services which are required for a target to achieve its function should
-be RequiredBy that target (not WantedBy)
+- All services which are required for a target to achieve its function should be
+ RequiredBy that target (not WantedBy)
- All services should first try to be "Type=oneshot" so that we can just rely on
-the target failure path
+ the target failure path
- If a service can not be "Type=oneshot", then it needs to have a
-`OnFailure=obmc-quiesce-host@.target` and ideally set "RemainAfterExit=no"
-(but see caveats on this below)
+ `OnFailure=obmc-quiesce-host@.target` and ideally set "RemainAfterExit=no"
+ (but see caveats on this below)
- If a service can not be any of these then it's up to the service application
-to call systemd with the `obmc-quiesce-host@.target` on failures
+ to call systemd with the `obmc-quiesce-host@.target` on failures
### RemainAfterExit
+
This is set to "yes" for most OpenBMC services to handle the situation where
-someone starts the same target twice. If the associated service with that
-target is not running (i.e. RemainAfterExit=no), then the service will be
-executed again. Think about someone accidentally running the
-`obmc-chassis-poweron@.target` twice. If you execute it when the operating system
-is up and running, and the service which toggles the pgood pin is re-executed,
-you're going to crash your system. Given this info, the goal should always be
-to write "oneshot" services that have RemainAfterExit set to yes.
+someone starts the same target twice. If the associated service with that target
+is not running (i.e. RemainAfterExit=no), then the service will be executed
+again. Think about someone accidentally running the
+`obmc-chassis-poweron@.target` twice. If you execute it when the operating
+system is up and running, and the service which toggles the pgood pin is
+re-executed, you're going to crash your system. Given this info, the goal should
+always be to write "oneshot" services that have RemainAfterExit set to yes.
## Target and Service Dependency Details
-There are some tools available out there to visualize systemd service and
-target dependencies (systemd-analyze) but due to the complexity of our design,
-they do not generate anything very useful.
+
+There are some tools available out there to visualize systemd service and target
+dependencies (systemd-analyze) but due to the complexity of our design, they do
+not generate anything very useful.
For now, document the current dependencies on a witherspoon system for
reference.
@@ -236,6 +252,7 @@
```
### Soft Power Off
+
```
obmc-host-shutdown.target
R: xyz.openbmc_project.Ipmi.Internal.SoftPowerOff.service
@@ -270,6 +287,7 @@
```
#### Synchronization Target Dependencies
+
```
obmc-power-stop.target
W: obmc-power-stop-pre.target
diff --git a/architecture/redfish-logging-in-bmcweb.md b/architecture/redfish-logging-in-bmcweb.md
index a339e54..4996888 100644
--- a/architecture/redfish-logging-in-bmcweb.md
+++ b/architecture/redfish-logging-in-bmcweb.md
@@ -1,19 +1,19 @@
# Redfish Event Logging in bmcweb
-This guide is intended to help developers add new messages to the bmcweb
-Redfish event log.
+This guide is intended to help developers add new messages to the bmcweb Redfish
+event log.
-Redfish Message Objects can be represented in different ways. In bmcweb, we
-have chosen to use Message Registries with Message Objects that are referenced
-using a MessageId and MessageArgs fields.
+Redfish Message Objects can be represented in different ways. In bmcweb, we have
+chosen to use Message Registries with Message Objects that are referenced using
+a MessageId and MessageArgs fields.
Additional details can be found in the
[Redfish Specification](http://redfish.dmtf.org/schemas/DSP0266_1.6.1.html).
## Message Registries
-The first step when adding a new message to the Redfish event log is to find
-or add an appropriate message in a Message Registry.
+The first step when adding a new message to the Redfish event log is to find or
+add an appropriate message in a Message Registry.
The bmcweb Message Registries are located under
"\redfish-core\include\registries" in source code, and they can be examined
@@ -22,8 +22,7 @@
If an appropriate message exists, note the
1. Title of the Message Object (required as the MessageKey in the MessageId).
-2. Args (notated as "%x") in the "Message" field
-(required for the MessageArgs).
+2. Args (notated as "%x") in the "Message" field (required for the MessageArgs).
If an appropriate message does not exist, new messages can be added as follows:
@@ -37,28 +36,27 @@
## Logging Messages
-Logging messages is done by providing a Redfish MessageId and any
-corresponding MessageArgs to bmcweb.
+Logging messages is done by providing a Redfish MessageId and any corresponding
+MessageArgs to bmcweb.
A Redfish MessageId is represented in this format:
`RegistryName.MajorVersion.MinorVersion.MessageKey`
-bmcweb will search the specified Message Registry for the MessageKey,
-construct the final message using the MessageArgs, and display that in the
-event log.
+bmcweb will search the specified Message Registry for the MessageKey, construct
+the final message using the MessageArgs, and display that in the event log.
### journal-based Redfish Logging
-The journal is the current mechanism used to log Redfish Messages. bmcweb
-looks for two fields in the journal metadata:
+The journal is the current mechanism used to log Redfish Messages. bmcweb looks
+for two fields in the journal metadata:
- `REDFISH_MESSAGE_ID`: A string holding the MessageId
- `REDFISH_MESSAGE_ARGS`: A string holding a comma-separated list of args
These fields can be added to a journal entry using either the
-`phosphor::logging::entry()` command or directly using the
-`sd_journal_send()` command.
+`phosphor::logging::entry()` command or directly using the `sd_journal_send()`
+command.
### Examples
@@ -81,8 +79,8 @@
},
```
-Since there are no parameters, no MessageArgs are required, so this message
-can be logged to the journal as follows:
+Since there are no parameters, no MessageArgs are required, so this message can
+be logged to the journal as follows:
```cpp
phosphor::logging::log<log::level>(
@@ -100,6 +98,7 @@
```
#### Logging a ResourceErrorThresholdExceeded event
+
The
[Resource Event Message Registry](https://redfish.dmtf.org/registries/ResourceEvent.1.0.0.json)
holds the ResourceErrorThresholdExceeded message:
@@ -127,8 +126,8 @@
`"NumberOfArgs"` field. The meaning and types of these parameters are derived
from the `"Message"` and `"ParamTypes"` fields in the Message Registry.
-In this example, `%1` is a string holding the property name and `%2` is a
-number holding the threshold value.
+In this example, `%1` is a string holding the property name and `%2` is a number
+holding the threshold value.
The parameters are filled from a comma-separated list of the MessageArgs, so
this message can be logged to the journal as follows:
@@ -150,4 +149,4 @@
"ResourceEvent.1.0.ResourceErrorThresholdExceeded",
"REDFISH_MESSAGE_ARGS=%s,%d", "Property Name",
propertyValue, NULL);
-```
\ No newline at end of file
+```
diff --git a/architecture/sensor-architecture.md b/architecture/sensor-architecture.md
index c611575..8502ee3 100644
--- a/architecture/sensor-architecture.md
+++ b/architecture/sensor-architecture.md
@@ -1,16 +1,16 @@
# Sensor Support for OpenBMC using phosphor-hwmon
-This document describes sensors provided by [phosphor-hwmon][15]. An alternate
-method is to use the suite of applications provided by [dbus-sensors][16].
-While the configuration details between the two methods differ, the D-Bus
+This document describes sensors provided by [phosphor-hwmon][15]. An alternate
+method is to use the suite of applications provided by [dbus-sensors][16]. While
+the configuration details between the two methods differ, the D-Bus
representation remains mostly the same.
-OpenBMC makes it easy to add sensors for your hardware and is compliant with
-the traditional Linux HWMon sensor format. The architecture of OpenBMC
-sensors is to map sensors to [D-Bus][1]
-objects. The D-Bus object will broadcast the `PropertiesChanged` signal when either
-the sensor or threshold value changes. It is the responsibility of other
-applications to determine the effect of the signal on the system.
+OpenBMC makes it easy to add sensors for your hardware and is compliant with the
+traditional Linux HWMon sensor format. The architecture of OpenBMC sensors is to
+map sensors to [D-Bus][1] objects. The D-Bus object will broadcast the
+`PropertiesChanged` signal when either the sensor or threshold value changes. It
+is the responsibility of other applications to determine the effect of the
+signal on the system.
## D-Bus
@@ -24,106 +24,113 @@
**Path definitions**
-* **<type\>** : The [HWMon class][2] name in lower case.
- - Examples include `temperature, fan_tach, voltage`.
+- **<type\>** : The [HWMon class][2] name in lower case.
-* **<label\>** : User defined name of the sensor.
- - Examples include `ambient, cpu0, fan5`
+ - Examples include `temperature, fan_tach, voltage`.
+
+- **<label\>** : User defined name of the sensor.
+ - 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**
-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 of the device it is monitoring using std::hash().
+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
+of the device it is monitoring using std::hash().
## Redfish
-The [BMCWeb Redfish][10] support returns information about sensors. The
-support depends on two types of [ObjectMapper associations][11] to find the
-necessary sensor information on D-Bus.
+The [BMCWeb Redfish][10] support returns information about sensors. The support
+depends on two types of [ObjectMapper associations][11] to find the necessary
+sensor information on D-Bus.
### Association Type #1: Linking a chassis to all sensors within the chassis
-Sensors are grouped by chassis in Redfish. An ObjectMapper association is used
-to link a chassis to all the sensors within the chassis. This includes the
-sensors for all hardware that is considered to be within the chassis. For
-example, a chassis might contain two fan sensors, an ambient temperature
-sensor, and a VRM output voltage sensor.
+Sensors are grouped by chassis in Redfish. An ObjectMapper association is used
+to link a chassis to all the sensors within the chassis. This includes the
+sensors for all hardware that is considered to be within the chassis. For
+example, a chassis might contain two fan sensors, an ambient temperature sensor,
+and a VRM output voltage sensor.
#### D-Bus object paths
The association links the following D-Bus object paths together:
-* Chassis inventory item object path
-* List of sensor object paths for sensors within the chassis
+
+- Chassis inventory item object path
+- List of sensor object paths for sensors within the chassis
#### Association names
-* "all_sensors"
- * Contains the list of all sensors for this chassis
-* "chassis"
- * Contains the chassis associated with this sensor
+
+- "all_sensors"
+ - Contains the list of all sensors for this chassis
+- "chassis"
+ - Contains the chassis associated with this sensor
#### Example associations
-* /xyz/openbmc_project/inventory/system/chassis/all_sensors
- * "endpoints" property contains
- * /xyz/openbmc_project/sensors/fan_tach/fan0_0
- * /xyz/openbmc_project/sensors/fan_tach/fan0_1
- * /xyz/openbmc_project/sensors/temperature/ambient
- * /xyz/openbmc_project/sensors/voltage/p0_vdn_voltage
-* /xyz/openbmc_project/sensors/fan_tach/fan0_0/chassis
- * "endpoints" property contains
- * /xyz/openbmc_project/inventory/system/chassis
+
+- /xyz/openbmc_project/inventory/system/chassis/all_sensors
+ - "endpoints" property contains
+ - /xyz/openbmc_project/sensors/fan_tach/fan0_0
+ - /xyz/openbmc_project/sensors/fan_tach/fan0_1
+ - /xyz/openbmc_project/sensors/temperature/ambient
+ - /xyz/openbmc_project/sensors/voltage/p0_vdn_voltage
+- /xyz/openbmc_project/sensors/fan_tach/fan0_0/chassis
+ - "endpoints" property contains
+ - /xyz/openbmc_project/inventory/system/chassis
### Association Type #2: Linking a low-level hardware item to its sensors
A sensor is usually related to a low-level hardware item, such as a fan, power
-supply, VRM, or CPU. The Redfish sensor support can obtain the following
+supply, VRM, or CPU. The Redfish sensor support can obtain the following
information from the related hardware item:
-* Presence ([Inventory.Item interface][12])
-* Functional state ([OperationalStatus interface][13])
-* Manufacturer, Model, PartNumber, SerialNumber ([Decorator.Asset interface][14])
+
+- Presence ([Inventory.Item interface][12])
+- Functional state ([OperationalStatus interface][13])
+- Manufacturer, Model, PartNumber, SerialNumber ([Decorator.Asset
+ interface][14])
For this reason, an ObjectMapper association is used to link a low-level
-hardware item to its sensors. For example, a processor VRM could have
-temperature and output voltage sensors, or a dual-rotor fan could have
-two tach sensors.
+hardware item to its sensors. For example, a processor VRM could have
+temperature and output voltage sensors, or a dual-rotor fan could have two tach
+sensors.
#### D-Bus object paths
The association links the following D-Bus object paths together:
-* Low-level hardware inventory item object path
-* List of sensor object paths for sensors related to that hardware item
+
+- Low-level hardware inventory item object path
+- List of sensor object paths for sensors related to that hardware item
#### Association names
-* "sensors"
- * Contains the list of sensors for this low-level hardware item
-* "inventory"
- * Contains the low-level hardware inventory item for this sensor
+
+- "sensors"
+ - Contains the list of sensors for this low-level hardware item
+- "inventory"
+ - Contains the low-level hardware inventory item for this sensor
#### Example associations
-* /xyz/openbmc_project/inventory/system/chassis/motherboard/fan0/sensors
- * "endpoints" property contains
- * /xyz/openbmc_project/sensors/fan_tach/fan0_0
- * /xyz/openbmc_project/sensors/fan_tach/fan0_1
-* /xyz/openbmc_project/sensors/fan_tach/fan0_0/inventory
- * "endpoints" property contains
- * /xyz/openbmc_project/inventory/system/chassis/motherboard/fan0
+
+- /xyz/openbmc_project/inventory/system/chassis/motherboard/fan0/sensors
+ - "endpoints" property contains
+ - /xyz/openbmc_project/sensors/fan_tach/fan0_0
+ - /xyz/openbmc_project/sensors/fan_tach/fan0_1
+- /xyz/openbmc_project/sensors/fan_tach/fan0_0/inventory
+ - "endpoints" property contains
+ - /xyz/openbmc_project/inventory/system/chassis/motherboard/fan0
## Development Details
-Sensor properties are standardized based on the type of sensor. A Threshold
+Sensor properties are standardized based on the type of sensor. A Threshold
sensor contains specific properties associated with the rise and fall of a
-sensor value. The [Sensor Interfaces][4]
-are described in their respective YAML files. The path location in the source
-tree is identical to the interface being described below the
-[phosphor-dbus-interfaces][5] parent directory.
+sensor value. The [Sensor Interfaces][4] are described in their respective YAML
+files. The path location in the source tree is identical to the interface being
+described below the [phosphor-dbus-interfaces][5] parent directory.
example:
[openbmc/phosphor-dbus-interfaces/xyz/openbmc_project/Sensor/Threshold/Warning.yaml][6]
-
Maps to D-Bus interface
`xyz.openbmc_project.Sensor.Threshold.Warning`
@@ -187,39 +194,37 @@
### Signals
-Any property value change broadcasts a signal on D-Bus. When a value trips
-past a threshold, an additional D-Bus signal is sent.
+Any property value change broadcasts a signal on D-Bus. When a value trips past
+a threshold, an additional D-Bus signal is sent.
Example, if the value of WarningLow is 5...
-| From | To | propertyChanged Signals |
-|---|---|---|
-| 1 | 5 | "xyz.openbmc_project.Sensor.Value" : value = 5 |
-| 1 | 6 | "xyz.openbmc\_project.Sensor.Value" : value = 6 ,<br>"xyz.openbmc\_project.Sensor.Threshold.Warning" : WarningAlarmLow = 0 |
-| 5 | 6 | "xyz.openbmc\_project.Sensor.Value" : value = 6 |
-| 6 | 1 | "xyz.openbmc\_project.Sensor.Value" : value = 1 ,<br>"xyz.openbmc\_project.Sensor.Threshold.Warning" : WarningAlarmLow = 1 |
-
+| From | To | propertyChanged Signals |
+| ---- | --- | ------------------------------------------------------------------------------------------------------------------------ |
+| 1 | 5 | "xyz.openbmc_project.Sensor.Value" : value = 5 |
+| 1 | 6 | "xyz.openbmc_project.Sensor.Value" : value = 6 ,<br>"xyz.openbmc_project.Sensor.Threshold.Warning" : WarningAlarmLow = 0 |
+| 5 | 6 | "xyz.openbmc_project.Sensor.Value" : value = 6 |
+| 6 | 1 | "xyz.openbmc_project.Sensor.Value" : value = 1 ,<br>"xyz.openbmc_project.Sensor.Threshold.Warning" : WarningAlarmLow = 1 |
### System Configuration
-On the BMC each sensor's configuration is located in a file. These files
-can be found as a child of the `/etc/default/obmc/hwmon` path.
-
+On the BMC each sensor's configuration is located in a file. These files can be
+found as a child of the `/etc/default/obmc/hwmon` path.
## Creating a Sensor
-HWMon sensors are defined in the `recipes-phosphor/sensor/phosphor-hwmon%`
-path within the [machine configuration][7].
-The children of the `obmc/hwmon` directory should follow the path of either:
+HWMon sensors are defined in the `recipes-phosphor/sensor/phosphor-hwmon%` path
+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.
-As an example, the Palmetto [configuration][8]
-file for the ambient temperature sensor.
+As an example, the Palmetto [configuration][8] file for the ambient temperature
+sensor.
```
recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/bus@1e78a000/i2c-bus@c0/tmp423@4c.conf
@@ -232,9 +237,9 @@
/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.
+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.
```
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
@@ -248,7 +253,7 @@
```
In order for the sensor to be exposed to D-Bus, the configuration file must
-describe the sensor attributes. Attributes follow a format.
+describe the sensor attributes. Attributes follow a format.
```
xxx_yyy#=value
@@ -258,31 +263,25 @@
yyy = HWMon sensor type (i.e. temp, pwm)
```
-| Attribute | Interfaces Added |
-|---|---|
-|LABEL | xyz.openbmc\_project.Sensor.Value |
-| WARNHI, WARNLO | xyz.openbmc\_project.Threshold.Warning |
-| CRITHI, CRITLO | xyz.openbmc\_project.Threshold.Critical |
-
+| Attribute | Interfaces Added |
+| -------------- | -------------------------------------- |
+| LABEL | xyz.openbmc_project.Sensor.Value |
+| WARNHI, WARNLO | xyz.openbmc_project.Threshold.Warning |
+| CRITHI, CRITLO | xyz.openbmc_project.Threshold.Critical |
The HWMon sensor type
-| [HWMon sensor type][2] | type |
-|---|---|
-| temp | temperature |
-| in | voltage |
-| * | All other names map directly |
+| [HWMon sensor type][2] | type |
+| ---------------------- | ---------------------------- |
+| temp | temperature |
+| in | voltage |
+| \* | All other names map directly |
+See the [HWMon interface][2] definitions for more definitions and keyword
+details
-
-See the [HWMon interface][2]
-definitions for more definitions and keyword details
-
-
-
-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.
-
+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
@@ -295,20 +294,23 @@
```
#### Additional Config File Entries
+
The phosphor-hwmon code supports these additional config file entries:
**INTERVAL**
-The interval, in microseconds, at which sensors should be read. If
-not specified the interval is 1000000us (1 second).
+The interval, in microseconds, at which sensors should be read. If not specified
+the interval is 1000000us (1 second).
+
```
INTERVAL=1000000
```
**GAIN**, **OFFSET**
-Used to support scaled sensor readings, where
-value = (raw sensor reading) * gain + offset
+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
@@ -316,27 +318,31 @@
**MINVALUE**, **MAXVALUE**
-If found, will be used to set the MinValue/MaxValue properties
-on the `xyz.openbmc_project.Sensor.Value` interface.
+If found, will be used to set the MinValue/MaxValue properties on the
+`xyz.openbmc_project.Sensor.Value` interface.
+
```
MINVALUE_temp1 = 1
```
**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 contains the known ID.
+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
+contains the known ID.
For example
+
```
temp26_input:29000
temp26_label:171
```
-Where the 26 is just what hwmon assigns, but the 171 corresponds
-to something like an IPMI sensor value for a DIMM temperature.
+
+Where the 26 is just what hwmon assigns, but the 171 corresponds to something
+like an IPMI sensor value for a DIMM temperature.
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
@@ -344,42 +350,47 @@
**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.
+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.
```
-**TARGET\_MODE**
+**TARGET_MODE**
-Allows one to choose the fan target mode, either RPM or PWM,
-if the device driver exposes both methods.
+Allows one to choose the fan target mode, either RPM or PWM, if the device
+driver exposes both methods.
+
```
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.
+
```
PWM_TARGET_fan0 = 1 #Use the pwm1 file to control fan 0
```
**ENABLE**
-Will write a value to a pwmN\_enable file on startup if present.
+Will write a value to a pwmN_enable file on startup if present.
+
```
ENABLE_fan1 = 2 #Write a 2 to pwm1_enable
```
### Defining sensors in an IPMI YAML configuration file
-For an example of how sensors entries are defined, consult the [example
-YAML](https://github.com/openbmc/phosphor-host-ipmid/blob/master/scripts/sensor-example.yaml)
+
+For an example of how sensors entries are defined, consult the
+[example YAML](https://github.com/openbmc/phosphor-host-ipmid/blob/master/scripts/sensor-example.yaml)
#### How to best choose coefficients
+
Sensor reading, according to IPMI spec, is calculated as:
```none
@@ -430,22 +441,29 @@
```
## Additional Reading
-Mailing List [Comments on Sensor design][9]
+Mailing List [Comments on Sensor design][9]
[1]: https://dbus.freedesktop.org/doc/dbus-tutorial.html
[2]: https://www.kernel.org/doc/Documentation/hwmon/sysfs-interface
[3]: https://dbus.freedesktop.org/doc/dbus-specification.html#basic-types
-[4]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Sensor
+[4]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Sensor
[5]: https://github.com/openbmc/phosphor-dbus-interfaces
-[6]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Sensor/Threshold/Warning.interface.yaml
+[6]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Sensor/Threshold/Warning.interface.yaml
[7]: https://github.com/openbmc/openbmc/tree/master/meta-openbmc-machines
-[8]: https://github.com/openbmc/openbmc/blob/master/meta-ibm/meta-palmetto/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/bus@1e78a000/i2c-bus@c0/tmp423@4c.conf
+[8]:
+ https://github.com/openbmc/openbmc/blob/master/meta-ibm/meta-palmetto/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/bus@1e78a000/i2c-bus@c0/tmp423@4c.conf
[9]: https://lists.ozlabs.org/pipermail/openbmc/2016-November/005309.html
[10]: https://github.com/openbmc/bmcweb/blob/master/DEVELOPING.md#redfish
-[11]: https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
-[12]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Inventory/Item.interface.yaml
-[13]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Decorator/OperationalStatus.interface.yaml
-[14]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Inventory/Decorator/Asset.interface.yaml
+[11]:
+ https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
+[12]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Inventory/Item.interface.yaml
+[13]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Decorator/OperationalStatus.interface.yaml
+[14]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Inventory/Decorator/Asset.interface.yaml
[15]: https://github.com/openbmc/phosphor-hwmon
[16]: https://github.com/openbmc/dbus-sensors
diff --git a/architecture/user-management.md b/architecture/user-management.md
index 65f95e4..e47cd4e 100644
--- a/architecture/user-management.md
+++ b/architecture/user-management.md
@@ -1,73 +1,79 @@
# User Management - OpenBMC - Design document
## Scope
+
This document covers the architectural, interface, and design details needed for
user-management components. The implementation detail is beyond the scope of
this document.
## Basic principles in design
+
1. Use common user-management (e.g. phosphor-user-manager) rather than
-application-based user-management. Especially, avoid IPMI based user-management.
+ application-based user-management. Especially, avoid IPMI based
+ user-management.
2. For security reasons, avoid transmitting passwords over any D-Bus API.
-Observe this rule even while creating, modifying or authenticating the user.
+ Observe this rule even while creating, modifying or authenticating the user.
3. Have applications use the PAM module to authenticate the user instead of
-relying on a D-Bus API-based approach.
+ relying on a D-Bus API-based approach.
4. User creation has to be generic in nature wherever possible.
5. As IPMI requires clear text password (Refer IPMI 2.0 specification, section
-13.19-13.33 inclusive for more details), new PAM module (e.g. pam-ipmi modules)
-has to be used along with regular PAM password hashing modules (e.g. pam-unix),
-which will store the password in encrypted form. Implementation can elect to
-skip this if the IPMI daemon is not the part of the distribution or if the user
-created doesn't have an 'ipmi' group role.
+ 13.19-13.33 inclusive for more details), new PAM module (e.g. pam-ipmi
+ modules) has to be used along with regular PAM password hashing modules (e.g.
+ pam-unix), which will store the password in encrypted form. Implementation
+ can elect to skip this if the IPMI daemon is not the part of the distribution
+ or if the user created doesn't have an 'ipmi' group role.
6. User name, Password, Group and Privilege roles are maintained by the common
-user-management (e.g. phosphor-user-manager), whereas individual user-related
-settings for any application has to be managed by that application. In other
-words, with the exception of User Name, Password, Group and Privileged Role,
-the rest of the settings needed has to be owned by the application in question.
-(e.g. IPMI daemon has to manage settings like channel based restriction etc.
-for the corresponding user). Design is made to cover this scenario.
+ user-management (e.g. phosphor-user-manager), whereas individual user-related
+ settings for any application has to be managed by that application. In other
+ words, with the exception of User Name, Password, Group and Privileged Role,
+ the rest of the settings needed has to be owned by the application in
+ question. (e.g. IPMI daemon has to manage settings like channel based
+ restriction etc. for the corresponding user). Design is made to cover this
+ scenario.
## Supported Group Roles
+
The purpose of group roles is to determine the first-level authorization of the
corresponding user. This is used to determine at a high level whether the user
-is authorized to the required interface.
-In other words, users should not be allowed to login to SSH if they only belong
-to webserver group and not to group SSH. Also having group roles in common
-user-management (e.g. phosphor-user-manager) allows different application to
-create roles for the other (e.g. Administrative user will be able to create a
-new user through webserver who will be able to login to webserver/REDFISH &
-IPMI etc.)
+is authorized to the required interface. In other words, users should not be
+allowed to login to SSH if they only belong to webserver group and not to group
+SSH. Also having group roles in common user-management (e.g.
+phosphor-user-manager) allows different application to create roles for the
+other (e.g. Administrative user will be able to create a new user through
+webserver who will be able to login to webserver/REDFISH & IPMI etc.)
-*Note: Group names are for representation only and can be modified/extended
- based on the need*
+_Note: Group names are for representation only and can be modified/extended
+based on the need_
-|Sl. No| Group Name | Purpose / Comments |
-|-----:|------------|-----------------------------------|
-|1 | ssh | Users in this group are only allowed to login through SSH.|
-|2 | ipmi | Users in this group are only allowed to use IPMI Interface.|
-|3 | redfish | Users in this group are only allowed to use REDFISH Interface.|
-|4 | web | Users in this group are only allowed to use webserver Interface.|
+| Sl. No | Group Name | Purpose / Comments |
+| -----: | ---------- | ---------------------------------------------------------------- |
+| 1 | ssh | Users in this group are only allowed to login through SSH. |
+| 2 | ipmi | Users in this group are only allowed to use IPMI Interface. |
+| 3 | redfish | Users in this group are only allowed to use REDFISH Interface. |
+| 4 | web | Users in this group are only allowed to use webserver Interface. |
## Supported Privilege Roles
+
OpenBMC supports privilege roles which are common across all the supported
groups (i.e. User will have same privilege for REDFISH / Webserver / IPMI /
-SSH). User can belong to any one of the following privilege roles at any point
+SSH). User can belong to any one of the following privilege roles at any point
of time.
-*Note: Privileges are for representation only and can be modified/extended
- based on the need*
+_Note: Privileges are for representation only and can be modified/extended based
+on the need_
-|Sl. No| Privilege roles | Purpose / Comments |
-|-----:|-----------------|-----------------------------------|
-|1 | admin | Users are allowed to configure all OpenBMC (including user-management, network and all configurations). Users will have full administrative access.|
-|2 | operator | Users are allowed to view and control basic operations. This includes reboot of the host, etc. But users are not allowed to change other configuration like user, network, etc.|
-|3 | user | Users only have read access and can't change any behavior of the system.|
-|4 | no-access | Users having empty or no privilege will be reported as no-access, from IPMI & REDFISH point of it.|
+| Sl. No | Privilege roles | Purpose / Comments |
+| -----: | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1 | admin | Users are allowed to configure all OpenBMC (including user-management, network and all configurations). Users will have full administrative access. |
+| 2 | operator | Users are allowed to view and control basic operations. This includes reboot of the host, etc. But users are not allowed to change other configuration like user, network, etc. |
+| 3 | user | Users only have read access and can't change any behavior of the system. |
+| 4 | no-access | Users having empty or no privilege will be reported as no-access, from IPMI & REDFISH point of it. |
## Common User Manager - D-Bus API (phosphor-user-manager)
-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
+
+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
for detailed user management D-Bus API and interfaces.
@@ -151,7 +157,6 @@
```
-
## OpenBMC - User Management - User creation from webserver flow - with all groups
```
@@ -318,10 +323,12 @@
| |
--------------------------------------------------------------------------
```
+
## Authentication flow
-Applications must use `pam_authenticate()` API to authenticate user.
-Stacked PAM modules are used such that `pam_authenticate()` can be used
-for both local & remote users.
+
+Applications must use `pam_authenticate()` API to authenticate user. Stacked PAM
+modules are used such that `pam_authenticate()` can be used for both local &
+remote users.
```
+----------------------------------+
@@ -345,12 +352,14 @@
| +-----------------------+ |
+----------------------------------+
```
+
## Password update
+
Applications must use `pam_chauthtok()` API to set / change user password.
-Stacked PAM modules allow all 'ipmi' group user passwords to be stored
-in encrypted form, which will be used by IPMI. The same has been performed
-by `pam_ipmicheck` and `pam_ipmisave` modules loaded as first & last modules
-in stacked pam modules.
+Stacked PAM modules allow all 'ipmi' group user passwords to be stored in
+encrypted form, which will be used by IPMI. The same has been performed by
+`pam_ipmicheck` and `pam_ipmisave` modules loaded as first & last modules in
+stacked pam modules.
```
+------------------+---------------+
@@ -427,11 +436,10 @@
```
-
## LDAP
SSH, Redfish and Webserver interface allows the user to authenticate against an
-LDAP directory. IPMI interface cannot be used to authenticate against LDAP,
+LDAP directory. IPMI interface cannot be used to authenticate against LDAP,
since IPMI needs the password in clear text at the time of session setup.
In OpenBMC, PAM based authentication is implemented, so for both LDAP users and
@@ -439,81 +447,90 @@
For the LDAP user accounts, there is no LDAP attribute type that corresponds to
the OpenBMC privilege roles. The preferred way is to group LDAP user accounts
-into LDAP groups. D-Bus API is provided for the user to assign privilege role
-to the LDAP group.
+into LDAP groups. D-Bus API is provided for the user to assign privilege role to
+the LDAP group.
## Authorization Flow
-This section explains how the privilege roles of the user accounts are
-consumed by the webserver interface. The privilege role is a property of the
-user D-Bus object for the local users. For the LDAP user accounts, the privilege
-role will be based on the LDAP group. The LDAP group to privilege role mapping
-needs to be configured prior to authenticating with the LDAP user accounts.
+This section explains how the privilege roles of the user accounts are consumed
+by the webserver interface. The privilege role is a property of the user D-Bus
+object for the local users. For the LDAP user accounts, the privilege role will
+be based on the LDAP group. The LDAP group to privilege role mapping needs to be
+configured prior to authenticating with the LDAP user accounts.
-1. Invoke PAM API for authenticating with user credentials. Proceed, if
-the authentication succeeds.
+1. Invoke PAM API for authenticating with user credentials. Proceed, if the
+ authentication succeeds.
2. Check if the user is a local user account. If the user account is local,
-fetch the privilege role from the D-Bus object and update the session
-information.
+ fetch the privilege role from the D-Bus object and update the session
+ information.
3. If the user account is not local, read the group name for the user.
4. Fetch the privilege role corresponding to the group name, update the session
-information with the privilege role.
+ information with the privilege role.
5. If there is no mapping for group name to privilege role, default to `user`
-privilege role for the session.
+ privilege role for the session.
## Recommended Implementation
+
1. As per IPMI spec the max user list can be 15 (+1 for NULL User). Hence
-implementation has to be done in such a way that no more than 15 users are
-getting added to the 'ipmi' Group. Phosphor-user-manager has to enforce this
-limitation.
+ implementation has to be done in such a way that no more than 15 users are
+ getting added to the 'ipmi' Group. Phosphor-user-manager has to enforce this
+ limitation.
2. Should add IPMI_NULL_USER by default and keep the user in disabled state.
-This is to prevent IPMI_NULL_USER from being created as an actual user. This is
-needed as NULL user with NULL password in IPMI can't be added as an entry from
-Unix user-management point of it.
-3. User creation request from IPMI / REDFISH must be handled in
-the same manner as described in the above flow diagram.
+ This is to prevent IPMI_NULL_USER from being created as an actual user. This
+ is needed as NULL user with NULL password in IPMI can't be added as an entry
+ from Unix user-management point of it.
+3. User creation request from IPMI / REDFISH must be handled in the same manner
+ as described in the above flow diagram.
4. Adding / removing a user name from 'ipmi' Group role must force a Password
-change to the user. This is needed as adding to the 'ipmi' Group of existing
-user requires clear text password to be stored in encrypted form. Similarly
-when removing a user from IPMI group, must force the password to be changed
-as part of security measure.
-5. IPMI spec doesn't support groups for the user-management. Hence the
-same can be implemented through OEM Commands, thereby creating a user in
-IPMI with different group roles.
-6. Do no use 'Set User Name' IPMI command to extend already existing
-non-ipmi group users to 'ipmi' group. 'Set User Name' IPMI command will not be
-able to differentiate between new user request or request to extend an existing
-user to 'ipmi' group. Use OEM Commands to extend existing users to 'ipmi' group.
-Note: 'Set User Name' IPMI command will return CCh 'Invalid data field in
-Request' completion code, if tried to add existing user in the system.
+ change to the user. This is needed as adding to the 'ipmi' Group of existing
+ user requires clear text password to be stored in encrypted form. Similarly
+ when removing a user from IPMI group, must force the password to be changed
+ as part of security measure.
+5. IPMI spec doesn't support groups for the user-management. Hence the same can
+ be implemented through OEM Commands, thereby creating a user in IPMI with
+ different group roles.
+6. Do no use 'Set User Name' IPMI command to extend already existing non-ipmi
+ group users to 'ipmi' group. 'Set User Name' IPMI command will not be able to
+ differentiate between new user request or request to extend an existing user
+ to 'ipmi' group. Use OEM Commands to extend existing users to 'ipmi' group.
+ Note: 'Set User Name' IPMI command will return CCh 'Invalid data field in
+ Request' completion code, if tried to add existing user in the system.
## Deployment - Out of factory
+
### Guidelines
-As per [SB-327 Information Privacy](https://leginfo.legislature.ca.gov/faces/billTextClient.xhtml?bill_id=201720180SB327), Connected devices must avoid
-shipping with generic user name & password. The reasonable security expected is
+
+As per
+[SB-327 Information Privacy](https://leginfo.legislature.ca.gov/faces/billTextClient.xhtml?bill_id=201720180SB327),
+Connected devices must avoid shipping with generic user name & password. The
+reasonable security expected is
+
1. Preprogrammed password unique to each device
2. Forcing user to generate new authentication account, before using the device.
### 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
-through any of the system in-band interfaces (like KCS etc.).
-IPMI 2.0 specification provides commands like `SetUserName`, `SetUserPassword`,
+through any of the system in-band interfaces (like KCS etc.). IPMI 2.0
+specification provides commands like `SetUserName`, `SetUserPassword`,
`SetUserAccess`, which must be used to create a new user account instead of
using any generic default user name and password. Accounts created through this
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:
+
Exposing root account (user id 0) to end-user by default (other than debug /
developer scenario) is security risk. Hence current architecture recommends not
-to enable root user by default for end-user.
-For general login for debug / developer builds, a new default user with password
-can be created by specifying the same in local.conf.sample file. This can be
-used to establish a session by default (CI systems etc. can use this account).
-From OpenBMC package user name `openbmc` with password `0penBmc$` can be added.
+to enable root user by default for end-user. For general login for debug /
+developer builds, a new default user with password can be created by specifying
+the same in local.conf.sample file. This can be used to establish a session by
+default (CI systems etc. can use this account). From OpenBMC package user name
+`openbmc` with password `0penBmc$` can be added.
#### Debugging use-case
+
`root` user / sudo privilege access are required during development / debug
phase of the program. For this purpose a new IPMI OEM command (TBD) / REDFISH
OEM action(TBD) to can be used to set password for the root user, after which
@@ -522,6 +539,7 @@
IPMI / REDFISH from user management point of view).
### 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
forcing end-user to update the same, before using the device (TBD).
diff --git a/cheatsheet.md b/cheatsheet.md
index e5e0c75..8518c30 100644
--- a/cheatsheet.md
+++ b/cheatsheet.md
@@ -1,4 +1,3 @@
-
# OpenBMC cheatsheet
This document is intended to provide a set of recipes for common OpenBMC
@@ -12,15 +11,15 @@
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:
+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:
```
SRC_URI = "git:///home/jk/devel/linux;branch=${KBRANCH}"
```
-The `SRCREV` variable can be used to set an explicit git commit, or
-set to `"${AUTOREV}"` to use the latest commit in `KBRANCH`.
+The `SRCREV` variable can be used to set an explicit git commit, or set to
+`"${AUTOREV}"` to use the latest commit in `KBRANCH`.
## Building for Palmetto
@@ -51,8 +50,8 @@
meta-<layer>/meta-<system>/conf/machine/machineB.conf
```
-You can specify the machine configuration you want to build by passing the
-name to the `setup`.
+You can specify the machine configuration you want to build by passing the name
+to the `setup`.
```
$ cd openbmc
@@ -61,12 +60,19 @@
```
## Building the OpenBMC SDK
-Looking for a way to compile your programs for 'ARM' but you happen to be running on a 'PPC' or 'x86' system? You can build the sdk receive a fakeroot environment.
+
+Looking for a way to compile your programs for 'ARM' but you happen to be
+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
```
-Follow the prompts. After it has been installed the default to setup your env will be similar to this command
+
+Follow the prompts. After it has been installed the default to setup your env
+will be similar to this command
+
```
. /opt/openbmc-phosphor/2.1/environment-setup-armv5e-openbmc-linux-gnueabi
```
@@ -74,9 +80,11 @@
## Rebuilds & Reconfiguration
You can reconfigure your build by removing the build/conf dir:
+
```
rm -rf build/conf
```
+
and running `setup` again.
## Useful D-Bus CLI tools
@@ -95,14 +103,15 @@
busctl call <path> <interface> <object> <method> <parameters>
```
-* \<parameters\> example : sssay "t1" "t2" "t3" 2 2 3
+- \<parameters\> example : sssay "t1" "t2" "t3" 2 2 3
## Using QEMU
-QEMU has a palmetto-bmc machine (as of v2.6.0) which implements the core
-devices to boot a Linux kernel. OpenBMC also [maintains a
-tree](https://github.com/openbmc/qemu) with patches on their way upstream or
-temporary work-arounds that add to QEMU's capabilities where appropriate.
+QEMU has a palmetto-bmc machine (as of v2.6.0) which implements the core devices
+to boot a Linux kernel. OpenBMC also
+[maintains a tree](https://github.com/openbmc/qemu) with patches on their way
+upstream or temporary work-arounds that add to QEMU's capabilities where
+appropriate.
```
qemu-system-arm -m 256 -M palmetto-bmc -nographic \
@@ -110,12 +119,16 @@
-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...
+
+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...
```
curl -c cjar -b cjar -k -H "Content-Type: application/json" \
-X POST https://localhost:2443/login -d "{\"data\": [ \"root\", \"0penBmc\" ] }"
```
+
or
```
@@ -135,11 +148,13 @@
../configure --target-list=arm-softmmu
make
```
-Built file will be located at: ```arm-softmmu/qemu-system-arm```
+
+Built file will be located at: `arm-softmmu/qemu-system-arm`
### Use a bridge device
-Using a bridge device requires a bit of root access to set it up. The benefit
-is your qemu session runs in the bridges subnet so no port forwarding is needed.
+
+Using a bridge device requires a bit of root access to set it up. The benefit is
+your qemu session runs in the bridges subnet so no port forwarding is needed.
There are packages needed to yourself a virbr0 such as...
```
@@ -152,23 +167,25 @@
```
There are some other useful parms like that can redirect the console to another
-window. This results in having an easily accessible qemu command session.
-```-monitor stdio -serial pty -nodefaults```
-
+window. This results in having an easily accessible qemu command session.
+`-monitor stdio -serial pty -nodefaults`
## Booting the host
Login:
+
```
curl -c cjar -k -X POST -H "Content-Type: application/json" -d '{"data": [ "root", "0penBmc" ] }' https://${bmc}/login
```
Connect to host console:
+
```
ssh -p 2200 root@bmc
```
Power on:
+
```
curl -c cjar -b cjar -k -H "Content-Type: application/json" -X PUT \
-d '{"data": "xyz.openbmc_project.State.Host.Transition.On"}' \
@@ -179,8 +196,8 @@
[SDK build](#building-the-openbmc-sdk) provides GDB and debug symbols:
-* `$GDB` is available to use once SDK environment is setup
-* Debug symbols are located in `.debug/` directory of each executable
+- `$GDB` is available to use once SDK environment is setup
+- Debug symbols are located in `.debug/` directory of each executable
To use GDB:
@@ -194,6 +211,7 @@
## Coredump
By default coredump is disabled in OpenBMC. To enable coredump:
+
```
echo '/tmp/core_%e.%p' | tee /proc/sys/kernel/core_pattern
ulimit -c unlimited
@@ -202,8 +220,8 @@
## Cleaning up read-write file system changes
You may want to investigate which file(s) are persisting through the overlay
-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.
+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.
```
/run/initramfs/rw/cow/
@@ -212,40 +230,44 @@
## Building
### Share downloads directory
+
It takes a long time for the first build of OpenBMC. It downloads various repos
from the internet.
Check `build/downloads` to see all the downloaded repos.
-* If a repo is a single archive, it usually looks like this:
- * `zlib-1.2.11.tar.xz` - The repo itself
- * `zlib-1.2.11.tar.xz.done` - A flag indicating the repo is downloaded
-* If a repo is managed by git, it usually looks like this:
- * `git2/github.com.openbmc.linux` - The git bare clone
- * `git2/github.com.openbmc.linux.done` - A flag indicating the repo is downloaded
+- If a repo is a single archive, it usually looks like this:
+ - `zlib-1.2.11.tar.xz` - The repo itself
+ - `zlib-1.2.11.tar.xz.done` - A flag indicating the repo is downloaded
+- If a repo is managed by git, it usually looks like this:
+ - `git2/github.com.openbmc.linux` - The git bare clone
+ - `git2/github.com.openbmc.linux.done` - A flag indicating the repo is
+ downloaded
Bitbake will extract the code to the working directory during build, so the
`downloads` directory could be shared by different builds on a system:
-* 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"
- ```
-* 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.
+- 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"
+ ```
+- 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.
## Using git proxy
+
If you experience extremely slow download speed during code fetch (e.g. if you
are in China), it is possible to use a git proxy to speed up the code fetch.
-Google `git-proxy-wrapper` will find various ways to setup the proxy for the
-git protocol.
+Google `git-proxy-wrapper` will find various ways to setup the proxy for the git
+protocol.
Below is an example wrapper in `~/bin` assuming a socks5 proxy at port 9054:
+
```
#!/bin/sh
## Use connect-proxy as git proxy wrapper which supports SOCKS5
@@ -253,14 +275,15 @@
## Use with `export GIT_PROXY_COMMAND=~/bin/git-proxy-wrapper`
/usr/bin/connect -S localhost:9054 "$@"
```
+
Then you can run `export GIT_PROXY_COMMAND=~/bin/git-proxy-wrapper` and you are
now downloading git code through your proxy.
## devtool
`devtool` is a convenient utility in Yocto to make changes in the local
-directory.
-Typical usage is:
+directory. Typical usage is:
+
```
# To create a local copy of recipe's code and build with it:
devtool modify <recipe>
@@ -272,19 +295,18 @@
```
To use this tool, you need the build environment, e.g. `. oe-init-build-env`.
-The above script will add `<WORKDIR>/scripts/` to your `PATH` env and
-`devtool` is in the path.
+The above script will add `<WORKDIR>/scripts/` to your `PATH` env and `devtool`
+is in the path.
Below are real examples.
-
### devtool on ipmi
-If you want to debug or add a new function in ipmi, you probably need to
-change the code in [phosphor-host-ipmid][1].
-Checking the recipes, you know this repo is in [phosphor-ipmi-host.bb][2].
-Below are the steps to use devtool to modify the code locally, build and test
-it.
+If you want to debug or add a new function in ipmi, you probably need to change
+the code in [phosphor-host-ipmid][1]. Checking the recipes, you know this repo
+is in [phosphor-ipmi-host.bb][2]. Below are the steps to use devtool to modify
+the code locally, build and test it.
+
1. Use devtool to create a local repo:
```
devtool modify phosphor-ipmi-host
@@ -299,10 +321,9 @@
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:
+ 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:
```
# 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/
@@ -311,33 +332,35 @@
```
5. Now you can test your changes.
-
## Develop linux kernel
### devtool on linux kernel
+
If you want to work on linux kernel, you can use devtool as well, with some
differences from regular repos.
**Note**: As of [ac72846][3] the linux kernel recipe name is changed to
-`linux-aspeed` for Aspeed based OpenBMC builds.
-In the following examples, replace `linux-obmc` with `linux-aspeed` if you are
-on a revision later than [ac72846][3].
+`linux-aspeed` for Aspeed based OpenBMC builds. In the following examples,
+replace `linux-obmc` with `linux-aspeed` if you are on a revision later than
+[ac72846][3].
-1. devtool does not create the 'devtool' branch. Instead, it checkout the
- branch specified in the recipe.
- For example, on the OpenBMC v2.2 tag, `linux-obmc_4.13.bb` specifies
- `dev-4.13` branch.
+1. devtool does not create the 'devtool' branch. Instead, it checkout the branch
+ specified in the recipe. For example, on the OpenBMC v2.2 tag,
+ `linux-obmc_4.13.bb` specifies `dev-4.13` branch.
2. If there are patches, `devtool` applies them directly on the branch.
3. devtool copies the defconfig and machine-specific config into `oe-workdir`.
4. devtool generates the `.config` file based on the above configs.
You can modify the code and build the kernel as usual as follows:
+
```
bitbake linux-obmc -c build
```
### Modify config
+
If you need to change the config and save it as defconfig for further use:
+
```
bitbake linux-obmc -c menuconfig
# Edit the configs and after save it generates
@@ -348,16 +371,18 @@
```
### Test linux kernel
-After build, you can flash the image to test the new kernel.
-However, it is always slow to flash an image to the chip.
+
+After build, you can flash the image to test the new kernel. However, it is
+always slow to flash an image to the chip.
There is a faster way to load the kernel via network so you can easily test
kernel builds.
OpenBMC kernel build generates `fit` image, including `kernel`, `dtb` and
-`initramfs`.
-Typically we can load it via tftp, taking Romulus as an example:
-1. Put `build/tmp/deploy/images/romulus/fitImage-obmc-phosphor-initramfs-romulus.bin`
+`initramfs`. Typically we can load it via tftp, taking Romulus as an example:
+
+1. Put
+ `build/tmp/deploy/images/romulus/fitImage-obmc-phosphor-initramfs-romulus.bin`
to a tftp server, name it to `fitImage`
2. Reboot BMC and press keys to enter uboot shell;
3. In uboot:
@@ -368,9 +393,10 @@
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.
-
+ Then you are running an OpenBMC with your updated kernel.
[1]: https://github.com/openbmc/phosphor-host-ipmid
-[2]: https://github.com/openbmc/openbmc/blob/c53f375a0f92f847d2aa50e19de54840e8472c8e/meta-phosphor/recipes-phosphor/ipmi/phosphor-ipmi-host_git.bb
-[3]: https://github.com/openbmc/openbmc/commit/ac7284629ea572cf27d69949dc4014b3b226f14f
+[2]:
+ https://github.com/openbmc/openbmc/blob/c53f375a0f92f847d2aa50e19de54840e8472c8e/meta-phosphor/recipes-phosphor/ipmi/phosphor-ipmi-host_git.bb
+[3]:
+ https://github.com/openbmc/openbmc/commit/ac7284629ea572cf27d69949dc4014b3b226f14f
diff --git a/code-of-conduct.md b/code-of-conduct.md
index 1b605af..b357fba 100644
--- a/code-of-conduct.md
+++ b/code-of-conduct.md
@@ -10,18 +10,18 @@
The purposes of LF Projects, LLC (“LF Projects”) are to:
-* support the collaborative development, availability and adoption of open
+- support the collaborative development, availability and adoption of open
source software, hardware and networking and other technologies and the
-collaborative development, availability and adoption of open protocols and
-standards (individually and collectively, “Open Technology”);
-* host various projects pursuing the development of Open Technology and other
+ collaborative development, availability and adoption of open protocols and
+ standards (individually and collectively, “Open Technology”);
+- host various projects pursuing the development of Open Technology and other
technical assets, materials and processes (each such project, which itself may
-include any number of projects, a “Project”);
-* provide enablement and support to Projects to assist their development
+ include any number of projects, a “Project”);
+- provide enablement and support to Projects to assist their development
activities; and
-* undertake such other lawful activity as permitted by law and as consistent
+- undertake such other lawful activity as permitted by law and as consistent
with the mission, purpose and tax status of LFP, Inc., a Delaware non-profit
-non-stock corporation and the sole member of LF Projects.
+ non-stock corporation and the sole member of LF Projects.
LF Projects hosts communities where participants choose to work together, and in
that process experience differences in language, location, nationality, and
@@ -35,7 +35,7 @@
provides a benchmark for self-evaluation and acts as a vehicle for better
identity of the organization.
-LF Projects is a Delaware series limited liability company. Projects of LF
+LF Projects is a Delaware series limited liability company. Projects of LF
Projects are formed as separate series of LF Projects (each, a “Series”).
References to “Projects” within this Policy include the applicable Series for
each Project.
@@ -44,7 +44,7 @@
limitation developers, participants in meetings, teleconferences, mailing lists,
conferences or functions, and contributors. Note that this Code complements
rather than replaces legal rights and obligations pertaining to any particular
-situation. In addition, with the approval of LF Projects, Projects are free to
+situation. In addition, with the approval of LF Projects, Projects are free to
adopt their own code of conduct in place of the Code.
## Statement of Intent
@@ -57,33 +57,33 @@
## Code
1. Treat each other with respect, professionalism, fairness, and sensitivity to
-our many differences and strengths, including in situations of high pressure and
-urgency.
-2. Never harass or bully anyone verbally, physically, sexually,
-or in digital or written form.
+ our many differences and strengths, including in situations of high pressure
+ and urgency.
+2. Never harass or bully anyone verbally, physically, sexually, or in digital or
+ written form.
3. Never discriminate on the basis of personal characteristics or group
-membership.
+ membership.
4. Communicate constructively and avoid demeaning or insulting behavior or
-language.
+ language.
5. Seek, accept, and offer objective work criticism, and acknowledge properly
-the contributions of others.
+ the contributions of others.
6. Be honest about your own qualifications, and about any circumstances that
-might lead to conflicts of interest.
+ might lead to conflicts of interest.
7. Respect the privacy of others and the confidentiality of data you access.
8. With respect to cultural differences, be conservative in what you do and
-liberal in what you accept from others, but not to the point of accepting
-disrespectful, unprofessional or unfair or unwelcome behavior or advances.
+ liberal in what you accept from others, but not to the point of accepting
+ disrespectful, unprofessional or unfair or unwelcome behavior or advances.
9. Promote the rules of this Code and take action (especially if you are in a
-leadership position) to bring the discussion back to a more civil level whenever
-inappropriate behaviors are observed.
+ leadership position) to bring the discussion back to a more civil level
+ whenever inappropriate behaviors are observed.
10. Stay on topic: Make sure that you are posting to the correct channel and
-avoid off-topic discussions. Remember when you update an issue or respond to an
-email you are potentially sending to a large number of people.
+ avoid off-topic discussions. Remember when you update an issue or respond to
+ an email you are potentially sending to a large number of people.
11. Step down considerately: participants in every project come and go, and LF
-Projects is no different. When you leave or disengage from the project, in whole
-or in part, we ask that you do so in a way that minimizes disruption to the
-project. This means you should tell people you are leaving and take the proper
-steps to ensure that others can pick up where you left off.
+ Projects is no different. When you leave or disengage from the project, in
+ whole or in part, we ask that you do so in a way that minimizes disruption
+ to the project. This means you should tell people you are leaving and take
+ the proper steps to ensure that others can pick up where you left off.
## Glossary
@@ -122,11 +122,11 @@
includes the following persons:
-* Developers
-* Representatives of corporate participants
-* Anyone from the Public partaking in the LF Projects work environment (e.g.
+- Developers
+- Representatives of corporate participants
+- Anyone from the Public partaking in the LF Projects work environment (e.g.
contribute code, comment on our code or specs, email us, attend our
-conferences, functions, etc)
+ conferences, functions, etc)
### Respect
@@ -144,13 +144,13 @@
Hard to define? Some questions to ask yourself are:
-* how would I feel if I were in the position of the recipient?
-* would my spouse, parent, child, sibling or friend like to be treated this way?
-* would I like an account of my behavior published in the organization’s
+- how would I feel if I were in the position of the recipient?
+- would my spouse, parent, child, sibling or friend like to be treated this way?
+- would I like an account of my behavior published in the organization’s
newsletter?
-* could my behavior offend or hurt other members of the work group?
-* could someone misinterpret my behavior as intentionally harmful or harassing?
-* would I treat my boss or a person I admire at work like that ? *Summary*: if
+- could my behavior offend or hurt other members of the work group?
+- could someone misinterpret my behavior as intentionally harmful or harassing?
+- would I treat my boss or a person I admire at work like that ? _Summary_: if
you are unsure whether something might be welcome or unwelcome, don’t do it.
### Unwelcome sexual advance
@@ -158,13 +158,13 @@
includes requests for sexual favors, and other verbal, digital, written, or
physical conduct of a sexual nature, where:
-* submission to such conduct is made either explicitly or implicitly a term or
+- submission to such conduct is made either explicitly or implicitly a term or
condition of an individual’s employment,
-* submission to or rejection of such conduct by an individual is used as a basis
+- submission to or rejection of such conduct by an individual is used as a basis
for employment decisions affecting the individual,
-* such conduct has the purpose or effect of unreasonably interfering with an
+- such conduct has the purpose or effect of unreasonably interfering with an
individual’s work performance or creating an intimidating hostile or offensive
-working environment.
+ working environment.
### Workplace Bullying
@@ -185,11 +185,11 @@
To report incidents or to appeal reports of incidents, send an email to a member
of the following escalation path:
-* Brad Bishop, Lead Maintainer, OpenBMC <bradleyb@fuzziesquirrel.com>
-* Nancy Yuen, Technical Steering Committee Member, OpenBMC <yuenn@google.com>
-* James Mihm, Technical Steering Committee Member, OpenBMC
+- Brad Bishop, Lead Maintainer, OpenBMC <bradleyb@fuzziesquirrel.com>
+- Nancy Yuen, Technical Steering Committee Member, OpenBMC <yuenn@google.com>
+- James Mihm, Technical Steering Committee Member, OpenBMC
<james.mihm@intel.com>
-* Mike Dolan, Manager of LF Projects, Linux Foundation <manager@lfprojects.org>
+- Mike Dolan, Manager of LF Projects, Linux Foundation <manager@lfprojects.org>
Please include any available relevant information, including links to any
publicly accessible material relating to the matter. Every effort will be taken
@@ -201,8 +201,9 @@
## Credits
-This code is based on the [W3C’s Code of Ethics and Professional
-Conduct](https://www.w3.org/Consortium/cepc) with some additions from the [Cloud
-Foundry](https://www.cloudfoundry.org/)’s Code of Conduct and the Hyperledger
-Project Code of Conduct. It has been modified from the Linux Foundation Project
-Code of Conduct to include incident managers local to the OpenBMC project.
+This code is based on the
+[W3C’s Code of Ethics and Professional Conduct](https://www.w3.org/Consortium/cepc)
+with some additions from the [Cloud Foundry](https://www.cloudfoundry.org/)’s
+Code of Conduct and the Hyperledger Project Code of Conduct. It has been
+modified from the Linux Foundation Project Code of Conduct to include incident
+managers local to the OpenBMC project.
diff --git a/console.md b/console.md
index 6b1b5c6..fddc204 100644
--- a/console.md
+++ b/console.md
@@ -1,5 +1,4 @@
-OpenBMC host console support
-============================
+# OpenBMC host console support
This document describes how to connect to the host UART console from an OpenBMC
management system.
@@ -8,17 +7,14 @@
UART. UART data from the host is output to all connections, and input from any
connection is sent to the host.
-Remote console connections
---------------------------
+## Remote console connections
-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:
+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]
-
-Local console connections
--------------------------
+## Local console connections
If you're already logged into an OpenBMC machine, you can start a console
session directly, using:
@@ -37,8 +33,7 @@
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
--------
+## Logging
Console logs are kept in:
diff --git a/cpp-style-and-conventions.md b/cpp-style-and-conventions.md
index 51b1312..9b4df7d 100644
--- a/cpp-style-and-conventions.md
+++ b/cpp-style-and-conventions.md
@@ -3,27 +3,28 @@
## General Philosophy
Being an extensive and complicated language, there are often differences of
-opinions on "good" and "bad" C++ code. Bjarne Stroustrup has said "Within C++
-is a smaller, simpler, safer language struggling to get out." We are striving
-to write in this variant of C++ and are therefore following the "C++ Core
+opinions on "good" and "bad" C++ code. Bjarne Stroustrup has said "Within C++ is
+a smaller, simpler, safer language struggling to get out." We are striving to
+write in this variant of C++ and are therefore following the "C++ Core
Guidelines" that Bjarne and Herb Sutter introduced at CppCon 2015.
Beyond a set of rules that help codify "good" and "bad" C++, we have general
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.
+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.
### Code should be clear and concise
> Brevity is the soul of wit.
It is important that code be optimized for the reviewer and maintainer and not
-for the writer. Solutions should avoid tricks that detract from the clarity
-of reviewing and understanding it.
+for the writer. Solutions should avoid tricks that detract from the clarity of
+reviewing and understanding it.
-Modern practices allow C++ to be an expressive, but concise, language. We tend
+Modern practices allow C++ to be an expressive, but concise, language. We tend
to favor solutions which succinctly represent the problem in as few lines as
possible.
@@ -33,19 +34,19 @@
### Code should be written with modern practices
We strive to keep our code conforming to and utilizing of the latest in C++
-standards. Today, that means all C++ code should be compiled using C++20
-compiler settings. As the C++23 standard is finalized and compilers support
-it, we will move to it as well.
+standards. Today, that means all C++ code should be compiled using C++20
+compiler settings. As the C++23 standard is finalized and compilers support it,
+we will move to it as well.
We also strive to keep the codebase up-to-date with the latest recommended
-practices by the language designers. This is reflected by the choice in
+practices by the language designers. This is reflected by the choice in
following the C++ Core Guidelines.
We finally desire to have computers do our thinking for us wherever possible.
This means having Continuous Integration tests on each repository so that
-regressions are quickly identified prior to merge. It also means having as
-much of this document enforced by tools as possible by, for example,
-clang-format and clang-tidy.
+regressions are quickly identified prior to merge. It also means having as much
+of this document enforced by tools as possible by, for example, clang-format and
+clang-tidy.
For those coming to the project from pre-C++11 environments we strongly
recommend the book "Effective Modern C++" as a way to get up to speed on the
@@ -54,14 +55,14 @@
### 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 that there are times where we must limit library selection and/or coding
-techniques to compensate for this constraint. Due to the current technology,
+similar processing power of a typical smart-watch available in 2016. This means
+that there are times where we must limit library selection and/or coding
+techniques to compensate for this constraint. Due to the current technology,
performance evaluation is done in order of { code size, cpu utilization, and
memory size }.
From a macro-optimization perspective, we expect all solutions to have an
-appropriate algorithmic complexity for the problem at hand. Therefore, an
+appropriate algorithmic complexity for the problem at hand. Therefore, an
`O(n^3)` algorithm may be rejected even though it has good clarity when an
`O(n*lg(n))` solution exists.
@@ -71,7 +72,7 @@
https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md
-[[ Last reviewed revision is 53bc78f ]]
+[[Last reviewed revision is 53bc78f]]
Exceptions:
@@ -84,8 +85,9 @@
### Style recommendations
The following are not followed:
- * NL.10 Avoid CamelCase
- * NL.17 Use K&R-derived layout
+
+- NL.10 Avoid CamelCase
+- NL.17 Use K&R-derived layout
## Library and Feature Specifics
@@ -99,18 +101,18 @@
### Boost
Use of boost is allowed, under the following circumstances:
-1. Use is done as a header-only library. This allows unused functions and
+
+1. Use is done as a header-only library. This allows unused functions and
methods to be removed by the compiler at link time, and avoids adding large
-amounts of overhead and flash usage.
+ amounts of overhead and flash usage.
2. Implementers should include the lowest level header required to solve the
- problem at hand. This allows uses to be found and moved forward when new
-standards are available, as well as reduce compile times, and decrease the
-possibility of accidental use. (ie, #include <boost/container/flat_map.hpp>
-not #include <boost/container.hpp>)
+ problem at hand. This allows uses to be found and moved forward when new
+ standards are available, as well as reduce compile times, and decrease the
+ possibility of accidental use. (ie, #include <boost/container/flat_map.hpp>
+ not #include <boost/container.hpp>)
3. The module used should not have an equivalent in the std namespace that meets
- the same requirements for implementation or clarity: For example,
-std::chrono should be preferred over boost::chrono. std::array over
-boost::array.
+ the same requirements for implementation or clarity: For example, std::chrono
+ should be preferred over boost::chrono. std::array over boost::array.
4. Use does not conflict with any of the core tenants of this coding standard
(clarity, modern practices, or performance).
@@ -118,11 +120,11 @@
The iostream conventions of using 'operator<<' contribute to an increased code
size over printf-style operations, due to individual function calls for each
-appended value. We therefore do not use iostreams, or iostream-style APIs,
-for logging.
+appended value. We therefore do not use iostreams, or iostream-style APIs, for
+logging.
There are cases when using an iostream utility (such as sstream) can result in
-clearer and similar-sized code. iostream may be used in those situations.
+clearer and similar-sized code. iostream may be used in those situations.
## Coding Style
@@ -130,34 +132,36 @@
### General
-* Line length should be limited to 80 characters.
-* Indentation should be done with 4 space characters.
-* Files should use Unix-style newlines (\n).
+- Line length should be limited to 80 characters.
+- Indentation should be done with 4 space characters.
+- Files should use Unix-style newlines (\n).
### Clang Formatting
-Individual OpenBMC repositories can use [clang-format](https://clang.llvm.org/docs/ClangFormat.html)
-if desired. The OpenBMC CI infrastructure will automatically verify the
-code formatting on code check-in if a .clang_format file is found
-within the root directory of the repository. This allows for automatic
-validation of code formatting upon check-in.
+Individual OpenBMC repositories can use
+[clang-format](https://clang.llvm.org/docs/ClangFormat.html) if desired. The
+OpenBMC CI infrastructure will automatically verify the code formatting on code
+check-in if a .clang_format file is found within the root directory of the
+repository. This allows for automatic validation of code formatting upon
+check-in.
If a custom configuration is desired, such as using different clang formatting
for C and C++ files, a format-code.sh script can be created, which can for
-example use different .clang* files as input depending on the file type.
-The format-code.sh script will be executed as part of CI if found in the root
+example use different .clang\* files as input depending on the file type. The
+format-code.sh script will be executed as part of CI if found in the root
directory of the repository, and will check that there are no files that were
modified after running it (same check as running clang).
-OpenBMC requires a clang-format of version 6.0 or greater. An example of
-how to run clang-format against all code in your repo can be found by
-referencing the [tool](https://github.com/openbmc/openbmc-build-scripts/blob/master/scripts/format-code.sh) used by CI.
+OpenBMC requires a clang-format of version 6.0 or greater. An example of how to
+run clang-format against all code in your repo can be found by referencing the
+[tool](https://github.com/openbmc/openbmc-build-scripts/blob/master/scripts/format-code.sh)
+used by CI.
[Example .clang-format](https://www.github.com/openbmc/docs/blob/master/style/cpp/.clang-format)
### Bracket style
-* Utilize 'Allman' style brackets. Brackets are on their own line at the same
+- Utilize 'Allman' style brackets. Brackets are on their own line at the same
indentation level as the statement that creates the scope.
```
@@ -174,7 +178,7 @@
}
```
-* Even one line conditional and loop statements should have brackets.
+- Even one line conditional and loop statements should have brackets.
```
/// Wrong.
@@ -190,7 +194,7 @@
### Indentation
-* Content within a namespace should be at the same indentation level as the
+- Content within a namespace should be at the same indentation level as the
namespace itself.
```
@@ -202,7 +206,7 @@
}
```
-* Content within a class / struct should be indented.
+- Content within a class / struct should be indented.
```
class Foo
@@ -212,7 +216,7 @@
}
```
-* Content within a function / conditional / loop should be indented.
+- Content within a function / conditional / loop should be indented.
```
void foo()
@@ -227,7 +231,7 @@
}
```
-* Switch / case statements should be indented.
+- Switch / case statements should be indented.
```
switch (foo)
@@ -246,10 +250,10 @@
}
```
-* Labels should be indented so they appear at 1 level less than the current
- indentation, rather than flush to the left. (This is not to say that goto
- and labels are preferred or should be regularly used, but simply when they
- are used, this is how they are to be used.)
+- Labels should be indented so they appear at 1 level less than the current
+ indentation, rather than flush to the left. (This is not to say that goto and
+ labels are preferred or should be regularly used, but simply when they are
+ used, this is how they are to be used.)
```
void foo()
@@ -273,9 +277,9 @@
### 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.
+- 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.
```
/// Correct.
@@ -288,6 +292,7 @@
### Header Ordering
Header inclusion order for a header file:
+
```
local headers (e.g. "daemon_sys.hpp")
c-libraries
@@ -295,6 +300,7 @@
```
Header inclusion order for a source file:
+
```
source.hpp (if applicable)
local headers
@@ -306,22 +312,22 @@
#### Files
-* C++ headers should end in ".hpp". C headers should end in ".h".
-* C++ files should be named with lower_snake_case.
+- C++ headers should end in ".hpp". C headers should end in ".h".
+- C++ files should be named with lower_snake_case.
#### Types
-* Prefer 'using' over 'typedef' for type aliases.
-* Structs, classes, enums, and typed template parameters should all be in
+- Prefer 'using' over 'typedef' for type aliases.
+- Structs, classes, enums, and typed template parameters should all be in
UpperCamelCase.
-* Prefer namespace scoping rather than long names with prefixes.
-* A single-word type alias within a struct / class may be lowercase to match
- STL conventions (`using type = T`) while a multi-word type alias should be
+- Prefer namespace scoping rather than long names with prefixes.
+- A single-word type alias within a struct / class may be lowercase to match STL
+ conventions (`using type = T`) while a multi-word type alias should be
UpperCamelCase (`using ArrayOfT = std::array<T, N>`).
-* Exception: A library API may use lower_snake_case to match conventions of the
- STL or an underlying C library it is abstracting. Application APIs should
- all be UpperCamelCase.
-* Exception: A for-convenience template type alias of a template class may end
+- Exception: A library API may use lower_snake_case to match conventions of the
+ STL or an underlying C library it is abstracting. Application APIs should all
+ be UpperCamelCase.
+- Exception: A for-convenience template type alias of a template class may end
in `_t` to match the conventions of the STL.
```
@@ -336,27 +342,26 @@
#### Variables
-* Variables should all be lowerCamelCase, including class members, with no
+- Variables should all be lowerCamelCase, including class members, with no
underscores.
#### Functions
-* Functions should all be lowerCamelCase.
-* Exception: A library API may use lower_snake-case to match conventions of
- the STL or an underlying C library it is abstracting. Application APIs
- should all be lowerCamelCase.
+- Functions should all be lowerCamelCase.
+- Exception: A library API may use lower_snake-case to match conventions of the
+ STL or an underlying C library it is abstracting. Application APIs should all
+ be lowerCamelCase.
#### Constants
-* Constants and enum members should be named like variables in lowerCamelCase.
+- Constants and enum members should be named like variables in lowerCamelCase.
#### Namespaces
-* Namespaces should be lower_snake_case.
-* Top-level namespace should be named based on the containing repository.
-* Favor a namespace called 'details' or 'internal' to indicate the equivalent
- of a "private" namespace in a header file and anonymous namespaces in a C++
- file.
+- Namespaces should be lower_snake_case.
+- Top-level namespace should be named based on the containing repository.
+- Favor a namespace called 'details' or 'internal' to indicate the equivalent of
+ a "private" namespace in a header file and anonymous namespaces in a C++ file.
### Header Guards
@@ -364,16 +369,16 @@
### Additional Whitespace
-* Follow NL.18: Use C++-style declarator layout.
+- Follow NL.18: Use C++-style declarator layout.
```
foo(T& bar, const S* baz); /// Correct.
foo(T &bar, const S *baz); /// Incorrect.
```
-* Follow NL.15: Use spaces sparingly.
+- Follow NL.15: Use spaces sparingly.
-* Insert whitespace after a conditional and before parens.
+- Insert whitespace after a conditional and before parens.
```
if (...)
@@ -381,14 +386,15 @@
for (...)
```
-* Insert whitespace around binary operators for readability.
+- Insert whitespace around binary operators for readability.
```
foo((a-1)/b,c-2); /// Incorrect.
foo((a - 1) / b, c - 2); /// Correct.
```
-* Do not insert whitespace around unary operators.
+- Do not insert whitespace around unary operators.
+
```
a = * b; /// Incorrect.
a = & b; /// Incorrect.
@@ -396,7 +402,7 @@
if (! a) /// Incorrect.
```
-* Do not insert whitespace inside parens or between a function call and
+- Do not insert whitespace inside parens or between a function call and
parameters.
```
@@ -408,7 +414,8 @@
} while(0); /// 'while' here is structured like a function call.
```
-* Prefer line-breaks after operators to show continuation.
+- Prefer line-breaks after operators to show continuation.
+
```
if (this1 == that1 &&
this2 == that2) /// Correct.
@@ -417,7 +424,7 @@
&& this2 == that2) /// Incorrect.
```
-* Long lines should have continuation start at the same level as the parens or
+- 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.
```
@@ -440,13 +447,10 @@
### 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 will do.
+- 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
+ will do.
-* Use `uint8_t`, `int16_t`, `uint32_t`, `int64_t`, etc. for types where size
- is important due to hardware interaction. Do not use them, without good
- reason, when hardware interaction is not involved; prefer size_t or int
- instead.
-
-
+- Use `uint8_t`, `int16_t`, `uint32_t`, `int64_t`, etc. for types where size is
+ important due to hardware interaction. Do not use them, without good reason,
+ when hardware interaction is not involved; prefer size_t or int instead.
diff --git a/designs/README.md b/designs/README.md
index 8d0fc96..7c8f46f 100644
--- a/designs/README.md
+++ b/designs/README.md
@@ -1,4 +1,4 @@
This is a directory of design documents.
-Newly authored design documents are encouraged to follow the [design document
-template](design-template.md).
+Newly authored design documents are encouraged to follow the
+[design document template](design-template.md).
diff --git a/designs/binarystore-via-blobs.md b/designs/binarystore-via-blobs.md
index b4fa032..de841a2 100644
--- a/designs/binarystore-via-blobs.md
+++ b/designs/binarystore-via-blobs.md
@@ -5,16 +5,17 @@
Created: 2018-12-07
## Problem Description
-Server platform host OS often needs to store and/or access data coupled
-with the machine itself, which in most cases has a 1:1 mapping with the
-motherboard. Traditionally, this is achieved by directly accessing the FRU
-EEPROM, or going through BMC using IPMI FRU commands. However, it may not
-always be viable or desirable due to:
-* The FRU data may be programmed by MFG and treated as read-only
-* The FRU data may not be in IPMI FRU format
-* The data to store may not fit in the data types defined in IPMI FRU spec
-* Host may want to store multiple copies in e.g. BMC EEPROM
+Server platform host OS often needs to store and/or access data coupled with the
+machine itself, which in most cases has a 1:1 mapping with the motherboard.
+Traditionally, this is achieved by directly accessing the FRU EEPROM, or going
+through BMC using IPMI FRU commands. However, it may not always be viable or
+desirable due to:
+
+- The FRU data may be programmed by MFG and treated as read-only
+- The FRU data may not be in IPMI FRU format
+- The data to store may not fit in the data types defined in IPMI FRU spec
+- Host may want to store multiple copies in e.g. BMC EEPROM
The BMC generic IPMI blobs binary store, or "binary store" in short, serves a
simple purpose: provide a read/write/serialize abstraction layer through IPMI
@@ -23,25 +24,28 @@
Despite its name, the binary blob store cannot be used for everything.
-* It is not a host/BMC mailbox. In general, BMC should reserve the space for
- blob store and not try to write it due to concurrency concerns. It is
- expected the only accessors are the IPMI blob store commands.
-* It is not a key store. Because the data stored is accessible to IPMI users
- and is not encrypted in anyway, extra caution should be used. It is not
- meant for storing data containing any keys or secrets.
-* The data to be stored should not be too large. Since each IPMI packet is
+- It is not a host/BMC mailbox. In general, BMC should reserve the space for
+ blob store and not try to write it due to concurrency concerns. It is expected
+ the only accessors are the IPMI blob store commands.
+- It is not a key store. Because the data stored is accessible to IPMI users and
+ is not encrypted in anyway, extra caution should be used. It is not meant for
+ storing data containing any keys or secrets.
+- The data to be stored should not be too large. Since each IPMI packet is
limited in size, trying to send an overly large binary is going to take too
long, and the overhead of the IPMI transport layer might make it not
worthwhile.
## Background and References
+
Please read the IPMI Blob protocol design as primer
[here](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 short.
+Under the hood, the binary blobs are stored as a binary
+[protocol buffer](https://github.com/protocolbuffers/protobuf), or "protobuf" in
+short.
## Requirements
+
1. BMC image should have `phosphor-ipmi-blobs` installed.
1. The host should know the specific blob base id that it intends to operate on.
For this design the discovery operations are limited.
@@ -50,8 +54,9 @@
or large binary data.
## Proposed Design
-This section describes how the handler `phosphor-ipmi-blobs-binarystore`
-defines each handler of the IPMI Blob protocol.
+
+This section describes how the handler `phosphor-ipmi-blobs-binarystore` defines
+each handler of the IPMI Blob protocol.
### Blob ID Definition
@@ -75,11 +80,12 @@
`/test/nested/dir` will fail.
### Platform Configuration
-For the binary store handler, a configuration file provides the base id,
-which file and which offset in the file to store the data. Optionally a
-"max\_size" param can be specified to indicate the total size of such binary
-storage should not exceed the limitation. If "max\_size" is specified as -1 or
-not specified, the storage could grow up to what the physical media allows.
+
+For the binary store handler, a configuration file provides the base id, which
+file and which offset in the file to store the data. Optionally a "max_size"
+param can be specified to indicate the total size of such binary storage should
+not exceed the limitation. If "max_size" is specified as -1 or not specified,
+the storage could grow up to what the physical media allows.
```none
base_id: /bmc_store/
@@ -87,12 +93,13 @@
offset: 256
max_size: 1024
```
+
[1] Example Configuration
### Binary Store Protobuf Definition
The data is stored as a binary protobuf containing a variable number of binary
-blobs, each having a unique blob\_id string with the base id as a common prefix.
+blobs, each having a unique blob_id string with the base id as a common prefix.
```none
message BinaryBlob {
@@ -115,24 +122,27 @@
The binary store handler will implement the following primitives:
#### BmcBlobGetCount/BmcBlobEnumerate
-Initially only the base id will appear when enumerating the existing blobs.
-Once a valid binary has successfully been committed, its blob id will appear
-in the list.
+
+Initially only the base id will appear when enumerating the existing blobs. Once
+a valid binary has successfully been committed, its blob id will appear in the
+list.
#### BmcBlobOpen
-`flags` can be `READ` for read-only access or `READ|WRITE`. `blob_id` can be
-any string with a matching prefix. If there is not already a valid binary
-stored with supplied `blob_id`, the handler treats it as a request to create
-such a blob.
+
+`flags` can be `READ` for read-only access or `READ|WRITE`. `blob_id` can be any
+string with a matching prefix. If there is not already a valid binary stored
+with supplied `blob_id`, the handler treats it as a request to create such a
+blob.
The `session_id` returned should be used by the rest of the session based
-commands to operate on the blob. If there is already an open session, this
-call will fail.
+commands to operate on the blob. If there is already an open session, this call
+will fail.
NOTE: the newly created blob is not serialized and stored until `BmcBlobCommit`
is called.
#### BmcBlobRead
+
Returns bytes with the requested offset and size. If there are not enough bytes
the handler will return the bytes that are available.
@@ -140,40 +150,48 @@
indicates that the memory content matches the data serialized to storage.
#### BmcBlobWrite
+
Writes bytes to the requested offset. Return number of bytes written if success,
zero if failed.
#### BmcBlobCommit
+
Store the serialized BinaryBlobStore to associated system file.
#### BmcBlobClose
+
Mark the session as closed. Any uncommitted changes to the blob state is lost.
#### BmcBlobDelete
-Delete the binary data associated with `blob_id`.
-Deleting the base\_id (the 'directory' level) will fail harmlessly.
+
+Delete the binary data associated with `blob_id`. Deleting the base_id (the
+'directory' level) will fail harmlessly.
#### BmcBlobStat
+
`size` returned equals to length of the `data` bytes in the protobuf.
`blob_state` will be set with `OPEN_R`, `OPEN_W`, and/or `COMMITTED` as
appropriate.
#### BmcBlobSessionStat/BmcBlobWriteMeta
+
Not supported.
### Example Host Command Flow
#### No binary data yet, write data
-1. `BmcBlobGetCount` followed by `BmcBlobEnumerate`. Since there is
- no valid blob with binary data stored, BMC handler only populates the
- `base_id` per platform configuration. e.g. `/bmc_store/`.
-1. `BmcBlobOpen` with `blob_id = /bmc_store/blob0`, BMC honors the
- request and returns `session_id = 0`.
+
+1. `BmcBlobGetCount` followed by `BmcBlobEnumerate`. Since there is no valid
+ blob with binary data stored, BMC handler only populates the `base_id` per
+ platform configuration. e.g. `/bmc_store/`.
+1. `BmcBlobOpen` with `blob_id = /bmc_store/blob0`, BMC honors the request and
+ returns `session_id = 0`.
1. `BmcBlobWrite` multiple times to write the data into the blob.
1. `BmcBlobCommit`. BMC writes data into configured path, e.g. to EEPROM.
1. `BmcBlobClose`
#### Read existing data
+
1. `BmcBlobGetCount` followed by `BmcBlobEnumerate` shows `/bmc_store/` and
`/bmc_store/blob0`.
1. `BmcBlobStat` on `/bmc_store/blob0` shows non-zero size and `COMMITTED`
@@ -183,29 +201,29 @@
1. `BmcBlobClose`.
## Alternatives Considered
-The first alternative considered was to store the data via IPMI FRU commands;
-as mentioned in the problem description, it is not always viable.
+
+The first alternative considered was to store the data via IPMI FRU commands; as
+mentioned in the problem description, it is not always viable.
There is a Google OEM I2C-over-IPMI driver that allows the host to read/write
I2C devices attached to the BMC. In comparison, the blob store approach proposed
offer more abstraction and is more flexible in where to store the data.
## Impacts
-***Security***:
-As mentioned, the binary store transfer mechanism doesn't offer encryption.
-Entities storing the data through this mechanism should be aware and either
-not to transfer security-critical data, or supply their own security
+
+**_Security_**: As mentioned, the binary store transfer mechanism doesn't offer
+encryption. Entities storing the data through this mechanism should be aware and
+either not to transfer security-critical data, or supply their own security
mechanism on top.
-***BMC performance***:
-Since the handler requires protobuf package, it may increase
-BMC image size if the package wasn't previously installed.
+**_BMC performance_**: Since the handler requires protobuf package, it may
+increase BMC image size if the package wasn't previously installed.
-***Host compatibility***:
-If data has been stored using IPMI blob binary store, then the host
-would need a handler that understands the blob transfer
-semantics to read the data.
+**_Host compatibility_**: If data has been stored using IPMI blob binary store,
+then the host would need a handler that understands the blob transfer semantics
+to read the data.
## Testing
+
Where possible mockable interfaces will be used to unit test the logic of the
code.
diff --git a/designs/bios-bmc-smm-error-logging.md b/designs/bios-bmc-smm-error-logging.md
index a853f8f..71a4704 100644
--- a/designs/bios-bmc-smm-error-logging.md
+++ b/designs/bios-bmc-smm-error-logging.md
@@ -1,13 +1,14 @@
# BIOS->BMC SMM Error Logging Queue Daemon
Author:
-* Brandon Kim / brandonkim@google.com / @brandonk
+
+- Brandon Kim / brandonkim@google.com / @brandonk
Other contributors:
-* Marco Cruz-Heredia / mcruzheredia@google.com
-Created:
- Mar 15, 2022
+- Marco Cruz-Heredia / mcruzheredia@google.com
+
+Created: Mar 15, 2022
## Problem Description
@@ -26,9 +27,9 @@
Different BMC vendors support different methods such as Shared Memory (SHM, via
LPC / eSPI) and P2A or PCI Mailbox, but the existing daemon that utilizes them
-do it over IPMI blob to communicate where and how much data has been
-transferred (see [phosphor-ipmi-flash](https://github.com/openbmc/phosphor-ipmi-flash)
-and [libmctp/astlpc](https://github.com/openbmc/libmctp/blob/master/docs/bindings/vendor-ibm-astlpc.md))
+do it over IPMI blob to communicate where and how much data has been transferred
+(see [phosphor-ipmi-flash](https://github.com/openbmc/phosphor-ipmi-flash) and
+[libmctp/astlpc](https://github.com/openbmc/libmctp/blob/master/docs/bindings/vendor-ibm-astlpc.md))
## Requirements
@@ -62,21 +63,21 @@
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 | <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 |
### Initialization
@@ -114,17 +115,17 @@
## Alternatives Considered
-* IPMI was considered, did not meet our speed requirement of writing 1KB entry
+- IPMI was considered, did not meet our speed requirement of writing 1KB entry
in about 50 microseconds.
- * For reference, initial PCI Mailbox performance measurement showed 1KB entry
+ - For reference, initial PCI Mailbox performance measurement showed 1KB entry
write took roughly 10 microseconds.
-* LPC / eSPI was also considered but our BMC's SHM buffer was limited to 4KB
+- LPC / eSPI was also considered but our BMC's SHM buffer was limited to 4KB
which was not enough for our use case.
-* `libmctp` and MCTP PCIe VDM were considered.
- * `libmctp`'s current implementation relies on LPC as the transport binding
+- `libmctp` and MCTP PCIe VDM were considered.
+ - `libmctp`'s current implementation relies on LPC as the transport binding
and IPMI KCS for synchronization. LPC as discussed, does not fit our current
need and synchronization does not work.
- * We may use MCTP PCIe VDM on our future platforms once we have more resources
+ - We may use MCTP PCIe VDM on our future platforms once we have more resources
with expertise both from the BMC and the BIOS side (which we currently lack)
for our current project timeline.
@@ -136,6 +137,7 @@
### Organizational
This design will require 2 repositories:
+
- bios-bmc-smm-error-logger
- This repository will implement the daemon described in this document
- Proposed maintainer: wltu@google.com , brandonkim@google.com
@@ -149,7 +151,6 @@
Unit tests will cover each parts of the daemon, mainly:
-* Initialization
-* Circular buffer processing
-* Decoding / Processing library
-
+- Initialization
+- Circular buffer processing
+- Decoding / Processing library
diff --git a/designs/bmc-boot-ready.md b/designs/bmc-boot-ready.md
index 05ea5c8..1d43d3b 100644
--- a/designs/bmc-boot-ready.md
+++ b/designs/bmc-boot-ready.md
@@ -7,32 +7,33 @@
Created: May 12, 2022
## Problem Description
+
There are services which run on the BMC which are required for the BIOS (host
-firmware) to power on and boot the system. The goal of this design is to
-define a mechanism to ensure these dependencies are met before a power on
-or boot is started.
+firmware) to power on and boot the system. The goal of this design is to define
+a mechanism to ensure these dependencies are met before a power on or boot is
+started.
-For example, on some system, you can not power on the chassis until the VPD
-has been collected from the VRM's by the BMC to determine their characteristics.
-On other systems, the BIOS service is needed so the host firmware can look
-for any overrides.
+For example, on some system, you can not power on the chassis until the VPD has
+been collected from the VRM's by the BMC to determine their characteristics. On
+other systems, the BIOS service is needed so the host firmware can look for any
+overrides.
-Currently, OpenBMC has an undefined behavior in this area. If a particular
-BMC has a large time gap between when the webserver is available and when all
-BMC services have completed running, there is a window there that a user could
+Currently, OpenBMC has an undefined behavior in this area. If a particular BMC
+has a large time gap between when the webserver is available and when all BMC
+services have completed running, there is a window there that a user could
request a power on via the webserver when not all needed services are running.
## 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 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 [BMC][3] state object is considered `Ready` once the systemd
`multi-user.target` has successfully started all if its services.
There are three options that have been discussed to solve this issue:
+
1. D-Bus objects don't exist until the backend is prepared to handle them.
2. If a user tries something that system is not in proper state to handle then
return an error code.
@@ -57,8 +58,10 @@
in this review though has been that this is the most preferred option.
[1]: https://lists.ozlabs.org/pipermail/openbmc/2022-April/030175.html
-[2]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/State
-[3]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC.interface.yaml
+[2]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/State
+[3]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC.interface.yaml
## Requirements
@@ -76,29 +79,32 @@
requested operation will be automatically executed.
## Alternatives Considered
-The "Background and References" section covered some alternative options
-and the complexity behind them.
+
+The "Background and References" section covered some alternative options and the
+complexity behind them.
Another option is to code the dependencies directly into the services. For
-example, if the power on service requires the vrm vpd collection service,
-encode that dependency in the systemd files. This is easy to say but in practice
-has been challenging. Some OpenBMC services have built in assumptions that
-the multi-user.target and all of it's dependent services have completed prior
-to a power on being started. The general consensus within IBM was that it's
-much easier and safer to just have a global wait-for-bmc-ready function as
-proposed in this design.
+example, if the power on service requires the vrm vpd collection service, encode
+that dependency in the systemd files. This is easy to say but in practice has
+been challenging. Some OpenBMC services have built in assumptions that the
+multi-user.target and all of it's dependent services have completed prior to a
+power on being started. The general consensus within IBM was that it's much
+easier and safer to just have a global wait-for-bmc-ready function as proposed
+in this design.
## Impacts
-Users will need to understand that their request to power on the system may
-be delayed by an undefined amount of time. In general, a BMC gets to Ready state
+Users will need to understand that their request to power on the system may be
+delayed by an undefined amount of time. In general, a BMC gets to Ready state
within a couple of minutes.
### Organizational
+
This function will be implemented within the existing phosphor-state-manager
repository. x86-power-control, an alternative to phosphor-state-manager, could
also implement this logic.
## Testing
+
- Ensure a power on request is properly queued and executed when it is made
prior to the BMC being `Ready`.
diff --git a/designs/bmc-health-monitor.md b/designs/bmc-health-monitor.md
index 36893b0..fc123da 100644
--- a/designs/bmc-health-monitor.md
+++ b/designs/bmc-health-monitor.md
@@ -1,13 +1,12 @@
### BMC Health Monitor
-Author:
- Vijay Khemka <vijaykhemka@fb.com>; <vijay!>
- Sui Chen <suichen@google.com>
+Author: Vijay Khemka <vijaykhemka@fb.com>; <vijay!> Sui Chen
+<suichen@google.com>
-Created:
- 2020-05-04
+Created: 2020-05-04
## Problem Description
+
The problem is to monitor the health of a system with a BMC so we have some
means to make sure the BMC is working correctly. User can get required metrics
data as per configurations instantly. Set of monitored metrics may include CPU
@@ -19,60 +18,59 @@
monitoring data, which may run on the BMC or on the host.) They perform the
following tasks:
-1) Configuration, where the user specifies what and how to collect,
- thresholds, etc.
-2) Metric collection, similar to what the read routine in phosphor-hwmon-readd
+1. Configuration, where the user specifies what and how to collect, thresholds,
+ etc.
+2. Metric collection, similar to what the read routine in phosphor-hwmon-readd
does.
-3) Metric staging. When metrics are collected, they will be ready to be read
+3. Metric staging. When metrics are collected, they will be ready to be read
anytime in accessible forms like DBus objects or raw files for use with
consumer programs. Because of this staging step, the consumer does not need
to poll and wait.
-4) Data transfer, where the consumer program obtains the metrics from the BMC
- by in-band or out-of-band methods.
-5) The consumer program may take certain actions based on the metrics
- collected.
+4. Data transfer, where the consumer program obtains the metrics from the BMC by
+ in-band or out-of-band methods.
+5. The consumer program may take certain actions based on the metrics collected.
Among those tasks, 1), 2), and 3) are the producer’s responsibility. 4) is
accomplished by both the producer and consumer. 5) is up to the consumer.
-We realize there is some overlap between sensors and health monitoring in
-terms of design rationale and existing infrastructure, so we largely follow
-the sensor design rationale. There are also a few differences between sensors
-and metrics:
+We realize there is some overlap between sensors and health monitoring in terms
+of design rationale and existing infrastructure, so we largely follow the sensor
+design rationale. There are also a few differences between sensors and metrics:
-1) Sensor data originate from hardware, while most metrics may be obtained
+1. Sensor data originate from hardware, while most metrics may be obtained
through software. For this reason, there may be more commonalities between
- metrics on all kinds of BMCs than sensors on BMCs, and we might not need
- the hardware discovery process or build-time, hardware-specific
- configuration for most health metrics.
-2) Most sensors are instantaneous readings, while metrics might accumulate
- over time, such as “uptime”. For those metrics, we might want to do
- calculations that do not apply to sensor readings.
+ metrics on all kinds of BMCs than sensors on BMCs, and we might not need the
+ hardware discovery process or build-time, hardware-specific configuration for
+ most health metrics.
+2. Most sensors are instantaneous readings, while metrics might accumulate over
+ time, such as “uptime”. For those metrics, we might want to do calculations
+ that do not apply to sensor readings.
As such, BMC Health Monitoring infrastructure will be an independent package
that presents health monitoring data in the sensor structure as defined in
-phosphor-dbus-interface, supporting all sensor packages and allowing metrics
-to be accessed and processed like sensors.
+phosphor-dbus-interface, supporting all sensor packages and allowing metrics to
+be accessed and processed like sensors.
## Background and References
-References:
-dbus-monitor
+
+References: dbus-monitor
## Requirements
The metric producer should provide
+
- A daemon to periodically collect various health metrics and expose them on
DBus
-- A dbus interface to allow other services, like redfish and IPMI, to access
- its data
+- A dbus interface to allow other services, like redfish and IPMI, to access its
+ data
- Capability to configure health monitoring
- Capability to take action as configured when values crosses threshold
- Optionally, maintain a certain amount of historical data
- Optionally, log critical / warning messages
-The metric consumer may be written in various different ways. No matter how
-the consumer is obtained, it should be able to obtain the health metrics from
-the producer through a set of interfaces.
+The metric consumer may be written in various different ways. No matter how the
+consumer is obtained, it should be able to obtain the health metrics from the
+producer through a set of interfaces.
The metric consumer is not in the scope of this document.
@@ -81,13 +79,13 @@
The metric producer is a daemon running on the BMC that performs the required
tasks and meets the requirements above. As described above, it is responsible
for
-1) Configuration
-2) Metric collection and
-3) Metric staging tasks
+
+1. Configuration
+2. Metric collection and
+3. Metric staging tasks
For 1) Configuration, There is a JSON configuration file for threshold,
-frequency of monitoring in seconds, window size and actions.
-For example,
+frequency of monitoring in seconds, window size and actions. For example,
```json
"CPU" : {
@@ -123,27 +121,27 @@
}
}
```
-Frequency : It is time in second when these data are collected in regular
- interval.
-Window_size: This is a value for number of samples taken to average out usage
- of system rather than taking a spike in usage data.
-Log : A boolean value which allows to log an alert. This field is an
- optional with default value for this in critical is 'true' and in
- warning it is 'false'.
-Target : This is a systemd target unit file which will called once value
- crosses its threshold and it is optional.
-For 2) Metric collection, this will be done by running certain functions
-within the daemon, as opposed to launching external programs and shell
-scripts. This is due to performance and security considerations.
+Frequency : It is time in second when these data are collected in regular
+interval. Window_size: This is a value for number of samples taken to average
+out usage of system rather than taking a spike in usage data. Log : A boolean
+value which allows to log an alert. This field is an optional with default value
+for this in critical is 'true' and in warning it is 'false'. Target : This is a
+systemd target unit file which will called once value crosses its threshold and
+it is optional.
+
+For 2) Metric collection, this will be done by running certain functions within
+the daemon, as opposed to launching external programs and shell scripts. This is
+due to performance and security considerations.
For 3) Metric staging, the daemon creates a D-bus service named
"xyz.openbmc_project.HealthMon" with object paths for each component:
"/xyz/openbmc_project/sensors/utilization/cpu",
-"/xyz/openbmc_project/sensors/utilization/memory", etc.
-which will result in the following D-bus tree structure
+"/xyz/openbmc_project/sensors/utilization/memory", etc. which will result in the
+following D-bus tree structure
"xyz.openbmc_project.HealthMon":
+
```
/xyz/openbmc_project
└─/xyz/openbmc_project/sensors
@@ -152,23 +150,25 @@
```
## Alternatives Considered
-We have tried doing health monitoring completely within the IPMI Blob
-framework. In comparison, having the metric collection part a separate daemon
-is better for supporting more interfaces.
+
+We have tried doing health monitoring completely within the IPMI Blob framework.
+In comparison, having the metric collection part a separate daemon is better for
+supporting more interfaces.
We have also tried doing the metric collection task by running an external
-binary as well as a shell script. It turns out running shell script is too
-slow, while running an external program might have security concerns (in that
-the 3rd party program will need to be verified to be safe).
+binary as well as a shell script. It turns out running shell script is too slow,
+while running an external program might have security concerns (in that the 3rd
+party program will need to be verified to be safe).
## Impacts
+
Most of what the Health Monitoring Daemon does is to do metric collection and
update DBus objects. The impacts of the daemon itself should be small.
## Testing
-To verify the daemon is functionally working correctly, we can monitor the
-DBus traffic generated by the Daemon, and the readings on the Daemon’s DBus
-objects.
+
+To verify the daemon is functionally working correctly, we can monitor the DBus
+traffic generated by the Daemon, and the readings on the Daemon’s DBus objects.
This can also be tested over IPMI/Redfish using sensor command as some of
metrics data are presented as sensors like CPU and Memory are presented as
diff --git a/designs/bmc-reset-with-host-up.md b/designs/bmc-reset-with-host-up.md
index 1a6fcbb..0a308eb 100644
--- a/designs/bmc-reset-with-host-up.md
+++ b/designs/bmc-reset-with-host-up.md
@@ -7,21 +7,24 @@
Created: June 23rd, 2020
## Problem Description
+
BMCs can reboot for a lot of different reasons. User request, firmware update,
and a variety of different error scenarios. When the BMC is rebooted while the
host is up and running, there needs to be a process by which the two synchronize
with each other and the BMC gets itself into a state that matches with the host.
## Background and References
+
A good portion of this is explained in the phosphor-state-manager [README][1].
-This design doc is written to formalize the design and add some more
-details on dealing with both IPMI and PLDM communication to the host as well as
-desired behavior when unable to talk with the host.
+This design doc is written to formalize the design and add some more details on
+dealing with both IPMI and PLDM communication to the host as well as desired
+behavior when unable to talk with the host.
The high level flow is that OpenBMC software first checks for pgood, and if set,
it then checks the host to see if it is up and alive. If the power is on and the
host is running, then files are created in the filesystem to indicate this:
+
- /run/openbmc/chassis@0-on
- /run/openbmc/host@0-on
@@ -33,37 +36,39 @@
implementation is done for the host via `phosphor-reset-host-check@.service` and
the file /run/openbmc/host@%i-on.
-If chassis power is on and the host is up, then
-`obmc-chassis-poweron@.target` and `obmc-host-start@.target` are started.
+If chassis power is on and the host is up, then `obmc-chassis-poweron@.target`
+and `obmc-host-start@.target` are started.
-The /run/ files are used by OpenBMC services to determine if they need to run
-or not when the chassis and host targets are started. For example, if the
-chassis is already powered on and the host is running, there is no need to
-actually turn power on, or start the host. The behavior wanted is that these
-services "start" but do nothing. That is commonly done within a systemd service
-file via the following:
+The /run/ files are used by OpenBMC services to determine if they need to run or
+not when the chassis and host targets are started. For example, if the chassis
+is already powered on and the host is running, there is no need to actually turn
+power on, or start the host. The behavior wanted is that these services "start"
+but do nothing. That is commonly done within a systemd service file via the
+following:
+
- `ConditionPathExists=!/run/openbmc/chassis@%i-on`
- `ConditionPathExists=!/run/openbmc/host@%i-on`
-This allows the targets to start and for the BMC to get in synch with the
-state of the chassis and host without any special software checks.
+This allows the targets to start and for the BMC to get in synch with the state
+of the chassis and host without any special software checks.
Different systems have different requirements on what the behavior should be
when the chassis power is on, but the host is unreachable. This design needs to
allow this customization. For example, some systems would prefer to just leave
the system in whatever state it is in and let the user correct things. Some
-systems want to recover automatically (i.e. reboot the host) for the user.
-Some systems have a hybrid approach where depending on where the host was in
-its boot, the BMC may leave it or recover.
+systems want to recover automatically (i.e. reboot the host) for the user. Some
+systems have a hybrid approach where depending on where the host was in its
+boot, the BMC may leave it or recover.
## Requirements
+
- Support both IPMI and PLDM as mechanisms to determine if the host is running.
- Allow either or both to be enabled
- Support custom behavior when chassis power is on but the BMC is unable to
communicate with the host
-- Both IPMI and PLDM stacks will give the host a set amount of time to
- respond. Lack of response within this time limit will result in the BMC
- potentially taking recovery actions.
+- Both IPMI and PLDM stacks will give the host a set amount of time to respond.
+ Lack of response within this time limit will result in the BMC potentially
+ taking recovery actions.
- This time limit must be configurable at build time
- IPMI and PLDM will implement a phosphor-dbus-interface interface,
`xyz.openbmc_project.Condition.HostFirmware`, which will have a
@@ -71,22 +76,26 @@
determine if the host is running.
### IPMI Detailed Requirements
+
- IPMI will continue to utilize the SMS_ATN command to indicate to the host that
a "Get Message Flags Command" is requested. Upon the host issuing that
command, it will be considered up and running
### PLDM Detailed Requirements
+
- PLDM will utilize a GetTID command to the host to determine if it is running
- Where applicable, PLDM will provide a mechanism to distinguish between
different host firmware stacks
- - For example, on IBM systems there is a difference between the
- hostboot (host initialization) firmware and Hypervisor firmware stacks.
- Both are host firmware and talking PLDM but the BMC recovery paths will
- differ based on which is running. The `CurrentFirmwareCondition` property
- should not return "Running" unless the Hypervisor firmware is running.
+ - For example, on IBM systems there is a difference between the hostboot (host
+ initialization) firmware and Hypervisor firmware stacks. Both are host
+ firmware and talking PLDM but the BMC recovery paths will differ based on
+ which is running. The `CurrentFirmwareCondition` property should not return
+ "Running" unless the Hypervisor firmware is running.
## Proposed Design
+
High Level Flow:
+
- Check pgood
- Call mapper for all implementations of
`xyz.openbmc_project.Condition.HostFirmware` PDI interface
@@ -98,23 +107,25 @@
IPMI and PLDM software will be started as applicable. A combination of systemd
services and applications within phosphor-state-manager will coordinate the
checking of pgood, and if set, request the IPMI and PLDM applications to
-discover if the host is running. Based on the response from these queries
-the software in phosphor-state-manager will take the appropriate action of
-creating the /run files and starting the chassis and host targets or entering
-into recovery of the host.
+discover if the host is running. Based on the response from these queries the
+software in phosphor-state-manager will take the appropriate action of creating
+the /run files and starting the chassis and host targets or entering into
+recovery of the host.
The systemd targets responsible for this and any common services will be hosted
-within phosphor-state-manager. Any system or company specific services can
-be installed in the common targets:
+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
### Automated Recovery when host does not respond
A separate service and application will be created within phosphor-state-manager
-to execute the following logic in situations where chassis power is on
-but the host has failed to respond to any of the different mechanisms to
-communicate with it:
+to execute the following logic in situations where chassis power is on but the
+host has failed to respond to any of the different mechanisms to communicate
+with it:
+
- If chassis power on (/run/openbmc/chassis@%i-on)
- And host is off (!ConditionPathExists=!/run/openbmc/host@%i-on)
- And restored BootProgress is not None
@@ -123,11 +134,12 @@
- Move host to Quiesce and allow automated recovery to kick in
### Note on custom mechanism for IBM systems
+
IBM systems will utilize a processor CFAM register. The specific register is
**Mailbox scratch register 12**.
-If the chassis power is on but the BMC is unable to communicate with the
-host via IPMI or PLDM, then the BMC will read this processor CFAM register.
+If the chassis power is on but the BMC is unable to communicate with the host
+via IPMI or PLDM, then the BMC will read this processor CFAM register.
The Host code will write `0xA5000001` to this register to indicate when it has
reached a state in which it can boot an operating system without needing the
@@ -137,35 +149,38 @@
but it will also show the host state as `Running`.
If the register is not `0xA5000001`, then the BMC will follow whatever recovery
-mechanisms are defined for when the host has a failure (most likely a reboot
-of the host).
+mechanisms are defined for when the host has a failure (most likely a reboot of
+the host).
-It is the responsibility of the host firmware to set this register as
-applicable during the boot of the system. Host firmware will clear this register
-in shutdown scenarios. To handle different host crash scenarios, the register
-will also be cleared by the BMC firmware on power off's, system checkstops, and
+It is the responsibility of the host firmware to set this register as applicable
+during the boot of the system. Host firmware will clear this register in
+shutdown scenarios. To handle different host crash scenarios, the register will
+also be cleared by the BMC firmware on power off's, system checkstops, and
during Memory Preserving reboots.
-
## Alternatives Considered
+
One thought was to avoid IPMI/PLDM all together and only use a "lowest common
denominator" hardware register of some sort. The problem with that is you start
creating your own protocol, and before you know it you have something like IPMI
-or PLDM anyway, except you created something custom. So 99% of the time the
-IPMI or PLDM path will be fine, and as a backup option, system owners can
-put their own custom host-detection applications in.
+or PLDM anyway, except you created something custom. So 99% of the time the IPMI
+or PLDM path will be fine, and as a backup option, system owners can put their
+own custom host-detection applications in.
## Impacts
+
None
## Testing
+
The normal path of IPMI and PLDM will be simple to test. Boot your system and
reboot the BMC. Verify the BMC chassis and host states are correct and verify
the host continued to run without issue throughout the BMC reset.
The more complicated tests will be error paths:
-- Reboot the BMC while the host is booting, but before it's in a state where
- it can continue to run without the BMC. Verify the BMC detects this error
+
+- Reboot the BMC while the host is booting, but before it's in a state where it
+ can continue to run without the BMC. Verify the BMC detects this error
scenario once it comes back from its reboot and takes the proper recovery
actions for the host.
- Reboot the BMC when the host is up and running but disable the IPMI/PLDM stack
@@ -173,4 +188,5 @@
reboot. Ensure the BMC follows the defined recovery for the system in this
situation.
-[1]: https://github.com/openbmc/phosphor-state-manager#bmc-reset-with-host-andor-chassis-on
+[1]:
+ https://github.com/openbmc/phosphor-state-manager#bmc-reset-with-host-andor-chassis-on
diff --git a/designs/bmc-service-failure-debug-and-recovery.md b/designs/bmc-service-failure-debug-and-recovery.md
index 06b9a26..a8afd64 100644
--- a/designs/bmc-service-failure-debug-and-recovery.md
+++ b/designs/bmc-service-failure-debug-and-recovery.md
@@ -1,13 +1,10 @@
# BMC Service Failure Debug and Recovery
-Author:
-Andrew Jeffery <andrew@aj.id.au> @arj
+Author: Andrew Jeffery <andrew@aj.id.au> @arj
-Other contributors:
-Andrew Geissler <geissonator@yahoo.com> @geissonator
+Other contributors: Andrew Geissler <geissonator@yahoo.com> @geissonator
-Created:
-6th May 2021
+Created: 6th May 2021
## Problem Description
@@ -15,13 +12,14 @@
meet the reliability and serviceability claims made for some platforms.
This design addresses a few classes of failures:
+
- A class of failure exists where a BMC service has entered a failed state but
the BMC is still operational in a degraded mode.
- A class of failure exists under which we can attempt debug data collection
despite being unable to communicate with the BMC via standard protocols.
-This proposal argues for and proposes a software-driven debug data capture
-and recovery of a failed BMC.
+This proposal argues for and proposes a software-driven debug data capture and
+recovery of a failed BMC.
## Background and References
@@ -34,16 +32,16 @@
As such, failures of BMC subsystems may impact external consumers.
The BMC firmware stack is not trivial, in the sense that common implementations
-are usually a domain-specific Linux distributions with complex or highly
-coupled relationships to platform subsystems.
+are usually a domain-specific Linux distributions with complex or highly coupled
+relationships to platform subsystems.
Complexity and coupling drive concern around the risk of critical failures in
the BMC firmware. The BMC firmware design should provide for resilience and
recovery in the face of well-defined error conditions, but the need to mitigate
ill-defined error conditions or entering unintended software states remains.
-The ability for a system to recover in the face of an error condition depends
-on its ability to detect the failure. Thus, error conditions can be assigned to
+The ability for a system to recover in the face of an error condition depends on
+its ability to detect the failure. Thus, error conditions can be assigned to
various classes based on the ability to externally observe the error:
1. Continued operation: The services detects the error and performs the actions
@@ -59,19 +57,17 @@
4. Unresponsive: The service fails to detect it cannot make progress and
continues to run but is unresponsive
-
As the state transformations to enter the ill-defined or unintended software
state are unanticipated, the actions required to gracefully return to an
expected state are also not well defined. The general approaches to recover a
-system or service to a known state in the face of entering an unknown state
-are:
+system or service to a known state in the face of entering an unknown state are:
1. Restart the affected service
2. Restart the affected set of services
3. Restart all services
-In the face of continued operation due to internal recovery a service restart
-is unnecessary, while in the case of a unresponsive service the need to restart
+In the face of continued operation due to internal recovery a service restart is
+unnecessary, while in the case of a unresponsive service the need to restart
cannot be detected by service state alone. Implementation of resiliency by way
of service restarts via a service manager is only possible in the face of a
graceful exit or application crash. Handling of services that have entered an
@@ -92,11 +88,11 @@
implement IPMI, HTTPS (e.g. for Redfish), MCTP and PLDM. This second class also
covers implementation-specific data transports such as D-Bus, which requires a
broker service. Failure of a platform data transport may result in one or all
-external interfaces becoming unresponsive and be viewed as a critical failure
-of the BMC.
+external interfaces becoming unresponsive and be viewed as a critical failure of
+the BMC.
-Like error conditions and services, the BMC's external interfaces can be
-divided into several classes:
+Like error conditions and services, the BMC's external interfaces can be divided
+into several classes:
1. Out-of-band interfaces: Remote, operator-driven platform management
2. In-band interfaces: Local, host-firmware-driven platform management
@@ -114,7 +110,7 @@
the system manages and mitigates error conditions as follows:
| Condition | Mechanism |
-|---------------------|-----------------------------------------------------|
+| ------------------- | --------------------------------------------------- |
| Continued operation | Application-specific error handling |
| Graceful exit | Application-specific error handling |
| Crash | Signal, unhandled exceptions, `assert()`, `abort()` |
@@ -133,7 +129,7 @@
manages and mitigates error conditions as follows:
| Condition | Mechanism |
-|---------------------|----------------------------------------|
+| ------------------- | -------------------------------------- |
| Continued operation | ramoops, ftrace, `printk()` |
| Graceful exit | System reboot |
| Crash | kdump or ramoops |
@@ -147,13 +143,12 @@
### Synthesis
In the context of the information above, handling of application lock-up error
-conditions is not provided. For applications in the platform-data-provider
-class of external interfaces, the system will continue to operate with reduced
+conditions is not provided. For applications in the platform-data-provider class
+of external interfaces, the system will continue to operate with reduced
functionality. For applications in the platform-data-transport-provider class,
this represents a critical failure of the firmware that must have accompanying
debug data.
-
## Handling platform-data-transport-provider failures
### Requirements
@@ -162,11 +157,11 @@
The ability for external consumers to control the recovery behaviour of BMC
services is usually coarse, the nuanced handling is left to the BMC
-implementation. Where available the options for external consumer tend to be,
-in ascending order of severity:
+implementation. Where available the options for external consumer tend to be, in
+ascending order of severity:
| Severity | BMC Recovery Mechanism | Used for |
-|----------|-------------------------|-----------------------------------------------------------------------|
+| -------- | ----------------------- | --------------------------------------------------------------------- |
| 1 | Graceful reboot request | Normal circumstances or recovery from platform data provider failures |
| 2 | Forceful reboot request | Recovery from unresponsive platform data transport providers |
| 3 | External hardware reset | Unresponsive operating system |
@@ -185,31 +180,31 @@
The need to escalate above mechanism 1 should come with data that captures why
it was necessary, i.e. dumps for services that failed in the path for 1.
However, by escalating straight to 3, the BMC will necessarily miss out on
-capturing a debug dump because there is no opportunity for software to
-intervene in the reset. Therefore, mechanism 2 should exist in the system
-design and its implementation should capture any appropriate data needed to
-debug the need to reboot and the inability to execute on approach 1.
+capturing a debug dump because there is no opportunity for software to intervene
+in the reset. Therefore, mechanism 2 should exist in the system design and its
+implementation should capture any appropriate data needed to debug the need to
+reboot and the inability to execute on approach 1.
The need to escalate to 3 would indicate that the BMC's own mechanisms for
detecting a kernel lockup have failed. Had they not failed, we would have
ramoops or kdump data to analyse. As data cannot be captured with an escalation
to method 3 the need to invoke it will require its own specialised debug
-experience. Given this and the kernel's own lockup detection and data
-collection mechanism, support for 2 can be implemented in BMC userspace.
+experience. Given this and the kernel's own lockup detection and data collection
+mechanism, support for 2 can be implemented in BMC userspace.
Mechanism 1 is typically initiated by the usual in-band interfaces, either IPMI
or PLDM. In order to avoid these in the implementation of mechanism 2, the host
needs an interface to the BMC that is dedicated to the role of BMC recovery,
-with minimal dependencies on the BMC side for initiating the dump collection
-and reboot. At its core, all that is needed is the ability to trigger a BMC
-IRQ, which could be as simple as monitoring a GPIO.
+with minimal dependencies on the BMC side for initiating the dump collection and
+reboot. At its core, all that is needed is the ability to trigger a BMC IRQ,
+which could be as simple as monitoring a GPIO.
#### Behavioural Requirements for Recovery Mechanism 2
The system behaviour requirement for the mechanism is:
-1. The BMC executes collection of debug data and then reboots once it observes
- a recovery message from the host
+1. The BMC executes collection of debug data and then reboots once it observes a
+ recovery message from the host
It's desirable that:
@@ -224,16 +219,16 @@
#### Analysis of BMC Recovery Mechanisms for Power10 Platforms
The implementation of recovery mechanism 1 is already accounted for in the
-in-band protocols between the host and the BMC and so is considered resolved
-for the purpose of the discussion.
+in-band protocols between the host and the BMC and so is considered resolved for
+the purpose of the discussion.
To address recovery mechanism 3, the Power10 platform designs wire up a GPIO
driven by the host to the BMC's EXTRST pin. If the host firmware detects that
the BMC has become unresponsive to its escalating recovery requests, it can
drive the hardware to forcefully reset the BMC.
-However, host-side GPIOs are in short supply, and we do not have a dedicated
-pin to implement recovery mechanism 2 in the platform designs.
+However, host-side GPIOs are in short supply, and we do not have a dedicated pin
+to implement recovery mechanism 2 in the platform designs.
#### Analysis of Implementation Methods on Power10 Platforms
@@ -244,14 +239,14 @@
2. LPC
3. PCIe
-FSI is inappropriate because the host is the peripheral in its relationship
-with the BMC. If the BMC has become unresponsive, it is possible it's in a
-state where it would not accept FSI traffic (which it needs to drive in the
-first place) and we would need an mechanism architected into FSI for the BMC to
-recognise it is in a bad state. PCIe and LPC are preferable by comparison as
-the BMC is the peripheral in this relationship, with the host driving cycles
-into it over either interface. Comparatively, PCIe is more complex than LPC, so
-an LPC-based approach is preferred.
+FSI is inappropriate because the host is the peripheral in its relationship with
+the BMC. If the BMC has become unresponsive, it is possible it's in a state
+where it would not accept FSI traffic (which it needs to drive in the first
+place) and we would need an mechanism architected into FSI for the BMC to
+recognise it is in a bad state. PCIe and LPC are preferable by comparison as the
+BMC is the peripheral in this relationship, with the host driving cycles into it
+over either interface. Comparatively, PCIe is more complex than LPC, so an
+LPC-based approach is preferred.
The host already makes use of several LPC peripherals exposed from the BMC:
@@ -269,20 +264,20 @@
In ASPEED BMC SoCs prior to the AST2600 the LPC mailbox required configuration
via the SuperIO device, which exposes the unrestricted iLPC2AHB backdoor into
-the BMC's physical address space. The iLPC2AHB capability could not be
-mitigated without disabling SuperIO support entirely, and so the ability to use
-the mailbox went with it. This security issue is resolved in the AST2600
-design, so the mailbox could be used in the Power10 platforms, but we have
-lower-complexity alternatives for generating an IRQ on the BMC. We could use
-the iLPC2AHB from the host to drive one of the watchdogs in the BMC to trigger
-a reset, but this exposes a stability risk due to the unrestricted power of the
-interface, let alone the security implications, and like the mailbox is more
-complex than the alternatives.
+the BMC's physical address space. The iLPC2AHB capability could not be mitigated
+without disabling SuperIO support entirely, and so the ability to use the
+mailbox went with it. This security issue is resolved in the AST2600 design, so
+the mailbox could be used in the Power10 platforms, but we have lower-complexity
+alternatives for generating an IRQ on the BMC. We could use the iLPC2AHB from
+the host to drive one of the watchdogs in the BMC to trigger a reset, but this
+exposes a stability risk due to the unrestricted power of the interface, let
+alone the security implications, and like the mailbox is more complex than the
+alternatives.
This draws us towards the use of a KCS device, which is best aligned with the
simple need of generating an IRQ on the BMC. AST2600 has at least 4 KCS devices
-of which one is already in use for IBM's vendor-defined MCTP LPC binding
-leaving at least 3 from which to choose.
+of which one is already in use for IBM's vendor-defined MCTP LPC binding leaving
+at least 3 from which to choose.
### Proposed Design
@@ -314,8 +309,8 @@
The proposed implementation provides for both the required and desired
behaviours outlined in the requirements section above.
-The host and BMC protocol operates as follows, starting with the BMC
-application invoked during the boot process:
+The host and BMC protocol operates as follows, starting with the BMC application
+invoked during the boot process:
1. Set the `Ready` bit in STR
@@ -348,22 +343,21 @@
7. If `Ready` becomes set before expiry, disarm the escalation timer. Recovery
is complete. Otherwise,
-8. Escalate to recovery mechanism 3 if the escalation timer expires at any
- point
+8. Escalate to recovery mechanism 3 if the escalation timer expires at any point
A SerIRQ is unnecessary for correct operation of the protocol. The BMC-side
implementation is not required to emit one and the host implementation must
behave correctly without one. Recovery is only necessary if other paths have
-failed, so STR can be read by the host when it decides recovery is required,
-and by read by time-based polling thereafter.
+failed, so STR can be read by the host when it decides recovery is required, and
+by read by time-based polling thereafter.
The host must be prepared to handle LPC SYNC errors when accessing the KCS
device IO addresses, particularly "No Response" aborts. It is not guaranteed
that the KCS device will remain available during BMC resets.
-As STR is polled by the host it's not necessary for the BMC to write to ODR.
-The protocol only requires the host to write to IDR and periodically poll STR
-for changes to IBF and Ready state. This removes bi-directional dependencies.
+As STR is polled by the host it's not necessary for the BMC to write to ODR. The
+protocol only requires the host to write to IDR and periodically poll STR for
+changes to IBF and Ready state. This removes bi-directional dependencies.
The uni-directional writes and the lack of SerIRQ reduce the features required
for correct operation of the protocol and thus the surface area for failure of
@@ -372,7 +366,7 @@
The layout of the KCS Status Register (STR) is as follows:
| Bit | Owner | Definition |
-|-----|----------|--------------------------|
+| --- | -------- | ------------------------ |
| 7 | Software | |
| 6 | Software | |
| 5 | Software | |
@@ -388,15 +382,15 @@
available kernel interfaces[1], and implementing the behaviour in the kernel
falls afoul of the defacto "mechanism, not policy" rule of kernel support.
-Realistically, on the host side the only requirements are the use of a timer
-and writing the appropriate value to the Input Data Register (IDR). All the
-proposed status bits can be ignored. With this in mind, the BMC's
-implementation can be reduced to reading an appropriate value from IDR.
-Reducing requirements on the 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).
+Realistically, on the host side the only requirements are the use of a timer and
+writing the appropriate value to the Input Data Register (IDR). All the proposed
+status bits can be ignored. With this in mind, the BMC's implementation can be
+reduced to reading an appropriate value from IDR. Reducing requirements on the
+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
@@ -407,7 +401,8 @@
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
@@ -432,31 +427,30 @@
data than might otherwise be possible. There are no obvious developer-specific
drawbacks.
-Due to simplicity being a design-point of the proposal, there are no
-significant API, performance or upgradability impacts.
+Due to simplicity being a design-point of the proposal, there are no significant
+API, performance or upgradability impacts.
### Testing
-Generally, testing this feature requires complex interactions with
-host firmware and platform-specific mechanisms for triggering the reboot
-behaviour.
+Generally, testing this feature requires complex interactions with host firmware
+and platform-specific mechanisms for triggering the reboot behaviour.
For Power10 platforms this feature may be safely tested under QEMU by scripting
the monitor to inject values on the appropriate KCS device. Implementing this
for automated testing may need explicit support in CI.
-
## Handling platform-data-provider failures
### Requirements
As noted above, these types of failures usually yield a system that can continue
-to operate in a reduced capacity. The desired behavior in this scenario can
-vary from system to system so the requirements in this area need to be flexible
+to operate in a reduced capacity. The desired behavior in this scenario can vary
+from system to system so the requirements in this area need to be flexible
enough to allow system owners to configure their desired behavior.
The requirements for OpenBMC when a platform-data-provider service enters a
failure state are that the BMC:
+
- Logs an error indicating a service has failed
- Collects a BMC dump
- Changes BMC state (CurrentBMCState) to indicate a degraded mode of the BMC
@@ -465,17 +459,18 @@
### Proposed Design
This will build upon the existing [target-fail-monitoring][1] design. The
-monitor service will be enhanced to also take json file(s) which list
-critical services to monitor.
+monitor service will be enhanced to also take json file(s) which list critical
+services to monitor.
-Define a "obmc-bmc-service-quiesce.target". System owners can install any
-other services they wish in this new target.
+Define a "obmc-bmc-service-quiesce.target". System owners can install any other
+services they wish in this new target.
-phosphor-bmc-state-manager will monitor this target and enter a `Quiesced`
-state when it is started. This state will be reported externally via the
-Redfish API under redfish/v1/Managers/bmc status property.
+phosphor-bmc-state-manager will monitor this target and enter a `Quiesced` state
+when it is started. This state will be reported externally via the Redfish API
+under redfish/v1/Managers/bmc status property.
This would look like the following:
+
- In a services-to-monitor configuration file, add all critical services
- The state-manager service-monitor will subscribe to signals for service
failures and do the following when one fails from within the configuration
@@ -487,20 +482,21 @@
the BMC state into Quiesced
- bmcweb looks at BMC state to return appropriate state to external clients
-[1]: https://github.com/openbmc/docs/blob/master/designs/target-fail-monitoring.md
+[1]:
+ https://github.com/openbmc/docs/blob/master/designs/target-fail-monitoring.md
### Alternatives Considered
One simpler option would be to just have the OnFailure result in a BMC reboot
but historically this has caused more problems then it solves:
+
- Rarely does a BMC reboot fix a service that was not fixed by simply restarting
it.
- A BMC that continuously reboots itself due to a service failure is very
difficult to debug.
-- Some BMC's only allow a certain amount of reboots so eventually the
- BMC ends up stuck in the boot loader which is inaccessible unless special
- debug cables are available so for all intents and purposes your system is now
- unusable.
+- Some BMC's only allow a certain amount of reboots so eventually the BMC ends
+ up stuck in the boot loader which is inaccessible unless special debug cables
+ are available so for all intents and purposes your system is now unusable.
### Impacts
@@ -511,5 +507,5 @@
### Testing
A variety of service should be put into the fail state and the tester should
-ensure the appropriate error is logged, dump is collected, and BMC state
-is changed to reflect this.
+ensure the appropriate error is logged, dump is collected, and BMC state is
+changed to reflect this.
diff --git a/designs/boot-progress.md b/designs/boot-progress.md
index 07c3531..3b4082b 100644
--- a/designs/boot-progress.md
+++ b/designs/boot-progress.md
@@ -7,41 +7,43 @@
Created: May 27, 2020
## Problem Description
-The boot progress of an OpenBMC managed system is complex. There are a mix
-of phosphor D-Bus properties, IPMI sensors, PLDM sensors, and Redfish
-properties to represent it. The goal of this design document is to highlight
-these different entities and provide a base for system implementors on what
-to implement.
+
+The boot progress of an OpenBMC managed system is complex. There are a mix of
+phosphor D-Bus properties, IPMI sensors, PLDM sensors, and Redfish properties to
+represent it. The goal of this design document is to highlight these different
+entities and provide a base for system implementors on what to implement.
## Background and References
-[phosphor-state-manager][1] implements D-Bus properties which track the state
-of the BMC, Chassis, and Host. This design is primarily focused on the status
-of the Host since it is the most complex. Specifically the goal is to provide
+
+[phosphor-state-manager][1] implements D-Bus properties which track the state of
+the BMC, Chassis, and Host. This design is primarily focused on the status of
+the Host since it is the most complex. Specifically the goal is to provide
detailed information on what the host is doing during a boot.
-[HostState][2] provides basic `Off`/`Running` type information along
-with an error state (`Quiesced`) and debug state (`DiagnosticMode`). The focus
-of this document is the `Running` state. This simply indicates whether something
-is running on the host processors.
+[HostState][2] provides basic `Off`/`Running` type information along with an
+error state (`Quiesced`) and debug state (`DiagnosticMode`). The focus of this
+document is the `Running` state. This simply indicates whether something is
+running on the host processors.
-phosphor-state-manager implements some other D-Bus properties that represent
-the host boot progress:
+phosphor-state-manager implements some other D-Bus properties that represent the
+host boot progress:
- [xyz.openbmc_project.State.Boot.Progress][3]
- [xyz.openbmc_project.State.OperatingSystem.Status][4]
-These two D-Bus properties are very IPMI-centric. They were defined based on
-two IPMI sensors which are set by the host firmware as it boots the system.
+These two D-Bus properties are very IPMI-centric. They were defined based on two
+IPMI sensors which are set by the host firmware as it boots the system.
PLDM also has a boot progress sensor. Search for "Boot Progress" in this
-[doc][5]. A subset of this maps fairly well to the IPMI sensors above. This
-PLDM sensor is not implemented yet in OpenBMC code.
+[doc][5]. A subset of this maps fairly well to the IPMI sensors above. This PLDM
+sensor is not implemented yet in OpenBMC code.
-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
+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]:
+[Status][state]:
+
- `xyz.openbmc_project.State.Host.HostState.Running` : `Enabled`
- `xyz.openbmc_project.State.Host.HostState.Quiesced` : `Quiesced`
- `xyz.openbmc_project.State.Host.HostState.DiagnosticMode` : `InTest`
@@ -64,8 +66,7 @@
- OEM
There is also a `LastStateTime` associated with this new BootProgress object
-which should be updated with the date and time the `LastState` was last
-updated.
+which should be updated with the date and time the `LastState` was last updated.
In the end, the goal is to be able to map either the IPMI or PLDM boot sensors
into all or some of the values in this new Redfish property.
@@ -73,38 +74,39 @@
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
-instance. Similarly, the Redfish system object is also an instance based
-object.
+instance. Similarly, the Redfish system object is also an instance based object.
## Requirements
+
- Enhance the existing [BootProgress][3] D-Bus property to cover all supported
PLDM boot progress codes
-- Create a new `BootProgressLastUpdate` D-Bus property that will hold the
- date and time of the last update to `BootProgress`
+- Create a new `BootProgressLastUpdate` D-Bus property that will hold the date
+ and time of the last update to `BootProgress`
- Ensure the `BootProgress` and `BootProgressLastUpdate` properties are updated
appropriately in both IPMI and PLDM based stacks
- - It is the responsibility of the IPMI or PLDM implementation to update
- the `BootProgress` property on D-Bus
+ - It is the responsibility of the IPMI or PLDM implementation to update the
+ `BootProgress` property on D-Bus
- It is the responsibility the phosphor-state-manager to update the
`BootProgressLastUpdate` property on D-Bus when it sees `BootProgress`
updated
-- Ensure the new Redfish `LastState` and `LastStateTime` properties
- have the appropriate mappings to the `BootProgress` and
- `BootProgressLastUpdate D-Bus properties
+- Ensure the new Redfish `LastState` and `LastStateTime` properties have the
+ appropriate mappings to the `BootProgress` and `BootProgressLastUpdate D-Bus
+ properties
Different OpenBMC systems could support different boot progress codes, and
support them in different orders. This document does not try to set any
-requirements on this other than that they must all be defined within
-the `BootProgress` D-Bus property and the ones which have a mapping
-to the Redfish BootProgress object will be shown via the Redfish interface.
+requirements on this other than that they must all be defined within the
+`BootProgress` D-Bus property and the ones which have a mapping to the Redfish
+BootProgress object will be shown via the Redfish interface.
## Proposed Design
-[BootProgress][3] will be enhanced to support a superset of what is provided
-by IPMI and PLDM.
-IPMI code already sets the `BootProgress` D-Bus property based on a config
-file. Look for `fw_boot_sensor` in this [file][8] for an example of how a
-particular IPMI sensor is mapped to this D-Bus property.
+[BootProgress][3] will be enhanced to support a superset of what is provided by
+IPMI and PLDM.
+
+IPMI code already sets the `BootProgress` D-Bus property based on a config file.
+Look for `fw_boot_sensor` in this [file][8] for an example of how a particular
+IPMI sensor is mapped to this D-Bus property.
PLDM software will do something similar.
@@ -112,28 +114,35 @@
appropriately to Redfish requests.
## Alternatives Considered
+
A lot of system BIOS's provided some form of a detailed boot progress codes.
UEFI has POST codes, POWER has istep progress codes. If more fine grained
-details were needed, we could look into using these. Currently though the
-need is just high level boot progress. Note that these POST/istep codes
-could be mapped to the appropriate BootProgress value if desired (or for
-cases where the host does not support an IPMI or PLDM stack that has
-BootProgress in it).
+details were needed, we could look into using these. Currently though the need
+is just high level boot progress. Note that these POST/istep codes could be
+mapped to the appropriate BootProgress value if desired (or for cases where the
+host does not support an IPMI or PLDM stack that has BootProgress in it).
## Impacts
-Each system will need to document which `BootProgress` codes they support
-and the expected order of them when a system is booting.
+
+Each system will need to document which `BootProgress` codes they support and
+the expected order of them when a system is booting.
## Testing
+
Ensure an IPMI and PLDM based system boot and update the `BootProgress` D-Bus
property as expected.
-
-[1]: https://github.com/openbmc/phosphor-state-manager#state-tracking-and-control
-[2]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Host.interface.yaml
-[3]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Boot/Progress.interface.yaml
-[4]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/OperatingSystem/Status.interface.yaml
-[5]: https://www.dmtf.org/sites/default/files/standards/documents/DSP0249_1.0.0.pdf
+[1]:
+ https://github.com/openbmc/phosphor-state-manager#state-tracking-and-control
+[2]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Host.interface.yaml
+[3]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Boot/Progress.interface.yaml
+[4]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/OperatingSystem/Status.interface.yaml
+[5]:
+ https://www.dmtf.org/sites/default/files/standards/documents/DSP0249_1.0.0.pdf
[6]: http://redfish.dmtf.org/schemas/v1/Resource.json#/definitions/Status
[7]: https://redfish.dmtf.org/schemas/v1/ComputerSystem.v1_13_0.json
-[8]: https://github.com/openbmc/meta-ibm/blob/master/recipes-phosphor/configuration/acx22-yaml-config/acx22-ipmi-sensors-mrw.yaml
+[8]:
+ https://github.com/openbmc/meta-ibm/blob/master/recipes-phosphor/configuration/acx22-yaml-config/acx22-ipmi-sensors-mrw.yaml
diff --git a/designs/certificate-revocation-list.md b/designs/certificate-revocation-list.md
index a295f47..889428b 100644
--- a/designs/certificate-revocation-list.md
+++ b/designs/certificate-revocation-list.md
@@ -11,31 +11,31 @@
## Background and References
-A certificate revocation list (CRL) is a list of digital certificates that
-have been revoked by the issuing certificate authority (CA) before their
-actual or assigned expiration date. In Google, there are use cases that BMC
-needs to install CRLs to the Redfish server, so that clients with revoked
-certificates will be rejected in TLS handshake. Supporting CRL is also
-recommended in most applications.
+A certificate revocation list (CRL) is a list of digital certificates that have
+been revoked by the issuing certificate authority (CA) before their actual or
+assigned expiration date. In Google, there are use cases that BMC needs to
+install CRLs to the Redfish server, so that clients with revoked certificates
+will be rejected in TLS handshake. Supporting CRL is also recommended in most
+applications.
Current OpenBMC certificate management architecture contains two main
components.
1. [phosphor-certificate-manager](https://github.com/openbmc/phosphor-certificate-manager)
-owns certificate objects and implements management interfaces; currently
-there are three types of certificates supported: client, server, and
-authority.
+ owns certificate objects and implements management interfaces; currently
+ there are three types of certificates supported: client, server, and
+ authority.
2. [BMCWeb](https://github.com/openbmc/bmcweb): the Redfish front-end which
-translates certificate objects into Redfish resources. BMCWeb is also a
-consumer of these certificates; it uses certificates in its TLS handshake.
+ translates certificate objects into Redfish resources. BMCWeb is also a
+ consumer of these certificates; it uses certificates in its TLS handshake.
DMTF doesn't support CRLs yet in the Redfish spec. Adding them is WIP. See
[this discussion](https://redfishforum.com/thread/618/resource-certificate-revocation-list?page=1&scrollTo=2173).
-Google doesn't plan on using Redfish interfaces to manage certificates and
-CRLs. Instead, Google has a dedicated daemon for credentials installation,
-and this daemon interacts with the OpenBMC certificate management
-architecture via DBus APIs.
+Google doesn't plan on using Redfish interfaces to manage certificates and CRLs.
+Instead, Google has a dedicated daemon for credentials installation, and this
+daemon interacts with the OpenBMC certificate management architecture via DBus
+APIs.
## Requirements
@@ -43,20 +43,21 @@
1. clients shall be able to install/delete/replace CRLs via DBus APIs
2. whenever CRLs change, the certificate management system shall notify
-consumers which use old CRLs to refresh with the newly given CRLs
+ consumers which use old CRLs to refresh with the newly given CRLs
3. other daemons, e.g., BMCWeb shall consume CRLs the same way as existing
-authority/server/client certificates, that is, via file path or directory
-determined at compile time.
+ authority/server/client certificates, that is, via file path or directory
+ determined at compile time.
## Proposed Design
### phosphor-dbus-interfaces
-We propose to introduce a new interface `CRL` in [Certs](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Certs).
+We propose to introduce a new interface `CRL` in
+[Certs](https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Certs).
Because no Redfish spec is available, we propose the only attribute of the
-interface to be `CRLString`, which contains the PEM encoded CRL. We can add
-more attributes as needed in the future.
+interface to be `CRLString`, which contains the PEM encoded CRL. We can add more
+attributes as needed in the future.
### phosphor-certificate-manager
@@ -66,27 +67,27 @@
The CRL-manager will implement the following common interfaces:
1. [InstallAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Certs/InstallAll.interface.yaml):
-install multiple CRLs and notify consumers. The notification process is
-the existing behaviour which phosphor-certificate-manager uses to tell
-consumers to reload newly installed credentials.
+ install multiple CRLs and notify consumers. The notification process is the
+ existing behaviour which phosphor-certificate-manager uses to tell consumers
+ to reload newly installed credentials.
2. [ReplaceAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Certs/ReplaceAll.interface.yaml):
-replace all existing CRLs with multiple new CRLs and notify consumers
+ replace all existing CRLs with multiple new CRLs and notify consumers
3. [DeleteAll](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Collection/DeleteAll.interface.yaml):
-delete all existing CRLs and notify consumers
+ delete all existing CRLs and notify consumers
### BMCWeb
-We propose to introduce CRLs into BMCWeb's SSL Context. Whenever BMCWeb
-reloads, it not only refreshes authority and server certificates, but also
-CRLs. Example codes can be found in many opensource projects, e.g., this
+We propose to introduce CRLs into BMCWeb's SSL Context. Whenever BMCWeb reloads,
+it not only refreshes authority and server certificates, but also CRLs. Example
+codes can be found in many opensource projects, e.g., this
[snippet](https://github.com/Icinga/icinga2/blob/master/lib/base/tlsutility.cpp#L338).
## Alternatives Considered
-We can model the whole CRLs list as a single object, but that's not aligned
-with the existing authorities list design.
+We can model the whole CRLs list as a single object, but that's not aligned with
+the existing authorities list design.
## Impacts
@@ -97,5 +98,5 @@
Add new unit tests in phosphor-certificate-manager.
-Manual integration tests: install CRLs and verify clients' revoked
-certificates are rejected.
+Manual integration tests: install CRLs and verify clients' revoked certificates
+are rejected.
diff --git a/designs/ci-authorization.md b/designs/ci-authorization.md
index dd55962..c00eb22 100644
--- a/designs/ci-authorization.md
+++ b/designs/ci-authorization.md
@@ -1,60 +1,57 @@
# Continuous integration and authorization for OpenBMC
-Author:
- Brad Bishop !radsquirrel
+Author: Brad Bishop !radsquirrel
-Other contributors:
- None
+Other contributors: None
-Created:
- 2019-01-30
+Created: 2019-01-30
## Problem Description
+
The OpenBMC project maintains a number of Jenkins CI jobs to ensure incoming
-contributions to the project source code meet a level of quality. Incoming
+contributions to the project source code meet a level of quality. Incoming
contributions can be made by the general public - anyone with a GitHub account.
However unlikely, it is possible for a bad actor to make code submissions that
attempt to compromise project resources, e.g. build systems, and as such some
amount of authorization of contributors must occur to provide some level of
protection from potential bad actors.
-
-The project already has contributor authorization for CI. This proposal serves
+The project already has contributor authorization for CI. This proposal serves
to describe the drawbacks of the current solution and propose an alternative
that addresses those drawbacks.
## Background and References
+
The current authorization solution checks the user for membership in the
-openbmc/general-developers GitHub team. If the contributor is a member of the
+openbmc/general-developers GitHub team. If the contributor is a member of the
team (or a general-developers sub-team), the automated CI processes are
-triggered without any human intervention. If the contributor is not a member of
+triggered without any human intervention. If the contributor is not a member of
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
+
The existing method for authorization has a singular problem - the GitHub
-organization owner role. In order for contributors to be added to the
+organization owner role. In order for contributors to be added to the
openbmc/general-developers GitHub team, the contributor must first be a member
-of the openbmc GitHub organization. Only organization owners can invite GitHub
-users to become members of an organization. Organization owners have
+of the openbmc GitHub organization. Only organization owners can invite GitHub
+users to become members of an organization. Organization owners have
unrestricted access to all aspects of the project - it would be unwise to bestow
organization ownership for the sole purpose of enabling
openbmc/general-developers group membership administrative capability.
-
An alternative authorization method for CI should:
- - Not require the GitHub organization owner role to administer the list of
- users authorized for CI.
- - Enable a hierarchical trust model for user authorization (groups nested
- within groups).
+
+- Not require the GitHub organization owner role to administer the list of users
+ authorized for CI.
+- Enable a hierarchical trust model for user authorization (groups nested within
+ groups).
## Proposed Design
+
The proposal is to simply migrate the current openbmc/general-developers GitHub
team, and all subordinate teams, to Gerrit groups:
@@ -69,13 +66,13 @@
group: `openbmc/ci-authorized` contains ->
- group `xyzcorp/ci-authorized`
+group `xyzcorp/ci-authorized`
- group `abccorp/ci-authorized`
+group `abccorp/ci-authorized`
- user `nancy`
+user `nancy`
- user `joe`
+user `joe`
This proposal also specifies a convention for administration of organizational
groups:
@@ -93,13 +90,16 @@
CCLA is signed and accepted by the project.
## Alternatives Considered
+
Assigning GitHub organization owner roles to organizational group administrators
was considered but is a major violation of the least-privilege-required
principle.
## Impacts
+
GitHub has vastly superior load balancing and backup capability so there is a
potential for decreased service availability and data loss.
## Testing
+
Deploy on a live production server 😀
diff --git a/designs/design-template.md b/designs/design-template.md
index 19be719..3e37184 100644
--- a/designs/design-template.md
+++ b/designs/design-template.md
@@ -1,108 +1,116 @@
-____
-# Document Guidelines - *Delete this section*
+---
+
+# Document Guidelines - _Delete this section_
## Document Content
-* Not all new features need a design document. If a feature can be
- contributed in a single reasonably small patchset that has little impact
- to any other areas, it doesn't need a design discussion and documentation.
-* The focus of the document is to define the problem we need to solve and
+- Not all new features need a design document. If a feature can be contributed
+ in a single reasonably small patchset that has little impact to any other
+ areas, it doesn't need a design discussion and documentation.
+
+- The focus of the document is to define the problem we need to solve and
analyse the trade-offs of different solutions. You should concentrate on
interactions between components, though analysing the trade-offs often
requires you to explore how each might be implemented.
-* Write this document as an [argumentative essay][argumentative-essay]. Good
+- Write this document as an [argumentative essay][argumentative-essay]. Good
design proposals compel the reviewers agree with the proposal's conclusions.
[argumentative-essay]: https://www.grammarly.com/blog/argumentative-essay/
-* This is not intended to be extensive documentation for a new feature.
+- This is not intended to be extensive documentation for a new feature.
-* You should get your design reviewed and merged before writing your code.
- However you are free to prototype the implementation, but remember that
- you may learn of new requirements during the design review process that
- could result in a very different solution.
+- You should get your design reviewed and merged before writing your code.
+ However you are free to prototype the implementation, but remember that you
+ may learn of new requirements during the design review process that could
+ result in a very different solution.
## Document Formatting
-* Your spec should be in Markdown format, like this template.
-* Please wrap text at 79 columns.
+- Your spec should be in Markdown format, like this template.
-* Please do not delete any of the sections in this template. If you have
- nothing to say for a whole section, just write: None
+- Please wrap text at 79 columns.
-* To view your .md file, see: https://stackedit.io/
+- Please do not delete any of the sections in this template. If you have nothing
+ to say for a whole section, just write: None
-* If you would like to provide a diagram with your spec, ASCII diagrams are
- required. http://asciiflow.com/ is a very nice tool to assist with making
- ASCII diagrams. Plain text will allow the review to proceed without
- having to look at additional files which can not be viewed in Gerrit. It
- will also allow inline feedback on the diagram itself.
+- To view your .md file, see: https://stackedit.io/
-* Once ready for review, submit to gerrit and set the topic of the review
- to "design"
-____
+- If you would like to provide a diagram with your spec, ASCII diagrams are
+ required. http://asciiflow.com/ is a very nice tool to assist with making
+ ASCII diagrams. Plain text will allow the review to proceed without having to
+ look at additional files which can not be viewed in Gerrit. It will also allow
+ inline feedback on the diagram itself.
+
+- Once ready for review, submit to gerrit and set the topic of the review to
+ "design"
+
+---
# Example design - this is the design title
-Author:
- < Name and Discord nickname >
+Author: < Name and Discord nickname >
-Other contributors:
- < Name and/or Discord nickname or `None` >
+Other contributors: < Name and/or Discord nickname or `None` >
-Created:
- < Date initially created in Month D, Yr format (e.g. June 17, 2020 or Dec 19,
- 2019)>
+Created: < Date initially created in Month D, Yr format (e.g. June 17, 2020 or
+Dec 19, 2019)>
## Problem Description
-(1 paragraph) What are we doing and why? What problem are you trying to
-solve? What are the goals and NON-goals? Please make the objective
-understandable for someone unfamiliar with this project by including the
-necessary context, but keep it short. Elaborate on the details below in the
-Background and Requirements sections.
+
+(1 paragraph) What are we doing and why? What problem are you trying to solve?
+What are the goals and NON-goals? Please make the objective understandable for
+someone unfamiliar with this project by including the necessary context, but
+keep it short. Elaborate on the details below in the Background and Requirements
+sections.
## Background and References
+
(1-2 paragraphs) What background context is necessary? You should mention
-related work inside and outside of OpenBMC. What other Open Source projects
-are trying to solve similar problems? Try to use links or references to
-external sources (other docs or Wikipedia), rather than writing your own
-explanations. Please include document titles so they can be found when links
-go bad. Include a glossary if necessary. Note: this is background; do not
-write about your design, specific requirements details, or ideas to solve
-problems here.
+related work inside and outside of OpenBMC. What other Open Source projects are
+trying to solve similar problems? Try to use links or references to external
+sources (other docs or Wikipedia), rather than writing your own explanations.
+Please include document titles so they can be found when links go bad. Include a
+glossary if necessary. Note: this is background; do not write about your design,
+specific requirements details, or ideas to solve problems here.
## Requirements
+
(2-5 paragraphs) What are the constraints for the problem you are trying to
-solve? Who are the users of this solution? What is required to be produced?
-What is the scope of this effort? Your job here is to quickly educate others
-about the details you know about the problem space, so they can help review
-your implementation. Roughly estimate relevant details. How big is the data?
-What are the transaction rates? Bandwidth?
+solve? Who are the users of this solution? What is required to be produced? What
+is the scope of this effort? Your job here is to quickly educate others about
+the details you know about the problem space, so they can help review your
+implementation. Roughly estimate relevant details. How big is the data? What are
+the transaction rates? Bandwidth?
## Proposed Design
-(2-5 paragraphs) A short and sweet overview of your implementation ideas. If
-you have alternative solutions to a problem, list them concisely in a bullet
-list. This should not contain every detail of your implementation, and do
-not include code. Use a diagram when necessary. Cover major structural
-elements in a very succinct manner. Which technologies will you use? What
-new components will you write? What technologies will you use to write them?
+
+(2-5 paragraphs) A short and sweet overview of your implementation ideas. If you
+have alternative solutions to a problem, list them concisely in a bullet list.
+This should not contain every detail of your implementation, and do not include
+code. Use a diagram when necessary. Cover major structural elements in a very
+succinct manner. Which technologies will you use? What new components will you
+write? What technologies will you use to write them?
## Alternatives Considered
+
(2 paragraphs) Include alternate design ideas here which you are leaning away
from. Elaborate on why a design was considered and why the idea was rejected.
-Show that you did an extensive survey about the state of the art. Compares
-your proposal's features & limitations to existing or similar solutions.
+Show that you did an extensive survey about the state of the art. Compares your
+proposal's features & limitations to existing or similar solutions.
## Impacts
-API impact? Security impact? Documentation impact? Performance impact?
-Developer impact? Upgradability impact?
+
+API impact? Security impact? Documentation impact? Performance impact? Developer
+impact? Upgradability impact?
### Organizational
-- Does this repository require a new repository? (Yes, No)
+
+- Does this repository require a new repository? (Yes, No)
- Who will be the initial maintainer(s) of this repository?
- Which repositories are expected to be modified to execute this design?
- Make a list, and add listed repository maintainers to the gerrit review.
## Testing
+
How will this be tested? How will this feature impact CI testing?
diff --git a/designs/device-tree-gpio-naming.md b/designs/device-tree-gpio-naming.md
index 037e9f3..92aec6f 100644
--- a/designs/device-tree-gpio-naming.md
+++ b/designs/device-tree-gpio-naming.md
@@ -2,28 +2,28 @@
Author: Andrew Geissler (geissonator)
-Other contributors:
- < None >
+Other contributors: < None >
Created: April 3, 2020
## Problem Description
+
The Linux kernel has deprecated the use of sysfs to interact with the GPIO
subsystem. The replacement is a "descriptor-based" character device interface.
[libgpiod][1] is a suite of tools and library implemented in C and C++ which
provides an abstraction to this new character device gpio interface.
-libgpiod provides a feature where you can access gpios by a name given to
-them in the kernel device tree files. The problem is there are no naming
-conventions for these GPIO names and if you want userspace code to be able
-to be consistent across different machines, these names would need to be
-consistent.
+libgpiod provides a feature where you can access gpios by a name given to them
+in the kernel device tree files. The problem is there are no naming conventions
+for these GPIO names and if you want userspace code to be able to be consistent
+across different machines, these names would need to be consistent.
## Background and References
+
The kernel [documentation][2] has a good summary of the GPIO subsystem. The
-specific field used to name the GPIOs in the DTS is `gpio-line-names`.
-This [patch][3] shows an example of naming the GPIOs for a system.
+specific field used to name the GPIOs in the DTS is `gpio-line-names`. This
+[patch][3] shows an example of naming the GPIOs for a system.
GPIOs are used for arbitrary things. It's pretty hard to have a coherent naming
scheme in the face of a universe of potential use-cases.
@@ -33,65 +33,83 @@
emerge.
## Requirements
+
- Ensure common function GPIOs within OpenBMC use the same naming convention
## Proposed Design
-Below are the standard categories. The "Pattern" in each section describes the
-naming convention and then the sub bullets list the common GPIO names to
-be used (when available on an OpenBMC system). This naming convention must be
-followed for all common GPIOs.
-This list below includes all common GPIOs within OpenBMC. Any OpenBMC
-system which provides one of the below GPIOs must name it as listed in
-this document. This document must be updated as new common GPIOs are added.
+Below are the standard categories. The "Pattern" in each section describes the
+naming convention and then the sub bullets list the common GPIO names to be used
+(when available on an OpenBMC system). This naming convention must be followed
+for all common GPIOs.
+
+This list below includes all common GPIOs within OpenBMC. Any OpenBMC system
+which provides one of the below GPIOs must name it as listed in this document.
+This document must be updated as new common GPIOs are added.
### Buttons
+
Pattern: `*-button`
-Buttons should always be considered 'input' to the BMC. There may be cases
-where BMC-less machines use a button to trigger system behavior and in a
-BMC-managed system this signal is emulated by the BMC (as output). These
-should not be considered a button in this document but enumerated as another
-signal type.
+Buttons should always be considered 'input' to the BMC. There may be cases where
+BMC-less machines use a button to trigger system behavior and in a BMC-managed
+system this signal is emulated by the BMC (as output). These should not be
+considered a button in this document but enumerated as another signal type.
#### power-button
### Host Ready
+
Below are input GPIO names specific to Host ready. The name of Host ready GPIO
depends on the index of Host and the active state is high or low.
Pattern:
+
- `host*-ready`: Host ready, active high
- `host*-ready-n`: Host ready, active low
Defined:
+
- host0-ready
- host1-ready-n
- ...
### LEDs
+
Pattern: `led-*`
#### led-fault
+
#### led-identify
+
#### led-power
+
#### led-sys-boot-status
+
#### led-attention
+
#### led-hdd-fault
+
#### led-rear-fault
+
#### led-rear-power
+
#### led-rear-id
### Power and Regulators
+
Pattern: `power-*`, `regulator-*`
#### power-chassis-control
+
Set to initiate power-on or power-off of the chassis.
#### power-chassis-good
+
Indicates the power good state of the chassis.
#### power-config-full-load
+
Output GPIO set by the power managing application that indicates to the hardware
the threshold of power supplies that are expected to be present and working for
this type of system for the case where a system has a model that supports two
@@ -102,13 +120,15 @@
performance so that it can maintain its powered on state.
#### power-ffs-sync-history
+
Output GPIO set by the power managing applications. The IBM Common Form Factor
power supplies use this line as an input. When set low and left low the power
-supply fans run at full speed (Fans Full Speed). When toggled low, then high,
-it resets the power supply input history (average and maximum power values over
-a time range).
+supply fans run at full speed (Fans Full Speed). When toggled low, then high, it
+resets the power supply input history (average and maximum power values over a
+time range).
#### regulator-standby-faulted
+
This GPIO value represents the status of standby power regulator fault detection
logic. This GPIO is an input only. The status will reflect a regulator
non-faulted condition after AC power cycle when no standby power regulator fault
@@ -116,80 +136,95 @@
condition when an unexpected drop in standby power is detected.
#### rtc-battery-voltage-read-enable
+
Output pin that enables the ADC to read the board RTC battery voltage.
### Presence
+
Pattern: `presence-*`
#### presence-ps0, presence-ps1, ..., presence-ps\<N>
### Reset Cause
+
These are GPIOs that provide more detail on the reason for a BMC reset. BMC
hardware generally provides some information on a BMC reboot, like a EXTRST
-(i.e. a BMC reset was reset by some external source). At times though,
-firmware needs more details on the cause of a reset. Hardware can be configured
-to latch an event into a GPIO for firmware to then utilize for different
-software logic.
+(i.e. a BMC reset was reset by some external source). At times though, firmware
+needs more details on the cause of a reset. Hardware can be configured to latch
+an event into a GPIO for firmware to then utilize for different software logic.
Pattern: `reset-cause-*`
#### reset-cause-pinhole
-The pinhole reset cause will be utilized by BMC firmware to know when it
-has been reset due to a user initiated pinhole reset. This is commonly done in
-error scenarios where the BMC is hanging or otherwise unresponsive. Note that
-this GPIO is not utilized to cause the actual reset, it is a GPIO that can be
-read after the BMC reset to know the reason for the reboot was a pinhole reset.
+
+The pinhole reset cause will be utilized by BMC firmware to know when it has
+been reset due to a user initiated pinhole reset. This is commonly done in error
+scenarios where the BMC is hanging or otherwise unresponsive. Note that this
+GPIO is not utilized to cause the actual reset, it is a GPIO that can be read
+after the BMC reset to know the reason for the reboot was a pinhole reset.
### Secure Boot
#### bmc-secure-boot
+
Input pin that indicates that the BMC is configured to boot with security
protections enforced.
-Pulled up by default (secure). Placing the jumper will pull the pin down
-(bypass security).
+Pulled up by default (secure). Placing the jumper will pull the pin down (bypass
+security).
### Special
+
These are special case and/or grandfathered in pin names.
#### air-water
+
Indicates whether system is air or water cooled
#### factory-reset-toggle
+
The software records the state of this GPIO and checks upon reboot if the state
has changed since the last reboot. If it has, it indicates that a factory reset
should be performed.
### POWER Specific GPIOs
+
Below are GPIO names specific to the POWER processor based servers.
#### Special
+
These are special case and/or grandfathered in pin names.
##### cfam-reset
+
Utilized to issue a processor logic reset to a IBM POWER processor.
##### checkstop
+
Utilized to indicate a IBM POWER processor has entered an unrecoverable error
state.
## Alternatives Considered
-- Continue to hard code a config file per system type that has the
-gpio bank and pin number. This removes a dependency on the device tree to
-have consistent names but adds overhead in supporting each new system.
-- Have the device tree GPIO names match the hardware schematics and then
-have another userspace config file that maps between the schematic names
-and logical pin names. This makes the GPIO to schematic mapping easy but
-adds an additional layer of work with the userspace config.
+- Continue to hard code a config file per system type that has the gpio bank and
+ pin number. This removes a dependency on the device tree to have consistent
+ names but adds overhead in supporting each new system.
+
+- Have the device tree GPIO names match the hardware schematics and then have
+ another userspace config file that maps between the schematic names and
+ logical pin names. This makes the GPIO to schematic mapping easy but adds an
+ additional layer of work with the userspace config.
## Impacts
+
Need to ensure OpenBMC device trees conform to the above naming conventions.
## Testing
+
Userspace utilization of the GPIO names will provide some testing coverage
during CI.
[1]: https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/about/
[2]: https://www.kernel.org/doc/html/latest/driver-api/gpio/index.html
-[3]: https://lore.kernel.org/linux-arm-kernel/20200306170218.79698-1-geissonator@yahoo.com/
+[3]:
+ https://lore.kernel.org/linux-arm-kernel/20200306170218.79698-1-geissonator@yahoo.com/
diff --git a/designs/dump-manager.md b/designs/dump-manager.md
index c5d5ef6..67d12bf 100644
--- a/designs/dump-manager.md
+++ b/designs/dump-manager.md
@@ -1,49 +1,54 @@
# Dump Manager Design
-Author:
- Dhruvaraj Subhashchandran <dhruvaraj@in.ibm.com>
+Author: Dhruvaraj Subhashchandran <dhruvaraj@in.ibm.com>
Other contributors:
Created: 12/12/2019
## Problem Description
+
During a crash or a host failure, an event monitor mechanism generates an error
log, but the size of the error log is limited to few kilobytes, so all the data
from the crash or failure may not fit into an error log. The additional data
-required for the debugging needs to be collected as a dump.
-The existing OpenBMC dump interfaces support only the dumps generated on
-the BMC and dump manager doesn't support download operations.
+required for the debugging needs to be collected as a dump. The existing OpenBMC
+dump interfaces support only the dumps generated on the BMC and dump manager
+doesn't support download operations.
## Glossary
- **System Dump**: A dump of the Host's main memory and processor registers.
- [Read More](https://en.wikipedia.org/wiki/Core_dump)
+ [Read More](https://en.wikipedia.org/wiki/Core_dump)
- **Memory Preserving Reboot(MPR)**: A method of reboot with preserving the
- contents of the volatile memory
+ contents of the volatile memory
- **PLDM**: An interface and data model to access low-level platform inventory,
- monitoring, control, event, and data/parameters transfer functions.
- [ReadMore](https://github.com/openbmc/docs/blob/master/designs/pldm-stack.md)
+ monitoring, control, event, and data/parameters transfer functions.
+ [ReadMore](https://github.com/openbmc/docs/blob/master/designs/pldm-stack.md)
- **Machine Check Exception**: A severe error inside a processor core that
- causes a processor core to stop all processing activities.
-- **BMCWeb**: An embedded webserver for OpenBMC. [More Info](https://github.com/openbmc/bmcweb/blob/master/README.md)
+ causes a processor core to stop all processing activities.
+- **BMCWeb**: An embedded webserver for OpenBMC.
+ [More Info](https://github.com/openbmc/bmcweb/blob/master/README.md)
## Background and References
-Various types of dumps are created based on the type and source of failure.
-The dump manager, which is orchestrating the collection and offload, needs to
+
+Various types of dumps are created based on the type and source of failure. The
+dump manager, which is orchestrating the collection and offload, needs to
provide methods to create, store the dump details, and offload it. Additionally,
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.
+
These are some of the dumps supported by dump manager.
#### BMC Dump
+
A dump collected when there is a failure in the BMC with various debug
information. This type of dump can be generated by user too to get the current
state of the BMC. This dump gets collected on BMC and stored on BMC
#### System Dump
+
A system dump is a collection of debugging information from the host, this may
include host memory and/or register data. This dump can be initiated by BMC and
there can be system reboots while collecting the dump. Dump gets stored in the
@@ -52,29 +57,34 @@
dump.
#### Resource dump
+
A special type of host dump is initiated and collected by the host based on the
request from a user. No system state change may be necessary during the
collection of this kind of a dump. A resource indicator may be used to indicate
what data to be collected. The content of the dump can be decided by the host.
This dump can be stored in host memory and offloaded through BMC or host can
-send this dump down to BMC once the collection is completed based on the size
-of the dump and the availability of space on the BMC.
+send this dump down to BMC once the collection is completed based on the size of
+the dump and the availability of space on the BMC.
#### Hostboot dump
+
A dump that can be collected during the boot failure of the host. This dump may
-or may not include the contents of the main memory and/or the processor registers.
+or may not include the contents of the main memory and/or the processor
+registers.
#### Hardware dump
-This dump can be collected during a critical failure on the hardware
-components like the processor while the host is booted and running. The host may
-stop during this dump and may collect various processor states and/or memory
-contents to help to debug the failure.
+This dump can be collected during a critical failure on the hardware components
+like the processor while the host is booted and running. The host may stop
+during this dump and may collect various processor states and/or memory contents
+to help to debug the failure.
## Requirements
+
#### 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.
- List the dumps: List all dumps present in the BMC.
@@ -82,30 +92,34 @@
- Notify: Notify the dump manager that a new dump is created.
- Delete the dump.
- Mark a dump as offloaded to an external entity.
-- Set the dump policies like disabling a type of dump or dump overwriting policy.
+- Set the dump policies like disabling a type of dump or dump overwriting
+ policy.
## Proposed Design
+
There are various types of dumps; interfaces are standard for most of the dumps,
-but huge dumps which cannot be stored on the BMC needs additional support.
-This document will explain the design of different types of dumps. The dumps are
+but huge dumps which cannot be stored on the BMC needs additional support. This
+document will explain the design of different types of dumps. The dumps are
classified based on where it is collected, stored, and how it is extracted. Two
major types are
- Collected by BMC and stored on BMC.
- Collected and stored on an attached entity but offloaded through BMC.
-This proposal focuses on re-using the existing [phosphor-debug-collector](https://github.com/openbmc/phosphor-debug-collector), which
-collects the dumps from BMC.
-
+This proposal focuses on re-using the existing
+[phosphor-debug-collector](https://github.com/openbmc/phosphor-debug-collector),
+which collects the dumps from BMC.
#### 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.
- An external request of dump is considered as a user-initiated BMC dump and
initiate BMC dump collection with a tool named dreport with type manual dump
-- The dreport create dump file in the dump path provided by the dump manager code.
+- The dreport create dump file in the dump path provided by the dump manager
+ code.
- A watch process is forked by the dump manager to catch the signal for the file
close on that path and assume the dump collection is completed.
- The watch process calls an internal dbus interface to create the dump entry
@@ -125,6 +139,7 @@
data to a path based on dump id.
#### 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
- Create will be returning an id which can be mapped to the actual dump once it
@@ -135,59 +150,61 @@
- Status of the dump, whether offloaded or not, will be added to the dump entry.
### Dump manager interfaces.
+
- Dump Manager DBus object provides interfaces for creating and managing dump
- Interfaces
- - **Create**: The interface to create a dump, called by clients to initiate
- user-initiated dump.
- - AdditionalData: The additional data, if any, for initiating the dump.
- The key in this case should be an implementation specific enum
- defined for the specific type of dump either in xyz or in a domain.
- The values can be either a string or a 64 bit number.
- The enum-format string is required to come from a parallel class
- with this specific Enum name. All of the Enum strings should be in
- the format
- 'domain.Dump.Create.CreateParameters.ParamName'.
- e.g.:
- {
- "key1": "value1",
- "key2": "value2"
- }
- ends up in AdditionaData like:
- ["KEY1=value1", "KEY2=value2"]
- - **Notify**: Notify the dump manager that a new dump is created.
- - ID: ID of the dump, if not 0 this will be the external id of the dump
- - Type: Type of dump that was created.
- - Size: Size of the dump
+ - **Create**: The interface to create a dump, called by clients to initiate
+ user-initiated dump.
- ### Dump entry interfaces
+ - AdditionalData: The additional data, if any, for initiating the dump. The
+ key in this case should be an implementation specific enum defined for the
+ specific type of dump either in xyz or in a domain. The values can be
+ either a string or a 64 bit number. The enum-format string is required to
+ come from a parallel class with this specific Enum name. All of the Enum
+ strings should be in the format
+ 'domain.Dump.Create.CreateParameters.ParamName'. e.g.: { "key1": "value1",
+ "key2": "value2" } ends up in AdditionaData like: ["KEY1=value1",
+ "KEY2=value2"]
+
+ - **Notify**: Notify the dump manager that a new dump is created.
+ - ID: ID of the dump, if not 0 this will be the external id of the dump
+ - Type: Type of dump that was created.
+ - Size: Size of the dump
+
+### Dump entry interfaces
+
- **InitiateOffload**: Initiate the offload of the dump.
- OffloadUri: The URI where the dump should be offloaded.
#### The properties common to all dumps
+
There will be a base dump entry with properties common to all types of dumps
+
- ID: Id of the dump
- Timestamp: Dump creation timestamp
- Size: Total size of the dump
- OffloadComplete: Set to true when offload is completed
- OffloadURI: The URI for offloading the dump, set while initiating the offload.
-Specific types need to inherit from this common dump entry class
-and add specific properties.
+ Specific types need to inherit from this common dump entry class and add
+ specific properties.
#### Additional propertries based on dump types
##### BMC Dump
+
- No Additional properties
##### System Dump
+
- External Source ID: ID provided by the Host, this id will be used for all
communication to the source of the dump, in this case, Host.
-
### Flow of dumps collected and stored in the Host
-PLDM is provided as an example dump transport and notification mechanism
-between Host and BMC.
+
+PLDM is provided as an example dump transport and notification mechanism between
+Host and BMC.
- Create: Initiate methods to create the dump in Host.
- Generating the dump in Host
@@ -196,33 +213,30 @@
- InitiateOffload: Dump manager request Host to start offload
- The Host sends the dump through PLDM, and PLDM on BMC sends it out.
-
## Alternatives Considered
+
- Offloading Host dumps through Host instead of BMC, but considered BMC option
- due to following reasons
- - The BMC is considered the "management path" of most servers and often
- the Host is not connected to the desired network for the offload
- location.
- - BMC provides one common point for all dumps generated in the system
- for external management appliance.
+ due to following reasons - The BMC is considered the "management path" of most
+ servers and often the Host is not connected to the desired network for the
+ offload location. - BMC provides one common point for all dumps generated in
+ the system for external management appliance.
## Impacts
-- The existing BMC dump interface needs to be re-used. The current interface is
+
+- The existing BMC dump interface needs to be re-used. The current interface is
not accepting a dump type, so a new interface to create the dump with type
will be provided for BMC dump also without changing the existing interface.
- Modifying the BMC dump infrastructure to support additional dumps.
- openpower-proc-control will be updated to call memory preserving chip-ops and
to handle memory preserving reboot on POWER platforms.
-- Additional system state to indicate the system is collecting debug data
- While performing memory preserving reboot.
-
+- Additional system state to indicate the system is collecting debug data While
+ performing memory preserving reboot.
## Testing
+
- Unit tests to make sure the dump manager interfaces are working.
-- Following integration tests will be executed to make sure the dump manager
-is working as expected.
- - Test creating host dumps and offloading it.
- - Test deleting host dumps
- - Create/List/Offload/Delete BMC dumps to make sure existing
- dump manager functions are not broken.
+- Following integration tests will be executed to make sure the dump manager is
+ working as expected. - Test creating host dumps and offloading it. - Test
+ deleting host dumps - Create/List/Offload/Delete BMC dumps to make sure
+ existing dump manager functions are not broken.
- Automated tests for dump Create/List/Offload/Delete to avoid regression.
diff --git a/designs/ecc-dbus-sel.md b/designs/ecc-dbus-sel.md
index 22dee88..bc1db98 100644
--- a/designs/ecc-dbus-sel.md
+++ b/designs/ecc-dbus-sel.md
@@ -30,12 +30,11 @@
#### 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 ECC D-Bus information will be added to the OpenBMC project and an ECC
-monitor service will be created to fetch the ECC count (ce_count/ue_count) from
-the EDAC 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.
+there is no relevant ECC information in the OpenBMC D-Bus architecture. The new
+ECC D-Bus information will be added to the OpenBMC project and an ECC monitor
+service will be created to fetch the ECC count (ce_count/ue_count) from the EDAC
+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
@@ -44,8 +43,8 @@
detection and correction of memory errors, which helps identify problems before
they become catastrophic faulty memory module.
-Many ECC memory systems use an "external" EDAC between the CPU and the memory
-to fix memory error. Most host integrate EDAC into the CPU's integrated memory
+Many ECC memory systems use an "external" EDAC between the CPU and the memory to
+fix memory error. Most host integrate EDAC into the CPU's integrated memory
controller.
According to Section 42.2 of the IPMI specification, Table 42 [2], these SEL
@@ -77,17 +76,14 @@
It also provide the following path on D-Bus:
-- bus name : `xyz.openbmc_project.Memory.ECC`
+- bus name : `xyz.openbmc_project.Memory.ECC`
- object path : `/xyz/openbmc_project/metrics/memory/BmcECC`
-- interface : `xyz.openbmc_project.Memory.MemoryECC`
+- interface : `xyz.openbmc_project.Memory.MemoryECC`
-The interface with the following properties:
-| Property | Type | Description |
-| -------- | ---- | ----------- |
-| isLoggingLimitReached | bool | ECC logging reach limits|
-| ceCount| int64 | correctable ECC events |
-| ueCount| int64 | uncorrectable ECC events |
-| state| string | bmc ECC event state |
+The interface with the following properties: | Property | Type | Description | |
+-------- | ---- | ----------- | | isLoggingLimitReached | bool | ECC logging
+reach limits| | ceCount| int64 | correctable ECC events | | ueCount| int64 |
+uncorrectable ECC events | | state| string | bmc ECC event state |
The error types for `xyz::openbmc_project::Memory::Ecc::Error::ceCount` and
`ueCount` and `isLoggingLimitReached` will be created which generated the error
@@ -100,25 +96,24 @@
- correctable ECC log : when fetching the `ce_count` from EDAC driver parameter
and the count exceeds previous count.
-- uncorrectable ECC log : when fetching the `ue_count` from EDAC driver parameter
- and the count exceeds previous count.
+- uncorrectable ECC log : when fetching the `ue_count` from EDAC driver
+ parameter and the count exceeds previous count.
- logging limit reached log : When the correctable ECC log reaches the
`maximum quantity`.
#### 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.
+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
-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.
+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
-Depending on the platform hardware design, this test requires an ECC
-driver to make fake ECC errors and then check the scenario is good.
+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/error-log-handling-for-phal.md b/designs/error-log-handling-for-phal.md
index 573f828..32c7000 100644
--- a/designs/error-log-handling-for-phal.md
+++ b/designs/error-log-handling-for-phal.md
@@ -1,49 +1,50 @@
# 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
+Other contributors: None
-Created:
-14/01/2020
+Created: 14/01/2020
## Problem Description
-Proposal to provide a mechanism to convert the failure data captured as part
-of power Hardware Abstraction Layer(pHAL) library calls to
-[Platform Event Log][1] (PEL) format.
+
+Proposal to provide a mechanism to convert the failure data captured as part of
+power Hardware Abstraction Layer(pHAL) library calls to [Platform Event Log][1]
+(PEL) format.
## Background and References
-OpenBmc Applications use the pHAL layer for hardware access and hardware
-initialization, any software/hardware error returned by the pHAL layer need
-to be converted to PEL format for logging the error entry. PEL helps to
-improve the firmware and platform serviceability during product development,
-manufacturing and in customer environment.
-Error data includes register data, targets to [guard][2] and callout.
-Guard refers to the action of "guarding" faulty hardware from impacting
-future system operation. Callout points to a specific hardware with in the
-server that relates to the identified error.
+OpenBmc Applications use the pHAL layer for hardware access and hardware
+initialization, any software/hardware error returned by the pHAL layer need to
+be converted to PEL format for logging the error entry. PEL helps to improve the
+firmware and platform serviceability during product development, manufacturing
+and in customer environment.
+
+Error data includes register data, targets to [guard][2] and callout. Guard
+refers to the action of "guarding" faulty hardware from impacting future system
+operation. Callout points to a specific hardware with in the server that relates
+to the identified error.
[Phosphor-logging][3] [Create][4] interface is used for creating PELs.
-pHAL layer constitutes below libraries and and these libraries return
-different return codes.
+pHAL layer constitutes below libraries and and these libraries return different
+return codes.
+
1. libipl used for initial program load
2. libfdt for device tree access
3. libekb for hardware procedure execution
4. libpdbg for hardware access
Proposal is to structure the return data to a standard return code format so
-that the caller can just handle the single return code format for conversion
-to PEL.
+that the caller can just handle the single return code format for conversion to
+PEL.
### Glossary
-pHAL: power Hardware Abstraction Layer. pHAL is group of libraries running
-in BMC. These libraries are used by Open Power specific application for
-hardware complex interactions, hostboot and Self Boot Engine initialization,
-diagnostics and debugging.
+
+pHAL: power Hardware Abstraction Layer. pHAL is group of libraries running in
+BMC. These libraries are used by Open Power specific application for hardware
+complex interactions, hostboot and Self Boot Engine initialization, diagnostics
+and debugging.
libfdt: pHAL uses to construct the in-memory tree structure of all targets.
[Reference][5]
@@ -51,12 +52,12 @@
libpdbg: library to allow debugging of the host POWER processors from the BMC
[Reference][6]
-MRW: Machine readable workbook. An XML description of a machine as specified
-by the system owner.
+MRW: Machine readable workbook. An XML description of a machine as specified by
+the system owner.
-HWP: Hardware procedure. A "black box" code module supplied by the hardware
-team that initializes host processor and memory subsystems in a platform
--independent fashion.
+HWP: Hardware procedure. A "black box" code module supplied by the hardware team
+that initializes host processor and memory subsystems in a platform -independent
+fashion.
Device Tree: A device tree is a data structure describing the hardware
components of a particular computer so that the operating system's kernel can
@@ -69,90 +70,109 @@
PEL: [Platform Entity Log][1]
## Requirement
+
### libekb
+
EKB library contains hardware procedures for the specific platform and the
corresponding error xml files for each hardware procedure. Error XML specifies
-attribute data, targets to callout, targets to guard, and targets to
-deconfigure for a specific error. Parsers in EKB library parse the error XML
-file and generate a c++ header file which is used by the hardware procedure
-in capturing the failure data.
+attribute data, targets to callout, targets to guard, and targets to deconfigure
+for a specific error. Parsers in EKB library parse the error XML file and
+generate a c++ header file which is used by the hardware procedure in capturing
+the failure data.
Add parser in libekb to parse the error XML file and provide methods that can
parse the failure data returned by the hardware procedure methods and return
data in key, value pairs so that the same can be used in the creation of PEL.
### libipl
+
Initial program load library used for booting the system. Library internally
calls hardware procedures (HWP) of EKB library. Hardware procedure execution
status need to be returned to the caller so that caller can create PEL on
hardware procedure execution failure.
### libpdbg
-libpdbg library is used for hardware access, any hardware access errors need
-to be captured as part of the PEL.
+libpdbg library is used for hardware access, any hardware access errors need to
+be captured as part of the PEL.
### Message Registry Entries
+
For errors to be raised in pHal corresponding error message registry entries
need to be created in the [message registry][8].
## Proposed design
+
### Hardware procedure failure
+
Add parser in libekb to parse the error XML file and provide methods that can
parse the failure data returned by the hardware procedure methods and return
data in key, value pairs so that the same can be used in the [Create][4]
interface for the creation of PEL.
-Inventory strings for the targets to Callout/Guard/Deconfig need to be added
-to the additional data section of the Create interface.
+Inventory strings for the targets to Callout/Guard/Deconfig need to be added to
+the additional data section of the Create interface.
Applications need to register callback methods in libekb library to get back the
error logging traces.
Debug traces returned through the callback method will be added to the PEL.
-
### libipl internal failure
+
Applications need to register callback methods in libipl library to get back the
error logging traces.
Debug traces returned through the callback method will be added to the PEL.
### libpdbg internal failure
+
Applications need to register callback methods to get the debug traces from
libpdbg library.
Debug traces returned through the callback method will be added to the PEL.
## Sequence diagrams
+
### Register for debug traces and boot errors
+
### Process debug traces
+
### Process boot failures
+
## Alternatives Considered
+
None
## Impacts
+
None
## Future changes
+
At present using [Create][4] by providing the data in std::map format the same
will be changed to JSON format when the corresponding support to pass JSON files
to the Create interface is added.
## Testing
+
1. Simulate hardware procedure failure and check if PEL is created.
-[1]: (https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/README.md)
-[2]: (https://gerrit.openbmc.org/#/c/openbmc/docs/+/27804/2/designs/gard_on_bmc.md)
+[1]:
+ (https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/README.md)
+[2]:
+ (https://gerrit.openbmc.org/#/c/openbmc/docs/+/27804/2/designs/gard_on_bmc.md)
[3]: (https://github.com/openbmc/phosphor-logging)
-[4]: (https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Logging/Create.interface.yaml)
+[4]:
+ (https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Logging/Create.interface.yaml)
[5]: (https://github.com/dgibson/dtc)
[6]: (https://github.com/open-power/pdbg)
[7]: (https://elinux.org/Device_Tree_Reference)
-[8]: (https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/registry/message_registry.json)
+[8]:
+ (https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/registry/message_registry.json)
diff --git a/designs/estoraged.md b/designs/estoraged.md
index 46e6637..fe95982 100644
--- a/designs/estoraged.md
+++ b/designs/estoraged.md
@@ -1,12 +1,9 @@
-
# eStoraged Design - Encrypted Secondary Storage Management Daemon
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
@@ -15,9 +12,9 @@
This daemon will serve as an abstraction for an encrypted storage device,
encapsulating the security functionality and providing a D-Bus interface to
manage the encrypted filesystem on the device. Using the D-Bus interface, other
-software components can interact with eStoraged to do things like create a
-new encrypted filesystem, wipe its contents, lock/unlock the device, or change
-the password.
+software components can interact with eStoraged to do things like create a new
+encrypted filesystem, wipe its contents, lock/unlock the device, or change the
+password.
## Background and References
@@ -38,7 +35,8 @@
additional security measure. This feature prohibits all read or write accesses
to the device while locked. Some documentation on this feature can be found in
the
-[JEDEC standard JESD84-B51A](https://www.jedec.org/document_search?search_api_views_fulltext=jesd84-b51), or in this document:
+[JEDEC standard JESD84-B51A](https://www.jedec.org/document_search?search_api_views_fulltext=jesd84-b51),
+or in this document:
[Enabling SD/uSD Card Lock/Unlock Feature in Linux](https://media-www.micron.com/-/media/client/global/documents/products/technical-note/sd-cards/tnsd01_enable_sd_lock_unlock_in_linux.pdf?rev=03f03a6bc0f8435fafa93a8fc8e88988).
There are several types of keys referenced in this doc:
@@ -52,6 +50,7 @@
## Requirements
This design should provide an interface for the following capabilities:
+
- Create a new LUKS encrypted filesystem on the device
- Securely wipe the device and verify that the data was wiped
- Lock the device
@@ -59,6 +58,7 @@
- Change the password
In addition, eStoraged should:
+
- Generate a volume key using a random number generator with enough entropy,
making it sufficiently random and secure.
- Utilize any security features provided by the hardware (as a defense-in-depth
@@ -67,21 +67,21 @@
support additional types of storage devices, as desired. For example,
different devices will have different command sets for device locking, e.g.
MMC, SATA, NVMe. Initially, we plan to only use eStoraged with eMMC devices,
- but we may wish to use this with other types of storage devices in the
- future.
+ but we may wish to use this with other types of storage devices in the future.
The users of this design can be any other software component in the BMC. Some
client daemon on the BMC will interact with eStoraged to set up a new encrypted
filesystem on the eMMC. In addition, the client daemon could be configured to
unlock the eMMC device when the BMC boots. It is the responsibility of the
-client daemon to provide a password. For example, this password could come
-from user input, fetched from a secure location, or the client daemon could
-generate the passwords itself.
+client daemon to provide a password. For example, this password could come from
+user input, fetched from a secure location, or the client daemon could generate
+the passwords itself.
## Proposed Design
-eStoraged will represent each eMMC device as an object on D-Bus that
-implements an interface providing these methods and properties:
+eStoraged will represent each eMMC device as an object on D-Bus that implements
+an interface providing these methods and properties:
+
- (method) Format
- (method) Erase
- (method) Lock
@@ -90,12 +90,12 @@
- (property) Locked
- (property) Status
-Upon startup, eStoraged will create a D-Bus object for each eMMC device in
-the system. Specifically, we will use udev to launch an eStoraged instance for
-each eMMC. The bus name and object name will be as follows:
+Upon startup, eStoraged will create a D-Bus object for each eMMC device in the
+system. Specifically, we will use udev to launch an eStoraged instance for each
+eMMC. The bus name and object name will be as follows:
-Bus Name: xyz.openbmc\_project.eStorage.\<device name\>
-Object Path: /xyz/openbmc\_project/storage/\<device name\>
+Bus Name: xyz.openbmc_project.eStorage.\<device name\> Object Path:
+/xyz/openbmc_project/storage/\<device name\>
The object path is intended to be generic enough, so that we could ultimately
have multiple daemons managing the same storage device, while using the same
@@ -106,9 +106,9 @@
[cryptsetup API](https://mbroz.fedorapeople.org/libcryptsetup_API/). This
library provides functions to create a new LUKS header, set the password, etc.
-For eMMC devices, we plan to enable the password locking feature (CMD42),
-to prevent all read or write accesses to the device while locked. So, the
-"Locked" property will mean both locked at the hardware level and locked at the
+For eMMC devices, we plan to enable the password locking feature (CMD42), to
+prevent all read or write accesses to the device while locked. So, the "Locked"
+property will mean both locked at the hardware level and locked at the
encryption level. We will likely use the ioctl interface to send the relevant
commands to the eMMC, similar to what
[mmc utils](https://git.kernel.org/pub/scm/utils/mmc/mmc-utils.git/) does.
@@ -117,11 +117,11 @@
but at the very least, encryption-only locking will be available, even if
hardware locking isn't supported for a particular device.
-As mentioned earlier, the client will provide a password. This password will
-be used by eStoraged to generate two different passwords: the encryption
-password and the device password (if hardware locking is available). The
-passwords will be different, so that in the event that one password is
-compromised, we still have some protection from the other password.
+As mentioned earlier, the client will provide a password. This password will be
+used by eStoraged to generate two different passwords: the encryption password
+and the device password (if hardware locking is available). The passwords will
+be different, so that in the event that one password is compromised, we still
+have some protection from the other password.
The Erase method should provide a way to specify the type of erase, e.g. write
all zeros, or do something else. Different organizations may have different
@@ -129,10 +129,11 @@
Since some of the D-Bus methods may take a while (e.g. installing a new
encrypted filesystem), the D-Bus interface will be asynchronous, with the
-"Status" property that can be queried to indicate one of the following:
-success, error, or in-progress.
+"Status" property that can be queried to indicate one of the following: success,
+error, or in-progress.
## Alternatives Considered
+
An alternative would be to use systemd targets to manage the eMMC. For example,
the
[systemd-cryptsetup@.service](https://www.freedesktop.org/software/systemd/man/systemd-cryptsetup@.service.html)
@@ -150,17 +151,18 @@
and ChangePassphrase. See the D-Bus interface
[org.freedesktop.UDisks2.Encrypted](http://storaged.org/doc/udisks2-api/2.7.5/gdbus-org.freedesktop.UDisks2.Encrypted.html).
The main problem preventing us from leveraging this tool is that it increases
-our image size too much. We found that the compressed image size increased by
-22 MB due to the transitive dependencies being pulled in, e.g. mozjs and
-python.
+our image size too much. We found that the compressed image size increased by 22
+MB due to the transitive dependencies being pulled in, e.g. mozjs and python.
## Impacts
+
To make use of eStoraged, it may be necessary to provide another client daemon
that manages the password and invokes the D-Bus API for eStoraged. Since the
password management scheme can be unique for different platforms and
organizations, it is outside the scope of this design.
## Testing
+
- Unit tests to validate the various code paths in eStoraged.
- Regression tests will exercise the various D-Bus methods: encrypt, erase,
lock, unlock, and change password.
diff --git a/designs/expired-password.md b/designs/expired-password.md
index 7328fb5..0b1de2a 100644
--- a/designs/expired-password.md
+++ b/designs/expired-password.md
@@ -1,262 +1,261 @@
# Initial expired passwords
-Author:
- Joseph Reynolds <josephreynolds1>
+Author: Joseph Reynolds <josephreynolds1>
-Other contributors:
- None
+Other contributors: None
-Created:
- 2019-07-24
+Created: 2019-07-24
## Problem Description
-OpenBMC has a default password, connects to the network via DHCP, and
-does not have a mechanism to require administrators to change the
-BMC's password. This may lead to BMCs which have default passwords
-being on the network for long time periods, effectively giving
-unrestricted access to the BMC.
+
+OpenBMC has a default password, connects to the network via DHCP, and does not
+have a mechanism to require administrators to change the BMC's password. This
+may lead to BMCs which have default passwords being on the network for long time
+periods, effectively giving unrestricted access to the BMC.
## Background and References
-Various computer systems ship with default userid and passwords and
-require the password be changed on the initial signon. This reduces
-the time window when the system is accessible with a default password.
-Various BMC interfaces require authentication before access is
-granted. The authentication and account validation steps typically
-result in outcomes like this:
-1. Success, when the access credentials (such as username and password)
- are correct and the account being accessed is valid.
-2. Failure, when either the access credentials are invalid or the
- account being accessed is invalid. For example, the account itself
- (not merely its password) may be expired.
-3. PasswordChangeRequired, when the access credentials are correct and
- the account is valid except the account's password is expired (such as
- indicated by PAM_CHANGE_EXPIRED_AUTHTOK).
+Various computer systems ship with default userid and passwords and require the
+password be changed on the initial signon. This reduces the time window when the
+system is accessible with a default password.
+
+Various BMC interfaces require authentication before access is granted. The
+authentication and account validation steps typically result in outcomes like
+this:
+
+1. Success, when the access credentials (such as username and password) are
+ correct and the account being accessed is valid.
+2. Failure, when either the access credentials are invalid or the account being
+ accessed is invalid. For example, the account itself (not merely its
+ password) may be expired.
+3. PasswordChangeRequired, when the access credentials are correct and the
+ account is valid except the account's password is expired (such as indicated
+ by PAM_CHANGE_EXPIRED_AUTHTOK).
OpenBMC currently implements the first two outcomes; it treats
-PasswordChangeRequired the same as an account that is invalid for any
-other reason. Some servers (such as the OpenSSH server) handle the
+PasswordChangeRequired the same as an account that is invalid for any other
+reason. Some servers (such as the OpenSSH server) handle the
PasswordChangeRequired by implementing a "password change dialog".
-The [Redfish Specification version 1.7.0][] section 13.2.6.1 ("Password
-change required handling") provides the ManagerAccount resource v1.3
-with a PasswordChangeRequired property which supports a password
-change dialog.
+The [Redfish Specification version 1.7.0][] section 13.2.6.1 ("Password change
+required handling") provides the ManagerAccount resource v1.3 with a
+PasswordChangeRequired property which supports a password change dialog.
-[Redfish Specification version 1.7.0]: https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf
+[redfish specification version 1.7.0]:
+ https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf
-Note the terminology:
-An "expired password" is a special case of "password change required".
+Note the terminology: An "expired password" is a special case of "password
+change required".
-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).
+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).
This design uses meanings 3 and 4 except where indicated.
## Requirements
+
The requirements are:
- - The BMC's initial password must be expired when the new
- EXPIRED_PASSWORD image feature is used.
- - An account with an expired password must not be allowed to use the
- BMC (except to change the password).
- - There must be a way to change the expired password using a
- supported interface.
+
+- The BMC's initial password must be expired when the new EXPIRED_PASSWORD image
+ feature is used.
+- An account with an expired password must not be allowed to use the BMC (except
+ to change the password).
+- There must be a way to change the expired password using a supported
+ interface.
The use case is:
- - The BMC automatically connects to its management network which
- offers administrative or operational interfaces (whether or not the
- BMC is normally operated via its host).
- - The BMC is operated from its management network.
+
+- The BMC automatically connects to its management network which offers
+ administrative or operational interfaces (whether or not the BMC is normally
+ operated via its host).
+- The BMC is operated from its management network.
Preconditions for the BMC include:
- - The BMC has at least one account with a default password built in.
- - The BMC can update the password; for example, the `/etc/passwd`
- file is writeable.
+
+- The BMC has at least one account with a default password built in.
+- The BMC can update the password; for example, the `/etc/passwd` file is
+ writeable.
## Proposed Design
+
This design has three main parts:
-1. There is a new image feature EXPIRED_PASSWORD. When
- EXPIRED_PASSWORD is enabled, the BMC's default password will
- initially be expired as if via the `passwd --expire root` command.
- This administratively expires the password and is not based on
- time. An account with an expired password is neither locked nor
- disabled.
+1. There is a new image feature EXPIRED_PASSWORD. When EXPIRED_PASSWORD is
+ enabled, the BMC's default password will initially be expired as if via the
+ `passwd --expire root` command. This administratively expires the password
+ and is not based on time. An account with an expired password is neither
+ locked nor disabled.
- This feature is intended to be enabled by default, with a staging
- plan: the feature will be disabled to give time for the continuous
- integration (CI) and test automation efforts to adapt, then enabled
- for the overall project.
+ This feature is intended to be enabled by default, with a staging plan: the
+ feature will be disabled to give time for the continuous integration (CI) and
+ test automation efforts to adapt, then enabled for the overall project.
-2. The BMC's network interfaces (such as REST APIs, SSH, and IPMI)
- disallow access via an account which has an expired password. If
- the access credentials are otherwise correct and the reason for the
- authentication failure is an expired password (determined by the
- usual Linux practices), where possible, the interface should
- indicate the password is expired and how to change it (see below).
- Otherwise the usual security protocols apply (giving no additional
- information).
+2. The BMC's network interfaces (such as REST APIs, SSH, and IPMI) disallow
+ access via an account which has an expired password. If the access
+ credentials are otherwise correct and the reason for the authentication
+ failure is an expired password (determined by the usual Linux practices),
+ where possible, the interface should indicate the password is expired and how
+ to change it (see below). Otherwise the usual security protocols apply
+ (giving no additional information).
- The `/login` URI is enhanced. If it is used with correct
- credentials (userid and password) and the password needs to be
- changed the request will fail to create a session and indicate a
- password change is needed. If it is used with correct userid and
- incorrect password, or with an incorrect userid, the behavior must
- not change. Note the `/login` URI is deprecated.
+ The `/login` URI is enhanced. If it is used with correct credentials (userid
+ and password) and the password needs to be changed the request will fail to
+ create a session and indicate a password change is needed. If it is used with
+ 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 indicate PasswordChangeRequired per the Redfish spec.
+ '/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 password. Note the RMCP+ standard, such as used for the
- BMC's network IPMI interface, does not support changing the
- password when establishing a session. The ipmitool is not being
- enhanced by this design.
+ The `ipmitool` command treats an expired password the same as an invalid
+ password. Note the RMCP+ standard, such as used for the BMC's network IPMI
+ interface, does not support changing the password when establishing a
+ session. The ipmitool is not being enhanced by this design.
- The Secure Shell access (via the `ssh` command) already correctly
- indicates when the password is expired. No change is needed. But
- see the next bullet for the expired password dialog.
+ The Secure Shell access (via the `ssh` command) already correctly indicates
+ when the password is expired. No change is needed. But see the next bullet
+ for the expired password dialog.
-3. There is a way for an account owner to change their own expired
- password. This can be either from a network-facing or in-band
- password changing protocol. For example:
- - Redfish: This design adds the Redfish PasswordChangeRequired
- handling to BMCWeb. See below for details.
- - SSH server: The SSH servers may have an expired password change
- dialog. For example, OpenSSH implement this feature. However,
- the Dropbear SSH server announces the password is expired, but
- does not implement the dialog to change it.
- - Access via the BMC's host: for example, via the `ipmitool user
- set password` command when accessed in-band.
+3. There is a way for an account owner to change their own expired password.
+ This can be either from a network-facing or in-band password changing
+ protocol. For example:
+ - Redfish: This design adds the Redfish PasswordChangeRequired handling to
+ BMCWeb. See below for details.
+ - SSH server: The SSH servers may have an expired password change dialog. For
+ example, OpenSSH implement this feature. However, the Dropbear SSH server
+ announces the password is expired, but does not implement the dialog to
+ change it.
+ - Access via the BMC's host: for example, via the
+ `ipmitool user set password` command when accessed in-band.
-When Redfish creates a session with PasswordChangeRequired, every
-response contains a PasswordChangeRequired message. The session
-effectively has only the 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.
+When Redfish creates a session with PasswordChangeRequired, every response
+contains a PasswordChangeRequired message. The session effectively has only the
+ConfigureSelf privilege which allows it to only change the password and
+terminate the session. The usage pattern is:
-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 as aging or via the `passwd --expire` command.
+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 enable the phosphor-webui web application
-to implement a password change dialog for the signon screen.
+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
+as aging or via the `passwd --expire` command.
+
+This design is intended to enable the phosphor-webui web application to
+implement a password change dialog for the signon screen.
Per the above design, when the web app uses either `/login` or
-`/redfish/v1/SessionService` to establish a session and the account
-has an expired password:
- - If the `/login` URI was used, the HTTP response indicates the
- password must be changed, and will not establish a session. In
- this case, the web app must use the Redfish API to establish a
- session.
- - POST to `/redfish/v1/SessionService/Sessions` will establish a
- session which will have the PasswordChangeRequired message.
- - At this point the web app can display a message that the password
- is expired and must be changed, then get the new password.
- - PATCH the password to the account specified in the
- PasswordChangeRequired message.
- - DELETE the Session object to terminate the session.
- - Create a new session and continue.
+`/redfish/v1/SessionService` to establish a session and the account has an
+expired password:
+
+- If the `/login` URI was used, the HTTP response indicates the password must be
+ changed, and will not establish a session. In this case, the web app must use
+ the Redfish API to establish a session.
+- POST to `/redfish/v1/SessionService/Sessions` will establish a session which
+ will have the PasswordChangeRequired message.
+- At this point the web app can display a message that the password is expired
+ and must be changed, then get the new password.
+- PATCH the password to the account specified in the PasswordChangeRequired
+ message.
+- DELETE the Session object to terminate the session.
+- Create a new session and continue.
## Alternatives Considered
+
The following alternate designs were considered:
-- Unique password per machine. That approach requires additional
- effort, for example, to set and track assigned passwords.
-- Default to having no users with access to the BMC via its network.
- When network access is needed, a technician would create or modify
- the userid to have network authority and establish a password at
- that time. This may be through the BMC's host system or via the
- BMC's serial console. That approach requires the tech to have
- access, and requires re-provisioning the account after factory reset
-- Disable network access by default. That approach requires another
- BMC access vector, such as physical access or via the BMC's host, to
- enable network access.
-- Provision the BMC with a certificate instead of a password, for
- example, an SSH client certificate. That approach suffers from the
- same limitations as a default password (when the matching private
- certificate becomes well known) and requires the BMC provide SSH
+
+- Unique password per machine. That approach requires additional effort, for
+ example, to set and track assigned passwords.
+- Default to having no users with access to the BMC via its network. When
+ network access is needed, a technician would create or modify the userid to
+ have network authority and establish a password at that time. This may be
+ through the BMC's host system or via the BMC's serial console. That approach
+ requires the tech to have access, and requires re-provisioning the account
+ after factory reset
+- Disable network access by default. That approach requires another BMC access
+ vector, such as physical access or via the BMC's host, to enable network
access.
-- Require physical presence to change the password. For example,
- applying a jumper, or signing in via a serial cable. That approach
- is not standard.
-- Have LDAP (or any authentication/authorization server) configured
- and have no local users which have default passwords configured in
- the BMC firmware image. That approach requires the customer have an
- LDAP (or similar) server. Also, how we can configure the LDAP, as
- we don't know the customer LDAP server configuration?
-- Have a new service to detect if any password has its default value,
- and write log messages for that condition, with the idea to alert
- the system owner of this condition. That approach doesn't solve the
- problem and burdens BMC resources.
+- Provision the BMC with a certificate instead of a password, for example, an
+ SSH client certificate. That approach suffers from the same limitations as a
+ default password (when the matching private certificate becomes well known)
+ and requires the BMC provide SSH access.
+- Require physical presence to change the password. For example, applying a
+ jumper, or signing in via a serial cable. That approach is not standard.
+- Have LDAP (or any authentication/authorization server) configured and have no
+ local users which have default passwords configured in the BMC firmware image.
+ That approach requires the customer have an LDAP (or similar) server. Also,
+ how we can configure the LDAP, as we don't know the customer LDAP server
+ configuration?
+- Have a new service to detect if any password has its default value, and write
+ log messages for that condition, with the idea to alert the system owner of
+ this condition. That approach doesn't solve the problem and burdens BMC
+ resources.
-Warning. This design may leave the BMC with its default password for
-an extended period of time if the use case given in the requirements
-section of this design does not apply. For example, when the host is
-operated strictly via its power button and not through the BMC's
-network interface. In this case, the alternatives listed above may
-mitigate this risk. Another alternative is a design where the BMC is
-initially in a provisioning mode which does not allow the BMC to
-operate its host. The idea is that you have to establish access to
-the BMC (which includes changing its password) before you can leave
-provisioning mode.
+Warning. This design may leave the BMC with its default password for an extended
+period of time if the use case given in the requirements section of this design
+does not apply. For example, when the host is operated strictly via its power
+button and not through the BMC's network interface. In this case, the
+alternatives listed above may mitigate this risk. Another alternative is a
+design where the BMC is initially in a provisioning mode which does not allow
+the BMC to operate its host. The idea is that you have to establish access to
+the BMC (which includes changing its password) before you can leave provisioning
+mode.
-The BMCWeb Redfish server could be enhanced so that when the Password
-is successfully patched, the session no longer asserts the
-PasswordChangeRequired condition and re-asserts the user's usual
-authority immediately without requiring a new session. This is
-allowed by the Redfish spec, but was not implemented because it would
-be more difficult to code and test.
+The BMCWeb Redfish server could be enhanced so that when the Password is
+successfully patched, the session no longer asserts the PasswordChangeRequired
+condition and re-asserts the user's usual authority immediately without
+requiring a new session. This is allowed by the Redfish spec, but was not
+implemented because it would be more difficult to code and test.
## Impacts
-Having to change an expired password is annoying and breaks
-operational procedures and scripts. Documentation, lifecycle review,
-and test are needed. Expect pain when this is enabled.
-To help with this, the [REDFISH-cheatsheet][] will be updated with
-commands needed to detect and change an expired password.
+Having to change an expired password is annoying and breaks operational
+procedures and scripts. Documentation, lifecycle review, and test are needed.
+Expect pain when this is enabled.
-[REDFISH-cheatsheet]: https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md
+To help with this, the [REDFISH-cheatsheet][] will be updated with commands
+needed to detect and change an expired password.
+
+[redfish-cheatsheet]:
+ https://github.com/openbmc/docs/blob/master/REDFISH-cheatsheet.md
This design does not affect other policies such as password aging.
## Testing
+
Scenarios:
+
1. Ensure that when the BMC is in its initial state:
- - All available network interfaces deny access.
- - Selected interfaces allow the password to be changed.
-2. Ensure factory reset resets the password to its initial expired
- state (repeat the tests above).
-3. Ensure the password change is effective for users entering from all
- supported interfaces. For example, change the password via the
- Redfish API, and validate that the old password does not work and
- the new password does work via IPMI for the same user.
-4. Handle BMC code update scenarios. For example, (A) Ensure code
- update does not cause a previously set password to change to
- default or to expire. (B) Validate what happens when the BMC has a
- default password and does code update to a release which has the
- default expired password design (this design).
-5. Ensure the BMC continues to operate its host, for example, when the
- BMC is factory reset while the host is running. Ensure the power
- button can be used to power off the host while the BMC's password is
- expired.
-6. Test on BMC using Linux PAM both with and without LDAP or
- ActiveDirectory configured.
-7. Validate you can to change an IPMI user's expired password, such as
- with: ipmitool user set password 1 NEWPASSWORD. This can be from
- another IPMI user's session or from unauthenticated access.
+ - All available network interfaces deny access.
+ - Selected interfaces allow the password to be changed.
+2. Ensure factory reset resets the password to its initial expired state (repeat
+ the tests above).
+3. Ensure the password change is effective for users entering from all supported
+ interfaces. For example, change the password via the Redfish API, and
+ validate that the old password does not work and the new password does work
+ via IPMI for the same user.
+4. Handle BMC code update scenarios. For example, (A) Ensure code update does
+ not cause a previously set password to change to default or to expire. (B)
+ Validate what happens when the BMC has a default password and does code
+ update to a release which has the default expired password design (this
+ design).
+5. Ensure the BMC continues to operate its host, for example, when the BMC is
+ factory reset while the host is running. Ensure the power button can be used
+ to power off the host while the BMC's password is expired.
+6. Test on BMC using Linux PAM both with and without LDAP or ActiveDirectory
+ configured.
+7. Validate you can to change an IPMI user's expired password, such as with:
+ ipmitool user set password 1 NEWPASSWORD. This can be from another IPMI
+ user's session or from unauthenticated access.
diff --git a/designs/external-sensor.md b/designs/external-sensor.md
index a9da1bc..832fe9a 100644
--- a/designs/external-sensor.md
+++ b/designs/external-sensor.md
@@ -18,30 +18,30 @@
There are 10 existing sensor daemons in _dbus-sensors_. Why add another sensor
daemon?
-* Most of the existing sensor daemons are tied to one particular physical
- quantity they are measuring, such as temperature, and are hardcoded as such.
- An externally-updated sensor has no such limitation, and should be flexible
- enough to measure any physical quantity currently supported by OpenBMC.
+- Most of the existing sensor daemons are tied to one particular physical
+ quantity they are measuring, such as temperature, and are hardcoded as such.
+ An externally-updated sensor has no such limitation, and should be flexible
+ enough to measure any physical quantity currently supported by OpenBMC.
-* 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 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 primary purpose for which they were designed.
+- 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
+ 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
+ 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 initialize itself and participate in the OpenBMC software stack.
+- 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
+ initialize itself and participate in the OpenBMC software stack.
-* For the same reason it is desirable for existing sensor daemons to detect
- and properly indicate failures of their underlying hardware, it is desirable
- for _ExternalSensor_ to detect and properly indicate loss of timely sensor
- updates from their external source. This is a new feature, and does not
- cleanly fit into the architecture of any existing sensor daemon, thus a new
- daemon is the correct choice for this behavior.
+- For the same reason it is desirable for existing sensor daemons to detect and
+ properly indicate failures of their underlying hardware, it is desirable for
+ _ExternalSensor_ to detect and properly indicate loss of timely sensor updates
+ from their external source. This is a new feature, and does not cleanly fit
+ 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
daemon in _dbus-sensors_.
@@ -116,46 +116,46 @@
optional. For fields listed as "Numeric" below, this means that it can be either
integer or valid floating-point.
-* "Name": String. The sensor name, which this sensor will be known as. A
- mandatory component of the `entity-manager` configuration, and the resulting
- D-Bus object path.
+- "Name": String. The sensor name, which this sensor will be known as. A
+ mandatory component of the `entity-manager` configuration, and the resulting
+ D-Bus object path.
-* "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
- mandatory component of the D-Bus object path.
+- "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
+ mandatory component of the D-Bus object path.
-* "MinValue": Numeric. The minimum valid value for this sensor. Although not
- used by _ExternalSensor_ directly, it is a valuable hint for services such
- as IPMI, which need to know the minimum and maximum valid sensor values in
- order to scale their reporting range accurately. As _ExternalSensor_ is not
- tied to one particular physical quantity, there is no suitable default value
- for minimum and maximum. Thus, unlike other sensor daemons where this
- parameter is optional, in _ExternalSensor_ it is mandatory.
+- "MinValue": Numeric. The minimum valid value for this sensor. Although not
+ used by _ExternalSensor_ directly, it is a valuable hint for services such as
+ IPMI, which need to know the minimum and maximum valid sensor values in order
+ to scale their reporting range accurately. As _ExternalSensor_ is not tied to
+ one particular physical quantity, there is no suitable default value for
+ minimum and maximum. Thus, unlike other sensor daemons where this parameter is
+ optional, in _ExternalSensor_ it is mandatory.
-* "MaxValue": Numeric. The maximum valid value for this sensor. It is treated
- similarly to "MinValue".
+- "MaxValue": Numeric. The maximum valid value for this sensor. It is treated
+ similarly to "MinValue".
-* "Timeout": Numeric. This parameter is unique to _ExternalSensor_. It is the
- timeout value, in seconds. If this amount of time elapses with no new
- updates received over D-Bus from the external source, this sensor will be
- deemed stale. The value of this sensor will be replaced with floating-point
- _NaN_, as described above. This field is optional. If not given, the timeout
- feature will be disabled for this sensor (so it will never be deemed stale).
+- "Timeout": Numeric. This parameter is unique to _ExternalSensor_. It is the
+ timeout value, in seconds. If this amount of time elapses with no new updates
+ received over D-Bus from the external source, this sensor will be deemed
+ stale. The value of this sensor will be replaced with floating-point _NaN_, as
+ described above. This field is optional. If not given, the timeout feature
+ will be disabled for this sensor (so it will never be deemed stale).
-* "Type": String. Must be exactly "ExternalSensor". This string is used by
- _ExternalSensor_ to obtain configuration information from _entity-manager_
- during initialization. This string is what differentiates JSON stanzas
- intended for _ExternalSensor_ versus JSON stanzas intended for other
- _dbus-sensors_ sensor daemons.
+- "Type": String. Must be exactly "ExternalSensor". This string is used by
+ _ExternalSensor_ to obtain configuration information from _entity-manager_
+ during initialization. This string is what differentiates JSON stanzas
+ intended for _ExternalSensor_ versus JSON stanzas intended for other
+ _dbus-sensors_ sensor daemons.
-* "Thresholds": JSON dictionary. This field is optional. It is passed through
- to the main _Sensor_ class during initialization, similar to other sensor
- daemons. Other than that, it is not used by _ExternalSensor_.
+- "Thresholds": JSON dictionary. This field is optional. It is passed through to
+ the main _Sensor_ class during initialization, similar to other sensor
+ daemons. Other than that, it is not used by _ExternalSensor_.
-* "PowerState": String. This field is optional. Similarly to "Thresholds", it
- is passed through to the main _Sensor_ class during initialization.
+- "PowerState": String. This field is optional. Similarly to "Thresholds", it is
+ passed through to the main _Sensor_ class during initialization.
Here is an example. The sensor created by this stanza will form this object
path: /xyz/openbmc_project/sensors/temperature/HostDevTemp
@@ -221,15 +221,25 @@
[^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
+[^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
+[^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
+[^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
+[^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
diff --git a/designs/fail-boot-on-hw-error.md b/designs/fail-boot-on-hw-error.md
index 319c537..db66677 100644
--- a/designs/fail-boot-on-hw-error.md
+++ b/designs/fail-boot-on-hw-error.md
@@ -4,10 +4,10 @@
Other contributors:
-Created: Feb 20, 2020
-Updated: Apr 12, 2022
+Created: Feb 20, 2020 Updated: Apr 12, 2022
## Problem Description
+
Some groups, for example a manufacturing team, have a requirement for the BMC
firmware to halt a system if an error log is created which calls out a piece of
hardware. The reason behind this is to ensure a system is not shipped to a
@@ -20,25 +20,27 @@
OpenBMC firmware needs a mechanism to support this use case.
## Background and References
+
Within IBM, this function has been enabled/disabled by what is called
manufacturing flags. They were bits the user could set in registry variables
-which the firmware would then query. These registry variables were only
-settable by someone with admin authority to the system. These flags were not
-used outside of manufacturing and test.
+which the firmware would then query. These registry variables were only settable
+by someone with admin authority to the system. These flags were not used outside
+of manufacturing and test.
Extensions within phosphor-logging may process logs that do not always come
-through the standard phosphor-logging interfaces (for example logs sent
-down by the host). In these cases the system must still halt if those logs
-contain hardware callouts.
+through the standard phosphor-logging interfaces (for example logs sent down by
+the host). In these cases the system must still halt if those logs contain
+hardware callouts.
[This][1] email thread was sent on this topic to the list.
## Requirements
+
- Provide a mechanism to cause the OpenBMC firmware to halt a system if a
phosphor-logging log is created with a inventory callout
- - The mechanism to enable/disable this feature does not need to be an
- external API (i.e. Redfish). It can simply be a busctl command one runs
- in an ssh to the BMC
+ - The mechanism to enable/disable this feature does not need to be an external
+ API (i.e. Redfish). It can simply be a busctl command one runs in an ssh to
+ the BMC
- The halt must be obvious to the user when it occurs
- The log which causes the halt must be identifiable
- The halt must only stop the chassis/host instance that encountered the error
@@ -47,20 +49,21 @@
- 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 that caused the halt is resolved or deleted
- - A BMC reset will clear this power on prevention
+ - The chassis/host instance pair will not be allowed to power on until the log
+ that caused the halt is resolved or deleted
+ - A BMC reset will clear this power on prevention
- Ensure the mechanism used to halt firmware on inventory callouts can also be
utilized by phosphor-logging extensions to halt firmware for other causes
- These causes will be defined within the extensions documentation
- Quiesce the associated host during this failure
-**Special Note:** Initially the associated host and chassis will be hard coded to
-chassis0 and host0. More work throughout the BMC stack is required to handle
+**Special Note:** Initially the associated host and chassis will be hard coded
+to chassis0 and host0. More work throughout the BMC stack is required to handle
multiple chassis and hosts. This design allows that type of feature to be
enabled at a later time.
## Proposed Design
+
Create a [phosphor-settingsd][2] setting,
`xyz.openbmc_project.Logging.Settings`. Within this create a boolean property
called QuiesceOnHwError. This property will be hosted under the
@@ -79,25 +82,25 @@
`xyz.openbmc_project.Logging.Settings.QuiesceOnHwError`. If this is true then
phosphor-logging will create a `/xyz/openbmc_project/logging/blockX` D-Bus
object with a `xyz.openbmc_project.Logging.ErrorBlocksTransition` interface
-under it. A mapper [association][3] between the log and this new D-Bus
-object will be created. The corresponding host instance will be put
-in quiesce by phosphor-logging.
+under it. A mapper [association][3] between the log and this new D-Bus object
+will be created. The corresponding host instance will be put in quiesce by
+phosphor-logging.
The blocked state can be exited by rebooting the BMC or clearing the log
-responsible for the blocking. Other system specific policies could be placed
-in the appropriate targets (for example if a chassis power off should clear
-the block)
+responsible for the blocking. Other system specific policies could be placed in
+the appropriate targets (for example if a chassis power off should clear the
+block)
See the phosphor-logging [callout][4] design for more information on callouts.
-A new `obmc-host-graceful-quiesce@.target` systemd target will be started.
-This new target will ensure a graceful shutdown of the host is initated
-and then start the `obmc-host-quiesce@.target` which will stop the host
-and move the host state to Quiesced.
+A new `obmc-host-graceful-quiesce@.target` systemd target will be started. This
+new target will ensure a graceful shutdown of the host is initated and then
+start the `obmc-host-quiesce@.target` which will stop the host and move the host
+state to Quiesced.
-obmcutil will be enhanced to look for these block interfaces and notify the
-user via the `obmcutil state` command if a block is enabled and what log
-is associated with it.
+obmcutil will be enhanced to look for these block interfaces and notify the user
+via the `obmcutil state` command if a block is enabled and what log is
+associated with it.
The goal is to build upon this concept when future design work is done to allow
developers to associate certain error logs with causing a halt to the system
@@ -105,21 +108,23 @@
## Host Errors
-In certain scenarios, it is desirable to also halt the boot, and prevent it
-from rebooting, when the host sends down certain errors to the BMC.
+In certain scenarios, it is desirable to also halt the boot, and prevent it from
+rebooting, when the host sends down certain errors to the BMC.
-These errors may be of SEL format, or may be OEM specific, such as the
-[PEL format][5] used by IBM.
+These errors may be of SEL format, or may be OEM specific, such as the [PEL
+format][5] used by IBM.
The interfaces provided within phosphor-logging to handle the hardware callout
scenarios can be repurposed for this use case.
## Alternatives Considered
-Currently this feature is a part of the base phosphor-logging design. If no
-one other then IBM sees value, we could roll this into the PEL-specific
-portion of phosphor-logging.
+
+Currently this feature is a part of the base phosphor-logging design. If no one
+other then IBM sees value, we could roll this into the PEL-specific portion of
+phosphor-logging.
## Impacts
+
This will require some additional checking on reported logs but should have
minimal overhead.
@@ -127,15 +132,18 @@
setting.
## Testing
+
Unit tests will be run to ensure logic to detect errors with logs and verify
both possible values of the new setting.
Test cases will need to look for this new blocking D-Bus object and handle
appropriately.
-
[1]: https://lists.ozlabs.org/pipermail/openbmc/2020-February/020575.html
[2]: https://github.com/openbmc/phosphor-settingsd
-[3]: https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
-[4]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Common/Callout/README.md
-[5]: https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/README.md
+[3]:
+ https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md#associations
+[4]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Common/Callout/README.md
+[5]:
+ https://github.com/openbmc/phosphor-logging/blob/master/extensions/openpower-pels/README.md
diff --git a/designs/firmware-update-via-blobs.md b/designs/firmware-update-via-blobs.md
index fe8a3b6..f786452 100644
--- a/designs/firmware-update-via-blobs.md
+++ b/designs/firmware-update-via-blobs.md
@@ -36,26 +36,25 @@
The following statements are reflective of the initial requirements.
-* Any update mechanism must provide support for UBI tarballs and legacy
- (static layout) flash images. Leveraging the BLOB protocol allows a system
- to provide support for any image type simply by implementing a mechanism for
- handling it.
+- Any update mechanism must provide support for UBI tarballs and legacy (static
+ layout) flash images. Leveraging the BLOB protocol allows a system to provide
+ support for any image type simply by implementing a mechanism for handling it.
-* Any update mechanism must allow for triggering an image verification step
- before the image is used.
+- Any update mechanism must allow for triggering an image verification step
+ before the image is used.
-* Any update mechanism must allow implementing the data staging via different
- in-band mechanisms.
+- Any update mechanism must allow implementing the data staging via different
+ in-band mechanisms.
-* Any update mechanism must provide a handshake or equivalent protocol for
- coordinating the data transfer. For instance, whether the BMC should enable
- the P2A bridge and what region to use or whether to turn on the LPC memory
- map bridge.
+- Any update mechanism must provide a handshake or equivalent protocol for
+ coordinating the data transfer. For instance, whether the BMC should enable
+ the P2A bridge and what region to use or whether to turn on the LPC memory map
+ bridge.
-* Any update mechanism must attempt to maintain security, insomuch as not
- leaving a memory region open by default. For example, before starting the
- verification step, access to the staged firmware image must not be still
- accessible from the host.
+- Any update mechanism must attempt to maintain security, insomuch as not
+ leaving a memory region open by default. For example, before starting the
+ verification step, access to the staged firmware image must not be still
+ accessible from the host.
## Proposed Design
@@ -86,11 +85,11 @@
The blob ids for the mechanisms will be as follows:
-Flash Blob Id | Type
----------------- | -------------
-`/flash/image` | Static Layout
-`/flash/tarball` | UBI
-`/flash/bios` | Host BIOS image
+| Flash Blob Id | Type |
+| ---------------- | --------------- |
+| `/flash/image` | Static Layout |
+| `/flash/tarball` | UBI |
+| `/flash/bios` | Host BIOS image |
The flash handler will determine what commands it should expect to receive and
responses it will return given the blob opened, based on the flags provided to
@@ -103,9 +102,9 @@
The following blob ids are defined for storing the hash for the image:
-Hash Blob | Id Mechanism
-------------- | --------------------
-`/flash/hash` | Whichever flash blob was opened
+| Hash Blob | Id Mechanism |
+| ------------- | ------------------------------- |
+| `/flash/hash` | Whichever flash blob was opened |
The flash handler will only allow one open file at a time, such that if the host
attempts to send a firmware image down over IPMI BlockTransfer, it won't allow
@@ -125,9 +124,9 @@
the BmcBlobOpen command will fail until both the hash and image file are closed.
Further on the ideal command sequence below.
-Trigger Blob | Note
---------------- | ------------------------
-`/flash/verify` | Verify Trigger Mechanism
+| Trigger Blob | Note |
+| --------------- | ------------------------ |
+| `/flash/verify` | Verify Trigger Mechanism |
When the verification file is closed, if verification was completed
successfully, it'll add an update blob id, defined below.
@@ -136,41 +135,41 @@
#### Update Blob
-The update blob id is available once `/flash/verify` is closed with a valid image
-or tarball. The update blob needs to be opened and commit() called on that blob
-id to trigger the update mechanism.
+The update blob id is available once `/flash/verify` is closed with a valid
+image or tarball. The update blob needs to be opened and commit() called on that
+blob id to trigger the update mechanism.
The update process can be checked periodically by calling stat() on the update
blob id.
-Update Blob | Note
---------------- | ------------------------
-`/flash/update` | Trigger Update Mechanism
+| Update Blob | Note |
+| --------------- | ------------------------ |
+| `/flash/update` | Trigger Update Mechanism |
The update process used is not defined by this design.
#### Cleanup Blob
-The cleanup blob id is always present. The goal of this blob is to handle
-deletion of update artifacts on failure, or success. It can be implemented to
-do any manner of cleanup required, but for systems under memory pressure, it is
-a convenient cleanup mechanism.
+The cleanup blob id is always present. The goal of this blob is to handle
+deletion of update artifacts on failure, or success. It can be implemented to do
+any manner of cleanup required, but for systems under memory pressure, it is a
+convenient cleanup mechanism.
The cleanup blob has no state or knowledge and is meant to provide a simple
-system cleanup mechanism. This could also be accomplished by warm rebooting
-the BMC. The cleanup blob will delete a list of files. The cleanup blob has
-no state recognition for the update process, and therefore can interfere with
-an update process. The host tool will only use it on failure cases. Any other
-tool developed should respect this and not employ it unless the goal is to
-cleanup artifacts.
+system cleanup mechanism. This could also be accomplished by warm rebooting the
+BMC. The cleanup blob will delete a list of files. The cleanup blob has no state
+recognition for the update process, and therefore can interfere with an update
+process. The host tool will only use it on failure cases. Any other tool
+developed should respect this and not employ it unless the goal is to cleanup
+artifacts.
-To trigger the cleanup, simply open the blob, commit, and close. It has no
-knowledge of the update process. This simplification is done through the
-design of a convenience mechanism instead of a required mechanism.
+To trigger the cleanup, simply open the blob, commit, and close. It has no
+knowledge of the update process. This simplification is done through the design
+of a convenience mechanism instead of a required mechanism.
-Cleanup Blob | Note
----------------- | -------------------------
-`/flash/cleanup` | Trigger Cleanup Mechanism
+| Cleanup Blob | Note |
+| ---------------- | ------------------------- |
+| `/flash/cleanup` | Trigger Cleanup Mechanism |
### Caching Images
@@ -292,7 +291,7 @@
in progress. Closing the file does not delete the staged images. Only delete
will.
-***Note*** The active image blob_ids cannot be opened. This can be reconsidered
+**_Note_** The active image blob_ids cannot be opened. This can be reconsidered
later.
#### BmcBlobRead
@@ -364,7 +363,7 @@
If the image verification fails, it will automatically delete any files
associated with the update.
-***Note:*** During development testing, a developer will want to upload files
+**_Note:_** During development testing, a developer will want to upload files
that are not signed. Therefore, an additional bit will be added to the flags to
change this behavior.
diff --git a/designs/firmware-update-via-usb.md b/designs/firmware-update-via-usb.md
index 147c923..a25bbd0 100644
--- a/designs/firmware-update-via-usb.md
+++ b/designs/firmware-update-via-usb.md
@@ -22,75 +22,76 @@
## Requirements
The following statements are reflective of the initial requirements.
- * Monitor whether the USB key is inserted.
- * The first tar file found in the sorted list of files on the USB device is
-copied to `/tmp/images`.
- * Manually trigger firmware upgrade.
- * Disable automatic reboot the BMC firmware after upgrade is complete to
-prevent a potential loop in the event of a key inserted.
- * This mechanism attempts to maintain security, for example this feature is
-disabled by default or can be enabled or disabled via Redfish.
+
+- Monitor whether the USB key is inserted.
+- The first tar file found in the sorted list of files on the USB device is
+ copied to `/tmp/images`.
+- Manually trigger firmware upgrade.
+- Disable automatic reboot the BMC firmware after upgrade is complete to prevent
+ a potential loop in the event of a key inserted.
+- This mechanism attempts to maintain security, for example this feature is
+ disabled by default or can be enabled or disabled via Redfish.
## Proposed Design
-The new code would be part of the phosphor-software-manager
-repository(eg: phosphor-usb-code-update).
-The design process is as follows:
- - Define a macro switch (`usb-code-update`) in [phosphor-software-manager][1]
-repository to identify whether to enable the USB Code Update function,
-which is _enabled_ by default.
- - If `usb-code-update` enabled, install the udev rules file to
-`/lib/udev/rules.d` during compilation.
- - Once the udev rules are met, the systemd service is directly triggered and
-start the phosphor-usb-code-update daemon.
- - This daemon verifies the `/run/media/usb/sda1` directory and copies
-the first `.tar` file in the directory to `/tmp/images` and starts
-verification.
- - Set ApplyTime to OnReset so that the proposed usb code update app does not
-reboot the BMC after activation.
- - Set RequestedActivation to Active, follow the updated status, start to
-update the firmware, and restart the BMC after completion.
- - Exit the phosphor-usb-code-update daemon.
+The new code would be part of the phosphor-software-manager repository(eg:
+phosphor-usb-code-update). The design process is as follows:
+
+- Define a macro switch (`usb-code-update`) in [phosphor-software-manager][1]
+ repository to identify whether to enable the USB Code Update function, which
+ is _enabled_ by default.
+- If `usb-code-update` enabled, install the udev rules file to
+ `/lib/udev/rules.d` during compilation.
+- Once the udev rules are met, the systemd service is directly triggered and
+ start the phosphor-usb-code-update daemon.
+- This daemon verifies the `/run/media/usb/sda1` directory and copies the first
+ `.tar` file in the directory to `/tmp/images` and starts verification.
+- Set ApplyTime to OnReset so that the proposed usb code update app does not
+ reboot the BMC after activation.
+- Set RequestedActivation to Active, follow the updated status, start to update
+ the firmware, and restart the BMC after completion.
+- Exit the phosphor-usb-code-update daemon.
## Pseudocode
The udev rules files for example:
+
```
SUBSYSTEM=="block", ACTION=="add", ENV{ID_USB_DRIVER}=="usb-storage", ENV{DEVTYPE}=="partition", ENV{SYSTEMD_WANTS}="usb-code-update@%k", TAG+="systemd"
```
## Security
- - It is recommended to run a local CI run and analyze & avoid potential
-vulnerabilities via cppcheck.
- - Assuming that the USB drive has a physical security vulnerability
-(such as memory overflow, etc.), should disable "USB code update" via Redfish.
-After the vulnerability is fixed, enable "USB code update" again via Redfish.
+- It is recommended to run a local CI run and analyze & avoid potential
+ vulnerabilities via cppcheck.
+- Assuming that the USB drive has a physical security vulnerability (such as
+ memory overflow, etc.), should disable "USB code update" via Redfish. After
+ the vulnerability is fixed, enable "USB code update" again via Redfish.
## Alternatives Considered
If the OS fails to boot due to an error, so the firmware update cannot be done
through the OS, or the network fails, and the update cannot be done through
Redfish or scp, the server support staff can only uninstall the flash chip and
-re-flashing, this is not Reasonably, service support should have local access
-to the machine and update the system to a working firmware level.
+re-flashing, this is not Reasonably, service support should have local access to
+the machine and update the system to a working firmware level.
## Impacts
This impacts security because it can copy files to the BMC via an external USB
-key. There is no expected performance impact since the process just copies
-files during runtime and exits automatically after completion.
+key. There is no expected performance impact since the process just copies files
+during runtime and exits automatically after completion.
## Testing
- - When the USB code update is disabled, the service will return directly
-without any update.
- - Manually insert the USB key with the firmware upgrade package, and check
-whether the upgrade file is correct through the log.
- - Simulate `dev/sda1` on qemu with some test scripts and start the
-service(eg: `systemcl start usb-code-update@sda1.service`)
- - Verify that the ApplyTime attribute value is set to OnRest.
- - Verify that the RequestedActivation property value is set to Active.
- - Verify that the firmware update was successful.
+- When the USB code update is disabled, the service will return directly without
+ any update.
+- Manually insert the USB key with the firmware upgrade package, and check
+ whether the upgrade file is correct through the log.
+- Simulate `dev/sda1` on qemu with some test scripts and start the service(eg:
+ `systemcl start usb-code-update@sda1.service`)
+- Verify that the ApplyTime attribute value is set to OnRest.
+- Verify that the RequestedActivation property value is set to Active.
+- Verify that the firmware update was successful.
[1]: https://github.com/openbmc/phosphor-bmc-code-mgmt
diff --git a/designs/gpio-based-cable-presence.md b/designs/gpio-based-cable-presence.md
index 53372f0..8763a5f 100644
--- a/designs/gpio-based-cable-presence.md
+++ b/designs/gpio-based-cable-presence.md
@@ -1,11 +1,11 @@
## GPIO-based Cable Presence Detection
-Author:
- Chu Lin (linchuyuan@google.com)
-Created:
- 2021-07-29
+Author: Chu Lin (linchuyuan@google.com)
+
+Created: 2021-07-29
## Problem Description
+
The intent of this new daemon design is to report GPIO-based cable presence
status. IPMI currently doesn't support grouping discrete values and it could at
most support 255 sensor IDs. On a systems with 25 cables, and 255 sensor IDs,
@@ -14,19 +14,23 @@
less SDR IDs.
## 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
## Requirements
+
1. The openbmc IPMI interface should support exposing cable presence states.
2. The OpenBMC dbus interface should be compatible with redfish
## Proposed Design
+
Inventory.Item.Cable will be introduced as a new dbus interface for querying
cable objects. We will also need to introduce a new dbus daemon to collect
Presence states. This new daemon will resIDe in openbmc/dbus-sensors. Its
runtime configuration will be provIDed by EntityManager during startup. A
proposed config file looks like the following:
+
```
{
"Exposes": [
@@ -51,18 +55,20 @@
]
}
```
-The `Name` attribute is a unique name for each object from the config file.
-The `GpioLine` is the gpio line label from the device tree. The `Polarity`
-should tell the daemon whether it needs to revert the GPIO signal. Each entry
-from the config would get translated into one object on the dbus. In addition,
-the daemon polls the gpio presence signal for these objects in an interval of
-10 seconds. When the cable is not properly seated, the daemon will assert on
-the corresponding fault led group. This should cause the corresponding led to
-blink or to turn on base on how phosphor-led-manager is configured. No action
-is taken if FaultLedGroup is empty.
+
+The `Name` attribute is a unique name for each object from the config file. The
+`GpioLine` is the gpio line label from the device tree. The `Polarity` should
+tell the daemon whether it needs to revert the GPIO signal. Each entry from the
+config would get translated into one object on the dbus. In addition, the daemon
+polls the gpio presence signal for these objects in an interval of 10 seconds.
+When the cable is not properly seated, the daemon will assert on the
+corresponding fault led group. This should cause the corresponding led to blink
+or to turn on base on how phosphor-led-manager is configured. No action is taken
+if FaultLedGroup is empty.
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,
+
```
└─/xyz
└─/xyz/openbmc_project
@@ -71,18 +77,20 @@
└─/xyz/openbmc_project/inventory/item/cable0
└─/xyz/openbmc_project/inventory/item/cable1
```
+
In this example, we have both cable0 and cable1 and we expect to group them
-together. The grouping handler first removes all the trailing index from the
-SDR name. In this case, the SDR name is cable0 and cable1. After that, both
-cable0 and cable1 become cable. Therefore, objects with the same name after
-removing the trailing index indicates that they need to be grouped. After
-grouping, the new SDR name is cable[0-1]. The SDR name implies that this SDR
-has the presence state for cable0 and cable1. Meanwhile, the bit position
-for cable0 is 0 and the bit position for cable1 is 1. In the case of having
-more than 14 presence states, the group handler will automatically jump to use
-a new SDR. For example, if there are 20 cable indexed from 0 to 19, we
-shall see two SDRs. One is cable0-13. One is cable[14-19]. If the object path
-is not indexed by the user, it will take one SDR ID.
+together. The grouping handler first removes all the trailing index from the SDR
+name. In this case, the SDR name is cable0 and cable1. After that, both cable0
+and cable1 become cable. Therefore, objects with the same name after removing
+the trailing index indicates that they need to be grouped. After grouping, the
+new SDR name is cable[0-1]. The SDR name implies that this SDR has the presence
+state for cable0 and cable1. Meanwhile, the bit position for cable0 is 0 and the
+bit position for cable1 is 1. In the case of having more than 14 presence
+states, the group handler will automatically jump to use a new SDR. For example,
+if there are 20 cable indexed from 0 to 19, we shall see two SDRs. One is
+cable0-13. One is cable[14-19]. If the object path is not indexed by the user,
+it will take one SDR ID.
+
```
ipmitool sdr list event
# /xyz/openbmc_project/inventory/item/cdfp0 to
@@ -95,8 +103,9 @@
On the other hand, if the object name from the config file is not indexed. For
example, `/xyz/openbmc_project/inventory/item/cable`. The group handler will not
-try to group it with anything and use 1 SDR ID for its presence state.
-See the following for an example output.
+try to group it with anything and use 1 SDR ID for its presence state. See the
+following for an example output.
+
```
ipmitool sdr list event
cdfp[0-3] | Event-Only | ns
@@ -104,6 +113,7 @@
osfp | Event-Only | ns
osfp[1-2] | Event-Only | ns
```
+
During the fetch operation, once the ipmi daemon receives the client request. It
forwards the request to the dynamic ipmi commands. In the get method, the range
string is extracted from the tailing square bracket. The original dbus path can
@@ -111,52 +121,52 @@
constructed after collecting the OperationalStatus from the dbus from each
individual dbus objects.
-The design is also compatible with the Redfish daemon. Redfish can call the
+The design is also compatible with the Redfish daemon. Redfish can call the
GetSubTree method to list all the instances under the cable interface. In
addition, Redfish doesn't have a limit of 256 SDR IDs. Therefore, no need to
implement grouping mechanism. It should work out of the box.
## Alternatives Considered
-* Explore the option of reporting the presence state via type12 record instead
+- Explore the option of reporting the presence state via type12 record instead
of discrete sensors. The challenge here is that type12 record also has a limit
of 255 IDs. Meanwhile, it doesn't support stacking multiple presence states in
one ID.
-* We could also let the user define how to group different cables from config
+- We could also let the user define how to group different cables from config
file. However, this requires users to have a deep understanding of how ipmid
works. It is better if the ipmi daemon just takes care of this.
-* Instead of having a sleep-poll mechanism, it is better to have a event
+- 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
We could spawn threads to listen to each chips but I don't think we should
increase the complexity of such a simple daemon.
-* The polling interval is 10 seconds. Is this too long/short for some other
+- The polling interval is 10 seconds. Is this too long/short for some other
projects? For now, let's make it a compiler option.
-* IPMI name string can only be 16 characters. Using square brackets would take
+- IPMI name string can only be 16 characters. Using square brackets would take
away 2 chars. However, using square brackets gives a better indication for the
start of the index string. Hence, the index string will be enclosed by square
bracket.
-
## Testing
+
Testing can be accomplished via automated or manual testing to verify that:
-* The presence state that is reported by GpioCableSevice is matching the result
+- The presence state that is reported by GpioCableSevice is matching the result
from linux gpioget command.
-* Given the SDR name from `ipmitool sdr list event`, say cable[0-1], make sure
+- Given the SDR name from `ipmitool sdr list event`, say cable[0-1], make sure
the zeroth bit is matching the presence state of object
`/xyz/openbmc_project/inventory/item/cable0` on the dbus and the first bit is
matching the state of object `/xyz/openbmc_project/inventory/item/cable`.
-* Unindex items from the config should have its own SDR ID. For example,
+- Unindex items from the config should have its own SDR ID. For example,
`/xyz/openbmc_project/inventory/item/cable` should not be grouped to another
group. Meanwhile, only the zero bit is used to report the presence state.
-* The state of the cable presence need to change with 10 seconds once a cable is
+- The state of the cable presence need to change with 10 seconds once a cable is
plug or unplug from the system.
diff --git a/designs/guard-on-bmc.md b/designs/guard-on-bmc.md
index 3b07ec4..09cd29f 100644
--- a/designs/guard-on-bmc.md
+++ b/designs/guard-on-bmc.md
@@ -1,6 +1,7 @@
# Guard on BMC
## Problem Description
+
On systems with multiple processor units and other redundant vital resources,
the system downtime can be prevented by isolating the faulty components. This
document discusses the design of the BMC support for such isolation procedures.
@@ -8,50 +9,52 @@
actions required to isolate the parts will be dependant on the architecture and
taken care of by the host. But the BMC needs to support a few steps like
notifying users about the components in isolation, clearing isolation, isolating
-a suspected part, or isolating when the host is down due to a severe fault.
-The process of isolation is mentioned as guard in this document, which means
+a suspected part, or isolating when the host is down due to a severe fault. The
+process of isolation is mentioned as guard in this document, which means
guarding the system from faulty components.
## Glossary
+
**Guard**: Guarding the system against failures by permanently isolating faulty
units.
-**Guard Records**: A file in the persistent storage with the list of
-permanently isolated components.
+**Guard Records**: A file in the persistent storage with the list of permanently
+isolated components.
**Manual guard**: An operation to manually add a unit to the list of isolated
units. This operation is helpful in isolating a suspected component without
physically removing it from the server.
-
## Background and References
The guard in the servers is for managing a record of faulty components to keep
them out of service. The list of faulty but guarded components can be stored in
multiple locations based on the ownership of the component. How to store the
-record or manage the record will be decided by the respective component.
-Some of the examples are guard on motherboard components managed by
-the host, guard on the fans can be managed by the fan control application, or
-the guard on the power components can be managed by the power
-management application.
+record or manage the record will be decided by the respective component. Some of
+the examples are guard on motherboard components managed by the host, guard on
+the fans can be managed by the fan control application, or the guard on the
+power components can be managed by the power management application.
-These records will be created when an error is encountered on an element
-that can be isolated. The decision to create a record is based on the type of
-error, usecase, and the availability of a redundant hardware resource to keep
-the system in a usable state. The record which gets created to isolate the
-component is named as Guard Record. The guard record will be deleted after
-a repair action or manually by service personnel. Most of the time, the host
-creates the guard record since the host is responsible for the initialization
-and use of the hardware resources in a server system. The BMC creates guard
-records on a limited set of units during the early boot time, after a severe
-fault, which brings the host down or on the components like a power supply or
-fan which can be controlled by BMC. The BMC retrieves the guard records for
-presenting to an external interface for the review of customers and service
-personnel form various guard record sources.
+These records will be created when an error is encountered on an element that
+can be isolated. The decision to create a record is based on the type of error,
+usecase, and the availability of a redundant hardware resource to keep the
+system in a usable state. The record which gets created to isolate the component
+is named as Guard Record. The guard record will be deleted after a repair action
+or manually by service personnel. Most of the time, the host creates the guard
+record since the host is responsible for the initialization and use of the
+hardware resources in a server system. The BMC creates guard records on a
+limited set of units during the early boot time, after a severe fault, which
+brings the host down or on the components like a power supply or fan which can
+be controlled by BMC. The BMC retrieves the guard records for presenting to an
+external interface for the review of customers and service personnel form
+various guard record sources.
## Requirements
+
### Primary requirements
+
+
- When user requests, create a record in the right guard record repository,
based on the hardware component.
- An option should be given to user to create guard record for DIMM and
@@ -63,6 +66,7 @@
on the guard records.
### Assumptions
+
- The guard records on the units which are owned by the host will be applied
only in a subsequent boot.
- The sub-system which owns the hardware resource will apply the guard record
@@ -73,57 +77,64 @@
BMC for the components.
## Proposed Design
+
The guard proposed here is an aggregator for the guard records from various
sources and provide a common interface for creating, deleting and listing those
records.
### D-Bus Interfaces
-On BMC, There will be a guard manager object and objects for each entry.
-#### Guard Manager
-Guard manager is for providing the external interfaces for managing the guard
-records and retrieving information about guard records.
-The methods and properties of the guard manager.
-- Create Guard: Create guard record for a DIMM or Processor core
- Inputs:
- - Inventory path of the DIMM or Processor core to be guarded.
-- Delete Guard: Delete an existing guard record
- Deleting the guard record D-Bus entry should delete the underlying
- record.
+On BMC, There will be a guard manager object and objects for each entry.
+
+#### Guard Manager
+
+Guard manager is for providing the external interfaces for managing the guard
+records and retrieving information about guard records. The methods and
+properties of the guard manager.
+
+- Create Guard: Create guard record for a DIMM or Processor core Inputs: -
+ Inventory path of the DIMM or Processor core to be guarded.
+
+- Delete Guard: Delete an existing guard record Deleting the guard record D-Bus
+ entry should delete the underlying record.
- Clear all guard: Clear all guard records in the system.
-- List Guard: List all the guarded components.
+- List Guard: List all the guarded components.
**Note:** In few platforms may be the system or hardware is not in a state where
guard operation can be performed either "permanently" or "temporarily".
#### Guard Entry
-The properties of each guard entry will be part of this object
-Properties:
+
+The properties of each guard entry will be part of this object Properties:
- ID: Id of the record which is part of the entry object path.
- Associations:
+
- Guarded hardware inventory path:
- Forward Name must be "isolated_hw".
- Reverse Name must be "isolated_hw_entry".
- BMC Error Log:
+
- Forward Name must be "isolated_hw_errorlog".
- Reverse Name must be "isolated_hw_entry".
- Error Log association can be optional because a user may be
- tried guard hardware and it is not an error case.
+ Error Log association can be optional because a user may be tried guard
+ hardware and it is not an error case.
+
- Severity: Type of Guard
- Manual - Manually Guarded
- Critical - Guarded based on a critical error
- Warning - Guarded based on an error which is not critical, but eventually,
- there can be critical failures.
+ there can be critical failures.
- Resolved: Status of guarded hardware
+
- Used to indicate whether guarded hardware is repaired or replaced.
- **Note:** Setting this to "true" will not delete this entry because
- in a few system platforms guarded hardware records may not be
- deleted and used for further analysis.
+ **Note:** Setting this to "true" will not delete this entry because in a few
+ system platforms guarded hardware records may not be deleted and used for
+ further analysis.
The underlying guard function is implemented by the applications managing the
hardware units. The application which implements the common guard entry
@@ -133,9 +144,12 @@
## Redfish interface
### Manual guard
+
Creating manual gurad record, set the "Enabled" property to "false" to manually
guard a unit which is present in the inventory.
+
#### redfish » v1 » Systems » system » Processors » CPU1
+
```
{
"@odata.type": "#Processor.v1_7_0.Processor",
@@ -162,8 +176,11 @@
```
### Listing the guard record
+
#### redfish >> v1 >> Systems >> system >> LogServices >> IsolatedHardware
+
#### >> Entries
+
```
{
"@odata.id": "/redfish/v1/Systems/system/LogServices/IsolatedHardware/Entries",
@@ -203,26 +220,27 @@
Some of the units like which are controlled by the host can be isolated only
after a reboot, but the units controlled by BMC can be immediately taken out of
service. The alternatives are
-- The host creates, applies, and present guard records: In this case,
- BMC has no control, and the host needs to provide the user interface,
- so there may not be a common interface across different types of hosts.
- Different user interfaces are required for guard records created by
- BMC and host.
-- BMC manages the external interfaces for guard: There will be one common
- point for presenting or managing the guard records created by multiple hosts
- or BMC itself. There are some guard records created after a severe failure
- in the host; as a system control entity, it will be easier for BMC
- to handle such situations and create the records.
+- The host creates, applies, and present guard records: In this case, BMC has no
+ control, and the host needs to provide the user interface, so there may not be
+ a common interface across different types of hosts. Different user interfaces
+ are required for guard records created by BMC and host.
+- BMC manages the external interfaces for guard: There will be one common point
+ for presenting or managing the guard records created by multiple hosts or BMC
+ itself. There are some guard records created after a severe failure in the
+ host; as a system control entity, it will be easier for BMC to handle such
+ situations and create the records.
## Impacts
+
- The guard records will be presented as an extension to logs
-- Redfish implementation will have an impact to do the operations required
- for the guard record management by the user. A request for standardization is
- planned for the method to list the isolated units in the redfish since that
- is not yet available in the redfish standard.
+- Redfish implementation will have an impact to do the operations required for
+ the guard record management by the user. A request for standardization is
+ planned for the method to list the isolated units in the redfish since that is
+ not yet available in the redfish standard.
## Testing
-The necessary tests needed are creating, deleting, and listing the guard
-records and that should be automated, further tests on the isolation of each
-type of the unit is implementation-specific.
+
+The necessary tests needed are creating, deleting, and listing the guard records
+and that should be automated, further tests on the isolation of each type of the
+unit is implementation-specific.
diff --git a/designs/hw-fault-monitor.md b/designs/hw-fault-monitor.md
index 9e35368..2e59a86 100644
--- a/designs/hw-fault-monitor.md
+++ b/designs/hw-fault-monitor.md
@@ -1,40 +1,37 @@
# 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
+Created: Aug 5, 2021
## Problem Description
+
The goal is to create a new hardware fault monitor which will provide a
framework for collecting various fault and sensor information and making it
available externally via Redfish for data center monitoring and management
purposes. The information logged would include a wide variety of chipset
registers and data from manageability hardware. In addition to collecting
-information through BMC interfaces, the hardware fault monitor will also
-receive information via Redfish from the associated host kernel (specifically
-for cases in which the desired information cannot be collected directly by the
-BMC, for example when accessing registers that are read and cleared by the host
-kernel).
+information through BMC interfaces, the hardware fault monitor will also receive
+information via Redfish from the associated host kernel (specifically for cases
+in which the desired information cannot be collected directly by the BMC, for
+example when accessing registers that are read and cleared by the host kernel).
-Future expansion of the hardware fault monitor would include adding the means
-to locally analyze fault and sensor information and then based on specified
+Future expansion of the hardware fault monitor would include adding the means to
+locally analyze fault and sensor information and then based on specified
criteria trigger repair actions in the host BIOS or kernel. In addition, the
hardware fault monitor could receive repair action requests via Redfish from
external data center monitoring software.
-
## Background and References
+
The following are a few related existing OpenBMC modules:
-- 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
+- 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
- bmcweb implements a Redfish webserver for openbmc:
https://github.com/openbmc/bmcweb. The Redfish LogService schema is available
@@ -64,16 +61,16 @@
recommends delivering error logs from the BMC:
https://drive.google.com/file/d/1A9Qc7hB3THw0wiEK_dbXYj85_NOJWrb5/
-
## Requirements
+
- The users of this solution are Redfish clients in data center software. The
goal of the fault monitor is to enable rich error logging (OEM and CPU vendor
specific) for data center tools to monitor servers, manage repairs, predict
crashes, etc.
- The fault monitor must be able to handle receiving fault information that is
- polled periodically as well as fault information that may come in
- sporadically based on fault incidents (e.g. crash dumps).
+ polled periodically as well as fault information that may come in sporadically
+ based on fault incidents (e.g. crash dumps).
- The fault monitor should allow for logging of a variety of sizes of fault
information entries (on the order of bytes to megabytes). In general, more
@@ -91,8 +88,8 @@
recent couple of hours is always kept intact. The log does not have to be
stored persistently (though it can be).
-
## Proposed Design
+
A generic fault monitor will be created to collect fault information. First we
discuss a few example use cases:
@@ -128,16 +125,16 @@
functionality needed for the fault monitor. For instance, based on the needs of
the OEM, the fault monitor will register to be notified of D-Bus signals of
interest in order to be alerted when fault events occur. The fault monitor will
-also poll registers of interest and log their values to the fault log
-(described more later). In addition, the host will be able to write fault
-information to the fault log (via a POST (Create) request to its corresponding
-Redfish log resource collection). When the fault monitor becomes aware of a new
-fault occurrence through any of these ways, it may add fault information to the
-fault log. The fault monitor may also gather relevant sensor data (read via
-D-Bus from the dbus-sensors services) and add it to the fault log, with a
-reference to the original fault event information. The EventGroupID in a
-Redfish LogEntry could potentially be used to associate multiple log entries
-related to the same fault event.
+also poll registers of interest and log their values to the fault log (described
+more later). In addition, the host will be able to write fault information to
+the fault log (via a POST (Create) request to its corresponding Redfish log
+resource collection). When the fault monitor becomes aware of a new fault
+occurrence through any of these ways, it may add fault information to the fault
+log. The fault monitor may also gather relevant sensor data (read via D-Bus from
+the dbus-sensors services) and add it to the fault log, with a reference to the
+original fault event information. The EventGroupID in a Redfish LogEntry could
+potentially be used to associate multiple log entries related to the same fault
+event.
The fault log for storing relevant fault information (and exposing it to
external data center monitoring software) will be a new Redfish LogService
@@ -147,39 +144,38 @@
implementation of the fault log including saving and managing log files will be
added into the existing Phosphor Debug Collector repository with an associated
D-bus object (e.g. xyz/openbmc_project/dump/faultlog) whose interface will
-include methods for writing new data into the log, retrieving data from the
-log, and clearing the log. The fault log will be implemented as a new dump type
-in an existing Phosphor Debug Collector daemon (specifically the one whose
-main() function is in dump_manager_main.cpp). The new fault log would contain
-dump files that are collected in a variety of ways in a variety of formats. A
-new fault log dump entry class (deriving from the "Entry" class in
-dump_entry.hpp) would be defined with an additional "dump type" member variable
-to identify the type of data that a fault log dump entry's corresponding dump
-file contains.
+include methods for writing new data into the log, retrieving data from the log,
+and clearing the log. The fault log will be implemented as a new dump type in an
+existing Phosphor Debug Collector daemon (specifically the one whose main()
+function is in dump_manager_main.cpp). The new fault log would contain dump
+files that are collected in a variety of ways in a variety of formats. A new
+fault log dump entry class (deriving from the "Entry" class in dump_entry.hpp)
+would be defined with an additional "dump type" member variable to identify the
+type of data that a fault log dump entry's corresponding dump file contains.
-bmcweb will be used as the associated Redfish webserver for external entities
-to read and write the fault log. Functionality for handling a POST (Create)
-request to a Redfish log resource collection will be added in bmcweb. When
-delivering a Redfish fault log entry to a Redfish client, large-sized fault
-information (e.g. crashdumps) can be specified as an attachment sub-resource
-(AdditionalDataURI) instead of being inlined. Redfish events (EventService
-schema) will be used to send external notifications, such as when the fault
-monitor needs to notify external data center monitoring software of new fault
-information being available. Redfish events may also be used to notify the host
-kernel and/or BIOS of any repair actions that need to be triggered based on the
-latest fault information.
-
+bmcweb will be used as the associated Redfish webserver for external entities to
+read and write the fault log. Functionality for handling a POST (Create) request
+to a Redfish log resource collection will be added in bmcweb. When delivering a
+Redfish fault log entry to a Redfish client, large-sized fault information (e.g.
+crashdumps) can be specified as an attachment sub-resource (AdditionalDataURI)
+instead of being inlined. Redfish events (EventService schema) will be used to
+send external notifications, such as when the fault monitor needs to notify
+external data center monitoring software of new fault information being
+available. Redfish events may also be used to notify the host kernel and/or BIOS
+of any repair actions that need to be triggered based on the latest fault
+information.
## Alternatives Considered
+
We considered adding the fault logs into the main system event log
-(/redfish/v1/Systems/system/LogServices/EventLog) or other logs already
-existing in bmcweb (e.g. /redfish/v1/Systems/system/LogServices/Dump,
+(/redfish/v1/Systems/system/LogServices/EventLog) or other logs already existing
+in bmcweb (e.g. /redfish/v1/Systems/system/LogServices/Dump,
/redfish/v1/Managers/bmc/LogServices/Dump), but we would like to implement a
separate custom overwrite policy to ensure the most important information (such
as first errors and most severe errors) is retained for local analysis.
-
## Impacts
+
There may be situations where external consumers of fault monitor logs (e.g.
data center monitoring tools) are running software that is newer or older than
the version matching the BMC software running on a machine. In such cases,
@@ -190,6 +186,7 @@
little to no performance impact.
## Testing
+
Error injection mechanisms or simulations may be used to artificially create
error conditions that will be logged by the fault monitor module.
diff --git a/designs/management-console/Authorities_List_Management.md b/designs/management-console/Authorities_List_Management.md
index d6b2d3e..0f13bea 100644
--- a/designs/management-console/Authorities_List_Management.md
+++ b/designs/management-console/Authorities_List_Management.md
@@ -1,54 +1,50 @@
# Authorities List Management
-Author:
- Nan Zhou (nanzhoumails@gmail.com)
+Author: Nan Zhou (nanzhoumails@gmail.com)
-Created:
- 12/01/2021
+Created: 12/01/2021
## Problem Description
-There are use cases where a system has multiple root certificates installed
-to verify different clients. For example, In Google, a trust bundle file (
-which is a list of authorities) is installed on BMC for mTLS authentication.
+There are use cases where a system has multiple root certificates installed to
+verify different clients. For example, In Google, a trust bundle file ( which is
+a list of authorities) is installed on BMC for mTLS authentication.
The current phosphor-certificate-manager doesn't have good support to manage
multiple root certificates:
-1. It only allows replacing a single Authority object in dbus; however,
-Google's use case requires bulk replacement (see the ReplaceAll interface
-below)
+1. It only allows replacing a single Authority object in dbus; however, Google's
+ use case requires bulk replacement (see the ReplaceAll interface below)
-2. It only extracts the first certificate given a PEM encoded file
-with multiple certs; however, Google's trust bundle file contains multiple
-PEM encoded certificates
+2. It only extracts the first certificate given a PEM encoded file with multiple
+ certs; however, Google's trust bundle file contains multiple PEM encoded
+ certificates
## Requirements
-
-
Phosphor-certificate-manager (only the Authority Manager) and BMCWeb will
support authorities list:
1. Bulk Installation: given a PEM file with multiple root certificates, it
-validates & installs all of them and returns a list of created objects
+ validates & installs all of them and returns a list of created objects
2. Bulk Replacement: given a PEM file with multiple root certificates, it will
-firstly delete all current root certificates and redo the installation
+ firstly delete all current root certificates and redo the installation
3. Redfish: BMCWeb will export all authorities as Redfish Certificate
-4. Recovery at boot up: when the phosphor-certificate-manager gets
-instantiated, if it finds a authorities list in the installation path, it
-will recover from the list via a bulk installation
+4. Recovery at boot up: when the phosphor-certificate-manager gets instantiated,
+ if it finds a authorities list in the installation path, it will recover from
+ the list via a bulk installation
-5. Atomic: Bulk Installation and Bulk Replacement are atomic; that is, if
-there is an invalid certificate in the list, the service won't install any of
-the certificates in the list
+5. Atomic: Bulk Installation and Bulk Replacement are atomic; that is, if there
+ is an invalid certificate in the list, the service won't install any of the
+ certificates in the list
## Proposed Design
We propose two new interfaces:
+
1. InstallAll
2. ReplaceAll
@@ -56,11 +52,10 @@
When certificate type is Authority, rather than just extract the first
certificate, we will iterate through each certificate, validate it, create
-corresponding object in DBus, dump individual certificates into PEM files in
-the installation path, creates alias according to subject hash
-(requirements from boost's `ssl_context`) for each certificate, and finally
-copy the PEM file to the installation path(the PEM file will have a fixed
-name)
+corresponding object in DBus, dump individual certificates into PEM files in the
+installation path, creates alias according to subject hash (requirements from
+boost's `ssl_context`) for each certificate, and finally copy the PEM file to
+the installation path(the PEM file will have a fixed name)
We return all created object paths as a vector of strings.
@@ -73,17 +68,17 @@
PEM file.
The certificate manager will implement the new ReplaceAll interface. Upon
-invocation, it deletes all current authority objects, takes the input PEM,
-and redo the installation.
+invocation, it deletes all current authority objects, takes the input PEM, and
+redo the installation.
For other types of certificate manager (server & client), the service throws a
NOT ALLOWED error.
### xyz.openbmc_project.Certs.Replace
-No changes. Individual authority certificate can still be replaced
-respectively. It only extracts the first certificate even if the PEM contains
-multiple root certificates.
+No changes. Individual authority certificate can still be replaced respectively.
+It only extracts the first certificate even if the PEM contains multiple root
+certificates.
## Impacts
@@ -92,10 +87,11 @@
## Alternatives Considered
We can also create a trust bundle interface (instead of using multiple
-Certificates) and implement its standalone manager daemon. It has less impact
-in existing codes. However, trust bundle isn't in BMCWeb, neither in Redfish
+Certificates) and implement its standalone manager daemon. It has less impact in
+existing codes. However, trust bundle isn't in BMCWeb, neither in Redfish
schema.
## Testing
+
Enhance existing unit tests in phosphor-certificates-manager to test bulk
installation and replacements.
diff --git a/designs/management-console/VMI_Certificate_Exchange.md b/designs/management-console/VMI_Certificate_Exchange.md
index 81d8a20..7dd7cd5 100644
--- a/designs/management-console/VMI_Certificate_Exchange.md
+++ b/designs/management-console/VMI_Certificate_Exchange.md
@@ -1,24 +1,22 @@
# VMI Certificate Exchange
-Author:
- Raviteja Bailapudi
+Author: Raviteja Bailapudi
-Other contributors:
- Ratan Gupta
+Other contributors: Ratan Gupta
-Created:
- 07/10/2019
+Created: 07/10/2019
## Glossary
-- HMC - Hardware Management Console : Management console for IBM enterprise
- servers.
-- PHYP - Power Hypervisor : This orchestrates and manages system
- virtualization.
-- VMI - Virtual Management Interface : The interface facilitating
- communications between HMC and PHYP embedded linux virtual machine.
-- KVM - Kernel Virtual Machine : Open source virtualization software
+
+- HMC - Hardware Management Console : Management console for IBM enterprise
+ servers.
+- PHYP - Power Hypervisor : This orchestrates and manages system virtualization.
+- VMI - Virtual Management Interface : The interface facilitating communications
+ between HMC and PHYP embedded linux virtual machine.
+- KVM - Kernel Virtual Machine : Open source virtualization software
## Problem Description
+
On enterprise POWER systems, the Hardware management console (HMC) needs to
establish a secure connection to the Virtualization management interface (VMI)
for virtualization management.
@@ -26,53 +24,57 @@
VMI is an embedded Linux VM created and run on PHYP which provides the
virtualization function.
-HMC requires client key, client.crt, and CA.crt to establish
-secure connection to VMI.
+HMC requires client key, client.crt, and CA.crt to establish secure connection
+to VMI.
-BMC needs to provide certificate exchange functionality to management
-console due to following reasons:
+BMC needs to provide certificate exchange functionality to management console
+due to following reasons:
+
- Host firmware (PHYP) does not have authentication mechanism.
-- VMI trusts that BMC has authenticated and verified the authenticity of
- any client connected as there is a secure authenticated connection already
- exists between HMC and BMC.
+- VMI trusts that BMC has authenticated and verified the authenticity of any
+ client connected as there is a secure authenticated connection already exists
+ between HMC and BMC.
Management console needs an API through which it can send the CSR to VMI (CA)
-and gets the signed certificate and the CA certificate from VMI.
-This design will describe how certificates get exchanged between management
-console and VMI
+and gets the signed certificate and the CA certificate from VMI. This design
+will describe how certificates get exchanged between management console and VMI
-IBM systems can run both IBM specific host-firmware (PHYP) and Linux KVM.
-This API would be used only for the PHYP based machines.
+IBM systems can run both IBM specific host-firmware (PHYP) and Linux KVM. This
+API would be used only for the PHYP based machines.
Enable and disable of this API would be controlled by the build time
configurable variable.
## Background and References
+
- VMI will be created and run on PHYP that will provide the virtualization
function.
-- When the VMI is powered on it generates a public-private key pair and
- a self-signed root certificate is created using this key pair.
+- When the VMI is powered on it generates a public-private key pair and a
+ self-signed root certificate is created using this key pair.
- VMI acts as root CA only for VMI endpoints, its not an official CA and uses
its self-signed certificate to sign CSR from client.
- HMC needs to establish secure connection to VMI to perform virtualization
management.
## Requirements
+
BMC will provide an interface for management console to exchange certificate
information from VMI so that HMC can establish secure connection to VMI.
## Proposed Design
-The management console can send CSR string to VMI (CA) and get signed certificate
-and Root CA certificate via proposed BMC interface.
-In this interface perspective, the HTTP error code could be 4XX/5XX.
-It would be mapped depending on the PLDM error response.
+The management console can send CSR string to VMI (CA) and get signed
+certificate and Root CA certificate via proposed BMC interface.
-HMC can query BMC state and use this API to initiate certificate
-exchange.If HMC runs this command before PHYP boots, PLDM command returns error
-If PLDM command throws an error, that would be mapped to Internal server Error (500).
+In this interface perspective, the HTTP error code could be 4XX/5XX. It would be
+mapped depending on the PLDM error response.
+
+HMC can query BMC state and use this API to initiate certificate exchange.If HMC
+runs this command before PHYP boots, PLDM command returns error If PLDM command
+throws an error, that would be mapped to Internal server Error (500).
### Design Flow
+
```ascii
+------------+ +--------+ +--------+
| HMC | | BMC | | VMI |
@@ -100,21 +102,24 @@
+ + +
```
+
### VMI certificate exchange
+
Management console should use the below REST commands to exchange certificates
with VMI
#### Get Signed certificate:
+
REST command to get signed client certificate from VMI
Request:
+
```bash
curl -k -H "X-Auth-Token: <token>" -X POST "Content-Type: application/json" -d
'{"CsrString":"<CSR string>"}' https://{BMC_IP}/ibm/v1/Host/Actions/SignCSR
```
-Response:
-This will return the certificate string which contains signed client
+Response: This will return the certificate string which contains signed client
certificate
```
@@ -123,16 +128,19 @@
}
```
+
#### Get Root certificate:
+
REST command to get VMI root certificate
Request:
+
```bash
curl -k -H "X-Auth-Token: <token>" -X GET http://{BMC_IP}/ibm/v1/Host/Certificate/root
```
-Response:
-This will return the certificate string which contains and root CA certificate.
+Response: This will return the certificate string which contains and root CA
+certificate.
```
{
@@ -140,6 +148,7 @@
}
```
+
This interface returns HTTP error codes 5XX/4XX in failure cases
## Alternatives considered:
@@ -149,27 +158,29 @@
### Current flow for generating and installing Certificates (CSR Based):
-* Certificate Signing Request CSR is a message sent from an applicant to a
+- Certificate Signing Request CSR is a message sent from an applicant to a
certificate authority in order to apply for a digital identity certificate.
-* The user calls CSR interface BMC creates new private key and CSR Certificate
+- The user calls CSR interface BMC creates new private key and CSR Certificate
File
-* CSR certificate is passed onto the CA to sign the certificate and then upload
+- CSR certificate is passed onto the CA to sign the certificate and then upload
CSR signed certificate and install the certificate.
### Note
-* Our existing BMC certificate manager/service have interfaces to generate CSR,
- upload certificates and other interfaces to manage certificates(replace,delete..etc).
-* In VMI certificate exchange, requirement for BMC is to provide an interface for
- management console to get CSR certificate signed by VMI (CA).
-* We don’t have any existing certificate manager interface to forward CSR
+- Our existing BMC certificate manager/service have interfaces to generate CSR,
+ upload certificates and other interfaces to manage
+ certificates(replace,delete..etc).
+- In VMI certificate exchange, requirement for BMC is to provide an interface
+ for management console to get CSR certificate signed by VMI (CA).
+- We don’t have any existing certificate manager interface to forward CSR
request to CA to get signed by CA.
-* Here proposal is to have SignCSR() interface which accepts CSR string and
+- Here proposal is to have SignCSR() interface which accepts CSR string and
return signed certificate and Root CA certificate.
-* This requirement is out of scope for existing certificate manager so proposing
+- This requirement is out of scope for existing certificate manager so proposing
SignCSR interface as management console specific interface.
### Alternate Design
+
```ascii
+------------+ +--------+ +--------+
| HMC | | BMC | | VMI |
@@ -197,49 +208,57 @@
|<--------------------------------------->|
```
-* In this alternate design, Management console establishes connection to VMI and
- sends Verify Password command to authenticate user to establish secure session.
-* VMI does not have authentication method, so VMI needs to use BMC authentication method
- over PLDM.
-* There are security concerns if raw password is getting sent over PLDM in clear text
- over LPC, so this design ruled out.
+
+- In this alternate design, Management console establishes connection to VMI and
+ sends Verify Password command to authenticate user to establish secure
+ session.
+- VMI does not have authentication method, so VMI needs to use BMC
+ authentication method over PLDM.
+- There are security concerns if raw password is getting sent over PLDM in clear
+ text over LPC, so this design ruled out.
## Impacts
-- Create new interface GetRootCertificate in webserver which reads root certificate from
- '/var/lib/bmcweb/RootCert' file.This API can handle muptiple requests at the sametime.
+
+- Create new interface GetRootCertificate in webserver which reads root
+ certificate from '/var/lib/bmcweb/RootCert' file.This API can handle muptiple
+ requests at the sametime.
- PLDM gets root certificate as soon as VMI boots and it writes to
'/var/lib/bmcweb/RootCert'.
-- Implement D-Bus interface to create dbus object for each signCSR so that multiple requests
- can work at the sametime.
- D-bus service: xyz.openbmc_project.Certs.ca.authority.Manager
- Object path : /xyz/openbmc_project/certs/ca
- Interface : xyz.openbmc_project.Certs.Authority
- Method : SignCSR
+- Implement D-Bus interface to create dbus object for each signCSR so that
+ multiple requests can work at the sametime. D-bus service:
+ xyz.openbmc_project.Certs.ca.authority.Manager Object path :
+ /xyz/openbmc_project/certs/ca Interface : xyz.openbmc_project.Certs.Authority
+ Method : SignCSR
- Dbus object contains CSR,ClientCertificate and Status properties.
-- PLDM looks for interface added signal for each object created and reads CSR property for
- CSR string and forwards this CSR string to VMI for signing this CSR.
-- Once PLDM on BMC gets the client certificate from VMI, it updates the ClientCertificate
- D-bus property and updates the Status property to Complete in the Dbus object.
-- Create new interface SignCSR in webserver which takes CSR string as input and returns
- certificate string.This interface calls SignCSR dbus method and looks for Status
- property changed signal to verify status.Reads ClientCertificate property content and
- return certificate string.
-- On completion of serving the sign CSR request, respective dbus object will be deleted
- before returning certificate string to client.
-- BMC is passthrough which allows certificate exchange between VMI and HMC.
- BMC does not store or parse these certificates.
-- Build time configure variable defined to control enable and disable of this API
- in webserver. It is required only for IBM systems with IBM specific host-firmware (PHYP)
+- PLDM looks for interface added signal for each object created and reads CSR
+ property for CSR string and forwards this CSR string to VMI for signing this
+ CSR.
+- Once PLDM on BMC gets the client certificate from VMI, it updates the
+ ClientCertificate D-bus property and updates the Status property to Complete
+ in the Dbus object.
+- Create new interface SignCSR in webserver which takes CSR string as input and
+ returns certificate string.This interface calls SignCSR dbus method and looks
+ for Status property changed signal to verify status.Reads ClientCertificate
+ property content and return certificate string.
+- On completion of serving the sign CSR request, respective dbus object will be
+ deleted before returning certificate string to client.
+- BMC is passthrough which allows certificate exchange between VMI and HMC. BMC
+ does not store or parse these certificates.
+- Build time configure variable defined to control enable and disable of this
+ API in webserver. It is required only for IBM systems with IBM specific
+ host-firmware (PHYP)
## Testing
+
- Test the interface command from a management console and verify if certificate
exchange worked as expected and verify if management console able to establish
secure connection to VMI.
- Certificate exchange fails in the following scenarios
- * If PHYP is not up
- * If PHYP throws error for certificate validation.
- This interface returns appropriate HTTP error code (4XX/5XX) based on type of error.
-- If there are issues like certificate expiry, revocation, incorrect date/time and
- incorrect certificates, then HMC fails to establish connection to VMI.
+ - If PHYP is not up
+ - If PHYP throws error for certificate validation. This interface returns
+ appropriate HTTP error code (4XX/5XX) based on type of error.
+
+- If there are issues like certificate expiry, revocation, incorrect date/time
+ and incorrect certificates, then HMC fails to establish connection to VMI.
diff --git a/designs/management-console/service-discovery.md b/designs/management-console/service-discovery.md
index 44f1b01..a6598a1 100644
--- a/designs/management-console/service-discovery.md
+++ b/designs/management-console/service-discovery.md
@@ -1,4 +1,5 @@
# Service processor discovery through Avahi
+
Author: Ratan Gupta
Other contributors: Asmitha KR
@@ -6,25 +7,29 @@
Created: 2019-07-12
# 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
-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 LMMNR.
+[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
+LMMNR.
## Problem Description
-In a network where there are thousands of system, Management console should
-be able to discover the server. We have a requirement where the management
-console wants to discover the vendor-specific server.
+
+In a network where there are thousands of system, Management console should be
+able to discover the server. We have a requirement where the management console
+wants to discover the vendor-specific server.
eg: Management console wants to discover the low-end server of manufacturer XYZ.
## Proposed Design
-Currently in openBMC, Avahi is being used as service discovery.
-Avahi is a system which facilitates service discovery on a local network via the
-mDNS/DNS-SD protocol suite. BMC publishes the hostname and interface details to
+
+Currently in openBMC, Avahi is being used as service discovery. Avahi is a
+system which facilitates service discovery on a local network via the
+mDNS/DNS-SD protocol suite. BMC publishes the hostname and interface details to
the network using the Avahi service.
The services that are being published by Avahi have various fields like -
@@ -41,45 +46,42 @@
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:
-1) Hostname
-2) IP address
-3) Service Port
-4) Service Type
-5) Additional data
+
+1. Hostname
+2. IP address
+3. Service Port
+4. Service Type
+5. Additional data
### 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 : _obmc_rest._tcp
-avahi-browse -rt _obmc_rest._tcp
-Output of the above command is as follows
-avahi-browse -rt _obmc_rest._tcp
-+ eth0 IPv6 obmc_rest _obmc_rest._tcp local
-+ eth0 IPv4 obmc_rest _obmc_rest._tcp local
-= eth0 IPv6 obmc_rest _obmc_rest._tcp local
- hostname = [witherspoon-cdcb785972fb41f082c7ca747e287fa6.local]
- address = [fe80::72e2:84ff:fe14:2390]
- port = [443]
- txt = ["Manufacturer=XYZ"]
- txt = ["Type=abc"]
-= eth0 IPv4 obmc_rest _obmc_rest._tcp local
- hostname = [witherspoon-cdcb785972fb41f082c7ca747e287fa6.local]
- address = [9.5.180.233]
- port = [443]
- txt = ["Manufacturer=XYZ"]
- txt = ["Type=abc"]
+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
+
+- eth0 IPv6 obmc_rest \_obmc_rest.\_tcp local
+- eth0 IPv4 obmc_rest \_obmc_rest.\_tcp local = eth0 IPv6 obmc_rest
+ \_obmc_rest.\_tcp local hostname =
+ [witherspoon-cdcb785972fb41f082c7ca747e287fa6.local] address =
+ [fe80::72e2:84ff:fe14:2390] port = [443] txt = ["Manufacturer=XYZ"] txt =
+ ["Type=abc"] = eth0 IPv4 obmc_rest \_obmc_rest.\_tcp local hostname =
+ [witherspoon-cdcb785972fb41f082c7ca747e287fa6.local] address = [9.5.180.233]
+ port = [443] txt = ["Manufacturer=XYZ"] txt = ["Type=abc"]
## Alternatives Considered
+
openSLP
## Impacts
+
None.
## Testing
+
The path /etc/avahi/services contain all the services that avahi publishes on
startup.
diff --git a/designs/mctp/mctp-kernel.md b/designs/mctp/mctp-kernel.md
index 77394ec..fc2d914 100644
--- a/designs/mctp/mctp-kernel.md
+++ b/designs/mctp/mctp-kernel.md
@@ -11,38 +11,37 @@
# Requirements for a kernel implementation
- * The MCTP messaging API should be an obvious application of the existing POSIX
- socket interface
+- The MCTP messaging API should be an obvious application of the existing POSIX
+ socket interface
- * Configuration should be simple for a straightforward MCTP endpoint: a single
- network with a single local endpoint id (EID).
+- Configuration should be simple for a straightforward MCTP endpoint: a single
+ network with a single local endpoint id (EID).
- * Infrastructure should be flexible enough to allow for more complex MCTP
- networks, allowing:
+- Infrastructure should be flexible enough to allow for more complex MCTP
+ networks, allowing:
- - each MCTP network (as defined by section 3.2.31 of DSP0236) may
- consist of multiple local physical interfaces, and/or multiple EIDs;
+ - each MCTP network (as defined by section 3.2.31 of DSP0236) may consist of
+ multiple local physical interfaces, and/or multiple EIDs;
- - multiple distinct (ie., non-bridged) networks, possibly containing
- duplicated EIDs between networks;
+ - multiple distinct (ie., non-bridged) networks, possibly containing
+ duplicated EIDs between networks;
- - multiple local EIDs on a single interface, and
+ - multiple local EIDs on a single interface, and
- - customisable routing/bridging configurations within a network.
+ - customisable routing/bridging configurations within a network.
-
-# Proposed Design #
+# Proposed Design
The design contains several components:
- * An interface for userspace applications to send and receive MCTP messages: A
- mapping of the sockets API to MCTP usage
+- An interface for userspace applications to send and receive MCTP messages: A
+ mapping of the sockets API to MCTP usage
- * Infrastructure for control and configuration of the MCTP network(s),
- consisting of a configuration utility, and a kernel messaging facility for
- this utility to use.
+- Infrastructure for control and configuration of the MCTP network(s),
+ consisting of a configuration utility, and a kernel messaging facility for
+ this utility to use.
- * Kernel drivers for physical interface bindings.
+- Kernel drivers for physical interface bindings.
In general, the kernel components cover the transport functionality of MCTP,
such as message assembly/disassembly, packet forwarding, and physical interface
@@ -64,16 +63,16 @@
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.
An interface (or "link") is an instance of an MCTP physical transport binding
(as defined by DSP0236, section 3.2.47), likely connected to a specific hardware
-device. This is represented as a `struct netdevice`, and has a user-visible
-name and index (`ifindex`). Non-hardware-attached interfaces are permitted, to
-allow local loopback and/or virtual interfaces.
+device. This is represented as a `struct netdevice`, and has a user-visible name
+and index (`ifindex`). Non-hardware-attached interfaces are permitted, to allow
+local loopback and/or virtual interfaces.
A network defines a unique address space for MCTP endpoints by endpoint-ID
(described by DSP0236, section 3.2.31). A network has a user-visible identifier
@@ -86,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:
@@ -153,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.
@@ -185,26 +184,26 @@
The `smctp_tag` value will configure the tags accepted from the remote side of
this socket. Given the above, the only valid value is `MCTP_TAG_OWNER`, which
will result in remotely "owned" tags being routed to this socket. Since
-`MCTP_TAG_OWNER` is set, the 3 least-significant bits of `smctp_tag` are
-not used; callers must set them to zero. See the [Tag behaviour for transmitted
-messages](#tag-behaviour-for-transmitted-messages) section for more details. If
-the `MCTP_TAG_OWNER` bit is not set, `bind()` will fail with an errno of
-`EINVAL`.
+`MCTP_TAG_OWNER` is set, the 3 least-significant bits of `smctp_tag` are not
+used; callers must set them to zero. See the
+[Tag behaviour for transmitted messages](#tag-behaviour-for-transmitted-messages)
+section for more details. If the `MCTP_TAG_OWNER` bit is not set, `bind()` will
+fail with an errno of `EINVAL`.
A `smctp_network` value of `MCTP_NET_ANY` will configure the socket to receive
incoming packets from any locally-connected network. A specific network value
will cause the socket to only receive incoming messages from that network.
The `smctp_addr` field specifies a local address to bind to. A value of
-`MCTP_ADDR_ANY` configures the socket to receive messages addressed to any
-local destination EID.
+`MCTP_ADDR_ANY` configures the socket to receive messages addressed to any local
+destination EID.
The `smctp_type` field specifies which message types to receive. Only the lower
7 bits of the type is matched on incoming messages (ie., the most-significant IC
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:
@@ -243,18 +242,18 @@
"owned" tag to be allocated for this socket, and will remain allocated for all
future outgoing messages, until either the socket is closed, or `connect()` is
called again. If a tag cannot be allocated, `connect()` will report an error,
-with an errno value of `EAGAIN`. See the [Tag behaviour for transmitted
-messages](#tag-behaviour-for-transmitted-messages) section for more details. If
-the `MCTP_TAG_OWNER` bit is not set, `connect()` will fail with an errno of
-`EINVAL`.
+with an errno value of `EAGAIN`. See the
+[Tag behaviour for transmitted messages](#tag-behaviour-for-transmitted-messages)
+section for more details. If the `MCTP_TAG_OWNER` bit is not set, `connect()`
+will fail with an errno of `EINVAL`.
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:
+An MCTP message is transmitted using one of the `sendto()`, `sendmsg()`,
+`send()` or `write()` syscalls. Using `sendto()` as the primary example:
```c
struct sockaddr_mctp addr;
@@ -304,9 +303,9 @@
expired either by timeout or by a subsequent `sendto()`.
The `sendmsg()` system call allows a more compact argument interface, and the
-message buffer to be specified as a scatter-gather list. At present no
-ancillary message types (used for the `msg_control` data passed to `sendmsg()`)
-are defined.
+message buffer to be specified as a scatter-gather list. At present no ancillary
+message types (used for the `msg_control` data passed to `sendmsg()`) are
+defined.
Transmitting a message on an unconnected socket with `MCTP_TAG_OWNER` specified
will cause an allocation of a tag, if no valid tag is already allocated for that
@@ -316,10 +315,10 @@
allocation is lost. This tag behaviour can be controlled through the
`MCTP_TAG_CONTROL` socket option.
-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.
+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
@@ -357,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
@@ -367,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.
@@ -398,8 +397,7 @@
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:
@@ -430,46 +428,44 @@
Changing the default tag control behaviour should only be required when:
- * 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.
+- 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:
- * `listen()`
- * `accept()`
- * `ioctl()`
- * `shutdown()`
- * `mmap()`
+- `listen()`
+- `accept()`
+- `ioctl()`
+- `shutdown()`
+- `mmap()`
-### Userspace examples ###
+### Userspace examples
These examples cover three general use-cases:
- - **requester**: sends requests to a particular (EID, type) target, and
- receives responses to those packets
+- **requester**: sends requests to a particular (EID, type) target, and receives
+ responses to those packets
- This is similar to a typical UDP client
+ This is similar to a typical UDP client
- - **responder**: receives all locally-addressed messages of a specific
- message-type, and responds to the requester immediately.
+- **responder**: receives all locally-addressed messages of a specific
+ message-type, and responds to the requester immediately.
- This is similar to a typical UDP server
+ This is similar to a typical UDP server
- - **controller**: a specific service for a bus owner; may send broadcast
- messages, manage EID allocations, update local MCTP stack state. Will
- need low-level packet data.
+- **controller**: a specific service for a bus owner; may send broadcast
+ messages, manage EID allocations, update local MCTP stack state. Will need
+ low-level packet data.
- This is similar to a DHCP server.
+ 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`.
+"Client"-side implementation to send requests to a responder, and receive a
+response. This uses a (fictitious) message type of `MCTP_TYPE_ECHO`.
```c
int main() {
@@ -519,11 +515,11 @@
}
```
-#### 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 `struct
-sockaddr_mctp`; only messages matching this type will be received.
+This uses a (fictitious) message type of `MCTP_TYPE_ECHO` in the
+`struct sockaddr_mctp`; only messages matching this type will be received.
```c
int main() {
@@ -578,7 +574,7 @@
}
```
-#### Broadcast request ####
+#### Broadcast request
Sends a request to a broadcast EID, and receives (unicast) replies. Typical
control protocol pattern.
@@ -656,13 +652,13 @@
}
```
-### 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 `struct
-sockaddr_mctp`.
+destination via the `smctp_network` and `smctp_addr` fields of a
+`struct sockaddr_mctp`.
The `smctp_addr` field maps directly to the destination endpoint's EID.
@@ -681,7 +677,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.
@@ -694,7 +690,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
@@ -706,9 +702,9 @@
This allocation will expire when any of the following occur:
- * the socket is closed
- * a new message is sent to a new destination EID
- * an implementation-defined timeout expires
+- the socket is closed
+- a new message is sent to a new destination EID
+- an implementation-defined timeout expires
Because the "tag space" is limited, it may not be possible for the kernel to
allocate a unique tag for the outgoing message. In this case, the `sendto()`
@@ -724,8 +720,8 @@
persistent remote address. In this case, the tag will be allocated during
connect(), and remain reserved for this socket until any of the following occur:
- * the socket is closed
- * the remote address is changed through another call to `connect()`.
+- the socket is closed
+- the remote address is changed through another call to `connect()`.
In particular, calling `sendto()` with a different address does not release the
tag reservation.
@@ -740,11 +736,10 @@
For this reason, applications wanting to send to the broadcast address should
use the `connect()` system call to reserve a tag, and guarantee its availability
for future message transmission. Note that this will remove the tag value for
-use with *any other EID*. Sending to the broadcast address should be avoided; we
+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
@@ -758,30 +753,30 @@
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
table are of the format:
- | EID range | interface | physical address | metric | MTU | flags | expiry |
- |-----------|-----------|------------------|--------|-----|-------|--------|
+| EID range | interface | physical address | metric | MTU | flags | expiry |
+| --------- | --------- | ---------------- | ------ | --- | ----- | ------ |
This table can be updated from two sources:
- * From userspace, via a netlink interface (see the
- [Utility and configuration interfaces](#utility-and-configuration-interfaces)
- section).
+- From userspace, via a netlink interface (see the
+ [Utility and configuration interfaces](#utility-and-configuration-interfaces)
+ section).
- * Directly within the kernel, when basic neighbour information is discovered.
- Kernel-originated routes are marked as such in the flags field, and have a
- maximum validity age, indicated by the expiry field.
+- Directly within the kernel, when basic neighbour information is discovered.
+ Kernel-originated routes are marked as such in the flags field, and have a
+ maximum validity age, indicated by the expiry field.
Kernel-discovered routing information can originate from two sources:
- * physical-to-EID mappings discovered through received packets
+- physical-to-EID mappings discovered through received packets
- * explicit endpoint physical-address resolution requests
+- explicit endpoint physical-address resolution requests
When a packet is to be transmitted to an EID that does not have an entry in the
routing table, the kernel may attempt to resolve the physical address of that
@@ -791,7 +786,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
@@ -800,7 +795,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>
@@ -809,7 +804,7 @@
mctp link set <link> bus-owner <hwaddr>
```
-### `mctp network`: manage networks ###
+### `mctp network`: manage networks
```sh
mctp network create <network-id>
@@ -818,14 +813,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>]
@@ -833,7 +828,7 @@
mctp route show [net <network-id>]
```
-### `mctp stat`: query socket status ###
+### `mctp stat`: query socket status
```sh
mctp stat
@@ -842,10 +837,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
@@ -865,7 +859,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`
@@ -877,7 +871,8 @@
The `smctp_type` implementation was chosen as it better matches the "addressing"
model of the message type; sockets are bound to an incoming message type,
-similar to the IP protocol's model of binding UDP sockets to a local port number.
+similar to the IP protocol's model of binding UDP sockets to a local port
+number.
There is no kernel behaviour that depends on the specific type (particularly
given the design choice above), so it is not suited to use the protocol argument
@@ -886,8 +881,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
@@ -902,44 +896,44 @@
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
+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:
- * needlessly consumes a tag on non-tag-owning sockets (ie, those which send
- with TO=0 - responders); and
+- needlessly consumes a tag on non-tag-owning sockets (ie, those which send with
+ TO=0 - responders); and
- * limits us to 8 sockets per network.
+- 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
-sending those packets. Tags would be released when the last packet has been sent.
+sending those packets. Tags would be released when the last packet has been
+sent.
However, this removes any facility to correlate responses with the correct
socket, which is the purpose of the TO bit in DSP0236. In order for the sending
application to receive the response, we would either need to:
- * limit the system to one socket of each message type (which, for example,
- precludes running a requester and a responder of the same type); or
+- limit the system to one socket of each message type (which, for example,
+ precludes running a requester and a responder of the same type); or
- * forward all incoming messages of a specific message-type to all sockets
- listening on that type, making it trivial to eavesdrop on MCTP data of
- other applications
+- forward all incoming messages of a specific message-type to all sockets
+ 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) is
-observed.
+and then release that allocation after the incoming response to that tag (TO=0)
+is observed.
However, MCTP protocols exist that do not have a 1:1 mapping of responses to
requests - more than one response may be valid for a given request message. For
diff --git a/designs/mctp/mctp-userspace.md b/designs/mctp/mctp-userspace.md
index 35ba877..cd09b61 100644
--- a/designs/mctp/mctp-userspace.md
+++ b/designs/mctp/mctp-userspace.md
@@ -12,8 +12,8 @@
## Proposed Design
The MCTP core specification just provides the packetisation, routing and
-addressing mechanisms. The actual transmit/receive of those packets is up to
-the hardware binding of the MCTP transport.
+addressing mechanisms. The actual transmit/receive of those packets is up to the
+hardware binding of the MCTP transport.
For OpenBMC, we would introduce a MCTP daemon, which implements the transport
over a configurable hardware channel (eg., Serial UART, I2C or PCIe), and
@@ -74,14 +74,14 @@
blocked daemon, but this would be of a limited size. Handlers whose sockets
exceed this queue would be disconnected from the daemon.
-One design intention of the multiplexer daemon is to allow a future
-kernel-based MCTP implementation without requiring major structural changes to
-handler applications. The socket-based interface facilitates this, as the
-unix-domain socket interface could be fairly easily swapped out with a new
-kernel-based socket type.
+One design intention of the multiplexer daemon is to allow a future kernel-based
+MCTP implementation without requiring major structural changes to handler
+applications. The socket-based interface facilitates this, as the unix-domain
+socket interface could be fairly easily swapped out with a new kernel-based
+socket type.
-MCTP is intended to be an optional component of OpenBMC. Platforms using
-OpenBMC are free to adopt it as they see fit.
+MCTP is intended to be an optional component of OpenBMC. Platforms using OpenBMC
+are free to adopt it as they see fit.
### Demultiplexer daemon interface
@@ -115,22 +115,20 @@
The rest of the message data is the complete MCTP message, including MCTP
message type field.
-The daemon does not provide a facility for clients to specify or retrieve
-values for the tag field in individual MCTP packets.
-
+The daemon does not provide a facility for clients to specify or retrieve values
+for the tag field in individual MCTP packets.
## Alternatives Considered
In terms of an MCTP daemon structure, an alternative is to have the MCTP
-implementation contained within a single process, using the libmctp API
-directly for passing messages from the core code to application-level handlers.
-The drawback of this approach is that this single process needs to implement
-all possible functionality that is available over MCTP, which may be quite a
+implementation contained within a single process, using the libmctp API directly
+for passing messages from the core code to application-level handlers. The
+drawback of this approach is that this single process needs to implement all
+possible functionality that is available over MCTP, which may be quite a
disjoint set. This would likely lead to unnecessary restrictions on the
implementation of those application-level handlers (programming language,
-frameworks used, etc). Also, this single-process approach would likely need
-more significant modifications if/when MCTP protocol support is moved to the
-kernel.
+frameworks used, etc). Also, this single-process approach would likely need more
+significant modifications if/when MCTP protocol support is moved to the kernel.
The interface between the demultiplexer daemon and clients is currently defined
as a socket-based interface. However, an alternative here would be to pass MCTP
diff --git a/designs/mctp/mctp.md b/designs/mctp/mctp.md
index d5ebc13..b0e8cf1 100644
--- a/designs/mctp/mctp.md
+++ b/designs/mctp/mctp.md
@@ -4,37 +4,34 @@
## Problem Description
-Currently, we have a few different methods of communication between host
-and BMC. This is primarily IPMI-based, but also includes a few
-hardware-specific side-channels, like hiomap. On OpenPOWER hardware at
-least, we've definitely started to hit some of the limitations of IPMI
-(for example, we have need for >255 sensors), as well as the hardware
-channels that IPMI typically uses.
+Currently, we have a few different methods of communication between host and
+BMC. This is primarily IPMI-based, but also includes a few hardware-specific
+side-channels, like hiomap. On OpenPOWER hardware at least, we've definitely
+started to hit some of the limitations of IPMI (for example, we have need
+for >255 sensors), as well as the hardware channels that IPMI typically uses.
-This design aims to use the Management Component Transport Protocol
-(MCTP) to provide a common transport layer over the multiple channels
-that OpenBMC platforms provide. Then, on top of MCTP, we have the
-opportunity to move to newer host/BMC messaging protocols to overcome
-some of the limitations we've encountered with IPMI.
+This design aims to use the Management Component Transport Protocol (MCTP) to
+provide a common transport layer over the multiple channels that OpenBMC
+platforms provide. Then, on top of MCTP, we have the opportunity to move to
+newer host/BMC messaging protocols to overcome some of the limitations we've
+encountered with IPMI.
## Background and References
-Separating the "transport" and "messaging protocol" parts of the current
-stack allows us to design these parts separately. Currently, IPMI
-defines both of these; we currently have BT and KCS (both defined as
-part of the IPMI 2.0 standard) as the transports, and IPMI itself as the
-messaging protocol.
+Separating the "transport" and "messaging protocol" parts of the current stack
+allows us to design these parts separately. Currently, IPMI defines both of
+these; we currently have BT and KCS (both defined as part of the IPMI 2.0
+standard) as the transports, and IPMI itself as the messaging protocol.
-Some efforts of improving the hardware transport mechanism of IPMI have
-been attempted, but not in a cross-implementation manner so far. This
-does not address some of the limitations of the IPMI data model.
+Some efforts of improving the hardware transport mechanism of IPMI have been
+attempted, but not in a cross-implementation manner so far. This does not
+address some of the limitations of the IPMI data model.
-MCTP defines a standard transport protocol, plus a number of separate
-physical layer bindings for the actual transport of MCTP packets. These
-are defined by the DMTF's Platform Management Working group; standards
-are available at:
+MCTP defines a standard transport protocol, plus a number of separate physical
+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
@@ -42,95 +39,88 @@
-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 I2C, PCI, Serial or custom hardware channel, without the
-higher layers of that stack needing to be aware of the hardware
-implementation. These higher levels only need to be aware that they are
-communicating with a certain entity, defined by an Entity ID (MCTP EID).
-These entities may be any element of the platform that communicates
-over MCTP - for example, the host device, the BMC, or any other
-system peripheral - static or hot-pluggable.
+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
+I2C, PCI, Serial or custom hardware channel, without the higher layers of that
+stack needing to be aware of the hardware implementation. These higher levels
+only need to be aware that they are communicating with a certain entity, defined
+by an Entity ID (MCTP EID). These entities may be any element of the platform
+that communicates over MCTP - for example, the host device, the BMC, or any
+other system peripheral - static or hot-pluggable.
-This document is focused on the "transport" part of the platform design.
-While this does enable new messaging protocols (mainly PLDM), those
-components are not covered in detail much; we will propose those parts
-in separate design efforts. For example, the PLDM design at
-[pldm-stack.md].
+This document is focused on the "transport" part of the platform design. While
+this does enable new messaging protocols (mainly PLDM), those components are not
+covered in detail much; we will propose those parts in separate design efforts.
+For example, the PLDM design at [pldm-stack.md].
-As part of the design, the references to MCTP "messages" and "packets"
-are intentional, to match the definitions in the MCTP standard. MCTP
-messages are the higher-level data transferred between MCTP endpoints,
-which packets are typically smaller, and are what is sent over the
-hardware. Messages that are larger than the hardware Maximum Transmit
-Unit (MTU) are split into individual packets by the transmit
-implementation, and reassembled at the receive implementation.
+As part of the design, the references to MCTP "messages" and "packets" are
+intentional, to match the definitions in the MCTP standard. MCTP messages are
+the higher-level data transferred between MCTP endpoints, which packets are
+typically smaller, and are what is sent over the hardware. Messages that are
+larger than the hardware Maximum Transmit Unit (MTU) are split into individual
+packets by the transmit implementation, and reassembled at the receive
+implementation.
## Requirements
Any channel between host and BMC should:
- - Have a simple serialisation and deserialisation format, to enable
- implementations in host firmware, which have widely varying runtime
- capabilities
+- Have a simple serialisation and deserialisation format, to enable
+ implementations in host firmware, which have widely varying runtime
+ capabilities
- - Allow different hardware channels, as we have a wide variety of
- target platforms for OpenBMC
+- Allow different hardware channels, as we have a wide variety of target
+ platforms for OpenBMC
- - Be usable over simple hardware implementations, but have a facility
- for higher bandwidth messaging on platforms that require it.
+- Be usable over simple hardware implementations, but have a facility for higher
+ bandwidth messaging on platforms that require it.
- - Ideally, integrate with newer messaging protocols
+- Ideally, integrate with newer messaging protocols
## Proposed Designs
The MCTP infrastrcuture in OpenBMC is implemented in two approaches:
- - A userspace-based approach, using a core library, plus a
- demultiplexing daemon. This is described in [MCTP
- Userspace](mctp-userspace.md).
+- A userspace-based approach, using a core library, plus a demultiplexing
+ daemon. This is described in [MCTP Userspace](mctp-userspace.md).
- This is in use by a few platforms, but should be avoided for new
- designs.
+ This is in use by a few platforms, but should be avoided for new designs.
- - A kernel-based approach, using a sockets API for client and server
- applications. This approach is recommended for new designs, and is
- described in [MCTP Kernel](mctp-kernel.md)
+- A kernel-based approach, using a sockets API for client and server
+ applications. This approach is recommended for new designs, and is described
+ in [MCTP Kernel](mctp-kernel.md)
-Design details for both approaches are covered in their relevant
-documents, but both share the same Problem Description, Background and
-Requirements, Alternatives and Impacts sections as defined by this
-document.
+Design details for both approaches are covered in their relevant documents, but
+both share the same Problem Description, Background and Requirements,
+Alternatives and Impacts sections as defined by this document.
## Alternatives Considered
-There have been two main alternatives to an MCTP implementation in
-OpenBMC:
+There have been two main alternatives to an MCTP implementation in OpenBMC:
-Continue using IPMI, but start making more use of OEM extensions to
-suit the requirements of new platforms. However, given that the IPMI
-standard is no longer under active development, we would likely end up
-with a large amount of platform-specific customisations. This also does
-not solve the hardware channel issues in a standard manner.
+Continue using IPMI, but start making more use of OEM extensions to suit the
+requirements of new platforms. However, given that the IPMI standard is no
+longer under active development, we would likely end up with a large amount of
+platform-specific customisations. This also does not solve the hardware channel
+issues in a standard manner.
-Redfish between host and BMC. This would mean that host firmware needs a
-HTTP client, a TCP/IP stack, a JSON (de)serialiser, and support for
-Redfish schema. While this may be present in some environments (for
-example, UEFI-based firmware), this is may not be feasible for all host
-firmware implementations (for example, OpenPOWER). It's possible that we
-could run a simplified Redfish stack - indeed, MCTP has a proposal for a
-Redfish-over-MCTP channel (DSP0218), which uses simplified serialisation
-format and no requirement on HTTP. However, this may involve a large
-amount of complexity in host firmware.
+Redfish between host and BMC. This would mean that host firmware needs a HTTP
+client, a TCP/IP stack, a JSON (de)serialiser, and support for Redfish schema.
+While this may be present in some environments (for example, UEFI-based
+firmware), this is may not be feasible for all host firmware implementations
+(for example, OpenPOWER). It's possible that we could run a simplified Redfish
+stack - indeed, MCTP has a proposal for a Redfish-over-MCTP channel (DSP0218),
+which uses simplified serialisation format and no requirement on HTTP. However,
+this may involve a large amount of complexity in host firmware.
## Impacts
-Development would be required to implement the MCTP transport, plus any
-new users of the MCTP messaging (eg, a PLDM implementation). These would
-somewhat duplicate the work we have in IPMI handlers.
+Development would be required to implement the MCTP transport, plus any new
+users of the MCTP messaging (eg, a PLDM implementation). These would somewhat
+duplicate the work we have in IPMI handlers.
-We'd want to keep IPMI running in parallel, so the "upgrade" path should
-be fairly straightforward.
+We'd want to keep IPMI running in parallel, so the "upgrade" path should be
+fairly straightforward.
-Design and development needs to involve potential host, management
-controllers and managed device implementations.
+Design and development needs to involve potential host, management controllers
+and managed device implementations.
diff --git a/designs/multi-host-postcode.md b/designs/multi-host-postcode.md
index cc2e9f1..7529f82 100644
--- a/designs/multi-host-postcode.md
+++ b/designs/multi-host-postcode.md
@@ -16,20 +16,14 @@
## Background and References
-The below component diagram shows the design for single-host postcode and history at
-high-level overview. The single-host design is updated slightly from the
-original to better comply with community conventions (using suffix 0 on D-Bus
-objects).
+The below component diagram shows the design for single-host postcode and
+history at high-level overview. The single-host design is updated slightly from
+the original to better comply with community conventions (using suffix 0 on
+D-Bus objects).
-Diagram Legend:
-|Label|Signifies|
-|-----|---------|
-|`I:` |D-Bus interface|
-|`S:` |D-Bus service name (well-known bus name)|
-|`R:` |Repository name|
-|`U:` |Systemd service unit name|
-|`A:` |Executable name|
-|`H:` |HW Module|
+Diagram Legend: |Label|Signifies| |-----|---------| |`I:` |D-Bus interface|
+|`S:` |D-Bus service name (well-known bus name)| |`R:` |Repository name| |`U:`
+|Systemd service unit name| |`A:` |Executable name| |`H:` |HW Module|
```
+-----------+
@@ -76,14 +70,14 @@
## Requirements
- - Read postcode from all servers.
- - Display the host postcode to the 7 segment display based on host position
- selection.
- - Provide a command interface for user to see any server(multi-host) current
- postcode.
- - Provide a command interface for user to see any server(multi-host) postcode
- history.
- - Support for hot-plug-able host.
+- Read postcode from all servers.
+- Display the host postcode to the 7 segment display based on host position
+ selection.
+- Provide a command interface for user to see any server(multi-host) current
+ postcode.
+- Provide a command interface for user to see any server(multi-host) postcode
+ history.
+- Support for hot-plug-able host.
## Proposed Design
@@ -95,14 +89,15 @@
Following modules will be updated for this implementation
- - phosphor-host-postd.
- - phosphor-post-code-manager.
- - platform specific OEM handler (fb-ipmi-oem).
- - bmcweb (redfish logging service).
+- phosphor-host-postd.
+- phosphor-post-code-manager.
+- platform specific OEM handler (fb-ipmi-oem).
+- bmcweb (redfish logging service).
**Interface Diagram**
Provided below the post code interface diagram with flow sequence
+
```
+---------------------------------------------------+
| BMC |
@@ -150,42 +145,42 @@
**Postcode Flow:**
- - BMC power-on the host.
- - Host starts sending the postcode IPMI message continuously to the BMC.
- - The ipmbbridged (phosphor-ipmi-ipmb) passes along the message to IPMI daemon.
- - The ipmid (phosphor-ipmi-host) appends host information with postcode and
- writes value to appropriate D-Bus object hosted by phosphor-host-postd.
- - phosphor-host-postd displays postcode in the seven segment display based on
- host position reads through D-bus interface.
- - phosphor-post-code-manager receives new POST codes via D-Bus signal and
- stores the postcode as history in the /var directory.
+- BMC power-on the host.
+- Host starts sending the postcode IPMI message continuously to the BMC.
+- The ipmbbridged (phosphor-ipmi-ipmb) passes along the message to IPMI daemon.
+- The ipmid (phosphor-ipmi-host) appends host information with postcode and
+ writes value to appropriate D-Bus object hosted by phosphor-host-postd.
+- phosphor-host-postd displays postcode in the seven segment display based on
+ host position reads through D-bus interface.
+- phosphor-post-code-manager receives new POST codes via D-Bus signal and stores
+ the postcode as history in the /var directory.
-## Platform Specific OEM Handler (fb-ipmi-oem)
+## Platform Specific OEM Handler (fb-ipmi-oem)
-This library is part of the [phosphor-ipmi-host](https://github.com/openbmc/phosphor-host-ipmid)
-and gets the postcode from host through
+This library is part of the
+[phosphor-ipmi-host](https://github.com/openbmc/phosphor-host-ipmid) and gets
+the postcode from host through
[phosphor-ipmi-ipmb](https://github.com/openbmc/ipmbbridge).
- - Register IPMI OEM postcode callback handler.
- - Extract postcode from IPMI message (phosphor-ipmi-host/phosphor-ipmi-ipmb).
- - Sets `Value` property on appropriate D-Bus `Raw` object hosted by
- `phosphor-host-postd`. Other programs (e.g. `phosphor-post-code-manager`) can
- subscribe to `PropertiesChanged` signals on this object to get the updates.
+- Register IPMI OEM postcode callback handler.
+- Extract postcode from IPMI message (phosphor-ipmi-host/phosphor-ipmi-ipmb).
+- Sets `Value` property on appropriate D-Bus `Raw` object hosted by
+ `phosphor-host-postd`. Other programs (e.g. `phosphor-post-code-manager`) can
+ subscribe to `PropertiesChanged` signals on this object to get the updates.
## phosphor-host-postd
This implementation involves the following changes in the phosphor-host-postd.
- - `phosphor-host-postd` handles property set events for the `Value` property on
- each instance of the `xyz.openbmc_project.State.Boot.Raw` interface.
- - phosphor-host-postd reads the host selection from the dbus property.
- - Display the latest postcode of the selected host read through D-Bus on a
- 7-segment display.
+- `phosphor-host-postd` handles property set events for the `Value` property on
+ each instance of the `xyz.openbmc_project.State.Boot.Raw` interface.
+- phosphor-host-postd reads the host selection from the dbus property.
+- 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.
+The following D-Bus names need to be created for the multi-host post-code.
Service name -- xyz.openbmc_project.State.Boot.Raw
@@ -195,21 +190,21 @@
## phosphor-post-code-manager
-The phosphor-post-code-manager is a multi service design for multi-host.
-The single host postcode handling D-bus naming conventions will be updated
-to comply with the community naming scheme.
+The phosphor-post-code-manager is a multi service design for multi-host. The
+single host postcode handling D-bus naming conventions will be updated to comply
+with the community naming scheme.
- - Create D-Bus service names for single-host and multi-host system
- accordingly. The community follows conventions Host0 for single host
- and Host1 to N for multi-host.
- - phosphor-post-code-manager subscribes to changes on the `Raw<N>` object
- hosted by `phosphor-host-postd`.
- - 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.
+- Create D-Bus service names for single-host and multi-host system accordingly.
+ The community follows conventions Host0 for single host and Host1 to N for
+ multi-host.
+- phosphor-post-code-manager subscribes to changes on the `Raw<N>` object hosted
+ by `phosphor-host-postd`.
+- 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.
+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)
@@ -218,18 +213,19 @@
Interface name -- xyz.openbmc_project.State.Boot.PostCode
## bmcweb
- The postcode history needs to be handled for the multi-host through
- redfish logging service.
+
+The postcode history needs to be handled for the multi-host through redfish
+logging service.
## Alternate design
**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.
+This implementation consider single service to handle multi-host postcode. In
+this approach, all D-Bus handling will taken care by the single process.
- Single service is different than existing x86-power-control and obmc-console
- where multi-service approach is used.
+Single service is different than existing x86-power-control and obmc-console
+where multi-service approach is used.
- Multi-service approach is more scalable to handle multi-host than
- the single service.
+Multi-service approach is more scalable to handle multi-host than the single
+service.
diff --git a/designs/multihost-ipmi-design.md b/designs/multihost-ipmi-design.md
index 1970f4e..d2855e4 100644
--- a/designs/multihost-ipmi-design.md
+++ b/designs/multihost-ipmi-design.md
@@ -1,30 +1,31 @@
# Multi-host IPMI design
-Author:
- Velumani T(velu), [velumanit@hcl](mailto:velumanit@hcl.com)
- Kumar T(kumar_t), [thangavel.k@hcl.com](mailto:thangavel.k@hcl.com)
+Author: Velumani T(velu), [velumanit@hcl](mailto:velumanit@hcl.com) Kumar
+T(kumar_t), [thangavel.k@hcl.com](mailto:thangavel.k@hcl.com)
Other contributors:
-Created:
- June 26, 2020
+Created: June 26, 2020
## Problem Description
+
The current version of OpenBMC does not support multi-host implementation in
-IPMI commands handling. We have a multi-host system and proposing the design
-to support multi-host.
+IPMI commands handling. We have a multi-host system and proposing the design to
+support multi-host.
As detailed below the hosts are connected in the IPMB interface, all host
related communication is based on IPMB. The OpenBMC uses ipmbbridged to manage
IPMB buses and the IPMB messages are routed to ipmid.
-Issue 1: ipmbridged does not send the channel number (ie HostId)
-Issue 2: ipmid does not have the information on which IPMB channel the request
-has come from. The ipmid handlers should have the host details to fetch the
-host specific responses.
+Issue 1: ipmbridged does not send the channel number (ie HostId) Issue 2: ipmid
+does not have the information on which IPMB channel the request has come from.
+The ipmid handlers should have the host details to fetch the host specific
+responses.
## Background and References
+
IPMI and IPMB System architecture:
+
```
+------------------------------------+
| BMC |
@@ -49,106 +50,78 @@
| +-----------+ +------------+ | +--------+
+------------------------------------+
```
+
Hosts are connected with IPMB interface, the hosts can be 1 to N. The IPMB
-request coming from the hosts are routed to ipmid by the ipmbbridged.
-The IPMB requests are routed from ipmid or any service by D-Bus interface and
-The outgoing IPMB requests are routed by ipmbbridged to IPMB interface.
+request coming from the hosts are routed to ipmid by the ipmbbridged. The IPMB
+requests are routed from ipmid or any service by D-Bus interface and The
+outgoing IPMB requests are routed by ipmbbridged to IPMB interface.
## Requirements
The current version of OpenBMC does not support multi-host implementation in
-IPMI commands handling. We have a multi-host system and proposing the design
-to support multi-host.
+IPMI commands handling. We have a multi-host system and proposing the design to
+support multi-host.
## Proposed Design
To address issue1 and issue2, we propose the following design changes in
-ipmbbridged and ipmid.
-To address out-of-band IPMI command from the network,the proposal is captured
-in section "Changes in netipmid".
+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**
-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 will send '"devIndex": 0' as optional parameter(options) in D-Bus
-interface to ipmid.This can be used to get the information on which IPMB bus
-the message comes from.
+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
+will send '"devIndex": 0' as optional parameter(options) in D-Bus interface to
+ipmid.This can be used to get the information on which IPMB bus the message
+comes from.
The json file looks like below. Each devIndex can have one "me" and "ipmb"
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
-},
+{ "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
passed to the command handlers in both common and oem handlers.The command
handlers can make use of the host information to fetch host specific data.
-For example, host1 send a request to get boot order from BMC, BMC maintains
-data separately for each host. When this command comes to ipmid the commands
-handler gets the host in which the command received. The handler will fetch
-host1 boot order details and respond from the command handler. This is
-applicable for both common and oem handlers.
+For example, host1 send a request to get boot order from BMC, BMC maintains data
+separately for each host. When this command comes to ipmid the commands handler
+gets the host in which the command received. The handler will fetch host1 boot
+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.
-The netipmid sends the "devIndex" on which channel the request comes from.
-There will not be any further changes required in ipmid.
-The netipmid can have multiple approaches to handle multi-host.Some of the
-approaches are listed down and but not limited to this list.
+The netipmid sends the "devIndex" on which channel the request comes from. There
+will not be any further changes required in ipmid. The netipmid can have
+multiple approaches to handle multi-host.Some of the approaches are listed down
+and but not limited to this list.
+
1. Virtual Ethernet interfaces - One virtual interface per host.
2. Different port numbers - Can have different port numbers for each host.
-3. VLAN Ids- VLAN IDs can be used to support multi host.
-The netipmid shall have a config file where in the interfaces can be configured
-for each host. Also one or more interfaces can be configured to each of the
-host. The interfaces can be virtual or physical.
-Below is the sample configuration file
+3. VLAN Ids- VLAN IDs can be used to support multi host. The netipmid shall have
+ a config file where in the interfaces can be configured for each host. Also
+ one or more interfaces can be configured to each of the host. The interfaces
+ can be virtual or physical. Below is the sample configuration file
-{"Host":1,
-"Interface-1":"eth0",
-"Interface-2":"eth1",
-"Interface-3":"veth4",
-"Interface-4":"veth5"
-},
-{"Host":2,
-"Interface-1":"eth2",
-"Interface-2":"eth3",
-"Interface-3":"veth1",
-"Interface-4":"veth2"
-},
+{"Host":1, "Interface-1":"eth0", "Interface-2":"eth1", "Interface-3":"veth4",
+"Interface-4":"veth5" }, {"Host":2, "Interface-1":"eth2", "Interface-2":"eth3",
+"Interface-3":"veth1", "Interface-4":"veth2" },
Example implementation of approach1:Virtual ethernet interface.
@@ -174,27 +147,28 @@
| +--------+ +-----------+ +------+ | +--------+
+--------------------------------------------+
```
-In the above diagram one instance of netipmid runs per host. Each instance
-is tied to one virtual ethernet interface, The virtual interface ID can be
-used to make a devIndex. This represents the HostId.
+
+In the above diagram one instance of netipmid runs per host. Each instance is
+tied to one virtual ethernet interface, The virtual interface ID can be used to
+make a devIndex. This represents the HostId.
## Alternatives Considered
-Approach1:ipmbbridged to send host-id in the payload
--
+## Approach1:ipmbbridged to send host-id in the payload
+
The ipmbbridged shall be modified to send the host id in data payload. This
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.
--
-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.
+## Approach2:Create multiple ipmid to handle multihost.One ipmid process per host.
-Approach3:Using a different IPMI channel for handling multiple 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.
+
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
multiple instances of ipmbbridged and each instance will be registered with the
@@ -208,9 +182,9 @@
## Testing
-The proposed design can be tested in a platform in which the multiple hosts
-are connected.The commands requests are received from all the hosts and
-responses are host specific data.When the request coming from the host as IPMB
-command, ipmbbridged appends devIndex and ipmid receives the respective
-devIndex.ipmid responds based on the received devIndex(Host Id) and
-response reaches all the way to host.The data can be validated in host.
+The proposed design can be tested in a platform in which the multiple hosts are
+connected.The commands requests are received from all the hosts and responses
+are host specific data.When the request coming from the host as IPMB command,
+ipmbbridged appends devIndex and ipmid receives the respective devIndex.ipmid
+responds based on the received devIndex(Host Id) and response reaches all the
+way to host.The data can be validated in host.
diff --git a/designs/multihost-phosphor-buttons.md b/designs/multihost-phosphor-buttons.md
index 5a218e9..4d2fbca 100644
--- a/designs/multihost-phosphor-buttons.md
+++ b/designs/multihost-phosphor-buttons.md
@@ -1,39 +1,38 @@
# Multi-host front panel phosphor buttons interface
-Author:
- Velumani T(velu), [velumanit@hcl](mailto:velumanit@hcl.com)
- Naveen Moses S(naveen.moses), [naveen.mosess@hcl.com](mailto:naveen.mosess@hcl.com)
+Author: Velumani T(velu), [velumanit@hcl](mailto:velumanit@hcl.com) Naveen Moses
+S(naveen.moses), [naveen.mosess@hcl.com](mailto:naveen.mosess@hcl.com)
Other contributors:
-Created:
- August 3, 2021
+Created: August 3, 2021
## Problem Description
-Phosphor buttons module has currently option to monitor gpio events of power
-and reset buttons and trigger power event handlers.
-phosphor-buttons currently only support push type buttons.support for
-different form factor inputs such as switches/MUX other than push type
-buttons are needed for some hardwares. It will be helpful if we could
-add option to support additional input types in phosphor button interfaces
-and event handling.
+Phosphor buttons module has currently option to monitor gpio events of power and
+reset buttons and trigger power event handlers.
-Currently handler events are only based on monitoring gpio events
-as input (power and reset).There may be cases where we need to create
-button interface which monitors non gpio events
-and triggers button actions for example events based on dbus property changes.
+phosphor-buttons currently only support push type buttons.support for different
+form factor inputs such as switches/MUX other than push type buttons are needed
+for some hardwares. It will be helpful if we could add option to support
+additional input types in phosphor button interfaces and event handling.
+
+Currently handler events are only based on monitoring gpio events as input
+(power and reset).There may be cases where we need to create button interface
+which monitors non gpio events and triggers button actions for example events
+based on dbus property changes.
## Requirements
+
This feature is needed to support additional phosphor button interfaces
corresponding to platform specific hardware buttons/MUX/Switches which are
available in the front panel apart from existing power and reset button
interfaces.
## Background and References
-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.
+
+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.
```
+----------------------------------------------+
@@ -52,11 +51,11 @@
+----------------------------------------------+
```
-platform specific front panel may contain additional hardware buttons or
-mux switch
+platform specific front panel may contain additional hardware buttons or mux
+switch
-example for a multihost platform yosemite-V2 it has host selector switch mux
-as additional button in front panel.
+example for a multihost platform yosemite-V2 it has host selector switch mux as
+additional button in front panel.
```
+---------------------------+ +------------+
@@ -90,43 +89,43 @@
```
-There are two additional hardware buttons/switch available in the
-frontpanel for yv2.
+There are two additional hardware buttons/switch available in the frontpanel for
+yv2.
## 1.Host selector switch (selector switch)
+
This host selector switch/selector switch has 4 gpio connected as input and
-based on the gpio state values the host selector switch value is derived.
-The possible switch values can vary from 0 to 10.
-The specific mapping between gpio values and host selector values
-can be stored as part of gpio json config.
+based on the gpio state values the host selector switch value is derived. The
+possible switch values can vary from 0 to 10. The specific mapping between gpio
+values and host selector values can be stored as part of gpio json config.
-yosemiteV2 platform has 1 bmc and 4 hosts and only one power button and
-reset button.
+yosemiteV2 platform has 1 bmc and 4 hosts and only one power button and reset
+button.
-For example, when the power button is pressed,
-The value of the host selector switch position(1 to 10) decides whether the
-power button action is needs to be triggered for bmc or any one of the
-hosts.
+For example, when the power button is pressed, The value of the host selector
+switch position(1 to 10) decides whether the power button action is needs to be
+triggered for bmc or any one of the hosts.
This option is to use same power button and reset button for multiple hosts.
-The power/reset button press events are triggered based on the value of
-host selector switch position.
+The power/reset button press events are triggered based on the value of host
+selector switch position.
### 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 selector position value = 2,host 2 is mapped to power and reset buttons
-host selector position value = 3,host 3 is mapped to power and reset buttons
-host selector position value = 4,host 4 is mapped to power and reset buttons
+
+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
+selector position value = 2,host 2 is mapped to power and reset buttons host
+selector position value = 3,host 3 is mapped to power and reset buttons host
+selector position value = 4,host 4 is mapped to power and reset buttons
## 2.Serial console MUX switch
-There is also uart console for each host and bmc which is connected via a
-MUX switch.
+There is also uart console for each host and bmc which is connected via a MUX
+switch.
-At a time any one of the device (either bmc or any one host) can be accessed
-via the console which is based on the UART MUX switch configuration.
+At a time any one of the device (either bmc or any one host) can be accessed via
+the console which is based on the UART MUX switch configuration.
Based on the position of the host selector switch, a separate handler interface
can configure the respective serial console device is selected.
@@ -135,101 +134,104 @@
An OCP debug card can be connected to yosemitev2 via usb for debugging purpose.
-This is a extension which has three buttons :
-1.Power button
-2.reset button
+This is a extension which has three buttons : 1.Power button 2.reset button
3.host selector button
-Power and reset buttons are mapped to the same gpio of frontpanel so no
-separate event handling is required.
+Power and reset buttons are mapped to the same gpio of frontpanel so no separate
+event handling is required.
-The host selector button purpose is same as that of the front panel
-host selector switch in yosemitev2 front panel. The debug card host selector
-button (push button) has different gpio lines than that of front panel
-host selector switch gpios.
-Whenever the debug host selector button is pressed the host
-selector switch position value should be increased up to MaxPosition.
-If the host selector switch value is more than MaxPosition then it
-should be reset to zero.
+The host selector button purpose is same as that of the front panel host
+selector switch in yosemitev2 front panel. The debug card host selector button
+(push button) has different gpio lines than that of front panel host selector
+switch gpios. Whenever the debug host selector button is pressed the host
+selector switch position value should be increased up to MaxPosition. If the
+host selector switch value is more than MaxPosition then it should be reset to
+zero.
# Proposed Design
+
Three high level changes are required in the phosphor button interface class
-1. Add support for adding button interfaces which are monitoring more than
- one gpio event and process with single event handler.
+1. Add support for adding button interfaces which are monitoring more than one
+ gpio event and process with single event handler.
-2. Add support to monitor button / switch interface event based on dbus
-property changes (needed for serial console MUX).
+2. Add support to monitor button / switch interface event based on dbus property
+ changes (needed for serial console MUX).
3. Each button interface class can be extended with the following overridable
-methods to allow platform specific logic if needed in a derived class.
+ methods to allow platform specific logic if needed in a derived class.
-- init() - This method may have gpio configuration and
- event handler initialization.
+- init() - This method may have gpio configuration and event handler
+ initialization.
-- handleEvent() - This method may have custom event handling
- routines for the respective button interface.This should be
- be called from the main even handler function.
+- handleEvent() - This method may have custom event handling routines for the
+ respective button interface.This should be be called from the main even
+ handler function.
## The host selector switch interface
-The host selector switch has 4 gpios associated with it. host selector
-switch button interface monitors these 4 gpio io events as sd-event
-based event loop and a single event handler function is called for
-all 4 gpio events.
+The host selector switch has 4 gpios associated with it. host selector switch
+button interface monitors these 4 gpio io events as sd-event based event loop
+and a single event handler function is called for all 4 gpio events.
-Based on the 4 gpio state values, the host selector switch position value
-is derived and stored as a dbus property with name "Position".
+Based on the 4 gpio state values, the host selector switch position value is
+derived and stored as a dbus property with name "Position".
### Host selector dbus interface details
- 1. Position(property) - This is the property which holds the current
- value of the host selector switch based on the GPIO state.
- 2. MaxPosition(property) - This is the property which keeps the maximum
- number of Position the Position property can hold.(This value is based
- on the number of hosts available in the platform)
+1. Position(property) - This is the property which holds the current value of
+ the host selector switch based on the GPIO state.
-## OCP Debug card host selector button interface
+2. MaxPosition(property) - This is the property which keeps the maximum number
+ of Position the Position property can hold.(This value is based on the number
+ of hosts available in the platform)
+
+## OCP Debug card host selector button interface
+
A separate interface for debug card host selector button is created.
-This button interface monitors the corresponding gpio lines for debug card
-host selection button press and release event via sd-event based loop.
+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 :
- 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.
- When the event handler is called once the button is released,
-then the host selector switch dbus property "Position" is increased by 1.
-The host selector switch dbus property value is rollover to zero after Position
-value exceeds MaxPosition Value.
+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.
-This way when power and reset button press events are handled,
-the Host selector Position property is referred and based on the
-Position respective power events are called.
+When the event handler is called once the button is released, then the host
+selector switch dbus property "Position" is increased by 1. The host selector
+switch dbus property value is rollover to zero after Position value exceeds
+MaxPosition Value.
-## serial console MUX interface
+This way when power and reset button press events are handled, the Host selector
+Position property is referred and based on the Position respective power events
+are called.
+
+## serial console MUX interface
+
This button interface monitors for change in host selector switch Position dbus
property and based on the dbus property value change, corresponding serial
-console is selected.mux value can be set as configuring 4 gpio lines dedicated
+console is selected.mux value can be set as configuring 4 gpio lines dedicated
for the serial console mux.
+
### Example
-0 - bmc serial console
-1 - host 1 serial console
-2 - host 2 serial console
-3 - host 3 serial console
-4 - host 4 serial console
+
+0 - bmc serial console 1 - host 1 serial console 2 - host 2 serial console 3 -
+host 3 serial console 4 - host 4 serial console
### Change in power button and reset button interface event handler
-If selector button instance is available,then the power button and reset
-button pressed events must route to appropriate multihost dbus service name
+
+If selector button instance is available,then the power button and reset button
+pressed events must route to appropriate multihost dbus service name
## Impacts
- The change impacts are under phosphor buttons repo,the existing power and
- reset button handlers are calling dbus calls for single host power events.
- This calls should be modified to adapt corresponding multi host power events
- and the respective host dbus object is based on host selector position.
+
+The change impacts are under phosphor buttons repo,the existing power and reset
+button handlers are calling dbus calls for single host power events. This calls
+should be modified to adapt corresponding multi host power events and the
+respective host dbus object is based on host selector position.
## Testing
-The proposed design can be tested in a platform in which the multiple hosts
-are connected.
+
+The proposed design can be tested in a platform in which the multiple hosts are
+connected.
diff --git a/designs/nmi-dbus-interface.md b/designs/nmi-dbus-interface.md
index 87d0087..ef4ee66 100644
--- a/designs/nmi-dbus-interface.md
+++ b/designs/nmi-dbus-interface.md
@@ -6,85 +6,91 @@
Created: 2019-05-21
-
## Problem Description
+
Currently, servers that use OpenBMC cannot have the ability to capture relevant
debug data when the host is unresponsive or hung. These systems need the ability
to diagnose the root cause of hang and perform recovery along with debugging
data collected.
-
## 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 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.
+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.
Whenever the host is unresponsive/running, Admin needs to trigger an NMI event
which, in turn, triggers an architecture-dependent procedure that fires an
interrupt on all the available processors on the system.
## Proposed Design for servers that use OpenBMC
+
This proposal aims to trigger NMI, which in turn will invoke an
-architecture-specific procedure that enables data collection followed by recovery
-of the Host. This will enable Host/OS development teams to analyze and fix any
-issues where they see host hang and unresponsive system.
+architecture-specific procedure that enables data collection followed by
+recovery of the Host. This will enable Host/OS development teams to analyze and
+fix any issues where they see host hang and unresponsive system.
### D-Bus
+
Introducing new D-Bus interface in the control.host namespace
(/openbmc/phosphor-dbus-interfaces/xyz/openbmc_project/Control/Host/
-NMI.interface.yaml)
-and implement the new D-Bus back-end for respective processor specific targets.
+NMI.interface.yaml) and implement the new D-Bus back-end for respective
+processor specific targets.
### BMC Support
+
Enable NMI D-Bus phosphor interface and support this via Redfish
### Redfish Schema used
-* Reference: DSP2046 2018.3,
-* ComputerSystem 1.6.0 schema provides an action called #ComputerSystem.Reset,
- This action is used to reset the system.
- The ResetType parameter is used for indicating the type of reset needs to be
- performed. In this case, we can use
+
+- Reference: DSP2046 2018.3,
+- ComputerSystem 1.6.0 schema provides an action called #ComputerSystem.Reset,
+ This action is used to reset the system. The ResetType parameter is used for
+ indicating the type of reset needs to be performed. In this case, we can use
An NMI type
- * Nmi: Generate a Diagnostic Interrupt (usually an NMI on x86 systems)
- to cease normal operations, perform diagnostic actions and typically
- halt the system.
+ - Nmi: Generate a Diagnostic Interrupt (usually an NMI on x86 systems) to
+ cease normal operations, perform diagnostic actions and typically halt the
+ system.
## High-Level Flow
-1. Host/OS is hung or unresponsive or one need to take kernel dump
- to debug some error conditions.
-2. Admin/User can use the Redfish URI ComputerSystem.Reset that allows
- POST operations and change the Action and ResetType properties to
+
+1. Host/OS is hung or unresponsive or one need to take kernel dump to debug some
+ error conditions.
+2. Admin/User can use the Redfish URI ComputerSystem.Reset that allows POST
+ operations and change the Action and ResetType properties to
{"Action":"ComputerSystem.Reset","ResetType":"Nmi"} to trigger NMI.
3. Redfish URI will invoke a D-Bus NMI back-end call which will use an arch
- specific back-end implementation of xyz.openbmc_project.Control.Host.NMI
- to trigger an NMI on all the processors on the system.
-4. On receiving the NMI, the host will automatically invoke Architecture specific
- actions. One such action could be; invoking the kdump followed by the reboot.
+ specific back-end implementation of xyz.openbmc_project.Control.Host.NMI to
+ trigger an NMI on all the processors on the system.
+4. On receiving the NMI, the host will automatically invoke Architecture
+ specific actions. One such action could be; invoking the kdump followed by
+ the reboot.
-* Note: NMI can be sent to the host in any state, not just at an unresponsive
+- Note: NMI can be sent to the host in any state, not just at an unresponsive
state.
## Alternatives Considered
-Extending the existing D-Bus interface state.Host namespace
+
+Extending the existing D-Bus interface state.Host namespace
(/openbmc/phosphor-dbus-interfaces/xyz/openbmc_project/State/Host.interface.yaml)
-to support new RequestedHostTransition property called Nmi.
-D-Bus back-end can internally invoke processor-specific target to invoke NMI
-and do associated actions.
+to support new RequestedHostTransition property called Nmi. D-Bus back-end can
+internally invoke processor-specific target to invoke NMI and do associated
+actions.
There were strong reasons to move away from the above approach.
phosphor-state-manager has always been focused on the states of the BMC,
-Chassis, and Host. NMI will be more of action against the host than
-a state.
+Chassis, and Host. NMI will be more of action against the host than a state.
## Impacts
-This implementation only needs to make some changes to the system state when
-NMI is initiated irrespective of what host OS state is in, so it has minimal
-impact on the rest of the system.
+
+This implementation only needs to make some changes to the system state when NMI
+is initiated irrespective of what host OS state is in, so it has minimal impact
+on the rest of the system.
## Testing
+
Depending on the platform hardware design, this test requires a host OS kernel
module driver to create hard lockup/hang and then check the scenario is good.
-Also, one can invoke NMI to get the crash dump and confirm HOST received NMI
-via console logs.
-
+Also, one can invoke NMI to get the crash dump and confirm HOST received NMI via
+console logs.
diff --git a/designs/nvmemi-over-smbus.md b/designs/nvmemi-over-smbus.md
index 714cf41..59b1684 100644
--- a/designs/nvmemi-over-smbus.md
+++ b/designs/nvmemi-over-smbus.md
@@ -1,10 +1,8 @@
### NVMe-MI over SMBus
-Author:
- Tony Lee <tony.lee@quantatw.com>
+Author: Tony Lee <tony.lee@quantatw.com>
-Created:
- 3-8-2019
+Created: 3-8-2019
#### Problem Description
@@ -17,9 +15,9 @@
#### Background and References
NVMe-MI specification defines a command called
-`NVM Express Basic Management Command` that can read the NVMe drives
-information via SMBus directly. [1]. This command uses SMBus Block Read
-protocol specified by the SMBus specification. [2].
+`NVM Express Basic Management Command` that can read the NVMe drives information
+via SMBus directly. [1]. This command uses SMBus Block Read protocol specified
+by the SMBus specification. [2].
For our purpose is retrieve NVMe drives information, therefore, using NVM
Express Basic Management Command where describe in NVMe-MI specification to
@@ -35,9 +33,9 @@
The implementation should:
-- Provide a daemon to monitor NVMe drives. Parameters to be monitored are
- Status Flags, SMART Warnings, Temperature, Percentage Drive Life Used, Vendor
- ID, and Serial Number.
+- Provide a daemon to monitor NVMe drives. Parameters to be monitored are Status
+ Flags, SMART Warnings, Temperature, Percentage Drive Life Used, Vendor ID, and
+ Serial Number.
- Provide a D-bus interface to allow other services to access data.
- Capability of communication over hardware channel I2C to NVMe drives.
- Ability to turn the fault LED on/off for each drive by SmartWarnings if the
@@ -47,10 +45,9 @@
Create a D-bus service "xyz.openbmc_project.nvme.manager" with object paths for
each NVMe sensor: "/xyz/openbmc_project/sensors/temperature/nvme0",
-"/xyz/openbmc_project/sensors/temperature/nvme1", etc.
-There is a JSON configuration file for drive index, bus ID, and the fault LED
-object path for each drive.
-For example,
+"/xyz/openbmc_project/sensors/temperature/nvme1", etc. There is a JSON
+configuration file for drive index, bus ID, and the fault LED object path for
+each drive. For example,
```json
{
@@ -79,8 +76,7 @@
└─/xyz/openbmc_project/sensors/temperature/nvme0
```
-/xyz/openbmc_project/sensors/temperature/nvme0
-Which implements:
+/xyz/openbmc_project/sensors/temperature/nvme0 Which implements:
- xyz.openbmc_project.Sensor.Value
- xyz.openbmc_project.Sensor.Threshold.Warning
@@ -97,8 +93,8 @@
└─/xyz/openbmc_project/inventory/system/chassis/motherboard/nvme0
```
-/xyz/openbmc_project/inventory/system/chassis/motherboard/nvme0
-Which implements:
+/xyz/openbmc_project/inventory/system/chassis/motherboard/nvme0 Which
+implements:
- xyz.openbmc_project.Inventory.Item
- xyz.openbmc_project.Inventory.Decorator.Asset
@@ -107,44 +103,44 @@
Interface `xyz.openbmc_project.Sensor.Value`, it's for hwmon to monitor
temperature and with the following properties:
-| Property | Type | Description |
-| -------- | ---- | ----------- |
-| MaxValue | int64 | Sensor maximum value |
-| MinValue | int64 | Sensor minimum value |
-| Scale | int64 | Sensor value scale |
-| Unit | string | Sensor unit |
-| Value | int64 | Sensor value |
+| Property | Type | Description |
+| -------- | ------ | -------------------- |
+| MaxValue | int64 | Sensor maximum value |
+| MinValue | int64 | Sensor minimum value |
+| Scale | int64 | Sensor value scale |
+| Unit | string | Sensor unit |
+| Value | int64 | Sensor value |
Interface `xyz.openbmc_project.Nvme.Status` with the following properties:
-| Property | Type | Description |
-| -------- | ---- | ----------- |
-| SmartWarnings| string | Indicates smart warnings for the state |
-| StatusFlags | string | Indicates the status of the drives |
-| DriveLifeUsed | string | A vendor specific estimate of the percentage |
-| TemperatureFault| bool | If warning type about temperature happened |
-| BackupdrivesFault | bool | If warning type about backup drives happened |
-| CapacityFault| bool | If warning type about capacity happened |
-| DegradesFault| bool | If warning type about degrades happened |
-| MediaFault| bool | If warning type about media happened |
+| Property | Type | Description |
+| ----------------- | ------ | -------------------------------------------- |
+| SmartWarnings | string | Indicates smart warnings for the state |
+| StatusFlags | string | Indicates the status of the drives |
+| DriveLifeUsed | string | A vendor specific estimate of the percentage |
+| TemperatureFault | bool | If warning type about temperature happened |
+| BackupdrivesFault | bool | If warning type about backup drives happened |
+| CapacityFault | bool | If warning type about capacity happened |
+| DegradesFault | bool | If warning type about degrades happened |
+| MediaFault | bool | If warning type about media happened |
Interface `xyz.openbmc_project.Inventory.Item` with the following properties:
-| Property | Type | Description |
-| -------- | ---- | ----------- |
-| PrettyName| string | The human readable name of the item |
-| Present | bool | Whether or not the item is present |
+| Property | Type | Description |
+| ---------- | ------ | ----------------------------------- |
+| PrettyName | string | The human readable name of the item |
+| Present | bool | Whether or not the item is present |
Interface `xyz.openbmc_project.Inventory.Decorator.Asset` with the following
properties:
-| Property | Type | Description |
-| -------- | ---- | ----------- |
-| PartNumber| string | The item part number, typically a stocking number |
-| SerialNumber | string | The item serial number |
-| Manufacturer | string | The item manufacturer |
-| BuildDate| bool | The date of item manufacture in YYYYMMDD format |
-| Model | bool | The model of the item |
+| Property | Type | Description |
+| ------------ | ------ | ------------------------------------------------- |
+| PartNumber | string | The item part number, typically a stocking number |
+| SerialNumber | string | The item serial number |
+| Manufacturer | string | The item manufacturer |
+| BuildDate | bool | The date of item manufacture in YYYYMMDD format |
+| Model | bool | The model of the item |
##### xyz.openbmc_project.nvme.manager.service
@@ -156,15 +152,15 @@
LED object path from the json file mentioned above.
3. Each cycle will do following steps:
1. Check if the present pin of target drive is true, if true, means drive
- exists and go to next step. If not, means drive does not exists and
- remove object path from D-bus by drive index.
+ exists and go to next step. If not, means drive does not exists and remove
+ object path from D-bus by drive index.
2. Check if the power good pin of target drive is true, if true means drive
is ready then create object path by drive index and go to next step. If
not, means drive power abnormal, turn on fault LED and log in journal.
3. Send a NVMe-MI command via SMBus Block Read protocol by bus ID of target
- drive to get data. Data get from NVMe drives are "Status Flags",
- "SMART Warnings", "Temperature", "Percentage Drive Life Used",
- "Vendor ID", and "Serial Number".
+ drive to get data. Data get from NVMe drives are "Status Flags", "SMART
+ Warnings", "Temperature", "Percentage Drive Life Used", "Vendor ID", and
+ "Serial Number".
4. The data will be set to the properties in D-bus.
This service will run automatically and look up NVMe drives every second.
@@ -176,9 +172,8 @@
##### Add SEL related to NVMe
-The events `TemperatureFault`, `BackupdrivesFault`,
-`CapacityFault`, `DegradesFault` and `MediaFault` will be generated for the
-NVMe errors.
+The events `TemperatureFault`, `BackupdrivesFault`, `CapacityFault`,
+`DegradesFault` and `MediaFault` will be generated for the NVMe errors.
- Temperature Fault log : when the property `TemperatureFault` set to true
- Backupdrives Fault log : when the property `BackupdrivesFault` set to true
@@ -188,8 +183,8 @@
#### 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
+NVMe-MI specification defines multiple commands that can communicate with NVMe
+drives over MCTP protocol. The NVMe-MI over MCTP has the following key
capabilities:
- Discover drives that are present and learn capabilities of each drives.
@@ -209,17 +204,15 @@
#### 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 information and compare
-with the properties in D-bus to make sure they are the same.
-The testing can be performed on different NVMe drives by different
-manufacturers.
-For example: Intel P4500/P4600 and Micron 9200 Max/Pro.
+response data to D-bus. Testing will send SMBus command to the drives to get the
+information and compare with the properties in D-bus to make sure they are the
+same. The testing can be performed on different NVMe drives by different
+manufacturers. For example: Intel P4500/P4600 and Micron 9200 Max/Pro.
Unit tests will test by function:
-- It tests the length of responded data is as same as design in the function
-of getting NVMe information.
+- It tests the length of responded data is as same as design in the function of
+ getting NVMe information.
- It tests the function of setting values to D-bus is as same as design.
- It tests the function of turn the corresponding LED ON/OFF by different
-Smartwarnings values.
+ Smartwarnings values.
diff --git a/designs/oem/google/root_of_trust.md b/designs/oem/google/root_of_trust.md
index fab87fc..456b355 100644
--- a/designs/oem/google/root_of_trust.md
+++ b/designs/oem/google/root_of_trust.md
@@ -1,15 +1,13 @@
# Google Specific APIs - A New Service Root for Google
-Author:
- Feras Aldahlawi (faldahlawi)
+Author: Feras Aldahlawi (faldahlawi)
-Other contributors:
- None
+Other contributors: None
-Created:
- March 30, 2021
+Created: March 30, 2021
## Problem Description
+
Redfish API does not have a resource type that is similar to Google's Root of
Trust (RoT) chips. Google needs APIs that are not in the Redfish standard yet.
There are working groups dedicated to bring RoT chips support to the Redfish
@@ -18,21 +16,26 @@
Google needs for its new service root.
## Background and References
+
At Google, we rely on communicating with RoT chips using a variety of transport
mechanisms. Google wants to extend the support to include REST based APIs. The
-future of RoT devices at Google will adopt the [SPDM protocol](https://www.dmtf.org/sites/default/files/PMCI_Security-Architecture_12-11-2019.pdf).
+future of RoT devices at Google will adopt the
+[SPDM protocol](https://www.dmtf.org/sites/default/files/PMCI_Security-Architecture_12-11-2019.pdf).
However, this design doc is targeting a group of RoT devices that will never be
capable of supporting standards based interface.
## Requirements
+
- Create a new service root of Google specific APIs.
- Create a schema for a RootOfTrust resource.
- Be able to execute RoT actions (attestation etc) from the API.
## Proposed Design
+
A new service root under `google/v1`. This service root will contain a
collection of `RootOfTrust` entities that have the following properties and
Actions:
+
- Chip type string
- Unique Hardware id string
- Firmware version map string to string
@@ -53,6 +56,7 @@
This new service root is very similar to `/ibm/v1`. This would require a new
dbus interface to service this API:
+
```
description: >
Forward bytes to Google RoT devices.
@@ -71,43 +75,46 @@
```
## Alternatives Considered
+
Considered adding the new APIs as an OEM extension to the TPM resource. However,
it was an unnatural extension. Here are the reason why it is somewhat unnatural
to use TPM for Google's RoT:
- FirmwareVersion1/2
- * Somewhat closely fixed to the design of TPM. TPM 1.2 had 32-bit firmware
- version and TPM 2.0 extended it clumsily by just tacking on another firmware
- version 32-bit field.
- * TPM "Firmware 1" and "Firmware 2" together refer to the 64-bit firmware
- version number. Most TPM2.0 vendors divide this into 4 fields each 2 bytes
- wide: (big-endian, each character is a byte:) 0xMMmmrrbb (M major, m minor, r
- rev, b build). Infineon uses a different convention for firmware version
- numbers than the rest of the TPM vendors, reserving some bits and expressing
- only a 1-byte wide "build number" as 0xMMmm_rrb
- * These being exposed as a string out to the Redfish interface works for
- Google. But I am just trying to provide info on how uniform this currently
- is (not) within the TPM ecosystem.
+ - Somewhat closely fixed to the design of TPM. TPM 1.2 had 32-bit firmware
+ version and TPM 2.0 extended it clumsily by just tacking on another firmware
+ version 32-bit field.
+ - TPM "Firmware 1" and "Firmware 2" together refer to the 64-bit firmware
+ version number. Most TPM2.0 vendors divide this into 4 fields each 2 bytes
+ wide: (big-endian, each character is a byte:) 0xMMmmrrbb (M major, m minor,
+ r rev, b build). Infineon uses a different convention for firmware version
+ numbers than the rest of the TPM vendors, reserving some bits and expressing
+ only a 1-byte wide "build number" as 0xMMmm_rrb
+ - These being exposed as a string out to the Redfish interface works for
+ Google. But I am just trying to provide info on how uniform this currently
+ is (not) within the TPM ecosystem.
- InterfaceType
- * Currently closely fixed to the ecosystem of TPM variants.
- * Which flavor of TPM interface is implemented. TCM is the "China version"
- of TPM 1.2. The Chinese TPM switched over to TPM 2.0 after that version of the
- spec was available.
- * TPM 1.2 and 2.0 are entirely different API surfaces, analogous to the
- difference between any TPM and Google's RoT chips.
+ - Currently closely fixed to the ecosystem of TPM variants.
+ - Which flavor of TPM interface is implemented. TCM is the "China version" of
+ TPM 1.2. The Chinese TPM switched over to TPM 2.0 after that version of the
+ spec was available.
+ - TPM 1.2 and 2.0 are entirely different API surfaces, analogous to the
+ difference between any TPM and Google's RoT chips.
- InterfaceTypeSelection
- * Currently closely fixed to the ecosystem of TPM variants.
- * Some TPMs can be switched between TPM 1.2 and 2.0. This could be ignorable
- by Google unless Google start shipping an open sourced RoT that could be
- switched into a TPM mode via firmware update. (Which would be a good move)
+ - Currently closely fixed to the ecosystem of TPM variants.
+ - Some TPMs can be switched between TPM 1.2 and 2.0. This could be ignorable
+ by Google unless Google start shipping an open sourced RoT that could be
+ switched into a TPM mode via firmware update. (Which would be a good move)
Though we can put everything under TPM's OEM (e.g. version numbers and other
functionality), most of the fields will be unusable for Google's RoT.
## Impacts
+
New daemon, new Rest API.
## Testing
+
Testing will be done in Google internally. This feature should not impact CI
testing. We will try golden paths and bad paths. We will also implement fuzz
tests as well.
diff --git a/designs/oem/ibm/system-power-mode.md b/designs/oem/ibm/system-power-mode.md
index 097f56f..65a019a 100644
--- a/designs/oem/ibm/system-power-mode.md
+++ b/designs/oem/ibm/system-power-mode.md
@@ -1,117 +1,112 @@
# System Power Mode and Idle Power Saver Support
-Author:
-Chris Cain
+Author: Chris Cain
-Other contributors:
-Martha Broyles
+Other contributors: Martha Broyles
-Created:
-12/03/2020
+Created: 12/03/2020
## Problem Description
-Power management on POWER platforms needs assistance from the BMC for
-managing the system power mode and idle power save modes.
-We need the ability to set and query the system power mode and also
-the ability to control and set idle power save parameters.
-This design is only applicable to POWER processors.
+Power management on POWER platforms needs assistance from the BMC for managing
+the system power mode and idle power save modes. We need the ability to set and
+query the system power mode and also the ability to control and set idle power
+save parameters. This design is only applicable to POWER processors.
## Background and References
-Each POWER processor contains an embedded PowerPC 405 processor that is
-referred to as the On Chip Controller or OCC. The OCC provides real time
-power and thermal monitoring and control.
-When a system is powered on, the OCCs will go to an Active state.
-Anytime the OCC state changes to active, the BMC will need to send a
-mode change and idle power saver (IPS) settings to the OCC. It will also
+Each POWER processor contains an embedded PowerPC 405 processor that is referred
+to as the On Chip Controller or OCC. The OCC provides real time power and
+thermal monitoring and control. When a system is powered on, the OCCs will go to
+an Active state. Anytime the OCC state changes to active, the BMC will need to
+send a mode change and idle power saver (IPS) settings to the OCC. It will also
need to send the commands if the user changes the mode or idle power save
parameters.
## Requirements
-When a system is booted, the OCC will move to an ACTIVE state. In the
-ACTIVE state, the OCC is managing the processor frequency, power consumption,
-and monitoring the systems thermal sensors. For certain error conditions
-it may be necessary to reset the OCC. When this happens, the OCC will move
-out of ACTIVE state. After recovery, the OCC will be put back into the
-ACTIVE state.
-Anytime the OCC state changes to ACTIVE or the customer updates these new
-parameters at runtime, the BMC will need to send the mode and the idle
-power saver settings to the OCC.
+When a system is booted, the OCC will move to an ACTIVE state. In the ACTIVE
+state, the OCC is managing the processor frequency, power consumption, and
+monitoring the systems thermal sensors. For certain error conditions it may be
+necessary to reset the OCC. When this happens, the OCC will move out of ACTIVE
+state. After recovery, the OCC will be put back into the ACTIVE state. Anytime
+the OCC state changes to ACTIVE or the customer updates these new parameters at
+runtime, the BMC will need to send the mode and the idle power saver settings to
+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
Current Customer Settable System Power Modes that will be sent to the OCCs:
- - Static
- - Power Saver
- - Maximum Performance
-A proposal for adding Idle Power Saving parameters was submitted to the
-Redfish committee and will be used if/when approved.
+- Static
+- Power Saver
+- Maximum Performance
+
+A proposal for adding Idle Power Saving parameters was submitted to the Redfish
+committee and will be used if/when approved.
Customer Settable Idle Power Save Parameters:
- - Enabled / Disabled
- - Enter Delay Time (in seconds)
- - Enter Utilization threshold (percentage)
- - Exit Delay Time (in seconds)
- - Exit Utilization threshold (percentage)
+
+- Enabled / Disabled
+- Enter Delay Time (in seconds)
+- Enter Utilization threshold (percentage)
+- Exit Delay Time (in seconds)
+- Exit Utilization threshold (percentage)
Defaults will need to be configurable by the system owner (via JSON file)
## Proposed Design
-The new code would be part of the openpower-occ-control repository.
-New code will be triggered by the following:
- - OCC poll response data showing a new state of Active (0x03)
- - OCC Active sensor is enabled (may be covered in above bullet)
- - Customer updates system power mode user interface or Redfish interface
- - Customer updates idle power save setting or Redfish interface
-Code will need to trigger off of OCC state changes. The kernel currently
-sends a POLL command to the OCC periodically (every second). The OCC state
-is available in the OCC poll response data.
+The new code would be part of the openpower-occ-control repository. New code
+will be triggered by the following:
-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:
+- OCC poll response data showing a new state of Active (0x03)
+- OCC Active sensor is enabled (may be covered in above bullet)
+- Customer updates system power mode user interface or Redfish interface
+- Customer updates idle power save setting or Redfish interface
+
+Code will need to trigger off of OCC state changes. The kernel currently sends a
+POLL command to the OCC periodically (every second). The OCC state is available
+in the OCC poll response data.
+
+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
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
-parameters, these default values will be used. If/when the customer does
-set any of these, that new customer parameter will become current and the
-default value will no longer be used.
+parameters for the system. If the customer has not yet set any of these
+parameters, these default values will be used. If/when the customer does set any
+of these, that new customer parameter will become current and the default value
+will no longer be used.
-The customer requested PowerMode and Idle Power Saver parameters will
-be stored as D-Bus object in the phosphor-dbus-interfaces repository:
- xyz/openbmc_project/Control/Power/Mode.interface.yaml
-Once set, these values will be retained across power cycles, AC loss,
-code updates, etc.
+The customer requested PowerMode and Idle Power Saver parameters will be stored
+as D-Bus object in the phosphor-dbus-interfaces repository:
+xyz/openbmc_project/Control/Power/Mode.interface.yaml Once set, these values
+will be retained across power cycles, AC loss, code updates, etc.
## Alternatives Considered
-- Using hardcoded power mode and Idle Power Save parameters (no flexibility
-to control system power usage)
+
+- Using hardcoded power mode and Idle Power Save parameters (no flexibility to
+ control system power usage)
## Impacts
+
New interfaces that were described in the requirements section will be
-implemented. Parameters should be able to be set via user interface or
-via Redfish.
-API impact - Add Redfish support for new parameters as well as new user
+implemented. Parameters should be able to be set via user interface or via
+Redfish. API impact - Add Redfish support for new parameters as well as new user
interface to allow customer to set power mode and idle power saver settings
-Security impact - update of these parameters should be able to be restricted
-to specific users/groups (may not want any user updating these parameters)
-Documentation impact - need to document new parameters
-Performance impact - minimal, new code will only execute on OCC state change
-which should normally happen once at boot time or when user changes parameters.
-The new code is only sending 2 additional commands which should complete
-within a few seconds.
-Developer impact - code to be written by OCC team with guidance from
-OpenBMC power management team
-Upgradability impact - None
+Security impact - update of these parameters should be able to be restricted to
+specific users/groups (may not want any user updating these parameters)
+Documentation impact - need to document new parameters Performance impact -
+minimal, new code will only execute on OCC state change which should normally
+happen once at boot time or when user changes parameters. The new code is only
+sending 2 additional commands which should complete within a few seconds.
+Developer impact - code to be written by OCC team with guidance from OpenBMC
+power management team Upgradability impact - None
## Testing
-This will be able to be tested by directly updating the power mode and
-idle power saver setting.
-This testing will be automated
+
+This will be able to be tested by directly updating the power mode and idle
+power saver setting. This testing will be automated
diff --git a/designs/phosphor-audit.md b/designs/phosphor-audit.md
index f3cc378..86464ac 100644
--- a/designs/phosphor-audit.md
+++ b/designs/phosphor-audit.md
@@ -1,14 +1,12 @@
# 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
+Created: 2019-07-23
## Problem Description
@@ -22,8 +20,8 @@
changes. Currently, most changes leave no trace in OpenBMC logs, which hampers
the aforementioned investigation.
-It is required to develop a mechanism that would allow for tracking such
-user activity, logging it, and taking certain actions if necessary.
+It is required to develop a mechanism that would allow for tracking such user
+activity, logging it, and taking certain actions if necessary.
## Background and References
@@ -44,30 +42,30 @@
## Requirements
- * Provide a unified method of logging user actions independent of the user
- interface, where possible user actions are:
- * Redfish/REST PUT/POST/DELETE/PATCH
- * IPMI
- * PAM
- * PLDM
- * Any other suitable service
- * Provide a way to configure system response actions taken upon certain user
- actions, where possible response actions are:
- * Log an event
- * Notify an administrator or an arbitrary notification receiver
- * Run an arbitrary command
- * Provide a way to configure notification receivers:
- * E-mail
- * SNMP
- * Instant messengers
- * D-Bus
+- Provide a unified method of logging user actions independent of the user
+ interface, where possible user actions are:
+ - Redfish/REST PUT/POST/DELETE/PATCH
+ - IPMI
+ - PAM
+ - PLDM
+ - Any other suitable service
+- Provide a way to configure system response actions taken upon certain user
+ actions, where possible response actions are:
+ - Log an event
+ - Notify an administrator or an arbitrary notification receiver
+ - Run an arbitrary command
+- Provide a way to configure notification receivers:
+ - E-mail
+ - SNMP
+ - Instant messengers
+ - D-Bus
## Proposed Design
-The main idea is to catch D-Bus requests sent by user interfaces, then handle the
-request according to the configuration. In future, support for flexible policies
-may be implemented that would allow for better flexibility in handling and
-tracking.
+The main idea is to catch D-Bus requests sent by user interfaces, then handle
+the request according to the configuration. In future, support for flexible
+policies may be implemented that would allow for better flexibility in handling
+and tracking.
The phosphor-audit service represents a service that provides user activity
tracking and corresponding action taking in response of user actions.
@@ -113,21 +111,23 @@
be dropped at this moment and will no longer be processed. After the filter
check, the audit event call sends the data through D-Bus to the audit service
which makes a decision regarding next steps. Also, it caches list of possible
-commands (blacklist or whitelist) and status of its service (disabled or enabled).
-If the service in undefined state, the call checks if service alive or not.
+commands (blacklist or whitelist) and status of its service (disabled or
+enabled). If the service in undefined state, the call checks if service alive or
+not.
- > `audit_event(type, rc, request, user, host, data)`
- > * type - type of event source : IPMI, REST, PAM, etc.
- > * rc - return code of the handler event (status, rc, etc.)
- > * request - a generalized identifier of the event, e.g. ipmi command
- > (cmd/netfn/lun), web path, or anything else that can describe the event.
- > * user - the user account on behalf of which the event was processed.
- > depends on context, NA/None in case of user inaccessibility.
- > * source - identifier of the host that the event has originated from. This can
- > be literally "host" for events originating from the local host (via locally
- > connected IPMI), or an IP address or a hostname of a remote host.
- > * data - any supplementary data that can help better identify the event
- > (e.g., some first bytes of the IPMI command data).
+> `audit_event(type, rc, request, user, host, data)`
+>
+> - type - type of event source : IPMI, REST, PAM, etc.
+> - rc - return code of the handler event (status, rc, etc.)
+> - request - a generalized identifier of the event, e.g. ipmi command
+> (cmd/netfn/lun), web path, or anything else that can describe the event.
+> - user - the user account on behalf of which the event was processed. depends
+> on context, NA/None in case of user inaccessibility.
+> - source - identifier of the host that the event has originated from. This can
+> be literally "host" for events originating from the local host (via locally
+> connected IPMI), or an IP address or a hostname of a remote host.
+> - data - any supplementary data that can help better identify the event (e.g.,
+> some first bytes of the IPMI command data).
Service itself can control flow of events with configuration on its side.
@@ -140,8 +140,7 @@
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:
+`audit_event(blob_data)` Blob can be described as structure:
struct blob_audit
{
@@ -158,26 +157,28 @@
in the server configuration.
Step by step execution of call:
- * client's layer
- 1. checks if audit is enabled for such service
- 2. checks if audit event should be whitelisted or blacklisted at
- the audit service side for preventing spamming of unneeded events
- to audit service
- 3. send the data to the audit service via D-Bus
- * server's layer
- 1. accept D-Bus request
- 2. goes through list of actions for each services
+
+- client's layer
+ 1. checks if audit is enabled for such service
+ 2. checks if audit event should be whitelisted or blacklisted at the audit
+ service side for preventing spamming of unneeded events to audit service
+ 3. send the data to the audit service via D-Bus
+- server's layer
+ 1. accept D-Bus request
+ 2. goes through list of actions for each services
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:
+The configuration structure can be described as tree with set of options, as
+example of structure:
```
[IPMI]
@@ -205,29 +206,29 @@
Options can be updated via D-Bus properties. The audit service listens changes
on configuration file and emit 'PropertiesChanged' signal with changed details.
-* The whitelisting and blacklisting
+- The whitelisting and blacklisting
- > Possible list of requests which have to be filtered and processed.
- > 'Whitelist' filters possible requests which can be processed.
- > 'Blacklist' blocks only exact requests.
+> Possible list of requests which have to be filtered and processed. 'Whitelist'
+> filters possible requests which can be processed. 'Blacklist' blocks only
+> exact requests.
-* Enable/disable the event processing for directed services, where the directed
+- Enable/disable the event processing for directed services, where the directed
service is any suitable services which can use audit service.
- > Each audit processing type can be disabled or enabled at runtime via
- > config file or D-Bus property.
+> Each audit processing type can be disabled or enabled at runtime via config
+> file or D-Bus property.
-* Notification setup via SNMP/E-mail/Instant messengers/D-Bus
+- Notification setup via SNMP/E-mail/Instant messengers/D-Bus
- > The end recipient notification system with different transports.
+> The end recipient notification system with different transports.
-* Logging
+- Logging
- > phosphor-logging, journald or anything else suitable for.
+> phosphor-logging, journald or anything else suitable for.
-* User actions
+- User actions
- > Running a command as consequenced action.
+> Running a command as consequenced action.
## Workflow
@@ -295,24 +296,25 @@
## Notification mechanisms
-The unified model for reporting accidents to the end user, where the transport can be:
+The unified model for reporting accidents to the end user, where the transport
+can be:
-* E-mail
+- E-mail
- > Sending a note to directed recipient which set in configuration via
- > sendmail or anything else.
+ > Sending a note to directed recipient which set in configuration via sendmail
+ > or anything else.
-* SNMP
+- SNMP
> Sending a notification via SNMP trap messages to directed recipient which
> set in configuration.
-* Instant messengers
+- Instant messengers
> Sending a notification to directed recipient which set in configuration via
> jabber/sametime/gtalk/etc.
-* D-Bus
+- D-Bus
> Notify the other service which set in configuration via 'method_call' or
> 'signal'.
@@ -322,40 +324,45 @@
## User Actions
- * Exec application via 'system' call.
- * The code for directed handling type inside handler itself.
- As example for 'net ipmi' in case of unsuccessful user login inside handler:
- * Sends a notification to administrator.
- * echo heartbeat > /sys/class/leds/alarm_red/trigger
+- Exec application via 'system' call.
+- The code for directed handling type inside handler itself. As example for 'net
+ ipmi' in case of unsuccessful user login inside handler:
+ - Sends a notification to administrator.
+ - echo heartbeat > /sys/class/leds/alarm_red/trigger
## Alternatives Considered
-Processing user requests in each dedicated interface service and logging
-them separately for each of the interfaces. Scattered handling looks like
-an error-prone and rigid approach.
+Processing user requests in each dedicated interface service and logging them
+separately for each of the interfaces. Scattered handling looks like an
+error-prone and rigid approach.
## Impacts
Improves system manageability and security.
Impacts when phosphor-audit is not enabled:
- - Many services will have slightly larger code size and longer CPU path length
- due to invocations of audit_event().
- - Increased D-Bus traffic.
-Impacts when phosphor-audit is enabled:
-All of the above, plus:
- - Additional BMC processor time needed to handle audit events.
- - Additional BMC flash storage needed to store logged events.
- - Additional outbound network traffic to notify users.
- - Additional space for notification libraries.
+- Many services will have slightly larger code size and longer CPU path length
+ due to invocations of audit_event().
+- Increased D-Bus traffic.
+
+Impacts when phosphor-audit is enabled: All of the above, plus:
+
+- Additional BMC processor time needed to handle audit events.
+- Additional BMC flash storage needed to store logged events.
+- Additional outbound network traffic to notify users.
+- Additional space for notification libraries.
## Testing
`dbus-send` as command-line tool for generating audit events.
Scenarios:
- - For each supported service (such as Redfish, net IPMI, host IPMI, PLDM), create audit events, and validate they get logged.
- - Ensure message-type and request-type filtering works as expected.
- - Ensure basic notification actions work as expected (log, command, notify).
- - When continuously generating audit-events, change the phosphor-audit service's configuration, and validate no audit events are lost, and the new configuration takes effect.
+
+- For each supported service (such as Redfish, net IPMI, host IPMI, PLDM),
+ create audit events, and validate they get logged.
+- Ensure message-type and request-type filtering works as expected.
+- Ensure basic notification actions work as expected (log, command, notify).
+- When continuously generating audit-events, change the phosphor-audit service's
+ configuration, and validate no audit events are lost, and the new
+ configuration takes effect.
diff --git a/designs/phosphor-hwmon-io-uring.md b/designs/phosphor-hwmon-io-uring.md
index 124d8fd..4e61bf8 100644
--- a/designs/phosphor-hwmon-io-uring.md
+++ b/designs/phosphor-hwmon-io-uring.md
@@ -3,6 +3,7 @@
Author: Jerry Zhu ([jerryzhu@google.com](mailto:jerryzhu@google.com))
Other contributors:
+
- Brandon Kim ([brandonkim@google.com](mailto:brandonkim@google.com), brandonk)
- William A. Kennington III ([wak@google.com](mailto:wak@google.com), wak)
@@ -22,8 +23,8 @@
io_uring is a new asynchronous framework for Linux I/O interface (added to 5.1
Linux kernel, 5.10 is preferred). It is an upgrade from the previous
-asynchronous IO called AIO, which had its limitations in context of its usage
-in sensor reads for OpenBMC.
+asynchronous IO called AIO, which had its limitations in context of its usage in
+sensor reads for OpenBMC.
[brandonkim@google.com](mailto:brandonkim@google.com) has previously created a
method for preventing sensors from blocking all other sensor reads and D-Bus if
@@ -38,14 +39,14 @@
accuracy as the current, synchronous reads in each of the daemons. Potential
OpenBMC repositories that will benefit from this library include:
-* [phosphor-hwmon](https://github.com/openbmc/phosphor-hwmon)
-* [phosphor-nvme](https://github.com/openbmc/phosphor-nvme)
-* [dbus-sensors](https://github.com/openbmc/dbus-sensors)
-* any other appropriate repository
+- [phosphor-hwmon](https://github.com/openbmc/phosphor-hwmon)
+- [phosphor-nvme](https://github.com/openbmc/phosphor-nvme)
+- [dbus-sensors](https://github.com/openbmc/dbus-sensors)
+- any other appropriate repository
The focus of this project is to add asynchronous sensor reads to the
-phosphor-hwmon repository, which is easier to implement than adding
-asynchronous sensor reads into dbus-sensors.
+phosphor-hwmon repository, which is easier to implement than adding asynchronous
+sensor reads into dbus-sensors.
Users will need the ability to choose whether they want to utilize this new
asynchronous method of reading sensors, or remain with the traditional,
@@ -65,9 +66,9 @@
entries, iterates through all sensors and calls `_ioAccess->read(...)` for each
one; this operation is potentially blocking.
-The refactor will maintain this loop over all sensors, but instead make the
-read operation non-blocking by using an io_uring wrapper. A caching layer will
-be used to store the read results, which will be the main access point for
+The refactor will maintain this loop over all sensors, but instead make the read
+operation non-blocking by using an io_uring wrapper. A caching layer will be
+used to store the read results, which will be the main access point for
obtaining sensor reads in mainloop.cpp.
```
@@ -117,39 +118,38 @@
The read cache is implemented using an `unordered_map` of {sensor hwmon path:
read result}. The read result is a struct that keeps track of any necessary
-information for processing the read values and handling errors. Such
-information includes open file descriptor from the `open()` system call,
-number of retries remaining for reading this sensor when errors occur, etc.
+information for processing the read values and handling errors. Such information
+includes open file descriptor from the `open()` system call, number of retries
+remaining for reading this sensor when errors occur, etc.
-Each call to access the read value of a particular sesnor in the read cache
-will not only return the cached value but will also submit a SQE (submission
-queue event) to io_uring for that sensor; this SQE acts as a read request
-that will be sent to the kernel. The implementation maintains a set of sensors
-that keeps track of any pre-existing submissions so that multiple SQEs for the
-same sensor do not get submitted and overlap; the set entries will be cleared
-upon successful return of the read result using the CQE (completion queue
-event). The CQE will then be processed, and its information will update the
-cache map.
+Each call to access the read value of a particular sesnor in the read cache will
+not only return the cached value but will also submit a SQE (submission queue
+event) to io_uring for that sensor; this SQE acts as a read request that will be
+sent to the kernel. The implementation maintains a set of sensors that keeps
+track of any pre-existing submissions so that multiple SQEs for the same sensor
+do not get submitted and overlap; the set entries will be cleared upon
+successful return of the read result using the CQE (completion queue event). The
+CQE will then be processed, and its information will update the cache map.
The asynchronous nature of this implementation comes from sending all possible
-SQE requests, a non-blocking operation, at once instead of being blocked by
-slow sensor reads in the synchronous implementation. The kernel will process
-these requests, and before the next iteration of sensor reads the cache will
-attempt to process any returned CQEs, a non-blocking operation as well.
+SQE requests, a non-blocking operation, at once instead of being blocked by slow
+sensor reads in the synchronous implementation. The kernel will process these
+requests, and before the next iteration of sensor reads the cache will attempt
+to process any returned CQEs, a non-blocking operation as well.
Simply put, an access to some "Sensor A" in the read cache will create an
-underlying read request that makes a best effort to update the value of
-"Sensor A" before the next time the sensor read loop (currently 1 s by default)
-gets the value of "Sensor A" through the cache.
+underlying read request that makes a best effort to update the value of "Sensor
+A" before the next time the sensor read loop (currently 1 s by default) gets the
+value of "Sensor A" through the cache.
## Alternatives Considered
Linux does have a native asynchronous IO interface, simply dubbed AIO; however,
-there are a number of limitations. The biggest limitation of AIO is that it
-only supports true asynchronous IO for un-buffered reads. Furthermore, there
-are a number of ways that the IO submission can end up blocking - for example,
-if metadata is required to perform IO. Additionally, the memory costs of AIO
-are more expensive than those of io_uring.
+there are a number of limitations. The biggest limitation of AIO is that it only
+supports true asynchronous IO for un-buffered reads. Furthermore, there are a
+number of ways that the IO submission can end up blocking - for example, if
+metadata is required to perform IO. Additionally, the memory costs of AIO are
+more expensive than those of io_uring.
For these primary reasons, the native AIO library will not be considered for
this implementation of asynchronous reads.
@@ -157,10 +157,10 @@
## Impacts
This project would impact all OpenBMC developers of openbmc/phosphor-hwmon
-initially. It has improved the latency performance of phosphor-hwmon;
-throughput has also been shown to increase (note that throughput profiling
-was more arbitrary than latency profiling). These performance changes will
-have to be calculated in further detail across different machines.
+initially. It has improved the latency performance of phosphor-hwmon; throughput
+has also been shown to increase (note that throughput profiling was more
+arbitrary than latency profiling). These performance changes will have to be
+calculated in further detail across different machines.
There will be no security impact.
diff --git a/designs/phosphor-hwmon-refactoring.md b/designs/phosphor-hwmon-refactoring.md
index 7a13087..578f77c 100644
--- a/designs/phosphor-hwmon-refactoring.md
+++ b/designs/phosphor-hwmon-refactoring.md
@@ -6,22 +6,21 @@
## Problem Description
-Convoluted code in phosphor-hwmon is imparing our ability to add features
-and identify/fix bugs.
+Convoluted code in phosphor-hwmon is imparing our ability to add features and
+identify/fix bugs.
## Background and References
A few cases of smelly code or bad design decisions throughout the code:
-* Limited unit testing coverage. Currently the unit tests in the repo [1] mostly
- test that the sensor can be constructed correctly, but there is no testing
- of correct behavior on various sensor reading or failure conditions.
-* Bloated mainloop. mainloop::read() sits at 146 lines [2] with complicated
- conditions, macros, and try/catch blocks.
-* Lack of abstraction and dependency injection. This makes the code hard to
- test and hard to read. For example, the conditional at [3]
- can be replaced by implementing different sensor::readValue() method for
- different sensor types.
+- Limited unit testing coverage. Currently the unit tests in the repo [1] mostly
+ test that the sensor can be constructed correctly, but there is no testing of
+ correct behavior on various sensor reading or failure conditions.
+- Bloated mainloop. mainloop::read() sits at 146 lines [2] with complicated
+ conditions, macros, and try/catch blocks.
+- Lack of abstraction and dependency injection. This makes the code hard to test
+ and hard to read. For example, the conditional at [3] can be replaced by
+ implementing different sensor::readValue() method for different sensor types.
[1](https://github.com/openbmc/phosphor-hwmon/tree/master/test)
[2](https://github.com/openbmc/phosphor-hwmon/blob/94a04c4e9162800af7b2823cd52292e3aa189dc3/mainloop.cpp#L390)
@@ -33,41 +32,44 @@
2. Improve overall design using OOD principles
3. Improve error handling and resiliency
4. Improve configurability
- * By providing a common configuration class, it will be feasible to add
- alternative configuration methods, e.g. JSON, while maintaining backward
- compatibility with existing env files approach.
+ - By providing a common configuration class, it will be feasible to add
+ alternative configuration methods, e.g. JSON, while maintaining backward
+ compatibility with existing env files approach.
## Proposed Design
Rough breakdown of refactoring steps:
1. Sensor configuration
- * Add a SensorConfig struct that does all std::getenv() calls in one place
- * DI: make the sensor struct take SensorConfig as dependency
- * Unit tests for SensorConfig
- * Add unit tests for sensor creation with various SensorConfigs
+ - Add a SensorConfig struct that does all std::getenv() calls in one place
+ - DI: make the sensor struct take SensorConfig as dependency
+ - Unit tests for SensorConfig
+ - Add unit tests for sensor creation with various SensorConfigs
2. Abstract sensors
- * Refine the sensor object interface and make it abstract
- * Define sensor types that inherit from the common interface
- * Add unit tests for sensor interface
- * DI: make the sensor map take sensor interface as dependency
- * Add a fake sensor that can exhibit controllable behavior
+ - Refine the sensor object interface and make it abstract
+ - Define sensor types that inherit from the common interface
+ - Add unit tests for sensor interface
+ - DI: make the sensor map take sensor interface as dependency
+ - Add a fake sensor that can exhibit controllable behavior
3. Refactor sensor management logic
- * Refactor sensor map to allow easier lookup/insertion
- * Add unit tests for sensor map
- * DI: make all other functions take sensor map as dependency
+ - Refactor sensor map to allow easier lookup/insertion
+ - Add unit tests for sensor map
+ - DI: make all other functions take sensor map as dependency
4. Abstract error handling
- * Add overridable error handler to sensor interface
- * Define different error handlers
- * Add unit tests for error handlers using the fake sensor
+ - Add overridable error handler to sensor interface
+ - Define different error handlers
+ - Add unit tests for error handlers using the fake sensor
## Alternatives Considered
+
N/A.
## Impacts
-The refactoring should have no external API impact. Performance impact should
-be profiled.
+
+The refactoring should have no external API impact. Performance impact should be
+profiled.
## Testing
-One of the goals is to have better unit test coverage. Overall functionality
-to be tested through functional and regression tests.
+
+One of the goals is to have better unit test coverage. Overall functionality to
+be tested through functional and regression tests.
diff --git a/designs/physical-topology.md b/designs/physical-topology.md
index 678356b..5af81b2 100644
--- a/designs/physical-topology.md
+++ b/designs/physical-topology.md
@@ -2,12 +2,12 @@
Author: Benjamin Fair <benjaminfair>
-Other contributors:
- Ed Tanous <edtanous>
+Other contributors: Ed Tanous <edtanous>
Created: June 1, 2022
## Problem Description
+
Complex systems may contain many inventory objects (such as chassis, power
supplies, cables, fans, etc.) with different types of relationships among these
objects. For instance, one chassis can contain another, be powered by a set of
@@ -15,10 +15,11 @@
currently have a standard way to represent these types of relationships.
## Background and References
-This builds on a [prior
-proposal](https://gerrit.openbmc.org/c/openbmc/docs/+/41468), but specifies
-using Associations for all relationships (Proposal II) rather than path
-hierarchies (Proposal I).
+
+This builds on a
+[prior proposal](https://gerrit.openbmc.org/c/openbmc/docs/+/41468), but
+specifies using Associations for all relationships (Proposal II) rather than
+path hierarchies (Proposal I).
The main driver of this design is Redfish, particularly the Links section of the
[Chassis schema](https://redfish.dmtf.org/schemas/Chassis.v1_20_0.json).
@@ -32,40 +33,47 @@
where some initial consensus was reached.
## Requirements
-* Must represent one-to-many relationships from chassis inventory objects which:
- * Connect to cables
- * Contain other chassis and/or are contained by a chassis
- * Contain storage drives
- * Are cooled by fans
- * Are powered by power supplies
- * Contain processors such as CPUs
- * Contain memory such as DIMMs
-* Must support relationships which are predefined, detected at runtime, or a
+
+- Must represent one-to-many relationships from chassis inventory objects which:
+ - Connect to cables
+ - Contain other chassis and/or are contained by a chassis
+ - Contain storage drives
+ - Are cooled by fans
+ - Are powered by power supplies
+ - Contain processors such as CPUs
+ - Contain memory such as DIMMs
+- Must support relationships which are predefined, detected at runtime, or a
combination of both
- * Runtime detection could include I2C bus scanning, USB enumeration, and/or
- MCTP discovery
+ - Runtime detection could include I2C bus scanning, USB enumeration, and/or
+ MCTP discovery
### Optional goals (beyond initial implementation)
-* Non-chassis inventory objects may also need one-to-many relationships
- * CPUs have CPU cores and associated PCIe slots
- * CPU cores have threads
+
+- Non-chassis inventory objects may also need one-to-many relationships
+ - CPUs have CPU cores and associated PCIe slots
+ - CPU cores have threads
## Proposed Design
+
The design affects three layers of the OpenBMC architecture:
phosphor-dbus-interfaces, inventory managers, and inventory consumers such as
bmcweb.
### phosphor-dbus-interfaces
+
In the interface definition for Chassis inventory items, we add an association
definition for each of the relationship types listed above and corresponding
association definitions for the other item types linking back to a Chassis item.
### Inventory Managers
+
#### phosphor-inventory-manager
+
phosphor-inventory-manager already has support for exporting custom
Associations, so no changes are needed here.
#### entity-manager
+
For entity-manager, we add new `Exposes` stanzas for the upstream and downstream
ports in the JSON configurations. The upstream port has a connector type (such
as a backplane connector, power input, etc). The downstream port has type
@@ -80,6 +88,7 @@
Example JSON configurations:
superchassis.json
+
```
{
"Exposes": [
@@ -95,6 +104,7 @@
```
subchassis.json:
+
```
{
"Exposes": [
@@ -111,16 +121,19 @@
```
#### Other inventory managers
+
If there are other daemons on the system exporting inventory objects, they can
choose to include the same Associations that phosphor-inventory-manager and
entity-manager use.
### Inventory consumers
+
When a daemon such as bmcweb wants to determine what other inventory items have
a relationship to a specific item, it makes a query to the object mapper which
returns a list of all associated items and the relationship types between them.
Example `busctl` calls:
+
```
$ busctl get-property xyz.openbmc_project.ObjectMapper \
/xyz/openbmc_project/inventory/system/chassis/Superchassis/chassisContains \
@@ -136,7 +149,9 @@
```
## Alternatives Considered
+
### Path hierarchies
+
An alternative proposal involves encoding the topological relationships between
inventory items using D-Bus path names. As an example, a chassis object
underneath another would be contained by that parent chassis. This works for
@@ -164,6 +179,7 @@
consumers to understand the topology.
## Impacts
+
This new API will be documented in phosphor-dbus-interfaces as described above.
If no topology information is added to configuration files for entity-manager or
phosphor-inventory-manager, then the D-Bus interfaces exported by them will not
@@ -171,10 +187,12 @@
associations, then their output such as Redfish will not change either.
### Organizational
-Does this repository require a new repository? No - all changes will go in
+
+Does this repository require a new repository? No - all changes will go in
existing repositories.
## Testing
+
All new code in entity-manager and bmcweb will be unit tested using existing
frameworks and infrastructure. We will add new end-to-end tests in
openbmc-test-automation to ensure the Redfish output is correct.
diff --git a/designs/pldm-stack.md b/designs/pldm-stack.md
index c871333..2de44cd 100644
--- a/designs/pldm-stack.md
+++ b/designs/pldm-stack.md
@@ -5,6 +5,7 @@
Created: 2019-01-22
## Problem Description
+
On OpenBMC, in-band IPMI is currently the primary industry-standard means of
communication between the BMC and the Host firmware. We've started hitting some
inherent limitations of IPMI on OpenPOWER servers: a limited number of sensors,
@@ -25,6 +26,7 @@
devices.
## Background and References
+
PLDM is designed to be an effective interface and data model that provides
efficient access to low-level platform inventory, monitoring, control, event,
and data/parameters transfer functions. For example, temperature, voltage, or
@@ -32,9 +34,9 @@
control the platform using a set of PLDM messages. PLDM defines data
representations and commands that abstract the platform management hardware.
-PLDM groups commands under broader functions, and defines
-separate specifications for each of these functions (also called PLDM "Types").
-The currently defined Types (and corresponding specs) are : PLDM base (with
+PLDM groups commands under broader functions, and defines separate
+specifications for each of these functions (also called PLDM "Types"). The
+currently defined Types (and corresponding specs) are : PLDM base (with
associated IDs and states specs), BIOS, FRU, Platform monitoring and control,
Firmware Update and SMBIOS. All these specifications are available at:
@@ -68,8 +70,9 @@
be proposed separately.
## Requirements
-How different BMC applications make use of PLDM messages is outside the scope
-of this requirements doc. The requirements listed here are related to the PLDM
+
+How different BMC applications make use of PLDM messages is outside the scope of
+this requirements doc. The requirements listed here are related to the PLDM
protocol stack and the request/response model:
- Marshalling and unmarshalling of PLDM messages, defined in various PLDM Type
@@ -107,13 +110,14 @@
- It should be possible to plug-in OEM PLDM types/functions into the PLDM stack.
## Proposed Design
+
This document covers the architectural, interface, and design details. It
provides recommendations for implementations, but implementation details are
outside the scope of this document.
The design aims at having a single PLDM daemon serve both the requester and
-responder functions, and having transport specific endpoints to communicate
-on different channels.
+responder functions, and having transport specific endpoints to communicate on
+different channels.
The design enables concurrency aspects of the requester and responder functions,
but the goal is to employ asynchronous IO and event loops, instead of multiple
@@ -143,8 +147,8 @@
implement a "register" API to plug-in handlers for specific PLDM messages.
Something like:
-template <typename Handler, typename... args>
-auto register(uint8_t type, uint8_t command, Handler handler);
+template <typename Handler, typename... args> auto register(uint8_t type,
+uint8_t command, Handler handler);
This allows for providing a strongly-typed C++ handler registration scheme. It
would also be possible to validate the parameters passed to the handler at
@@ -152,10 +156,11 @@
### Request/Response Model
-The PLDM daemon links with the encode/decode and provider libs. The daemon
-would have to implement the following functions:
+The PLDM daemon links with the encode/decode and provider libs. The daemon would
+have to implement the following functions:
#### Receiver/Responder
+
The receiver wakes up on getting notified of incoming PLDM messages (via D-Bus
signal or callback from the transport layer) from a remote PLDM device. If the
message type is "Request" it would route them to a PLDM provider library. Via
@@ -170,22 +175,22 @@
thread of it's own.
If the incoming PLDM message is of type "Response", then the receiver emits a
-D-Bus signal pointing to the response message. Any time the message is too
-large to fit in a D-Bus payload, the message is written to a file, and a
-read-only file descriptor pointing to that file is contained in the D-Bus
-signal.
+D-Bus signal pointing to the response message. Any time the message is too large
+to fit in a D-Bus payload, the message is written to a file, and a read-only
+file descriptor pointing to that file is contained in the D-Bus signal.
#### Requester
+
Designing the BMC as a PLDM requester is interesting. We haven't had this with
IPMI, because the BMC was typically an IPMI server. PLDM requester functions
will be spread across multiple OpenBMC applications (instead of a single big
requester app) - based on the responder they're talking to and the high level
function they implement. For example, there could be an app that lets the BMC
-upgrade firmware for other devices using PLDM - this would be a generic app
-in the sense that the same set of commands might have to be run irrespective
-of the device on the other side. There could also be an app that does fan
-control on a remote device, based on sensors from that device and algorithms
-specific to that device.
+upgrade firmware for other devices using PLDM - this would be a generic app in
+the sense that the same set of commands might have to be run irrespective of the
+device on the other side. There could also be an app that does fan control on a
+remote device, based on sensors from that device and algorithms specific to that
+device.
##### Proposed requester design
@@ -195,17 +200,17 @@
and unpack PLDM responses.
- A D-Bus API to generate a unique PLDM instance id. The id needs to be unique
- across all outgoing PLDM messages (from potentially different processes).
- This needs to be on D-Bus because the id needs to be unique across PLDM
- requester app processes.
+ across all outgoing PLDM messages (from potentially different processes). This
+ needs to be on D-Bus because the id needs to be unique across PLDM requester
+ app processes.
- A requester client API that provides blocking and non-blocking functions to
transfer a PLDM request message and to receive the corresponding response
- message, over MCTP (the blocking send() will return a PLDM response).
- This will be a thin wrapper over the socket API provided by the mctp demux
- daemon. This will provide APIs for common tasks so that the same may not
- be re-implemented in each PLDM requester app. This set of API will be built
- into the encode/decode library (so libpldm would house encode/decode APIs, and
+ message, over MCTP (the blocking send() will return a PLDM response). This
+ will be a thin wrapper over the socket API provided by the mctp demux daemon.
+ This will provide APIs for common tasks so that the same may not be
+ re-implemented in each PLDM requester app. This set of API will be built into
+ the encode/decode library (so libpldm would house encode/decode APIs, and
based on a compile time flag, the requester APIs as well). A PLDM requester
app can choose to not use the client requester APIs, and instead can directly
talk to the MCTP demux daemon.
@@ -266,7 +271,6 @@
+ + + +
```
-
b) With non-blocking API
```
@@ -335,17 +339,19 @@
PLDM requester apps can then invoke the above applications. While this
simplifies things for the user, it has two disadvantages :
+
- the app implementing such an interface could be a single point of failure,
plus sending messages concurrently would be a challenge.
- the message payload could be large (several pages), and copying the same for
D-Bus transfers might be undesirable.
### Multiple transport channels
+
The PLDM daemon might have to talk to remote PLDM devices via different
channels. While a level of abstraction might be provided by MCTP, the PLDM
-daemon would have to implement a D-Bus interface to target a specific
-transport channel, so that requester apps on the BMC can send messages over
-that transport. Also, it should be possible to plug-in platform specific D-Bus
+daemon would have to implement a D-Bus interface to target a specific transport
+channel, so that requester apps on the BMC can send messages over that
+transport. Also, it should be possible to plug-in platform specific D-Bus
objects that implement an interface to target a platform specific transport.
### Processing PLDM FRU information sent down by the host firmware
@@ -384,15 +390,17 @@
as it does today.
## Alternatives Considered
-Continue using IPMI, but start making more use of OEM extensions to
-suit the requirements of new platforms. However, given that the IPMI
-standard is no longer under active development, we would likely end up
-with a large amount of platform-specific customisations. This also does
-not solve the hardware channel issues in a standard manner.
-On OpenPOWER hardware at least, we've started to hit some of the limitations of
-IPMI (for example, we have need for >255 sensors).
+
+Continue using IPMI, but start making more use of OEM extensions to suit the
+requirements of new platforms. However, given that the IPMI standard is no
+longer under active development, we would likely end up with a large amount of
+platform-specific customisations. This also does not solve the hardware channel
+issues in a standard manner. On OpenPOWER hardware at least, we've started to
+hit some of the limitations of IPMI (for example, we have need for >255
+sensors).
## Impacts
+
Development would be required to implement the PLDM protocol, the
request/response model, and platform specific handling. Low level design is
required to implement the protocol specifics of each of the PLDM Types. Such low
@@ -402,6 +410,7 @@
controllers and management devices of a platform management subsystem.
## Testing
+
Testing can be done without having to depend on the underlying transport layer.
The responder function can be tested by mocking a requester and the transport
diff --git a/designs/power-recovery.md b/designs/power-recovery.md
index 9016f88..e3fe7a8 100644
--- a/designs/power-recovery.md
+++ b/designs/power-recovery.md
@@ -7,84 +7,87 @@
Created: October 11th, 2021
## Problem Description
-Modern computer systems have a feature, automated power-on recovery, which
-in essence is the ability to tell your system what to do when it hits
-issues with power to the system. If the system had a black out (i.e. power
-was completely cut to the system), should it automatically power the system
-on? Should it leave it off? Or maybe the user would like the system to
-go to whichever state it was at before the power loss.
-There are also instances where the user may not want automatic power recovery
-to occur. For example, some systems have op-panels, and on these op-panels
-there can be a pin hole reset. This is a manual mechanism for the user to
-force a hard reset to the BMC in situations where it is hung or not responding.
-In these situations, the user may wish for the system to not automatically
-power on the system, because they want to debug the reason for the BMC error.
+Modern computer systems have a feature, automated power-on recovery, which in
+essence is the ability to tell your system what to do when it hits issues with
+power to the system. If the system had a black out (i.e. power was completely
+cut to the system), should it automatically power the system on? Should it leave
+it off? Or maybe the user would like the system to go to whichever state it was
+at before the power loss.
+
+There are also instances where the user may not want automatic power recovery to
+occur. For example, some systems have op-panels, and on these op-panels there
+can be a pin hole reset. This is a manual mechanism for the user to force a hard
+reset to the BMC in situations where it is hung or not responding. In these
+situations, the user may wish for the system to not automatically power on the
+system, because they want to debug the reason for the BMC error.
During blackout scenarios, system owners may have a set of services they need
run once the power is restored. For example, IBM requires all LED's be toggled
-to off in a blackout. OpenBMC needs to provide a mechanism for system owners
-to run services in this scenario.
+to off in a blackout. OpenBMC needs to provide a mechanism for system owners to
+run services in this scenario.
A brownout is another scenario that commonly utilizes automated power-on
recovery features. A brownout is a scenario where BMC firmware detects (or is
-told) that chassis power can no longer be supported, but power to the BMC
-will be retained. On some systems, it's desired to utilize the automated
-power-on feature to turn chassis power back on as soon as the brownout condition
-ends.
+told) that chassis power can no longer be supported, but power to the BMC will
+be retained. On some systems, it's desired to utilize the automated power-on
+feature to turn chassis power back on as soon as the brownout condition ends.
Some system owners may chose to attach an Uninterrupted Power Supply (UPS) to
-their system. A UPS continues to provide power to a system through a blackout
-or brownout scenario. A UPS has a limited amount of power so it's main
-purpose is to handle brief power interruptions or to allow for an orderly
-shutdown of the host firmware.
+their system. A UPS continues to provide power to a system through a blackout or
+brownout scenario. A UPS has a limited amount of power so it's main purpose is
+to handle brief power interruptions or to allow for an orderly shutdown of the
+host firmware.
-The goal of this design document is to describe how OpenBMC firmware will
-deal with these questions.
+The goal of this design document is to describe how OpenBMC firmware will deal
+with these questions.
## Background and References
-The BMC already implements a limited subset of function in this area.
-The [PowerRestorePolicy][pdi-restore] property out in phosphor-dbus-interface
+
+The BMC already implements a limited subset of function in this area. The
+[PowerRestorePolicy][pdi-restore] property out in phosphor-dbus-interface
defines the function capability.
In smaller servers, this feature is commonly found within the Advanced
Configuration and Power Interface (ACPI).
-[openbmc/phosphor-state-manager][state-mgr] supports this property as defined
-in the phosphor-dbus-interface.
+[openbmc/phosphor-state-manager][state-mgr] supports this property as defined in
+the phosphor-dbus-interface.
## Requirements
### Automated Power-On Recovery
-OpenBMC software must ensure it persists the state of power to the chassis so
-it can know what to restore it to if necessary
+
+OpenBMC software must ensure it persists the state of power to the chassis so it
+can know what to restore it to if necessary
OpenBMC software must provide support for the following options:
-- Do nothing when power is lost to the system (this will be the
- default)
+
+- Do nothing when power is lost to the system (this will be the default)
- Always power the system on and boot the host
-- Always power the system off (previous power was on, power is now off, run
- all chassis power off services to ensure a clean state of software and
- hardware)
+- Always power the system off (previous power was on, power is now off, run all
+ chassis power off services to ensure a clean state of software and hardware)
- Restore the previous state of the chassis power and host
-These options are only checked and enforced in situations where the BMC does
-not detect that chassis power is already on to the system when it comes out
-of reboot.
+These options are only checked and enforced in situations where the BMC does not
+detect that chassis power is already on to the system when it comes out of
+reboot.
OpenBMC software must also support the concept of a one_time power restore
-policy. This is a separate instance of the `PowerRestorePolicy` which will
-be hosted under a D-Bus object path which ends with "one_time". If this
-one_time setting is not the default, `None`, then software will execute
-the policy defined under it, and then reset the one_time property to `None`.
-This one_time feature is a way for software to utilize automated power-on
-recovery function for other areas like firmware update scenarios where a
-certain power on behavior is desired once an update has completed.
+policy. This is a separate instance of the `PowerRestorePolicy` which will be
+hosted under a D-Bus object path which ends with "one_time". If this one_time
+setting is not the default, `None`, then software will execute the policy
+defined under it, and then reset the one_time property to `None`. This one_time
+feature is a way for software to utilize automated power-on recovery function
+for other areas like firmware update scenarios where a certain power on behavior
+is desired once an update has completed.
### BMC and System Recovery Paths
-In situations where the BMC or the system have gotten into a bad state, and
-the user has initiated some form of manual reset which is detectable by the
-BMC as being user initiated, the BMC software must:
+
+In situations where the BMC or the system have gotten into a bad state, and the
+user has initiated some form of manual reset which is detectable by the BMC as
+being user initiated, the BMC software must:
+
- Fill in appropriate `RebootCause` within the [BMC state interface][bmc-state]
- At a minimum, `PinholeReset` will be added. Others can be added as needed
- Log an error indicating a user initiated forced reset has occurred
@@ -94,30 +97,34 @@
- Turn power recovery back on once BMC has a normal reboot
### Blackout
+
A blackout occurs when AC power is cut from the system, resulting in a total
loss of power if there is no UPS installed to keep the system on. To identify
this scenario after a BMC reboot, chassis-state-manager will check to see what
-the last power state was before the loss of power and compares it against
-the pgood pin. Blackouts can be intentionally triggered by a user
-(i.e a pinhole reset) or in severe cases occur when there is some sort of
-an external outage. In either case the BMC must take into account this
-detrimental state.
-When this condition occurs, the BMC may(depending on configuration):
-- Provide a generic target, `obmc-chassis-blackout@.target` to be called when
- a blackout is detected
+the last power state was before the loss of power and compares it against the
+pgood pin. Blackouts can be intentionally triggered by a user (i.e a pinhole
+reset) or in severe cases occur when there is some sort of an external outage.
+In either case the BMC must take into account this detrimental state. When this
+condition occurs, the BMC may(depending on configuration):
+
+- Provide a generic target, `obmc-chassis-blackout@.target` to be called when a
+ blackout is detected
- Adhere to the current power restore policy
BMC firmware must also be able to:
-- Discover why the system is in a blackout situation. From either loss of
- power or user actions.
+
+- Discover why the system is in a blackout situation. From either loss of power
+ or user actions.
### Brownout
+
As noted above, a brownout condition is when AC power can not continue to be
supplied to the chassis, but the BMC can continue to have power and run.
When this condition occurs, the BMC must:
-- Power system off as quickly as situations requires (or gracefully handle
- the loss of power if it occurred without warning)
+
+- Power system off as quickly as situations requires (or gracefully handle the
+ loss of power if it occurred without warning)
- Log an error indicating the brownout event has occurred
- Support the ability for host firmware to indicate a one-time power restore
policy if they wish for when the brownout completes
@@ -127,15 +134,18 @@
policy defined for the system
BMC firmware must also be able to:
+
- Discover if system is in a brownout situation
- Run when the BMC first comes up to know if it should implement any automated
power-on recovery
- Not run any power-on recovery logic when a brownout is occurring
-- Tell the host firmware that it is a automated power-on recovery initiated
- boot when that firmware is what boots the system
+- Tell the host firmware that it is a automated power-on recovery initiated boot
+ when that firmware is what boots the system
### Uninterruptible Power Supply (UPS)
+
When a UPS is present and a blackout or brownout condition occurs, the BMC must:
+
- Log an error to indicate the condition has occurred
- If host firmware is running, notify the host firmware of this utility failure
condition (this behavior is build-time configurable)
@@ -151,59 +161,63 @@
## Proposed Design
### Automated Power-On Recovery
+
An application will be run after the chassis and host states have been
determined which will only run if the chassis power is not on.
-This application will look for the one_time setting and use it if its value
-is not `None`. If it does use the one_time setting then it will reset it
-to `None` once it has read it. Otherwise the application will read the
-persistent value of the `PowerRestorePolicy`. The application will then
-run the logic as defined in the Requirements above.
+This application will look for the one_time setting and use it if its value is
+not `None`. If it does use the one_time setting then it will reset it to `None`
+once it has read it. Otherwise the application will read the persistent value of
+the `PowerRestorePolicy`. The application will then run the logic as defined in
+the Requirements above.
This function will be hosted in phosphor-state-manger and potentially
x86-power-control.
### BMC and System Recovery Paths
-The BMC state manager application currently looks at a file in the
-sysfs to try and determine the cause of a BMC reboot. It then puts this
-reason in the `RebootCause` property.
-One possible cause of a BMC reset is an external reset (EXTRST). There are
-a variety of reasons an external reset can occur. Some systems are adding
-GPIOs to provide additional detail on these types of resets.
+The BMC state manager application currently looks at a file in the sysfs to try
+and determine the cause of a BMC reboot. It then puts this reason in the
+`RebootCause` property.
+
+One possible cause of a BMC reset is an external reset (EXTRST). There are a
+variety of reasons an external reset can occur. Some systems are adding GPIOs to
+provide additional detail on these types of resets.
A new GPIO name will be added to the [device-tree-gpio-naming.md][dev-tree]
which reports whether a pin hole reset has occurred on the previous reboot of
the BMC. The BMC state manager application will enhance its support of the
`RebootCause` to look for this GPIO and if present, read it and set
-`RebootCause` accordingly when it can either not determine the reason for
-the reboot via the sysfs or sysfs reports a EXTRST reason (in which case
-the GPIO will be utilized to enhance the reboot reason).
+`RebootCause` accordingly when it can either not determine the reason for the
+reboot via the sysfs or sysfs reports a EXTRST reason (in which case the GPIO
+will be utilized to enhance the reboot reason).
If the power recovery software sees the `PinholeReset` reason within the
-`RebootCause` then it will not implement any of its policy. Future BMC
-reboots which are not pin hole reset caused, will cause `RebootCause` to go
-back to a default and therefore power recovery policy will be re-enabled on that
-BMC boot.
+`RebootCause` then it will not implement any of its policy. Future BMC reboots
+which are not pin hole reset caused, will cause `RebootCause` to go back to a
+default and therefore power recovery policy will be re-enabled on that BMC boot.
-The phosphor-state-manager chassis software will not log a blackout error
-if it sees the `PinholeReset` reason (or any other reason that indicates a user
+The phosphor-state-manager chassis software will not log a blackout error if it
+sees the `PinholeReset` reason (or any other reason that indicates a user
initiated a reset of the system).
### Blackout
-A new systemd target `obmc-chassis-blackout.target` should be added to
-allow system maintainers to call services in this condition. This new target
-will be called when the BMC detects a blackout. The target will allow for
-system owners to add their own specific services to this new target.
+
+A new systemd target `obmc-chassis-blackout.target` should be added to allow
+system maintainers to call services in this condition. This new target will be
+called when the BMC detects a blackout. The target will allow for system owners
+to add their own specific services to this new target.
Phosphor-chassis-state-manager will ensure `obmc-chassis-blackout.target` will
be called after a blackout.
### Brownout
+
The existing `xyz.openbmc_project.State.Chassis` interface will be enhanced to
-support a `CurrentPowerStatus` property. The existing
+support a `CurrentPowerStatus` property. The existing
phosphor-chassis-state-manager, which is instantiated per instance of chassis in
the system, will support a read of this property. The following will be the
possible returned values for the power status of the target chassis:
+
- `Undefined`
- `BrownOut`
- `UninterruptiblePowerSupply`
@@ -211,13 +225,12 @@
The phosphor-psu-monitor application within the phosphor-power repository will
be responsible for monitoring for brownout conditions. It will support a
-per-chassis interface which represents the status of the power going into
-the target chassis. This interface will be generic in that other applications
-could host it to report the status of the power. The state-manager software
-will utilize mapper to look for all implementations of the interface for its
-chassis and aggregate the status (i.e. if any reports a brownout, then
-`BrownOut` will be returned). This interface will be defined in a later update
-to this document.
+per-chassis interface which represents the status of the power going into the
+target chassis. This interface will be generic in that other applications could
+host it to report the status of the power. The state-manager software will
+utilize mapper to look for all implementations of the interface for its chassis
+and aggregate the status (i.e. if any reports a brownout, then `BrownOut` will
+be returned). This interface will be defined in a later update to this document.
The application(s) responsible for detecting and reporting chassis power will
run on startup and discover the correct state for their property. These
@@ -225,8 +238,8 @@
power off.
If the system design needs it, the existing one-time function provided by
-phosphor-state-manager for auto power on policy will be utilized for when
-the brownout completes.
+phosphor-state-manager for auto power on policy will be utilized for when the
+brownout completes.
When the phosphor-power application detects that a brownout condition has
completed it will reset its interface representing power status to good and
@@ -239,21 +252,23 @@
prevented from booting.
### Uninterruptible Power Supply (UPS)
+
A new phosphor-dbus-interface will be defined to represent a UPS. A BMC
-application will implement one of these per UPS attached to the system.
-This application will monitor UPS status and monitor for the following:
+application will implement one of these per UPS attached to the system. This
+application will monitor UPS status and monitor for the following:
+
- UPS utility fail (system power has failed and UPS is providing system power)
- UPS battery low (UPS is about to run out of power)
-If the application sees power has been lost and the system is running on
-UPS battery power then it will monitor for the power remaining in the UPS and
-notify the host that a shutdown is required if needed. This application
-will also be responsible for logging an error indicating the UPS backup power
-has been switched to and set the appropriate property in their interface to
-indicate the scenario is present when the system can no longer remain on.
+If the application sees power has been lost and the system is running on UPS
+battery power then it will monitor for the power remaining in the UPS and notify
+the host that a shutdown is required if needed. This application will also be
+responsible for logging an error indicating the UPS backup power has been
+switched to and set the appropriate property in their interface to indicate the
+scenario is present when the system can no longer remain on.
phosphor-state-manager will query mapper for implementation of this new UPS
-interface and utilize them in combination with power supply brownout status
-when determining the value to return for its `CurrentPowerStatus`.
+interface and utilize them in combination with power supply brownout status when
+determining the value to return for its `CurrentPowerStatus`.
Similar to the above brownout scenario, phosphor-state-manager will ensure
automated power-on recovery logic is not run if `PowerStatus` is not set to
@@ -261,33 +276,39 @@
phosphor-state-manager.
## Alternatives Considered
+
None, this is a pretty basic feature that does not have a lot of alternatives
(other then just not doing it).
## Impacts
+
None
## Testing
+
The control of this policy can already bet set via the Redfish API.
+
```
# Power Restore Policy
curl -k -X PATCH -d '{"PowerRestorePolicy":"AlwaysOn"}' https://${bmc}/redfish/v1/Systems/system
curl -k -X PATCH -d '{"PowerRestorePolicy":"AlwaysOff"}' https://${bmc}/redfish/v1/Systems/system
curl -k -X PATCH -d '{"PowerRestorePolicy":"LastState"}' https://${bmc}/redfish/v1/Systems/system
```
+
For testing, each policy should be set and verified. The one_time aspect should
also be checked for each possible value and verified to only be used once.
-Validate that when multiple black outs occur, the firmware continues to try
-and power on the system when policy is `AlwaysOn` or `Restore`.
+Validate that when multiple black outs occur, the firmware continues to try and
+power on the system when policy is `AlwaysOn` or `Restore`.
-On supported systems, a pin hole reset should be done with a system that has
-a policy set to always power on. Tester should verify system does not
+On supported systems, a pin hole reset should be done with a system that has a
+policy set to always power on. Tester should verify system does not
automatically power on after a pin hole reset. Verify it does automatically
power on when a normal reboot of the BMC is done.
A brownout condition should be injected into a system and appropriate paths
should be verified:
+
- Error log generated
- Host notified (if running and notification possible)
- System quickly powered off
@@ -298,7 +319,10 @@
Plug a UPS into a system and ensure when power is cut to the system that an
error is logged and the host is notified and allowed to power off.
-[pdi-restore]:https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Power/RestorePolicy.interface.yaml
+[pdi-restore]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Power/RestorePolicy.interface.yaml
[state-mgr]: https://github.com/openbmc/phosphor-state-manager
-[bmc-state]:https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC.interface.yaml
-[dev-tree]:https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md
+[bmc-state]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/BMC.interface.yaml
+[dev-tree]:
+ https://github.com/openbmc/docs/blob/master/designs/device-tree-gpio-naming.md
diff --git a/designs/power-systems-memory-preserving-reboot.md b/designs/power-systems-memory-preserving-reboot.md
index 1928bb3..9834671 100644
--- a/designs/power-systems-memory-preserving-reboot.md
+++ b/designs/power-systems-memory-preserving-reboot.md
@@ -6,238 +6,249 @@
## Problem Description
-On POWER based servers, a hypervisor firmware manages and allocates
-resources to the logical partitions running on the server. If this hypervisor
-encounters an error and cannot continue with management operations, the server
-needs to be restarted. A typical server reboot will erase the content of the
-main memory with the current running configuration of the logical partitions
-and the data required for debugging the fault. Some hypervisors on the POWER
-based systems don't have access to a non-volatile storage to store this
-content after a failure. A warm reboot with preserving the main memory is needed
-on the POWER based servers to create a memory dump required for the
-debugging. This document explains the high-level flow of warm reboot and
-extraction of the resulting dump from the hypervisor memory.
-
+On POWER based servers, a hypervisor firmware manages and allocates resources to
+the logical partitions running on the server. If this hypervisor encounters an
+error and cannot continue with management operations, the server needs to be
+restarted. A typical server reboot will erase the content of the main memory
+with the current running configuration of the logical partitions and the data
+required for debugging the fault. Some hypervisors on the POWER based systems
+don't have access to a non-volatile storage to store this content after a
+failure. A warm reboot with preserving the main memory is needed on the POWER
+based servers to create a memory dump required for the debugging. This document
+explains the high-level flow of warm reboot and extraction of the resulting dump
+from the hypervisor memory.
## Glossary
- **Boot**: The process of initializing hardware components in a computer system
-and loading the operating system.
+ and loading the operating system.
- **Hostboot**: The firmware runs on the host processors and performs all
-processor, bus, and memory initialization on POWER based servers.
-[read more](https://github.com/open-power/docs/blob/master/hostboot/HostBoot_PG.md)
+ processor, bus, and memory initialization on POWER based servers.
+ [read more](https://github.com/open-power/docs/blob/master/hostboot/HostBoot_PG.md)
- **Self Boot Engine (SBE)**: A microcontroller built into the host processors
-of POWER systems to assist in initializing the processor during the boot.
-It also acts as an entry point for several hardware access operations to the
-processor. [read more](https://sched.co/SPZP)
+ of POWER systems to assist in initializing the processor during the boot. It
+ also acts as an entry point for several hardware access operations to the
+ processor. [read more](https://sched.co/SPZP)
- **Master Processor**: The processor which gets initialized first to execute
-boot firmware.
+ boot firmware.
- **POWER Hardware Abstraction Layer (PHAL)**: A software component on the BMC
-providing access to the POWER hardware.
+ providing access to the POWER hardware.
- **Hypervisor**: A hypervisor (or virtual machine monitor, VMM) is a computer
-software, firmware, or hardware that creates and runs virtual machines
-[read more](https://en.wikipedia.org/wiki/Hypervisor)
+ software, firmware, or hardware that creates and runs virtual machines
+ [read more](https://en.wikipedia.org/wiki/Hypervisor)
- **System Dump**: A dump of main memory and hardware states for debugging the
-faults in hypervisor.
+ faults in hypervisor.
- **Memory Preserving Reboot (MPR)**: A method of reboot with preserving the
-contents of the volatile memory.
+ contents of the volatile memory.
-- **Terminate Immediate (TI)**: A condition when the hypervisor encountered
-a fatal error and cannot continue with the normal operations.
+- **Terminate Immediate (TI)**: A condition when the hypervisor encountered a
+ fatal error and cannot continue with the normal operations.
-- **Attention**: The signal generated by the hardware or the firmware for
-a specific event.
+- **Attention**: The signal generated by the hardware or the firmware for a
+ specific event.
-- **Redfish**: The Redfish standard is a suite of specifications that deliver
-an industry-standard protocol providing a RESTful interface for the management
-of servers, storage, networking, and converged infrastructure.
-[Read More](https://en.wikipedia.org/wiki/Redfish_(specification))
+- **Redfish**: The Redfish standard is a suite of specifications that deliver an
+ industry-standard protocol providing a RESTful interface for the management of
+ servers, storage, networking, and converged infrastructure.
+ [Read More](<https://en.wikipedia.org/wiki/Redfish_(specification)>)
- **OCC**: An On-Chip Controller (OCC) is a co-processor that is embedded
-directly on the die of POWER processors. The OCC can be used to controls
-the processor frequency, power consumption, and temperature to maximize
-performance and minimize energy usage.
+ directly on the die of POWER processors. The OCC can be used to controls the
+ processor frequency, power consumption, and temperature to maximize
+ performance and minimize energy usage.
[Read More](https://openpowerfoundation.org/on-chip-controller-occ/)
+
- **Checkstop**: A severe error inside a processor core that causes a processor
-core to stop all processing activities.
+ core to stop all processing activities.
- **PNOR**: PNOR is a host NOR flash where the firmware is stored.
## Background and References
-When the POWER based server encounters a fault and needs a restart,
-it alerts BMC to initiate a memory preserving reboot. BMC starts the reboot
-by informing the SBE on each of the processors. SBE stops the running cores and
-collects the hardware states in a specified format and store into the host
-memory. Once the data is collected, the SBE returns control to the BMC. BMC then
-initiates a memory preserved reboot. Once the system finished booting,
-the hypervisor collects the hardware data and memory contents to create
-a dump file in the host memory.
+
+When the POWER based server encounters a fault and needs a restart, it alerts
+BMC to initiate a memory preserving reboot. BMC starts the reboot by informing
+the SBE on each of the processors. SBE stops the running cores and collects the
+hardware states in a specified format and store into the host memory. Once the
+data is collected, the SBE returns control to the BMC. BMC then initiates a
+memory preserved reboot. Once the system finished booting, the hypervisor
+collects the hardware data and memory contents to create a dump file in the host
+memory.
## Requirements
### Primary Requirements
-- System dump should be collected irrespective of the availability of an
- external entity to offload it at the time of a failure.
+- System dump should be collected irrespective of the availability of an
+ external entity to offload it at the time of a failure.
-- It should provide a mechanism for the user to request a system dump.
+- It should provide a mechanism for the user to request a system dump.
-- The server should boot back to runtime
+- The server should boot back to runtime
-- The hypervisor should send a special attention to BMC to notify about
- a severe fault.
+- The hypervisor should send a special attention to BMC to notify about a severe
+ fault.
-- BMC should receive special TI attention from hypervisor
+- BMC should receive special TI attention from hypervisor
-- BMC should change the host state to 'DiagnosticMode.'
+- BMC should change the host state to 'DiagnosticMode.'
-- BMC should inform SBE to start the memory preserving reboot and
- collect the hardware data.
+- BMC should inform SBE to start the memory preserving reboot and collect the
+ hardware data.
-- Error log associated with dump needs to be part of the dump package
+- Error log associated with dump needs to be part of the dump package
-- A dump summary should be created with size and other details of the dump
+- A dump summary should be created with size and other details of the dump
-- Once the dump is generated, the hypervisor should notify BMC.
+- Once the dump is generated, the hypervisor should notify BMC.
-- Hypervisor should offload the dump to BMC to transfer to an external client.
+- Hypervisor should offload the dump to BMC to transfer to an external client.
-- Provide Redfish interfaces to manage dump
+- Provide Redfish interfaces to manage dump
-- A tool to collect the dump from the server.
+- A tool to collect the dump from the server.
-- A method to parse the content of the dump.
+- A method to parse the content of the dump.
## Proposed Design
### The flow
+
The flow of the memory preserving reboot and system dump offloading
#### 1 - Server fault and notification to BMC
+
When there is a fault, the hypervisor generates attention. The attention
listener on the BMC detects the attention. In the case of OpenPOWER based Linux
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.
#### 3 - Initiate System Dump
-Attention on the BMC sets the Diagnostic target for reboot to initiate a
-memory preserving reboot.
+
+Attention on the BMC sets the Diagnostic target for reboot to initiate a memory
+preserving reboot.
#### 4 - Initiate Memory preserve transition
-following steps are executed as part of the reboot target
- - Set the system state to DiagnosticMode
- - Stop OCC
- - Disable checkstop monitoring
- - Issue enter_mpipl chip-op to each SBE
+
+following steps are executed as part of the reboot target - Set the system state
+to DiagnosticMode - Stop OCC - Disable checkstop monitoring - Issue enter_mpipl
+chip-op to each SBE
#### 5 - SBE collects the hardware data
+
Each SBE collects the architected states and stores it into a pre-defined
location.
#### 6 - BMC Start warm boot
+
Once the SBE finishes the hardware collection, it does following to boot the
-system with preserving the memory.
- - Reset VPNOR
- - Enable watchdog
- - Enable checkstop monitoring
- - Run istep proc_select_boot_master
- - Run istep sbe_config_update
- - Issue continue_mpipl chip-op instead of start_cbs on the
- master processor
+system with preserving the memory. - Reset VPNOR - Enable watchdog - Enable
+checkstop monitoring - Run istep proc_select_boot_master - Run istep
+sbe_config_update - Issue continue_mpipl chip-op instead of start_cbs on the
+master processor
#### 7 - Hostboot booting
+
Once SBE is started, it starts hostboot, hostboot copies the architected states
to the right location, move the memory contents to create the dump.
#### 8 - Hypervisor Formats dump and sends notification to BMC
+
Once the hypervisor is started, it formats the dump and sends a notification to
-BMC through PLDM and with the dump size PLDM calls the dump manager
-interface to notify the dump. Dump manager creates a dBus object for the
-new dump, with status not offloaded and dump size.
-BMC web catches the object creation signal and notifies HMC.
+BMC through PLDM and with the dump size PLDM calls the dump manager interface to
+notify the dump. Dump manager creates a dBus object for the new dump, with
+status not offloaded and dump size. BMC web catches the object creation signal
+and notifies HMC.
#### 9 - HMC send request to dump offload
+
Once HMC is ready to offload, it creates NBD server and send dump offload
-request to BMC. BMCWeb creates an NBD client and NBD proxy to
-offload the dump. BMC dump manager make a PLDM call with dump id provided
-by hypervisor and the NBD device id. PLDM sends the offload request to the
-hypervisor with the dump id.
+request to BMC. BMCWeb creates an NBD client and NBD proxy to offload the dump.
+BMC dump manager make a PLDM call with dump id provided by hypervisor and the
+NBD device id. PLDM sends the offload request to the hypervisor with the dump
+id.
#### 10 - Hypervisor starts dump offload
-Hypervisor start sending down the dump packets through DMA
-PLDM reads the DUMP and write to the NBD client endpoint
-The data reaches the NBD server on the HMC and get written to a dump file.
+
+Hypervisor start sending down the dump packets through DMA PLDM reads the DUMP
+and write to the NBD client endpoint The data reaches the NBD server on the HMC
+and get written to a dump file.
#### 11 - Hypervisor sends down offload complete message
+
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.
-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.
+
+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.
+
### Dump offload sequence
+
## Alternatives Considered
+
Offload the dump from hypervisor to external dump collection application instead
-of offloading through BMC. But offloading though BMC is selected due to following
-reasons.
- - BMC provides a common point for offloading all dumps
- - During the prototyping, it is found that the offloading
- through BMC gave better performance.
- - Offloading through BMC has less development impact on the host.
+of offloading through BMC. But offloading though BMC is selected due to
+following reasons. - BMC provides a common point for offloading all dumps -
+During the prototyping, it is found that the offloading through BMC gave better
+performance. - Offloading through BMC has less development impact on the host.
## Impacts
+
- PLDM on BMC and Host - Extensions to PLDM implementation to pass type of dump,
- and notification of new dump file to dump manager. [PLDM Design]([https://github.com/openbmc/docs/blob/7c8847e95203ebfaeddb82a6e1b9888bc6a11311/designs/pldm-stack.md])
+ and notification of new dump file to dump manager.
+ [PLDM Design]([https://github.com/openbmc/docs/blob/7c8847e95203ebfaeddb82a6e1b9888bc6a11311/designs/pldm-stack.md])
- Dump manager on BMC - BMC dump manager supports dump stored on BMC and that
needs to expanded to support host dumps.
- External dump offloading application needs to support NBD based offload
-- Proposing a new redfish schema for dump operations. [Redfish Dump Proposal](https://lists.ozlabs.org/pipermail/openbmc/2019-December/019827.html)
+- Proposing a new redfish schema for dump operations.
+ [Redfish Dump Proposal](https://lists.ozlabs.org/pipermail/openbmc/2019-December/019827.html)
- BMC Web needs to implement new redfish specification for dump.
- Add support to openpower-hw-diags to catch special attention and initiate
memory preserving reboot.
-- SBE needs to support a new operation to analyze the attention received
- from the host. The interface update is yet to be published.
+- SBE needs to support a new operation to analyze the attention received from
+ the host. The interface update is yet to be published.
## Testing
-- Unit test plans
- - Test dump manager interfaces using busctl
- - Test reboot by setting the diag mode target
- - Test the SBE chip on using standalone calls
- - Test PLDM by using hypervisor debug commands
- - Test BMCWeb interfaces using curl
+
+- Unit test plans - Test dump manager interfaces using busctl - Test reboot by
+ setting the diag mode target - Test the SBE chip on using standalone calls -
+ Test PLDM by using hypervisor debug commands - Test BMCWeb interfaces using
+ curl
- Integration testing by
- - User-initiated dump testing, which invokes a memory preserving reboot
- to collect dump.
- - Initiate memory preserving reboot by injecting host error
- - Offload dump collected in host.
+
+ - User-initiated dump testing, which invokes a memory preserving reboot to
+ collect dump.
+ - Initiate memory preserving reboot by injecting host error
+ - Offload dump collected in host.
- System Dump test plan
- - Automated tests to initiate and offload dump as part of test bucket.
- - Both user-initiated and error injection should be attempted.
+ - Automated tests to initiate and offload dump as part of test bucket.
+ - Both user-initiated and error injection should be attempted.
diff --git a/designs/psu-firmware-update.md b/designs/psu-firmware-update.md
index 6149bf7..fd62d6f 100644
--- a/designs/psu-firmware-update.md
+++ b/designs/psu-firmware-update.md
@@ -1,45 +1,41 @@
# 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
-
+Created: 2019-06-03
## Problem Description
There is no support in OpenBMC to update the firmware for PSUs.
-
## Background and References
In OpenBMC, there is an existing interface for [software update][1].
The update process consists of:
+
1. Uploading an image to the BMC;
2. Processing the image to check the version and purpose of the image;
3. Verifying and activating the image.
Currently, BMC and BIOS firmware update are supported:
-* [phosphor-bmc-code-mgmt][2] implements BMC code update, and it supports all
+
+- [phosphor-bmc-code-mgmt][2] implements BMC code update, and it supports all
the above 3 processes.
-* [openpower-pnor-code-mgmt][3] implements BIOS code update, and it only
- implements "verifying and activating" the image. It shares the function of
- the above 1 & 2 processes.
-* Both of the above use the same [Software DBus interface][1].
+- [openpower-pnor-code-mgmt][3] implements BIOS code update, and it only
+ implements "verifying and activating" the image. It shares the function of the
+ above 1 & 2 processes.
+- Both of the above use the same [Software DBus interface][1].
For PSU firmware update, it is preferred to re-use the same function for the
above 1 & 2.
-
## Requirements
The PSU firmware shall be updated in the below cases:
+
1. The user manually invokes the APIs to do the update;
2. After BMC code update and if there is a newer PSU image in the BMC's
filesystem, BMC shall update the PSU firmware;
@@ -49,65 +45,64 @@
different PSU firmware images need to be supported.
For some PSUs, it is risky to do PSU code update while the host is running to
-avoid power loss. This shall be handled by PSU vendor-specific tools, but not
-in the generic framework.
+avoid power loss. This shall be handled by PSU vendor-specific tools, but not in
+the generic framework.
Note: The "vendor-specific" referred below is the PSU vendor-specific.
So the below checks are optional and expected to be handled by vendor-specific
tool:
+
1. If the host is powered off;
2. If the redundant PSUs are all connected;
3. If the AC input and DC standby output is OK on all the PSUs;
-
## Proposed Design
-As described in the above requirements, there are different cases where the
-PSU firmware is updated:
-* When the APIs are invoked;
-* When a new version is updated together with BMC code update;
-* When a PSU is replaced with an old version of the firmware.
+As described in the above requirements, there are different cases where the PSU
+firmware is updated:
+
+- When the APIs are invoked;
+- When a new version is updated together with BMC code update;
+- When a PSU is replaced with an old version of the firmware.
### Update by API
This method is usually used by users who manually update PSU firmware.
-It will re-use the current interfaces to upload, verify, and activate the
-image.
+It will re-use the current interfaces to upload, verify, and activate the image.
1. The "Version" interface needs to be extended:
- * Add a new [VersionPurpose][4] for PSU;
- * Re-use the existing `ExtendedVersion` as an additional string for
+ - Add a new [VersionPurpose][4] for PSU;
+ - Re-use the existing `ExtendedVersion` as an additional string for
vendor-specific purpose, e.g. to indicate the PSU model.
2. Re-use the existing functions implemented by [phosphor-bmc-code-mgmt][2] for
uploading and processing the image.
- * The PSU update image shall be a tarball that consists of a MANIFEST,
+ - The PSU update image shall be a tarball that consists of a MANIFEST,
images, and signatures.
- * When the PSU image is uploaded and processed, a `VersionObject` shall be
+ - When the PSU image is uploaded and processed, a `VersionObject` shall be
created to indicate the version and its purpose.
3. There will be a new service that implements the [Activation][5] interface to
update the PSU firmware.
- * The service will be started by default when BMC starts;
- * On start, the service will check the PSU's existing firmware and create
- the `Version` and `Activation` interfaces.
- * The service shall watch the interface added on
+ - The service will be started by default when BMC starts;
+ - On start, the service will check the PSU's existing firmware and create the
+ `Version` and `Activation` interfaces.
+ - The service shall watch the interface added on
`/xyz/openbmc_project/Software`.
- * When a new object with PSU `VersionPurpose` is added, the service will
+ - When a new object with PSU `VersionPurpose` is added, the service will
verify the signature of the image;
- * The service shall check the `ExtendedVersion` to make sure the image
+ - The service shall check the `ExtendedVersion` to make sure the image
matches the PSU model.
- * The service will have a configuration file to describe the PSU model and
+ - The service will have a configuration file to describe the PSU model and
its related vendor-specific tools.
- * The service will find the matched vendor-specific tool to perform the code
- update.
- For example, if a vendor specific tool `foo` is configured in
+ - The service will find the matched vendor-specific tool to perform the code
+ update. For example, if a vendor specific tool `foo` is configured in
`psu-update@foo.service` which executes `foo psu.bin`, the service will
find the `psu-update@foo.service` and start it by systemd, which performs
the update.
- * When the PSU code update is completed, an informational event log shall be
+ - When the PSU code update is completed, an informational event log shall be
created.
- * When the PSU code update is completed, the image, MANIFEST, and optionally
+ - When the PSU code update is completed, the image, MANIFEST, and optionally
the signature will be saved to a pre-defined directory in read-write
filesystem for future use, in case a new PSU with old firmware is plugged.
4. The vendor-specific tool shall run all the checks it needs to be run, before
@@ -116,25 +111,24 @@
5. When the vendor-specific tool returns errors, the PSU update will be aborted
and an error event log shall be created.
6. During the update, the service shall set the related sensors to
- non-functional, and when the update is done, it shall set the related
- sensors back to functional.
+ non-functional, and when the update is done, it shall set the related sensors
+ back to functional.
### Update by new BMC image
When BMC is updated and a new version of PSU firmware is included, it shall be
-updated to the PSU.
-This will be done by the same service described above.
+updated to the PSU. This will be done by the same service described above.
1. On start, the service will check the PSU image, model and version in its
filesystem, compare with the ones in PSU hardware and decide if PSU firmware
update shall be performed.
2. There could be two places containing the PSU images:
- * The pre-defined directory in read-only filesystem, which is part of BMC
+ - The pre-defined directory in read-only filesystem, which is part of BMC
image.
- * The other pre-defined directory in read-write filesystem, which is the
- location for the saved PSU images by API update.
- Both places shall be checked and a newer version will be selected to compare
- with the PSU hardware.
+ - The other pre-defined directory in read-write filesystem, which is the
+ location for the saved PSU images by API update. Both places shall be
+ checked and a newer version will be selected to compare with the PSU
+ hardware.
3. If PSU update is needed, the service will find the matched vendor-specific
tool to perform the code update.
4. The following process will be the same as [Update by API].
@@ -142,78 +136,77 @@
### Update on replaced PSU
When a PSU is replaced, and the firmware version is older than the one in BMC
-filesystem, it shall be updated.
-This will be done by the same service described above.
+filesystem, it shall be updated. This will be done by the same service described
+above.
-1. On start, the service will subscribe to the PropertiesChanged signal to
- the PSU object path to monitor the PSU presence status.
- (Or maybe subscribe the InterfacesAdded/Removed signal?)
+1. On start, the service will subscribe to the PropertiesChanged signal to the
+ PSU object path to monitor the PSU presence status. (Or maybe subscribe the
+ InterfacesAdded/Removed signal?)
2. When a PSU's presence status is changed from false to true (or the
InterfacesAdded event occurs), the service will check the new PSU's model,
firmware version to decide if the firmware needs to be updated.
-3. If yes, the service will find the matched vendor-specific tool to perform
- the code update.
+3. If yes, the service will find the matched vendor-specific tool to perform the
+ code update.
4. The following process will be the same as [Update by API].
## Alternatives Considered
### General implementation
-The PSU firmware update could be implemented by separated recipes that only
-call vendor-specific tools.
-It will be a bit simpler but loses the unified interface provided by OpenBMC's
-existing [software update interface][1], and thus it will become difficult to
-use a standard API to the PSU firmware update.
+The PSU firmware update could be implemented by separated recipes that only call
+vendor-specific tools. It will be a bit simpler but loses the unified interface
+provided by OpenBMC's existing [software update interface][1], and thus it will
+become difficult to use a standard API to the PSU firmware update.
### VersionPurpose
-It is possible to re-use the `VersionPurpose.Other` to represent the PSU
-image's version purpose.
-But that requires additional information about the image, otherwise, there is
-no way to tell if the image is for PSU, or CPLD, or other peripherals.
-A new `VersionPurpose.PSU` is more specific and makes it easier to implement
-and friendly for the user.
+
+It is possible to re-use the `VersionPurpose.Other` to represent the PSU image's
+version purpose. But that requires additional information about the image,
+otherwise, there is no way to tell if the image is for PSU, or CPLD, or other
+peripherals. A new `VersionPurpose.PSU` is more specific and makes it easier to
+implement and friendly for the user.
### Additional string
+
The design proposal uses `ExtendedVersion` as the additional string for
vendor-specific purpose, e.g. to indicate the PSU model, so the implementation
-could check and compare if the image matches the PSU model.
-It is possible to make it optional or remove this additional string, then the
-implementation will not verify if the image matches the PSU. It could be OK if
-we trust the user who is uploading the correct image, especially the image
-shall be signed.
-But it is always risky in case the image does not match the PSU, and cause
-unintended damage if the incorrect PSU firmware is updated.
-
+could check and compare if the image matches the PSU model. It is possible to
+make it optional or remove this additional string, then the implementation will
+not verify if the image matches the PSU. It could be OK if we trust the user who
+is uploading the correct image, especially the image shall be signed. But it is
+always risky in case the image does not match the PSU, and cause unintended
+damage if the incorrect PSU firmware is updated.
## Impacts
This design only introduces a new `VersionPurpose` enum into the dbus
-interfaces.
-The newly introduced PSU firmware update service will be a new service that
-implements existing [Activation][5] interface.
-There will be new configuration files for the service to:
-* Link the vendor specific tool with PSU models.
-* Get the sensors related to the PSU.
-* etc.
+interfaces. The newly introduced PSU firmware update service will be a new
+service that implements existing [Activation][5] interface. There will be new
+configuration files for the service to:
+
+- Link the vendor specific tool with PSU models.
+- Get the sensors related to the PSU.
+- etc.
So the impacts are minimal to existing systems.
-
## Testing
It requires the manual tests to verify the PSU code update process.
-* Verify the PSU code update is done on all PSUs successfully;
-* Verify the PSU code update will fail if the vendor-specific tool fails on
+
+- Verify the PSU code update is done on all PSUs successfully;
+- Verify the PSU code update will fail if the vendor-specific tool fails on
pre-condition check, of fails on updating PSU.
-* Verify the PSU code update is performed after a new BMC image is updated
+- Verify the PSU code update is performed after a new BMC image is updated
containing a new version of PSU firmware.
-* Verify the PSU code update is performed after a PSU with old firmware is
+- Verify the PSU code update is performed after a PSU with old firmware is
plugged in.
-
-[1]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Software
+[1]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Software
[2]: https://github.com/openbmc/phosphor-bmc-code-mgmt/
[3]: https://github.com/openbmc/openpower-pnor-code-mgmt/
-[4]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/57b878d048f929643276f1bf7fdf750abc4bde8b/xyz/openbmc_project/Software/Version.interface.yaml#L14
-[5]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/Activation.interface.yaml
-
+[4]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/57b878d048f929643276f1bf7fdf750abc4bde8b/xyz/openbmc_project/Software/Version.interface.yaml#L14
+[5]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Software/Activation.interface.yaml
diff --git a/designs/psu-monitoring.md b/designs/psu-monitoring.md
index 075e846..0c80040 100644
--- a/designs/psu-monitoring.md
+++ b/designs/psu-monitoring.md
@@ -1,33 +1,31 @@
-
# Power Supply Monitoring Application
-Author:
- Brandon Wyman !bjwyman
+Author: Brandon Wyman !bjwyman
-Other contributors:
- Derek Howard
+Other contributors: Derek Howard
-Created:
- 2019-06-17
+Created: 2019-06-17
## Problem Description
-This is a proposal to provide a set of enhancements to the current OpenBMC
-power supply application for enterprise class systems. Some enterprise class
-systems may consist of a number of configuration variations including different
-power supply types and numbers. An application capable of communicating with the
+
+This is a proposal to provide a set of enhancements to the current OpenBMC power
+supply application for enterprise class systems. Some enterprise class systems
+may consist of a number of configuration variations including different power
+supply types and numbers. An application capable of communicating with the
different power supplies is needed in order to initialize the power supplies,
validate configurations, report invalid configurations, detect and report
various faults, and report vital product data (VPD). Some of the function will
be configurable to be included or excluded for use on different platforms.
## Background and References
+
The OpenBMC project currently has a [witherspoon-pfault-analysis][1] repository
that contains a power supply monitor application and a power sequencer monitor
application. The current power supply application is lacking things desired for
an enterprise class server.
-The intent of this new application design is to enhance the OpenBMC project
-with a single power supply application that can communicate with one or more
+The intent of this new application design is to enhance the OpenBMC project with
+a single power supply application that can communicate with one or more
[PMBus][2] power supplies and provide the enterprise features currently lacking
in the existing application that has multiple instances talking to a single
power supply.
@@ -38,47 +36,50 @@
could be configurable options as appropriate.
1. The power supply application must detect, isolate, and report individual
-input power and power FRU faults, during boot and at runtime only.
+ input power and power FRU faults, during boot and at runtime only.
2. The power supply application must determine power supply presence,
-configuration, and status, and report via external interfaces.
+ configuration, and status, and report via external interfaces.
3. The power supply application must report power supply failures to IPMI and
-Redfish requests (during boot and at runtime only).
+ Redfish requests (during boot and at runtime only).
4. The power supply application must report power supply present/missing changes
-and status to IPMI and Redfish requests, and to the hypervisor. Recipes and code
-for presence state monitoring and event log creation may need to be moved from
-the `phosphor-dbus-monitor` to this application, depending on if such function
-was already written or ported forward from a previously similar system.
+ and status to IPMI and Redfish requests, and to the hypervisor. Recipes and
+ code for presence state monitoring and event log creation may need to be
+ moved from the `phosphor-dbus-monitor` to this application, depending on if
+ such function was already written or ported forward from a previously similar
+ system.
5. The power supply application must ensure proper power supply configuration
-and report improper configurations (during boot and at runtime only).
+ and report improper configurations (during boot and at runtime only).
6. The power supply application must collect and report power supply VPD (unless
-that VPD is collected and reported via another application reading an EEPROM
-device).
+ that VPD is collected and reported via another application reading an EEPROM
+ device).
7. The power supply application must allow power supply hot-plug and concurrent
-maintenance (CM).
+ maintenance (CM).
8. The power supply application should create and update average and maximum
-power consumption metric interfaces for telemetry data.
+ power consumption metric interfaces for telemetry data.
9. The power supply application must be able to detect how many power supplies
-are present in the system, what type of power supply is present (maximum output
-power such as 900W, 1400W, 2200W, etc.), and what type of input power is being
-supplied (AC input, DC input, input voltage, etc.).
+ are present in the system, what type of power supply is present (maximum
+ output power such as 900W, 1400W, 2200W, etc.), and what type of input power
+ is being supplied (AC input, DC input, input voltage, etc.).
10. The application must be able to recognize if the power supplies present
-consist of a valid configuration. Certain invalid combinations may result in the
-application updating properties for a Minimum Ship Level ([MSL][3]) check.
+ consist of a valid configuration. Certain invalid combinations may result in
+ the application updating properties for a Minimum Ship Level ([MSL][3])
+ check.
11. The application must create error logs for invalid configurations, or for
-power supplies experiencing some other faulted condition (no input power, output
-over voltage, output over current, etc.).
+ power supplies experiencing some other faulted condition (no input power,
+ output over voltage, output over current, etc.).
12. The application would periodically communicate with the power supplies via
-the sysfs file system files updated via a PMBus device driver (currently only
-known to be created and updated by the [ibm-cffps][4] device driver). Certain
-device driver updates may be necessary to support some power supplies or power
-supply features. Any power supply that communicates using the PMBus
-specification should be able to be supported, some manufacturing specific code
-paths may be required for commands in the "User Data and Configuration"
-(USER_DATA_00 through USER_DATA_15) and the "Manufacturer Specific Commands"
-(MFR_SPECIFIC_00 through MFR_SPECIFIC_45), as well as bit definitions for
-STATUS_MFR_SPECIFIC and any other "MFR" command.
+ the sysfs file system files updated via a PMBus device driver (currently
+ only known to be created and updated by the [ibm-cffps][4] device driver).
+ Certain device driver updates may be necessary to support some power
+ supplies or power supply features. Any power supply that communicates using
+ the PMBus specification should be able to be supported, some manufacturing
+ specific code paths may be required for commands in the "User Data and
+ Configuration" (USER_DATA_00 through USER_DATA_15) and the "Manufacturer
+ Specific Commands" (MFR_SPECIFIC_00 through MFR_SPECIFIC_45), as well as bit
+ definitions for STATUS_MFR_SPECIFIC and any other "MFR" command.
## Proposed Design
+
The proposal is to create a single new power supply application in the OpenBMC
[phosphor-power][6] repository. The application would be written in C++17.
@@ -106,14 +107,17 @@
power supply, that function would be left to other userspace application(s).
## Alternatives Considered
+
The current implementation of multiple instances of a power supply monitor was
considered, essentially similar to the [psu-monitor][5] from the
[witherspoon-pfault-analysis][1] repository. This design was avoided due to:
- - Complexity of the various valid and invalid configuration combinations.
- - Power line disturbance communication.
- - Timing/serialization concerns with power supply communication.
+
+- Complexity of the various valid and invalid configuration combinations.
+- Power line disturbance communication.
+- Timing/serialization concerns with power supply communication.
## Impacts
+
The application is expected to have some impact on the PLDM API, due to the
various DBus properties it may be updating.
@@ -126,23 +130,28 @@
the one application per power supply.
## Testing
+
Testing can be accomplished via automated or manual testing to verify that:
-* Configuration not listed as valid results in appropriate behavior.
-* Application detects and logs faults for power supply faults including input
-faults, output faults, shorts, current share faults, communication failures,
-etc.
-* Power supply VPD data reported for present power supplies.
-* Power supply removal and insertion, on a system supporting concurrent
-maintenance, does not result in power loss to powered on system.
-* System operates through power supply faults and power line disturbances as
-appropriate.
+
+- Configuration not listed as valid results in appropriate behavior.
+- Application detects and logs faults for power supply faults including input
+ faults, output faults, shorts, current share faults, communication failures,
+ etc.
+- Power supply VPD data reported for present power supplies.
+- Power supply removal and insertion, on a system supporting concurrent
+ maintenance, does not result in power loss to powered on system.
+- System operates through power supply faults and power line disturbances as
+ appropriate.
CI testing could be impacted if a system being used for testing is in an
unsupported or faulted configuration.
[1]: https://github.com/openbmc/witherspoon-pfault-analysis
[2]: https://en.wikipedia.org/wiki/Power_Management_Bus
-[3]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/README.msl.md
-[4]: https://github.com/openbmc/linux/blob/dev-5.3/drivers/hwmon/pmbus/ibm-cffps.c
-[5]: https://github.com/openbmc/witherspoon-pfault-analysis/tree/master/power-supply
+[3]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/README.msl.md
+[4]:
+ https://github.com/openbmc/linux/blob/dev-5.3/drivers/hwmon/pmbus/ibm-cffps.c
+[5]:
+ https://github.com/openbmc/witherspoon-pfault-analysis/tree/master/power-supply
[6]: https://github.com/openbmc/phosphor-power/
diff --git a/designs/redfish-authorization.md b/designs/redfish-authorization.md
index 94c343d..5f9e4db 100644
--- a/designs/redfish-authorization.md
+++ b/designs/redfish-authorization.md
@@ -45,10 +45,11 @@
peer is missing.
**Note**, in the Redfish spec, OEM roles can be added via POST to the
-`RoleCollection` in the `AccountService`; `PrivilegesUsed`,
-`OEMPrivilegesUsed`, and properties of `Mappings` are all read-only.
+`RoleCollection` in the `AccountService`; `PrivilegesUsed`, `OEMPrivilegesUsed`,
+and properties of `Mappings` are all read-only.
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
@@ -64,11 +65,12 @@
("priv-admin", "priv-operator", "priv-user", "priv-noaccess"). These privileges
are implemented as Linux secondary groups.
-It also integrates LDAP (supports either ActiveDirectory or OpenLDAP) for
-remote user management, where BMC acts as a LDAP client and uses nslcd to
-automatically convert Linux system calls to LDAP queries.
+It also integrates LDAP (supports either ActiveDirectory or OpenLDAP) for remote
+user management, where BMC acts as a LDAP client and uses nslcd to automatically
+convert Linux system calls to LDAP queries.
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
@@ -82,17 +84,18 @@
BMCWeb supports various "authentication" options, but under the hood, to verify
the user is who they claim they are, there are two main authentication methods:
+
1. PAM based: use Linux-PAM to do username/password style of authentication
2. TLS based: use the Public Key infrastructure to verify signature of peer's
-certificates; then use identities (in X509 certificates, these are Common Name
-or Subject Alternative Name) as user names.
+ certificates; then use identities (in X509 certificates, these are Common
+ Name or Subject Alternative Name) as user names.
After getting the peer's user name, BMCWeb sends DBus queries to
-phosphor-user-manager to query the user's privileges and uses a hardcoded map
-to convert the privileges to Redfish roles. The hardcoded map is listed below:
+phosphor-user-manager to query the user's privileges and uses a hardcoded map to
+convert the privileges to Redfish roles. The hardcoded map is listed below:
| Phosphor-user-manager privileges (implemented as groups) | BMCWeb Redfish Roles |
-|----------------------------------------------------------|----------------------|
+| -------------------------------------------------------- | -------------------- |
| priv-admin | Administrator |
| priv-operator | Operator |
| priv-user | ReadOnly |
@@ -102,7 +105,7 @@
following hardcoded map:
| BMCWeb Redfish Roles | Assigned Redfish Privileges |
-|----------------------|----------------------------------------------------------------------------------------|
+| -------------------- | -------------------------------------------------------------------------------------- |
| Administrator | "Login", "ConfigureManager", "ConfigureUsers", "ConfigureSelf", "ConfigureComponents"} |
| Operator | "Login", "ConfigureSelf", "ConfigureComponents" |
| ReadOnly | "Login", "ConfigureSelf" |
@@ -110,19 +113,20 @@
At compile time, BMCWeb assigns each operation of each entity a set of required
Redfish Privileges. An authorization action is performed when a BMCWeb route
-callback is performed: check if the assigned Redfish Privileges is a superset
-of the required Redfish Privileges.
+callback is performed: check if the assigned Redfish Privileges is a superset of
+the required Redfish Privileges.
-In the following section, we refer a BMCWeb route as the handler of an
-operation of an given resource URI, which is what the BMCWEB_ROUTE macro has
-defined.
+In the following section, we refer a BMCWeb route as the handler of an operation
+of an given resource URI, which is what the BMCWEB_ROUTE macro has defined.
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
### Gaps
+
As mentioned above, majority of the current Redfish authorization settings are
configured at compile time including:
@@ -133,11 +137,11 @@
5. the operation-to-privilege mapping
However, modern systems have use cases where Redfish roles, Redfish privileges,
-and operation-to-privilege mapping need to change when the system keeps
-running. E.g., a new micro-service is introduced and needs to talk to existing
-BMCs in the fleet, we need to propagate a configuration so that this new peer
-gets a proper Redfish role and is authorized to access certain resources
-without rolling out a new BMC firmware.
+and operation-to-privilege mapping need to change when the system keeps running.
+E.g., a new micro-service is introduced and needs to talk to existing BMCs in
+the fleet, we need to propagate a configuration so that this new peer gets a
+proper Redfish role and is authorized to access certain resources without
+rolling out a new BMC firmware.
Another gap is that current Redfish roles and operation-to-privilege mapping
lead to a very coarse-grained access control, and doesn't implement the
@@ -148,49 +152,50 @@
For systems which have requirement where a given user only has access to the
resources it needs. For example, a micro-service responsible for remote power
control can only send GET to Chassis and ComputerSystems, and POST to
-corresponding ResetActions. With the existing implementation, such
-micro-service has at least ConfigureComponents Redfish privilege, which leads
-to being able to patch an EthernetInterface resource.
+corresponding ResetActions. With the existing implementation, such micro-service
+has at least ConfigureComponents Redfish privilege, which leads to being able to
+patch an EthernetInterface resource.
## Requirements
+
BMC implements a dynamic Redfish authorization system:
1. Clients shall be able to add new OEM Redfish privileges without recompile
2. Clients shall be able to add new OEM Redfish roles and assign it with any
-existing Redfish privileges without recompile
+ existing Redfish privileges without recompile
3. Clients shall be able to modify existing operation-to-privilege mappings
-without recompile
+ without recompile
4. Above changes on systems shall be atomic; that is, once changed, all new
-queries will use the latest configurations
+ queries will use the latest configurations
5. BMC shall perform sanity check on above modification; that is
- * It rejects ill formatted modification
- * It rejects modification of non-OEM privileges
- * It rejects deletion of OEM Redfish roles if any user (either local or
- remote) maps such roles
- * It rejects deletion of OEM Redfish privileges if any OEM Redfish role is
- assigned such privileges
+ - It rejects ill formatted modification
+ - It rejects modification of non-OEM privileges
+ - It rejects deletion of OEM Redfish roles if any user (either local or
+ remote) maps such roles
+ - It rejects deletion of OEM Redfish privileges if any OEM Redfish role is
+ assigned such privileges
6. BMC shall persist all the above modifications and recover from crash
7. Existing systems with the static authorization shall work as if this feature
-is not introduced, including non-Redfish routes (e.g., KVM websocket)
+ is not introduced, including non-Redfish routes (e.g., KVM websocket)
8. Default OEM roles and Redfish privileges must be selectable on a per system
-basis at compile time; default Redfish PrivilegeRegistry must be settable on a
-per system basis at compile time
+ basis at compile time; default Redfish PrivilegeRegistry must be settable on
+ a per system basis at compile time
9. The total storage used by this feature shall be limited; this is
- * The total rwfs disk usage increase is less than 100 KB on systems with
- the dynamic authorization feature enabled
- * The runtime memory usage increase is less than 1 MB on systems with
- the dynamic authorization feature enabled
- * The binary size increase of modified daemons is less than 100 KB on all
- systems
+ - The total rwfs disk usage increase is less than 100 KB on systems with the
+ dynamic authorization feature enabled
+ - The runtime memory usage increase is less than 1 MB on systems with the
+ dynamic authorization feature enabled
+ - The binary size increase of modified daemons is less than 100 KB on all
+ systems
10. BMC implements a complete privilege registry; that is
- * It shall implement all overrides in the Redfish base Privilege registries
- at compile time; it shall support configuring overrides at runtime but
- implementation may begin with static configuring and reject runtime
- modification
- * BMC exposes PrivilegeRegistry which represents the current configuration
- and reflects runtime changes
- * Changes to resource entities shall be propagated to the current privilege
- registries automatically
+ - It shall implement all overrides in the Redfish base Privilege registries
+ at compile time; it shall support configuring overrides at runtime but
+ implementation may begin with static configuring and reject runtime
+ modification
+ - BMC exposes PrivilegeRegistry which represents the current configuration
+ and reflects runtime changes
+ - Changes to resource entities shall be propagated to the current privilege
+ registries automatically
11. New Redfish resource can be implemented without modifying custom
PrivilegeRegistry
12. All the above shall be testable; CI must be capable of finding issues
@@ -211,11 +216,11 @@
To solve this, we propose the following solution:
-**Store Redfish Roles As Linux Users and Secondary Groups**
-We propose to store Redfish Roles as both Linux users and secondary groups.
-Storing as secondary groups is to associate users with Redfish roles. On the
-other hand, storing as users is to associate Redfish roles with Redfish
-privileges. See below section for these mappings.
+**Store Redfish Roles As Linux Users and Secondary Groups** We propose to store
+Redfish Roles as both Linux users and secondary groups. Storing as secondary
+groups is to associate users with Redfish roles. On the other hand, storing as
+users is to associate Redfish roles with Redfish privileges. See below section
+for these mappings.
Users for Redfish roles won't be any predefined groups (web, redfish, ipmi). We
can add extra attributes to distinguish them with real local and LDAP users.
@@ -229,18 +234,17 @@
configurable at compile time. Using acronym is to save characters since Linux
username has 31 characters limit.
-**Store Redfish Privileges as Secondary Groups**
-Redfish privileges will be stored as Linux secondary groups with a fixed prefix
-"openbmc-rfp". rfr" refers to Redfish privilege. OEM privileges will have fixed
-prefix "openbmc-orfp". "orfr" refers to OEM Redfish privilege.
+**Store Redfish Privileges as Secondary Groups** Redfish privileges will be
+stored as Linux secondary groups with a fixed prefix "openbmc-rfp". rfr" refers
+to Redfish privilege. OEM privileges will have fixed prefix "openbmc-orfp".
+"orfr" refers to OEM Redfish privilege.
-**Username to Redfish Role Mapping**
-Mapping a username to Redfish role becomes searching the group starting with
-"openbmc-rfr" that the user is in.
+**Username to Redfish Role Mapping** Mapping a username to Redfish role becomes
+searching the group starting with "openbmc-rfr" that the user is in.
-**Redfish Role to Redfish Privileges Mapping**
-Mapping a Redfish Role to Redfish privileges becomes searching all the groups
-starting with "openbmc-rfp" or "openbmc-orfp" of the user.
+**Redfish Role to Redfish Privileges Mapping** Mapping a Redfish Role to Redfish
+privileges becomes searching all the groups starting with "openbmc-rfp" or
+"openbmc-orfp" of the user.
A user maps be in multiple linux secondary groups meaning they are assigned
certain privileges; for example, user "PowerService" is in "openbmc-orfr-power"
@@ -281,18 +285,18 @@
+----------------------------+
```
-The above diagram works for LDAP users as well. A remote role or group can
-map to base Redfish roles or OEM Redfish roles via RemoteRoleMapping: an LDAP
-group maps to a single Redfish role stored as local users.
+The above diagram works for LDAP users as well. A remote role or group can map
+to base Redfish roles or OEM Redfish roles via RemoteRoleMapping: an LDAP group
+maps to a single Redfish role stored as local users.
We propose to extend the existing phosphor-user-manager:
1. It returns AllPrivileges dynamically by looking up the current groups
2. Phosphor-user-manager provides DBus APIs to query privileges of a given user
-The legacy groups (e.g., `priv-user`) still works as before. For example, a
-user in both `priv-user` and `openbmc-orfp-power` will have the following
-Redfish privileges: `Login`, `ConfigureSelf`, `OemPrivPower`.
+The legacy groups (e.g., `priv-user`) still works as before. For example, a user
+in both `priv-user` and `openbmc-orfp-power` will have the following Redfish
+privileges: `Login`, `ConfigureSelf`, `OemPrivPower`.
### Creation/Deletion: Users, Redfish Roles, and Redfish Privileges
@@ -300,8 +304,8 @@
#### OEM Redfish Privileges
-PATCH OEMPrivilegesUsed in PrivilegeRegistry creating/deleting OEM privileges
-to create or delete OEM Privileges at runtime.
+PATCH OEMPrivilegesUsed in PrivilegeRegistry creating/deleting OEM privileges to
+create or delete OEM Privileges at runtime.
We propose to extend the existing phosphor-user-manager:
@@ -311,9 +315,9 @@
2. Phosphor-user-manager keeps a maximum number of Redfish privileges; we
propose 32 as the first iteration considering fast bit manipulation
3. Phosphor-user-manager performs validation:
- * Names of OEM Redfish privileges are unique and valid; e.g., start with
+ - Names of OEM Redfish privileges are unique and valid; e.g., start with
"openbmc-orfp-"
- * Reject deletion of a privilege that's currently in use (assigned to any
+ - Reject deletion of a privilege that's currently in use (assigned to any
Redfish roles that have a user associated with)
Systems can also optionally add OEM Privileges at compile time via Yocto's
@@ -329,13 +333,14 @@
Predefined roles are not allowed to be deleted.
We propose to extend the existing phosphor-user-manager:
+
1. Phosphor-user-manager provides DBus APIs to create Redfish role
2. Phosphor-user-manager keeps a maximum number of Redfish roles; we propose 32
as the first iteration considering fast bit manipulation
3. Phosphor-user-manager performs validation:
- * Names of OEM Redfish roles are unique and valid; e.g., start with
+ - Names of OEM Redfish roles are unique and valid; e.g., start with
"openbmc-orfr-"
- * Reject deletion of a RedfishRole that's currently in use (associated with
+ - Reject deletion of a RedfishRole that's currently in use (associated with
users)
#### Users
@@ -352,8 +357,8 @@
#### Typical Workflow
In summary, a typical workflow to create a new local user with an new OEM
-Redfish role which is assigned a new set of OEM Redfish Privileges is mapped
-out below.
+Redfish role which is assigned a new set of OEM Redfish Privileges is mapped out
+below.
```
Root User BMCWeb Phosphor-User-Manager Linux
@@ -389,10 +394,12 @@
```
### Non-Redfish Routes or OEM Resources
+
We still keep the current `privileges` C++ API to add explicit Redfish
privileges for non-redfish routes via `BMCWEB_ROUTE`.
### Redfish Routes
+
We propose to create a new macro `REDFISH_ROUTE` so existing `REDFISH_ROUTE`
stay unchanged for non-redfish routes.
@@ -401,14 +408,15 @@
APIs:
1. `entity`: it takes a string representing the Resource name (the same
-definition as it in the PrivilegeRegistry); for example,
-"/redfish/v1/Managers/${ManagerId}/EthernetInterfaces/" will provide a string
-"EthernetInterfaceCollection" as the entity
+ definition as it in the PrivilegeRegistry); for example,
+ "/redfish/v1/Managers/${ManagerId}/EthernetInterfaces/" will provide a string
+ "EthernetInterfaceCollection" as the entity
2. `subordinateTo`: it takes an array of string representing what resource this
-router is subordinate to (the same definition as it in the PrivilegeRegistry);
-for example, a route with URL
-"/redfish/v1/Managers/${ManagerId}/EthernetInterfaces/" will provide an array
-of {"Manager", "EthernetInterfaceCollection"} as the value of `subordinateTo`.
+ router is subordinate to (the same definition as it in the
+ PrivilegeRegistry); for example, a route with URL
+ "/redfish/v1/Managers/${ManagerId}/EthernetInterfaces/" will provide an array
+ of {"Manager", "EthernetInterfaceCollection"} as the value of
+ `subordinateTo`.
Any Redfish route must provide these attributes. Non Redfish route shall not
provide them, instead, they specify `privileges` directly. The values of these
@@ -416,50 +424,52 @@
in C++ code, we can make them required parameters in constructors.
See below for how we propose to get required Redfish privileges for a given
-method on a given resource by using the proposed `entity` & `subordinateTo`,
-the existing `methods`, and the URL from the request.
+method on a given resource by using the proposed `entity` & `subordinateTo`, the
+existing `methods`, and the URL from the request.
See the alternatives section for how we can get rid of setting these attributes
at manually.
### Operation-to-Privilege Mapping Data Structure in Memory
+
BMCWeb keeps a JSON like data structure in memory to represent the whole
Operation-to-Privilege Mapping. For a given route with known entity name, HTTP
method, and resource URL, the required set of privileges can be retrieved
efficiently.
-The operation to check if a user is authorized to perform a Redfish operation
-is still the existing bit-wise `isSupersetOf` between the required privileges
-of a given operation on a given resource and the assigned privileges of a role.
+The operation to check if a user is authorized to perform a Redfish operation is
+still the existing bit-wise `isSupersetOf` between the required privileges of a
+given operation on a given resource and the assigned privileges of a role.
### Generate Operation-to-Privilege Mapping Data Structure at Compile Time
+
BMCWeb has requirements that it doesn't prefer to load a large file at service
start time since it slows down the service, and whatever services rely on it.
Thus, we propose to generate the data structure at compile time, it takes a
-PrivilegeRegistry JSON, and generate necessary headers and sources files to
-hold a variable that represent the whole Operation-to-Privilege Mapping. The
-input JSON can change across systems.
+PrivilegeRegistry JSON, and generate necessary headers and sources files to hold
+a variable that represent the whole Operation-to-Privilege Mapping. The input
+JSON can change across systems.
This can be implemented as a customized Meson generator.
We will delete the current static privileges header, but the generated header
-will increase the binary size. We shall limit the increase to <= 100KB. The
-size of `Redfish_1.3.0_PrivilegeRegistry.json` is about 275 KB; the minified
-version of it (no whitespace) is about 62 KB. When parsing this JSON and
-converting it to C++ codes, we shall not increase the binary size a lot
-otherwise we can just store the whole registry as a Nlohmann JSON object.
+will increase the binary size. We shall limit the increase to <= 100KB. The size
+of `Redfish_1.3.0_PrivilegeRegistry.json` is about 275 KB; the minified version
+of it (no whitespace) is about 62 KB. When parsing this JSON and converting it
+to C++ codes, we shall not increase the binary size a lot otherwise we can just
+store the whole registry as a Nlohmann JSON object.
### Operation-to-Privilege Mapping Overrides
-In routing codes, we can parse the Operation-to-Privilege Mapping Data
-Structure and look for SubordinateOverrides and ResourceURIOverrides, combine
-them with the attributes from route and request, and perform authorization.
+In routing codes, we can parse the Operation-to-Privilege Mapping Data Structure
+and look for SubordinateOverrides and ResourceURIOverrides, combine them with
+the attributes from route and request, and perform authorization.
Most part of the Authorization codes run before resource handlers. However,
-PropertyOverrides for read operation can only be executed when response is
-ready since we need to inspect the response attributes. PropertyOverrides for
-write operator shall still run before the handler codes: the authorization code
+PropertyOverrides for read operation can only be executed when response is ready
+since we need to inspect the response attributes. PropertyOverrides for write
+operator shall still run before the handler codes: the authorization code
inspect the request payload and corresponding properties, and look them up in
the Operation-to-Privilege Mapping in-memory Data Structure.
@@ -560,8 +570,8 @@
### Persistent Data
OEM Redfish roles, Redfish privileges, and users are persisted by Linux. With a
-maximum number of roles and privileges being set, the total persistent data
-will be very small (around several KB).
+maximum number of roles and privileges being set, the total persistent data will
+be very small (around several KB).
To minimize size of persistent data, we propose that BMCWeb only stores the
serial of PATCH requests on the PrivilegeRegistry. This data can be stored in
@@ -584,25 +594,28 @@
## Alternatives Considered
### Infer Entity and SubordinateTo from URL
+
We can infer the entity from the URL by building a Trie like data structure.
-However, it's not a big deal to hardcode an entity for a route, since entity
-and SubordinateTo never change at runtime.
+However, it's not a big deal to hardcode an entity for a route, since entity and
+SubordinateTo never change at runtime.
## Impacts
+
1. New DBus interfaces on phosphor-user-manager
2. New persistent data managed by BMCWeb will be added on BMCs
3. Binary size will increase on BMCWeb
4. Existing systems with the static authorization shall work as if this feature
-is not introduced
+ is not introduced
## Organizational
-No new repository is required. Phosphor-user-manager and BMCWeb will be
-modified to implement the design.
+
+No new repository is required. Phosphor-user-manager and BMCWeb will be modified
+to implement the design.
## Testing
-Existing tests shall still pass as if this feature is not introduced.
-New Robot Framework test can be added to test runtime modification of
-PrivilegeRegistry.
+
+Existing tests shall still pass as if this feature is not introduced. New Robot
+Framework test can be added to test runtime modification of PrivilegeRegistry.
Test cases should include:
@@ -610,11 +623,10 @@
respect the Redfish spec when no runtime modification is made
2. verify Redfish OemPrivilege can be added via PATCH to PrivilegeRegistry and
reflected in the PrivilegeRegistry resource
-3. verify Redfish OemRole can be added via POST to ManagerAccountCollection
- with assigned OemPrivilege and reflected in the ManagerAccountCollection
-4. verify operation-to-privilege can be modified via PATCH on
- PrivilegeRegistry; mapping of an action on a resource can be added with the
- above OemPrivilege, and finally the user of that OemRole now can access the
- resource
+3. verify Redfish OemRole can be added via POST to ManagerAccountCollection with
+ assigned OemPrivilege and reflected in the ManagerAccountCollection
+4. verify operation-to-privilege can be modified via PATCH on PrivilegeRegistry;
+ mapping of an action on a resource can be added with the above OemPrivilege,
+ and finally the user of that OemRole now can access the resource
5. verify the 3 dynamic overriding is working as expected; e.g., a new override
- can be added to PrivilegeRegistry and should be reflected in new requests
\ No newline at end of file
+ can be added to PrivilegeRegistry and should be reflected in new requests
diff --git a/designs/redfish-eventservice.md b/designs/redfish-eventservice.md
index 701d05c..f29f311 100644
--- a/designs/redfish-eventservice.md
+++ b/designs/redfish-eventservice.md
@@ -1,4 +1,5 @@
# Redfish EventService design
+
Author: AppaRao Puli
Other contributors: None
@@ -6,110 +7,110 @@
Created: 2019-07-24
## Problem description
-Redfish in OpenBMC currently supports sending response to the clients
-which requests for data. Currently there is no service to send asynchronous
-message to the client about any events, error or state updates.
-The goal of this design document is to give resource overview of
-redfish event service and its implementation details in OpenBMC.
+Redfish in OpenBMC currently supports sending response to the clients which
+requests for data. Currently there is no service to send asynchronous message to
+the client about any events, error or state updates.
+
+The goal of this design document is to give resource overview of redfish event
+service and its implementation details in OpenBMC.
## Background and references
- - [Redfish specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf)
- - [DMTF Redfish school events](https://www.dmtf.org/sites/default/files/Redfish_School-Events_2018.2.pdf)
- - [Redfish event logging](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md)
- - [Telemetry service](https://gerrit.openbmc.org/#/c/openbmc/docs/+/24357/)
- - [Beast async client](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async/)
- - [Beast async-ssl client](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async-ssl/)
- - [EventService schema](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml)
- - [EventDestinationCollection schema](https://redfish.dmtf.org/schemas/v1/EventDestinationCollection_v1.xml)
- - [EventDestination schema](https://redfish.dmtf.org/schemas/v1/EventDestination_v1.xml)
- - [Upgrade connection for SSE](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/13948/)
+- [Redfish specification](https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf)
+- [DMTF Redfish school events](https://www.dmtf.org/sites/default/files/Redfish_School-Events_2018.2.pdf)
+- [Redfish event logging](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md)
+- [Telemetry service](https://gerrit.openbmc.org/#/c/openbmc/docs/+/24357/)
+- [Beast async client](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async/)
+- [Beast async-ssl client](https://www.boost.org/doc/libs/develop/libs/beast/example/http/client/async-ssl/)
+- [EventService schema](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml)
+- [EventDestinationCollection schema](https://redfish.dmtf.org/schemas/v1/EventDestinationCollection_v1.xml)
+- [EventDestination schema](https://redfish.dmtf.org/schemas/v1/EventDestination_v1.xml)
+- [Upgrade connection for SSE](https://gerrit.openbmc.org/#/c/openbmc/bmcweb/+/13948/)
## Requirements
High level requirements:
- - BMC shall support send asynchronous event notification to external
- subscribed clients over network using redfish(http/https) protocol,
- instead of regular querying mechanism.
- - BMC shall provide mechanism to the users to configure event service
- with specific filters and accordingly send the event notifications
- to all the registered clients.
- - BMC shall preserve the event service configuration across reboots, and
- shall reset the same, when factory defaults applied.
- - BMC shall have provision to disable the EventService.
- - The BMC Redfish interface shall support the EventService, EventDestination
- and EventDestinationCollection schemas.
- - BMC can provide functionality to send out test events(SubmitTestEvent).
- - Must allow only users having 'ConfigureManager' to create, delete or
- updated event service configuration, subscriptions and restrict other users.
- Must allow users with 'Login' privileges to view the EventService
- configuration and subscription details.
- - EventService shall be specific to Redfish Interface alone.
- i.e No other service can add/modify/delete configuration or subscriptions.
- - Either the client or the service can terminate the event stream at any time.
- The service may terminate a subscription if the number of delivery error's
- exceeds preconfigured thresholds.
- - For Push style event subscription creation, BMC shall respond to a
- successful subscription with HTTP status 201 and set the HTTP Location
- header to the address of a new subscription resource. Subscriptions are
- persistent and shall remain across event service restarts.
- - For Push style event subscription creation, BMC shall respond to client with
- http status as
- - 400: If parameter in body is not supported.
- - 404: If request body contains both RegistryPrefixes and MessageIds.
- - SSE: BMC shall respond to GET method on URI specific in "ServerSentEventUri"
- in EventService schema with 201(created) along with subscription
- information. BMC shall open a new https connection and should keep
- connection alive till subscription is valid. BMC shall respond with https
- code 400, if filter parameters are not supported or 404 if filter
- parameter contains invalid data. Also SSE subscription data cannot be
- persistent across service resets/reboots.
- - Clients shall terminate a subscription by sending an DELETE message to
- the URI of the subscription resource.
- - BMC may terminate a subscription by sending a special "subscription
- terminated" event as the last message. Future requests to the associated
- subscription resource will respond with HTTP status code 404.
- - BMC shall accept the "Last-Event-ID" header from the client to allow a
- client to restart the event/metric report stream in case the connection
- is interrupted.
- - To avoid exhausting the connection resource, BMC shall implement a
- restriction of maximum 20 connections (Maximum of 10 SSE connections). BMC
- shall respond with 503 Service Unavailable server error response code
- indicating that the server is not ready to handle the request.
- - BMC shall log an redfish event message for subscription addition, deletion
- and modification.
- - Services shall not send a "push" event payload of size more than 1 MB.
+- BMC shall support send asynchronous event notification to external subscribed
+ clients over network using redfish(http/https) protocol, instead of regular
+ querying mechanism.
+- BMC shall provide mechanism to the users to configure event service with
+ specific filters and accordingly send the event notifications to all the
+ registered clients.
+- BMC shall preserve the event service configuration across reboots, and shall
+ reset the same, when factory defaults applied.
+- BMC shall have provision to disable the EventService.
+- The BMC Redfish interface shall support the EventService, EventDestination and
+ EventDestinationCollection schemas.
+- BMC can provide functionality to send out test events(SubmitTestEvent).
+- Must allow only users having 'ConfigureManager' to create, delete or updated
+ event service configuration, subscriptions and restrict other users. Must
+ allow users with 'Login' privileges to view the EventService configuration and
+ subscription details.
+- EventService shall be specific to Redfish Interface alone. i.e No other
+ service can add/modify/delete configuration or subscriptions.
+- Either the client or the service can terminate the event stream at any time.
+ The service may terminate a subscription if the number of delivery error's
+ exceeds preconfigured thresholds.
+- For Push style event subscription creation, BMC shall respond to a successful
+ subscription with HTTP status 201 and set the HTTP Location header to the
+ address of a new subscription resource. Subscriptions are persistent and shall
+ remain across event service restarts.
+- For Push style event subscription creation, BMC shall respond to client with
+ http status as
+ - 400: If parameter in body is not supported.
+ - 404: If request body contains both RegistryPrefixes and MessageIds.
+- SSE: BMC shall respond to GET method on URI specific in "ServerSentEventUri"
+ in EventService schema with 201(created) along with subscription information.
+ BMC shall open a new https connection and should keep connection alive till
+ subscription is valid. BMC shall respond with https code 400, if filter
+ parameters are not supported or 404 if filter parameter contains invalid data.
+ Also SSE subscription data cannot be persistent across service resets/reboots.
+- Clients shall terminate a subscription by sending an DELETE message to the URI
+ of the subscription resource.
+- BMC may terminate a subscription by sending a special "subscription
+ terminated" event as the last message. Future requests to the associated
+ subscription resource will respond with HTTP status code 404.
+- BMC shall accept the "Last-Event-ID" header from the client to allow a client
+ to restart the event/metric report stream in case the connection is
+ interrupted.
+- To avoid exhausting the connection resource, BMC shall implement a restriction
+ of maximum 20 connections (Maximum of 10 SSE connections). BMC shall respond
+ with 503 Service Unavailable server error response code indicating that the
+ server is not ready to handle the request.
+- BMC shall log an redfish event message for subscription addition, deletion and
+ modification.
+- Services shall not send a "push" event payload of size more than 1 MB.
## Proposed design
Redfish event service provides a way to subscribe to specific kinds of Events,
-MetricReport and asynchronously send subscribed type of events or reports
-to client whenever it occurs.
+MetricReport and asynchronously send subscribed type of events or reports to
+client whenever it occurs.
Two styles of events are supported OpenBMC EventService.
- 1. Push style events (https): When the service detects the need to send
- an event, it uses an HTTP POST to push the event message to the client.
- Clients can enable reception of events by creating a subscription entry
- in the EventService.
+1. Push style events (https): When the service detects the need to send an
+ event, it uses an HTTP POST to push the event message to the client. Clients
+ can enable reception of events by creating a subscription entry in the
+ EventService.
- 2. Server-Sent Events (SSE): Client opens an SSE connection to the service
- by performing a GET on the URI specified by the "ServerSentEventUri" in
- the Event Service.
+2. Server-Sent Events (SSE): Client opens an SSE connection to the service by
+ performing a GET on the URI specified by the "ServerSentEventUri" in the
+ Event Service.
This document majorly focuses on OpenBMC implementation point of view. For more
-details specific to EventService can be found in ["Redfish Specification"](
-https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf)
+details specific to EventService can be found in
+["Redfish Specification"](https://www.dmtf.org/sites/default/files/standards/documents/DSP0266_1.7.0.pdf)
sections:-
- - Eventing (Section 12.1)
- - Server Sent-Events (Section 12.5)
- - Security (Section 12 & 13.2.8)
-
+- Eventing (Section 12.1)
+- Server Sent-Events (Section 12.5)
+- Security (Section 12 & 13.2.8)
**BLOCK DIAGRAM**
+
```
+------------------------------------------------------------------------------------+
| CLIENT |
@@ -440,77 +441,76 @@
v v v v v v v
```
-
EventService design includes below major blocks.
- 1. Redfish resources (Schema based)
- 1. EventService
- 2. Subscription Collections (EventDestination collection)
- 3. Subscriptions (EventDestination)
- 2. Event Service Manager
- 1. Event log monitor
- 2. Event log formatter
- 3. MetricReport monitor/agent
- 4. MetricReport formatter
- 5. Event service Sender (Common)
- 3. EventService config store ( Persistent)
+1. Redfish resources (Schema based)
+ 1. EventService
+ 2. Subscription Collections (EventDestination collection)
+ 3. Subscriptions (EventDestination)
+2. Event Service Manager
+ 1. Event log monitor
+ 2. Event log formatter
+ 3. MetricReport monitor/agent
+ 4. MetricReport formatter
+ 5. Event service Sender (Common)
+3. EventService config store ( Persistent)
This document also covers the description of below modules.
- 1. Server-Sent Event(SSE): It covers details on what is SSE and
- how connection open, close are handled in different cases.
- 2. Push style events(HTTP/HTTPS): It covers how to subscribe for
- Push style events and how the http/https connections are handled
- in bmcweb.
- 3. SubmitTestEvent: Details on submit test event action.
+1. Server-Sent Event(SSE): It covers details on what is SSE and how connection
+ open, close are handled in different cases.
+2. Push style events(HTTP/HTTPS): It covers how to subscribe for Push style
+ events and how the http/https connections are handled in bmcweb.
+3. SubmitTestEvent: Details on submit test event action.
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.
-[link](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md)
+ Refer below link for more information on same.
- 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.
+ [link](https://github.com/openbmc/docs/blob/master/redfish-logging-in-bmcweb.md)
- 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..).
+ 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.
- Refer below link for design document of telemetry service.
-[link](https://gerrit.openbmc.org/#/c/openbmc/docs/+/24357/)
+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/)
### Redfish resource schema's
Redfish will have three major resources to support EventService.
- 1. Event Service
- 2. Subscription Collections
- 3. Subscriptions
+1. Event Service
+2. Subscription Collections
+3. Subscriptions
All the configuration and subscriptions information data will be cached on
bmcweb webserver and synced with config json file for restoring and persisting
@@ -518,50 +518,51 @@
**EventService**
- Contains the attributes of the service such as Service Enabled, status,
- delivery retry attempts, Event Types, Subscriptions, Actions URI etc.
+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 : [EventService](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml)
- - METHODS : `GET, PATCH`
+- URI : `/redfish/v1/EventService`
+- SCHEMA :
+ [EventService](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml)
+- METHODS : `GET, PATCH`
Refer Testing for supported properties and example.
-**Subscription Collections**
- This resource is used to get collection of all subscriptions and also used
- to configure the new subscriptions for automatic events.
+**Subscription Collections** This resource is used to get collection of all
+subscriptions and also used to configure the new subscriptions for automatic
+events.
- - URI : `/redfish/v1/EventService/Subscriptions`
- - SCHEMA : [EventDestinationCollection](https://redfish.dmtf.org/schemas/v1/EventDestinationCollection_v1.xml)
- - METHODS : `GET, POST`
+- URI : `/redfish/v1/EventService/Subscriptions`
+- SCHEMA :
+ [EventDestinationCollection](https://redfish.dmtf.org/schemas/v1/EventDestinationCollection_v1.xml)
+- METHODS : `GET, POST`
Refer Testing section for example.
-**Subscriptions**
- This resource contains the subscription details. Used to get each individual
- get subscription information, update & Delete existing subscription
- information.
+**Subscriptions** This resource contains the subscription details. Used to get
+each individual get subscription information, update & Delete existing
+subscription information.
- - URI : `/redfish/v1/EventService/Subscriptions/<ID>`
- - SCHEMA : [EventDestination](https://redfish.dmtf.org/schemas/v1/EventDestination_v1.xml)
- - METHODS : `GET, PATCH, DELETE`
+- URI : `/redfish/v1/EventService/Subscriptions/<ID>`
+- SCHEMA :
+ [EventDestination](https://redfish.dmtf.org/schemas/v1/EventDestination_v1.xml)
+- METHODS : `GET, PATCH, DELETE`
Refer Testing section for supported properties and example.
-
### Event service manager
Event Manager is main block which does monitor the events, format the request
body and send it to the subscribed destinations. It shall support for two types
of event formats which are define in redfish specification.
- 1. Event: Resource type 'Event' is used to receive alerts in the form of
- json body to subscribed clients when the subscription details matches
- for those event logs.
+1. Event: Resource type 'Event' is used to receive alerts in the form of json
+ body to subscribed clients when the subscription details matches for those
+ event logs.
- 2. MetricReport: It is used to receive alerts in the forms of json body
- to subscribed clients when the subscription details matches for the
- collected telemetry data by telemetry service.
+2. MetricReport: It is used to receive alerts in the forms of json body to
+ subscribed clients when the subscription details matches for the collected
+ telemetry data by telemetry service.
The "Event service sender" is common entity for both type of resources. The
formatter and monitor entities are different for each type of resources.
@@ -571,179 +572,167 @@
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
"Event service manager" will use **inotify** to watch on redfish event log file
-to identify the new events. Once it identifies the new events, it will read
-all logged events information from redfish event file and pass it to 'Event
-log formatter' for further processing. The last processed event data timestamp
-will be cached in bmcweb to identify the new events in redfish event log file.
+to identify the new events. Once it identifies the new events, it will read all
+logged events information from redfish event file and pass it to 'Event log
+formatter' for further processing. The last processed event data timestamp will
+be cached in bmcweb to identify the new events in redfish event log file.
-It monitors the live events for sending asynchronously and does not send
-the events logged before bmcweb service start.
+It monitors the live events for sending asynchronously and does not send the
+events logged before bmcweb service start.
**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 fetch all the subscription information from "Redfish
-event service store" and filter the events by checking severity, event
-type against the user subscribed information. It formats the http
-"request body" along with CustomText, HttpHeaders and send the Events over
-network using http protocol for the filtered subscribers.
+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
+fetch all the subscription information from "Redfish event service store" and
+filter the events by checking severity, event type against the user subscribed
+information. It formats the http "request body" along with CustomText,
+HttpHeaders and send the Events over network using http protocol for the
+filtered subscribers.
Refer Tested section for example request body.
**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.
-Monitoring service supports different monitoring modes (periodic, on change
-and on demand) along with aggregated operations such as single, average, max
-min, sum etc... This service periodically collects the metrics report depending
-on Telemetry service configuration such as 'Metric Definitions', 'Metric
-Report Definitions' and 'Metric Triggers'.
+Telemetry monitoring service ( Not covered in this document) is responsible for
+gathering metrics from D-Bus sensors and exposing them as D-Bus objects.
+Monitoring service supports different monitoring modes (periodic, on change and
+on demand) along with aggregated operations such as single, average, max min,
+sum etc... This service periodically collects the metrics report depending on
+Telemetry service configuration such as 'Metric Definitions', 'Metric Report
+Definitions' and 'Metric Triggers'.
-The telemetry monitor shall emit a signal when there is a collection of
-report. MetricReport monitor/agent shall implement the listener for
-telemetry signal and using the subscription information, it should match,
-filter the desired metric report to pass it on to 'MetricReport formatter'.
-Since 'MetricReport monitor' is tightly coupled with 'Telemetry monitor' which
-already does the monitoring loop, its responsibility of 'Telemetry
-monitor' to match the subscriptions rules and provide it to MetricReport
-formatter. The EventService should provide a way to communicate the
-subscriptions data whenever user creates or updates or delete subscription.
+The telemetry monitor shall emit a signal when there is a collection of report.
+MetricReport monitor/agent shall implement the listener for telemetry signal and
+using the subscription information, it should match, filter the desired metric
+report to pass it on to 'MetricReport formatter'. Since 'MetricReport monitor'
+is tightly coupled with 'Telemetry monitor' which already does the monitoring
+loop, its responsibility of 'Telemetry monitor' to match the subscriptions rules
+and provide it to MetricReport formatter. The EventService should provide a way
+to communicate the subscriptions data whenever user creates or updates or delete
+subscription.
**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.
+from 'MetricReport monitor/agent' by checking subscriptions information such as
+HttpHeaders, Custom text strings along with Telemetry report data.
**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 subscribers. It supports sending both https and http
-requests by using beast library. The http/https connections handling
-(open/close) differs for both subscription types such as 'Push style
-events' and 'SSE' and more detailed are covered in respective sections.
+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
+subscribers. It supports sending both https and http requests by using beast
+library. The http/https connections handling (open/close) differs for both
+subscription types such as 'Push style events' and 'SSE' and more detailed are
+covered in respective sections.
Beast is a C++ header-only library serving as a foundation for writing
-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
+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)
- 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/)
+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/)
- 2. Server-Sent Events (SSE): The EventDestination resource of the
- subscription data shall contains the opaque of opened client
- SSE stream connection. After receiving the formatted event associated
- with specific subscription information, EventSender writes the formatted
- event data on open SSE connection with specific ID so that client
- can receive the event.
+2. Server-Sent Events (SSE): The EventDestination resource of the subscription
+ data shall contains the opaque of opened client SSE stream connection. After
+ receiving the formatted event associated with specific subscription
+ information, EventSender writes the formatted event data on open SSE
+ connection with specific ID so that client can receive the event.
-In case of push style eventing, https connection will be established
-during first event. If the connection is already established with subscription
-ID, then it uses same connection handle for sending events. This connection
-handle and subscription map will be stored in event service sender. Users can
-have multiple subscriptions coming from single destination and BMC will
-have separate connection handle associated with each subscription. Event
-listeners (web servers) has capability to accept multiple connections from
-same client(BMC) and depending on routing rules, the received events will be
-parsed on event listener side.
+In case of push style eventing, https connection will be established during
+first event. If the connection is already established with subscription ID, then
+it uses same connection handle for sending events. This connection handle and
+subscription map will be stored in event service sender. Users can have multiple
+subscriptions coming from single destination and BMC will have separate
+connection handle associated with each subscription. Event listeners (web
+servers) has capability to accept multiple connections from same client(BMC) and
+depending on routing rules, the received events will be parsed on event listener
+side.
-In case of SSE, connection handle will be read from resource and used by
-sender for sending events.
+In case of SSE, connection handle will be read from resource and used by sender
+for sending events.
-Received formatted data will be pushed to queue maintained under sender,
-against the connection-subscription map. Upon successful sending
-of event data, formatted data entry will be pop-ed from queue and
-next formatted data will be attempted for send and so on.
+Received formatted data will be pushed to queue maintained under sender, against
+the connection-subscription map. Upon successful sending of event data,
+formatted data entry will be pop-ed from queue and next formatted data will be
+attempted for send and so on.
-If send event(logs or metric reports) fails, then it will retry for
-number of attempts configured in Event Service "DeliveryRetryAttempts" with
-an interval of "DeliveryRetryIntervalSeconds". In case of Push Style Events
-if send fails due to some reasons, https connection will be
-re-established and first send will be re-attempted. If the failure persist even
-after the configured retry attempts, subscription information will be deleted
-and same will be updated to consumers(Telemetry service or event log service).
-In SSE connection, bmcweb would only retry sending events in the case of
-network failure/timeout/congestion. If there is error like connreset/badf,
-bmcweb will delete the subscription as specified above. In such scenario's,
-user can re-subscribe for events. This is requirement as per current redfish
+If send event(logs or metric reports) fails, then it will retry for number of
+attempts configured in Event Service "DeliveryRetryAttempts" with an interval of
+"DeliveryRetryIntervalSeconds". In case of Push Style Events if send fails due
+to some reasons, https connection will be re-established and first send will be
+re-attempted. If the failure persist even after the configured retry attempts,
+subscription information will be deleted and same will be updated to
+consumers(Telemetry service or event log service). In SSE connection, bmcweb
+would only retry sending events in the case of network
+failure/timeout/congestion. If there is error like connreset/badf, bmcweb will
+delete the subscription as specified above. In such scenario's, user can
+re-subscribe for events. This is requirement as per current redfish
specification.
-Any temporary network failure during event notification, and the failure
-persist till threshold limit, subscription entry will be remove. This may be
-security concern as client may not know about subscription termination,
-once network comes back.
-Note: Redfish specification says, Event destination subscription should be
-terminated after reaching threshold limit. This is known security concern.
-TBD: Need to work with Redfish forum for resolution.
-
+Any temporary network failure during event notification, and the failure persist
+till threshold limit, subscription entry will be remove. This may be security
+concern as client may not know about subscription termination, once network
+comes back. Note: Redfish specification says, Event destination subscription
+should be terminated after reaching threshold limit. This is known security
+concern. TBD: Need to work with Redfish forum for resolution.
### Redfish event service store
-Redfish event service store is used to store the all configuration
-related to EventService and subscriptions information. This does
-below operations:
+Redfish event service store is used to store the all configuration related to
+EventService and subscriptions information. This does below operations:
- - During bmcweb service start, it gets all the configuration and
- subscriptions information from config json file and populates the
- internal structures data.
+- During bmcweb service start, it gets all the configuration and subscriptions
+ information from config json file and populates the internal structures data.
- - Redfish EventService resources will get/update this event store for any
- user activities via redfish(Like Get/Add/Update/Delete subscriptions etc.)
+- Redfish EventService resources will get/update this event store for any user
+ activities via redfish(Like Get/Add/Update/Delete subscriptions etc.)
- - It will sync the "event config store" with configuration Json file for
- persisting the information when there is update.
- __Note__: Configuration json file will be updated only for Push style event
- subscription information. SSE events subscription information
- is volatile and will not get updated to json file.
+- It will sync the "event config store" with configuration Json file for
+ persisting the information when there is update. **Note**: Configuration json
+ file will be updated only for Push style event subscription information. SSE
+ events subscription information is volatile and will not get updated to json
+ file.
- - It will be used for getting all the subscription information to the
- "Event service manager" for filtering event data.
+- It will be used for getting all the subscription information to the "Event
+ service manager" for filtering event data.
-
-The bmcweb service will update the config store data
-including EventService configuration and subscription information to the
-json file(location: /var/lib/bmcweb/eventservice_data.json).
-This will be persistent across the bmcweb service restarts or bmc reboots
-and loads this while initializing bmcweb EventService class.
+The bmcweb service will update the config store data including EventService
+configuration and subscription information to the json file(location:
+/var/lib/bmcweb/eventservice_data.json). This will be persistent across the
+bmcweb service restarts or bmc reboots and loads this while initializing bmcweb
+EventService class.
Note:
- 1. In case of SSE, Client is initiator of connection and so SSE stream
- connection can't be re-established when bmcweb service or BMC goes
- for reboot. Hence subscription information related to SSE will not
- be persistent and Client must re-subscribe for SSE events using
- "ServerSentEventUri", whenever bmc comes out of reset.
+1. In case of SSE, Client is initiator of connection and so SSE stream
+ connection can't be re-established when bmcweb service or BMC goes for
+ reboot. Hence subscription information related to SSE will not be persistent
+ and Client must re-subscribe for SSE events using "ServerSentEventUri",
+ whenever bmc comes out of reset.
- Limitation: If bmcweb server closes abruptly due to some reasons
- like watchdog trigger, then bmcweb can't send close connection
- event to SSE client(For notifying SSE client to re-establishing
- connection).
-
+ Limitation: If bmcweb server closes abruptly due to some reasons like
+ watchdog trigger, then bmcweb can't send close connection event to SSE
+ client(For notifying SSE client to re-establishing connection).
Cache implementation includes below major blocks:
- - EventServiceStore Class: It holds the map of all subscriptions with
- unique key and methods to Create/Delete/update subscription
- information. It also holds the high level configuration information
- associated with EventService schema.
+- EventServiceStore Class: It holds the map of all subscriptions with unique key
+ and methods to Create/Delete/update subscription information. It also holds
+ the high level configuration information associated with EventService schema.
- - Configuration structure: It holds the configuration associated with
- EventService schema properties.
+- Configuration structure: It holds the configuration associated with
+ EventService schema properties.
- - Subscription structure: It holds the data associated with each
- EventDestination schema properties along with established connection
- handle.
-
+- Subscription structure: It holds the data associated with each
+ EventDestination schema properties along with established connection handle.
### Server-Sent Events (SSE):
@@ -753,16 +742,16 @@
Server-Sent Events is a standard describing how servers can initiate data
transmission towards clients once an initial client connection has been
-established. They are commonly used to send message updates or continuous
-data streams to a browser client and designed to enhance native,
-cross-browser streaming through a JavaScript API called EventSource, through
-which a client requests a particular URL in order to receive an event stream.
+established. They are commonly used to send message updates or continuous data
+streams to a browser client and designed to enhance native, cross-browser
+streaming through a JavaScript API called EventSource, through which a client
+requests a particular URL in order to receive an event stream.
-The "EventService" resource contains a property called "ServerSentEventUri".
-If a client performs a GET on the URI specified by the "ServerSentEventUri",
-the bmcweb server keep the connection open and conform to the HTML5
-Specification until the client closes the socket. The bmcweb service
-should sent the response to GET URI with following headers.
+The "EventService" resource contains a property called "ServerSentEventUri". If
+a client performs a GET on the URI specified by the "ServerSentEventUri", the
+bmcweb server keep the connection open and conform to the HTML5 Specification
+until the client closes the socket. The bmcweb service should sent the response
+to GET URI with following headers.
```
'Content-Type': 'text/event-stream',
@@ -772,8 +761,9 @@
Events generated by the OpenBMC will be sent to the clients using the open
connection. Response of event message should contain the "data: " prefix and
-postfix "\n" on each line. For representing the end of data, it should end
-with "\n\n". Example sending json response should look like
+postfix "\n" on each line. For representing the end of data, it should end with
+"\n\n". Example sending json response should look like
+
```
data: {\n
data: "msg": "hello world",\n
@@ -781,31 +771,29 @@
data: }\n\n
```
-Open connection: When a client performs get on 'ServerSentEventUri' with
-desired filters, bmcweb create an EventDestination instance in the
-subscriptions 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 EventDestination resource shall be an opaque string generated by the
-service.
+Open connection: When a client performs get on 'ServerSentEventUri' with desired
+filters, bmcweb create an EventDestination instance in the subscriptions
+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
+EventDestination resource shall be an opaque string generated by the service.
-Note: since its GET operation on existing open connection(which is
-authenticated and authorized as normal operation), there is no special
-security breach with it. All bmcweb related security threat model applies
-here.
+Note: since its GET operation on existing open connection(which is authenticated
+and authorized as normal operation), there is no special security breach with
+it. All bmcweb related security threat model applies here.
-Close connection: Either the client or the server can terminate the event
-stream at any time and close the connection. The bmcweb server can delete the
+Close connection: Either the client or the server can terminate the event stream
+at any time and close the connection. The bmcweb server can delete the
corresponding EventDestination instance when the connection is closed.
Connection can be closed by,
- - Client by sending DELETE method on subscribed id URI.
- - Server(bmcweb) can close connection and send notification to client
- with 'event: close' request body.
+- Client by sending DELETE method on subscribed id URI.
+- Server(bmcweb) can close connection and send notification to client with
+ 'event: close' request body.
Since SSE is uni-directional, if client closes connection/browser abruptly,
bmcweb service doesn't know the client connection state. This is limitation on
@@ -813,28 +801,29 @@
the number of delivery errors exceeds preconfigured thresholds.
Note:
- - The SSE subscription data is not persistent in nature. When bmcweb
- restarts or BMC reboots, client should re-establish the SSE connection to
- bmcweb to listen for events.
- - In case of SSE, client can send the "Last-Event-ID" as header. Monitor
- service will fetch all the event or metric report stream captured after
- that specified "Last-Event-ID" and send to client after formatting. If
- it fails to find the specified event ID, it will start streaming only live
- events/metric reports.
-The service should support using the $filter query parameter provided in the
-URI for the SSE stream by the client to reduce the amount of data returned
-to the client.
+- The SSE subscription data is not persistent in nature. When bmcweb restarts or
+ BMC reboots, client should re-establish the SSE connection to bmcweb to listen
+ for events.
+- In case of SSE, client can send the "Last-Event-ID" as header. Monitor service
+ will fetch all the event or metric report stream captured after that specified
+ "Last-Event-ID" and send to client after formatting. If it fails to find the
+ specified event ID, it will start streaming only live events/metric reports.
+
+The service should support using the $filter query parameter provided in the URI
+for the SSE stream by the client to reduce the amount of data returned to the
+client.
Supported filters are:
- - RegistryPrefix
- - ResourceType
- - EventFormatType
- - MessageId
- - OriginResource
+- RegistryPrefix
+- ResourceType
+- EventFormatType
+- MessageId
+- OriginResource
Example for subscribing SSE with filters:
+
```
MessageId based filter:
METHOD: GET
@@ -851,47 +840,49 @@
### Push style events (HTTP/HTTPS)
-Unlike the SSE (where bmcweb act as server) push style events works in
-different way. In this case, BMC acts as HTTP client and send the data
-to webserver running on external system. In case of SSE, connection
-will be kept alive till stream closes but in push style events, connections
-are opened on need and closes immediately after pushing event/report data.
+Unlike the SSE (where bmcweb act as server) push style events works in different
+way. In this case, BMC acts as HTTP client and send the data to webserver
+running on external system. In case of SSE, connection will be kept alive till
+stream closes but in push style events, connections are opened on need and
+closes immediately after pushing event/report data.
By using POST method on '/redfish/v1/EventService/Subscriptions' URI with
desired request body (mandatory fields: Destination, Protocol), user can
-subscribe for the events. The monitor and formatter resources (both Event
-log and MetricReport) uses the subscribed data for match rules, when there
-is event log or Telemetry data available. The 'Event service sender' uses
-the destination field in subscribed data for opening the connection and
-pushing data to webserver running externally.
+subscribe for the events. The monitor and formatter resources (both Event log
+and MetricReport) uses the subscribed data for match rules, when there is event
+log or Telemetry data available. The 'Event service sender' uses the destination
+field in subscribed data for opening the connection and pushing data to
+webserver running externally.
It shall support both http and https (https is not defined in Redfish
-specification) connections which will be created using the boost::beast
-library. For https connection it uses the self-signed certificates which are
-loaded in certificate store. If establishing connection fails, it retries for
-configured retry attempts (DeliveryRetryAttempts) and delete the subscription
-if it reaches 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
+specification) connections which will be created using the boost::beast library.
+For https connection it uses the self-signed certificates which are loaded in
+certificate store. If establishing connection fails, it retries for configured
+retry attempts (DeliveryRetryAttempts) and delete the subscription if it reaches
+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)
-Example for created Push style event is documented in testing section
-of same document.
+Example for created Push style event is documented in testing section of same
+document.
### SubmitTestEvent
- This action shall add a test event to the event service with the event
- data specified in the action parameters. This message should then be sent
- to any all subscribed Listener destination targets depending on subscription
- data.
- - URI: `/redfish/v1/EventService/Actions/EventService.SubmitTestEvent`
- - SCHEMA: [EventService](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml)
- - METHODS : `POST`
+This action shall add a test event to the event service with the event data
+specified in the action parameters. This message should then be sent to any all
+subscribed Listener destination targets depending on subscription data.
+
+- URI: `/redfish/v1/EventService/Actions/EventService.SubmitTestEvent`
+- SCHEMA:
+ [EventService](https://redfish.dmtf.org/schemas/v1/EventService_v1.xml)
+- METHODS : `POST`
Note: EventService.v1_3_0 was updated to deprecate the EventType parameter in
- SubmitTestEvent, and add the EventGroupId parameter in SubmitTestEvent.
+SubmitTestEvent, and add the EventGroupId parameter in SubmitTestEvent.
Example POST Request body:
+
```
{
"Message": "Test Event for validation",
@@ -902,17 +893,16 @@
}
```
-
## Alternatives considered
**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.
-BMC provides a way to pool the event logs (using Events schema). Client can
-run continuously http GET on Events LogService and get the all the events from
-BMC. But in HTTP protocol fetching data revolves around request/response which
-is greater HTTP overhead.
+BMC provides a way to pool the event logs (using Events schema). Client can run
+continuously http GET on Events LogService and get the all the events from BMC.
+But in HTTP protocol fetching data revolves around request/response which is
+greater HTTP overhead.
Push style(https) eventing or SSE will avoid the http overhead of continuous
polling and send the data/events when it happens on server side to the
@@ -932,37 +922,36 @@
**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 centric which has its own limitation in terms of security, scalability
-etc. when compared with Redfish.
+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
+centric which has its own limitation in terms of security, scalability etc. when
+compared with Redfish.
-## Implementation design alternatives
+## Implementation design alternatives
- - Direct journal logs vs Redfish event log file using inotify
+- 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
- become very inefficient to monitor and process data to identify just for
- redfish event logs.
+1. sdjournal has multiple logs currently( not just event logs) and so this
+ become very inefficient to monitor and process data to identify just for
+ redfish event logs.
- 2. Some hooks need to be added to sdjournal to emit signals whenever messages
- are logged to sdjournal.
+2. Some hooks need to be added to sdjournal to emit signals whenever messages
+ are logged to sdjournal.
To overcome above challenges currently redfish event logs are filtered and
-logged to separate file using rsyslog. Same file is used by EventService
-by monitor the file using inotify.
+logged to separate file using rsyslog. Same file is used by EventService by
+monitor the file using inotify.
- - D-Bus service vs Event Service config store
+- D-Bus service vs Event Service config store
Considered creating separate D-Bus service for storing EventService
-configuration and subscriptions data. Also considered using settings
-D-Bus service for persisting the data across the reboots. But since
-EventService is specific to redfish/bmcweb and not consumed/updated
-by any other processes in system, there is no real gain with having D-Bus
-service.
+configuration and subscriptions data. Also considered using settings D-Bus
+service for persisting the data across the reboots. But since EventService is
+specific to redfish/bmcweb and not consumed/updated by any other processes in
+system, there is no real gain with having D-Bus service.
## Impacts
@@ -971,11 +960,11 @@
Push style events also support HTTP protocol which is not secured and is
susceptible to man-in-the-middle attacks and eavesdropping which may lead to
virus injections and leak sensitive information to attackers. The push style
-event subscription or changes to the BMC will be done over the
-secure HTTPS channel with full authentication and authorization. So, BMC side
-security is NOT compromised. Event Listener on client may get hacked data
-in-case of man-in-the-middle attacks. To avoid such attacks, it is recommended
-to use SSE event mechanism or https-based push style events.
+event subscription or changes to the BMC will be done over the secure HTTPS
+channel with full authentication and authorization. So, BMC side security is NOT
+compromised. Event Listener on client may get hacked data in-case of
+man-in-the-middle attacks. To avoid such attacks, it is recommended to use SSE
+event mechanism or https-based push style events.
SSE works on HTTPS protocol which is encrypted and secured. SSE EventService
subscriptions can be created or updated over HTTPS protocol along with proper
@@ -999,51 +988,50 @@
User should cover below functionalists.
- - View and update EventService configuration using GET and PATCH methods and
- validate the functionality.
- - Subscribe for Events (Both "Push style event" and "SSE") as described below
- and validate http status code for positive and negative use cases (Body
- parameter invalid, Invalid request, improper privilege - forbidden etc.).
- - Validate all subscription collections and each individual subscription.
- - Using delete method on subscription URI specific to ID and see connection
- closing properly on client side and subscription data clear on server side.
- - Enable and disable EventService, generate events and validate whether Events
- are sending properly to all subscriptions when its enabled and stopped
- sending when disabled.
- - Use SubmitTestEvent for generating Test Events. Also cover negative cases
- with invalid body data.
- - Validate the functionality of retry attempts and retry timeout with both
- positive and negative cases.
- - Client connection close: Close client connection which are listening for SSE
- and check server-side connection closes after configured retry attempts and
- clears the subscription information.
- - Reboot BMC or reset bmcweb service and check all "push style events"
- subscription is preserved and functional by generating and checking events.
- - Reboot BMC or reset bmcweb service and check all "SSE" subscription data
- is not preserved and client-side connection is closed properly.
- - Create user with multiple privileges and check create/delete/update
- subscription and configuration data are performed only for user having
- 'ConfiguredManager' privilege and view EventService information works only
- for 'Login'.
- - Create new subscription and check is the event message logged in redfish
- event logs or not. Also modify, delete subscription and see Redfish events
- are logged or not.
- - Validate the authenticity of events sent to client on subscription with
- proper filtered data(Ex: If RegisteryPrefixes is set to "OpenBMC.0.1", it
- should not send events with prefixes "OpenBMC.0.2") should be validated.
- - For security, validate GET on URI specified in "ServerSentEventUri" with
- un-authorized users and see it responds with properly http status code and
- should not create any subscription or open any http connection.
- - Max limit check: Creates max supported event subscriptions and validate.
-
+- View and update EventService configuration using GET and PATCH methods and
+ validate the functionality.
+- Subscribe for Events (Both "Push style event" and "SSE") as described below
+ and validate http status code for positive and negative use cases (Body
+ parameter invalid, Invalid request, improper privilege - forbidden etc.).
+- Validate all subscription collections and each individual subscription.
+- Using delete method on subscription URI specific to ID and see connection
+ closing properly on client side and subscription data clear on server side.
+- Enable and disable EventService, generate events and validate whether Events
+ are sending properly to all subscriptions when its enabled and stopped sending
+ when disabled.
+- Use SubmitTestEvent for generating Test Events. Also cover negative cases with
+ invalid body data.
+- Validate the functionality of retry attempts and retry timeout with both
+ positive and negative cases.
+- Client connection close: Close client connection which are listening for SSE
+ and check server-side connection closes after configured retry attempts and
+ clears the subscription information.
+- Reboot BMC or reset bmcweb service and check all "push style events"
+ subscription is preserved and functional by generating and checking events.
+- Reboot BMC or reset bmcweb service and check all "SSE" subscription data is
+ not preserved and client-side connection is closed properly.
+- Create user with multiple privileges and check create/delete/update
+ subscription and configuration data are performed only for user having
+ 'ConfiguredManager' privilege and view EventService information works only for
+ 'Login'.
+- Create new subscription and check is the event message logged in redfish event
+ logs or not. Also modify, delete subscription and see Redfish events are
+ logged or not.
+- Validate the authenticity of events sent to client on subscription with proper
+ filtered data(Ex: If RegisteryPrefixes is set to "OpenBMC.0.1", it should not
+ send events with prefixes "OpenBMC.0.2") should be validated.
+- For security, validate GET on URI specified in "ServerSentEventUri" with
+ un-authorized users and see it responds with properly http status code and
+ should not create any subscription or open any http connection.
+- Max limit check: Creates max supported event subscriptions and validate.
** Push style events: **
- 1) EventListner: Client should configure the web service for listening the
- events (Example: http://192.168.1.2/Events).
+1. EventListner: Client should configure the web service for listening the
+ events (Example: http://192.168.1.2/Events).
- 2) Subscription:
- Client can subscribe for events on BMC using below
+2. Subscription: Client can subscribe for events on BMC using below
+
```
URI: /redfish/v1/EventService/Subscriptions
METHOD: POST
@@ -1054,6 +1042,7 @@
"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.
@@ -1061,14 +1050,16 @@
Client can use "SubmitTestEvent" (Documented above) to test the working
state.
- 3) ViewSubscription: Client can get the subscriptions details using
+3. ViewSubscription: Client can get the subscriptions details using
+
```
URI: /redfish/v1/EventService/Subscriptions/<ID>
METHOD: GET
```
- 4) UpdateSubscription: At any point client can update the subscription
- information.
+4. UpdateSubscription: At any point client can update the subscription
+ information.
+
```
URI: /redfish/v1/EventService/Subscriptions/<ID>
METHOD: PATCH
@@ -1080,8 +1071,9 @@
}
```
- 5) DeleteSubscription: Client can unsubscribe and stop receiving events
- by deleting the subscription.
+5. DeleteSubscription: Client can unsubscribe and stop receiving events by
+ deleting the subscription.
+
```
URI: /redfish/v1/EventService/Subscriptions/<ID>
METHOD: DELETE
@@ -1089,36 +1081,41 @@
** Server-Sent events subscription: **
- 1) EventListner and Subscription: Client can open latest browser (chrome)
- and fire GET URI on "ServerSentEventUri" along with filters.
+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
```
+
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'
```
+
At this point onwards, client browser will receive events associated with
subscribed data.
Client can use "SubmitTestEvent" (Documented above) to test the working
state.
- 2) ViewSubscription: Client can get the subscriptions details using
+2. ViewSubscription: Client can get the subscriptions details using
+
```
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.
+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
@@ -1129,12 +1126,13 @@
}
```
- 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.
+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
@@ -1150,6 +1148,7 @@
There are multiple EventListners exist and here is simple node js server, which
can be run using "node server.js".
+
```
// server.js
const http = require("http");
@@ -1194,20 +1193,20 @@
});
```
-
Server-Sent Events (SSE):
-Client can open an SSE connection to the service by performing a GET
-on the URI specified by the "ServerSentEventUri" in the Event Service
-along with filters. Browser automatically prompt for credentials and
-upon successful completion of authentication and authorization, client
-connection will be established for listening events.
+Client can open an SSE connection to the service by performing a GET on the URI
+specified by the "ServerSentEventUri" in the Event Service along with filters.
+Browser automatically prompt for credentials and upon successful completion of
+authentication and authorization, client connection will be established for
+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)
-Another simple python script for testing SSE using EventSource.
-Run it using "python sse-client.py".
+Another simple python script for testing SSE using EventSource. Run it using
+"python sse-client.py".
+
```
// sse-client.py
import requests, json, sys, time, re, os
@@ -1243,24 +1242,23 @@
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.
+and SSEFilterPropertiesSupported\EventType properties.
Example GET Response:
+
```
{
"@odata.context": "/redfish/v1/$metadata#EventService.EventService",
@@ -1293,6 +1291,7 @@
**Subscription Collections**
Example GET output:
+
```
{
"@odata.type":"#EventDestinationCollection.EventDestinationCollection",
@@ -1314,17 +1313,18 @@
Supported properties:
-| PROPERTY NAME | TYPE | DESCRIPTION |
-|----------------------------|-------------|-----------------------------------|
-| Destination | String | The URI of the destination Event Service. |
-| Context | String | A client-supplied string that is stored with the event destination subscription. Default: null |
-| Protocol | Enum | The protocol type of the event connection. Default: redfish |
-| HttpHeaders | array(string) | This is for setting HTTP headers, such as authorization information. Default: null |
-| RegistryPrefixes | String | A list of the Prefixes for the Message Registries that contain the MessageIds that will be sent to this event destination. Default: null |
-| ResourceTypes | Array(String) | A list of Resource Type values (Schema names) that correspond to the OriginOfCondition. The version and full namespace should not be specified. Default: null |
-| EventFormatType | String | Indicates the content types of the message that will be sent to the EventDestination. Supported types are 'Event' and 'MetricReport'. Default: Event |
+| PROPERTY NAME | TYPE | DESCRIPTION |
+| ---------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Destination | String | The URI of the destination Event Service. |
+| Context | String | A client-supplied string that is stored with the event destination subscription. Default: null |
+| Protocol | Enum | The protocol type of the event connection. Default: redfish |
+| HttpHeaders | array(string) | This is for setting HTTP headers, such as authorization information. Default: null |
+| RegistryPrefixes | String | A list of the Prefixes for the Message Registries that contain the MessageIds that will be sent to this event destination. Default: null |
+| ResourceTypes | Array(String) | A list of Resource Type values (Schema names) that correspond to the OriginOfCondition. The version and full namespace should not be specified. Default: null |
+| EventFormatType | String | Indicates the content types of the message that will be sent to the EventDestination. Supported types are 'Event' and 'MetricReport'. Default: Event |
Example GET Request:
+
```
{
"@odata.context": "/redfish/v1/$metadata#EventDestination.EventDestination",
@@ -1353,7 +1353,8 @@
}
```
- - Event log formatted response body looks like:
+- Event log formatted response body looks like:
+
```
id: 1
data:{
@@ -1381,7 +1382,8 @@
data:}
```
- - Configuration structure pseudo code:
+- Configuration structure pseudo code:
+
```
struct EventSrvConfig
{
@@ -1391,7 +1393,8 @@
};
```
- - Subscription structure pseudo code:
+- Subscription structure pseudo code:
+
```
struct EventSrvSubscription
{
diff --git a/designs/redfish-health-rolllup.md b/designs/redfish-health-rolllup.md
index b1d90e1..7cf9623 100644
--- a/designs/redfish-health-rolllup.md
+++ b/designs/redfish-health-rolllup.md
@@ -1,6 +1,6 @@
# Redfish Health and Status
-Author: James Feist !jfei
+Author: James Feist !jfei
Other contributors: None
@@ -8,10 +8,10 @@
## Problem Description
-Redfish Status has 3 main properties: Health,
-HealthRollup, and State. We need ways to be able to determine from a high level
-the health of contained components. We also need to be able to determine the
-health of individual components.
+Redfish Status has 3 main properties: Health, HealthRollup, and State. We need
+ways to be able to determine from a high level the health of contained
+components. We also need to be able to determine the health of individual
+components.
## Background and References
@@ -37,6 +37,7 @@
ethernet interface failing needs to contribute to bmc health.
Some examples of health with different use cases are:
+
- Individual Sensors
- Chassis containing sensors
- Managers/BMC
@@ -71,6 +72,7 @@
https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Inventory/Item.interface.yaml
## Requirements
+
- Must minimize D-Bus calls needed to get health rollup
- Must minimize new D-Bus objects being created
- Should try to utilize existing D-Bus interfaces
@@ -85,11 +87,11 @@
### Chassis / System Health
-Chassis have individual sensors. Cross reference the individual sensors with
-the global health. If any of the sensors of the chassis are in the
-global health association for warning, the chassis rollup is warning.
-Likewise if any inventory for the chassis is in the global health critical, the
-chassis is critical. The global inventory item will be
+Chassis have individual sensors. Cross reference the individual sensors with the
+global health. If any of the sensors of the chassis are in the global health
+association for warning, the chassis rollup is warning. Likewise if any
+inventory for the chassis is in the global health critical, the chassis is
+critical. The global inventory item will be
xyz.openbmc_project.Inventory.Item.Global.
### Chassis / System Health Rollup
@@ -108,12 +110,11 @@
## Alternatives Considered
-A new daemon to track global health state. Although this would be difficult
-to reuse to track individual component health.
+A new daemon to track global health state. Although this would be difficult to
+reuse to track individual component health.
## Impacts
-
## Testing
Testing will be performed using sensor values and the status LED.
diff --git a/designs/redfish-pcie.md b/designs/redfish-pcie.md
index a0bebc2..9555d26 100644
--- a/designs/redfish-pcie.md
+++ b/designs/redfish-pcie.md
@@ -1,20 +1,19 @@
# Redfish PCIe Resources
-Author:
- Jason Bills, jmbills
+Author: Jason Bills, jmbills
-Other contributors:
- Ed Tanous
+Other contributors: Ed Tanous
-Created:
- April 3, 2019
+Created: April 3, 2019
## Problem Description
-Redfish has resources that describe PCIe devices and functions available
-on a system. It would be useful to provide these resources to users
-out-of-band over Redfish from OpenBMC.
+
+Redfish has resources that describe PCIe devices and functions available on a
+system. It would be useful to provide these resources to users out-of-band over
+Redfish from OpenBMC.
## Background and References
+
The Redfish PCIe resources are here:
[PCIeSlots](https://redfish.dmtf.org/schemas/PCIeSlots_v1.xml)
@@ -24,11 +23,13 @@
[PCIeFunction](https://redfish.dmtf.org/schemas/PCIeFunction_v1.xml)
## Requirements
-This feature is intended to meet the Redfish requirements for the PCIe
-resources above to provide useful system configuration information to system
+
+This feature is intended to meet the Redfish requirements for the PCIe resources
+above to provide useful system configuration information to system
administrators and operators.
## Proposed Design
+
The proposed implementation will follow the standard D-Bus producer-consumer
model used in OpenBMC. The producer will provide the required PCIe values read
from hardware. The consumer will retrieve and parse the D-Bus data to provide
@@ -43,27 +44,30 @@
hardware data will vary.
For example, on systems that the BMC has access to the host PCI configuration
-space, it can directly read the required registers. On systems without access
-to the host PCI configuration space, an entity such as the BIOS or OS can
-gather the required data and send it to the PCIe daemon through IPMI, etc.
+space, it can directly read the required registers. On systems without access to
+the host PCI configuration space, an entity such as the BIOS or OS can gather
+the required data and send it to the PCIe daemon through IPMI, etc.
When reading hardware directly, the PCIe daemon must be aware of power state
-changes and any BIOS timing requirements, so it can check for hardware
-changes, update its cache, and make the necessary changes to the D-Bus
-properties. This will allow a user to retrieve the latest PCIe resource data
-as of the last system boot even if it is powered off.
+changes and any BIOS timing requirements, so it can check for hardware changes,
+update its cache, and make the necessary changes to the D-Bus properties. This
+will allow a user to retrieve the latest PCIe resource data as of the last
+system boot even if it is powered off.
bmcweb will be the consumer. It will be responsible for retrieving the Redfish
PCIe resource data from the D-Bus properties and providing it to the user.
## Alternatives Considered
+
None.
## Impacts
-Possible performance impact on the hardware-scanning and D-Bus updates.
-The piece that implements hardware scanning should use mechanisms,
-such as caching of the hardware configuration, to minimize the scanning time
-and updates to D-Bus properties.
+
+Possible performance impact on the hardware-scanning and D-Bus updates. The
+piece that implements hardware scanning should use mechanisms, such as caching
+of the hardware configuration, to minimize the scanning time and updates to
+D-Bus properties.
## Testing
+
This can be tested using the Redfish Service Validator.
diff --git a/designs/redfish-postcodes.md b/designs/redfish-postcodes.md
index 430e764..0e4e329 100644
--- a/designs/redfish-postcodes.md
+++ b/designs/redfish-postcodes.md
@@ -1,25 +1,25 @@
# Logging BIOS POST Codes Through Redfish
-Author:
- Terry Duncan
+Author: Terry Duncan
-Other contributors:
- Jason Bills, Zhikui Ren
+Other contributors: Jason Bills, Zhikui Ren
-Created:
- December 23, 2019
+Created: December 23, 2019
## Problem Description
+
BIOS Power-On Self-Test (POST) codes are exposed on DBUS but not currently over
Redfish. This describes a method to expose the BIOS POST codes over the Redfish
interface using the logging service.
## Background and References
-The standard Redfish LogService and LogEntry schemas will be used to expose
-BIOS POST codes. An additional log service (PostCodes) will be added to
-the LogServiceCollection.
+
+The standard Redfish LogService and LogEntry schemas will be used to expose BIOS
+POST codes. An additional log service (PostCodes) will be added to the
+LogServiceCollection.
Sample [LogService](https://redfish.dmtf.org/schemas/LogService_v1.xml) entry:
+
```
https://obmc/redfish/v1/Systems/system/LogServices/PostCodes
{
@@ -43,6 +43,7 @@
Events will be exposed using the
[LogEntry](https://redfish.dmtf.org/schemas/LogEntry_v1.xml) schema.
+
```
https://obmc/redfish/v1/Systems/system/LogServices/PostCodes/Entries
{
@@ -75,9 +76,9 @@
}
```
-A new
-[MessageRegistry](https://redfish.dmtf.org/schemas/MessageRegistry_v1.xml)
+A new [MessageRegistry](https://redfish.dmtf.org/schemas/MessageRegistry_v1.xml)
schema entry defines the format for the message.
+
```
https://obmc/redfish/v1/Registries/OpenBMC/OpenBMC
{
@@ -109,16 +110,19 @@
```
## Requirements
-The Redfish Interface shall be Redfish compliant and pass the Redfish
-compliancy tests.
-The Redfish interface shall expose POST codes tracked on DBUS since the last
-BMC reset.
+The Redfish Interface shall be Redfish compliant and pass the Redfish compliancy
+tests.
+
+The Redfish interface shall expose POST codes tracked on DBUS since the last BMC
+reset.
## Proposed Design
+
Currently, OpenBMC exposes BIOS POST codes on DBus using the
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.
+
```
xyz.openbmc_project.State.Boot.PostCode
GetPostCodes(q undefined) → [uint64] undefined
@@ -128,6 +132,7 @@
The GetPostCodes method is called using the boot cycle index to retrieve the
codes for the boot cycle.
+
```
{
"call": "GetPostCodes",
@@ -152,6 +157,7 @@
The existing DBus GetPostCodes method will remain for backward compatibility. A
new method GetPostCodesTS will be added to include an ISO formatted time stamp
with micro-second resolution along with each POST code.
+
```
{
"call": "GetPostCodesTS",
@@ -175,6 +181,7 @@
The DBus DeleteAll interface will be implemented to remove entries. The Redfish
ClearLog action will call the DBus DeleteAll interface.
+
```
{
"call": "DeleteAll",
@@ -186,6 +193,7 @@
```
## Alternatives Considered
+
Consideration was given to using the existing DBus method and not exposing
associated time stamps. In this case, a single log entry could be used per boot
cycle exposing a string with all POST codes associated with that boot cycle.
@@ -196,8 +204,10 @@
discouraged. It can be revisited if DMTF adds a schema for POST codes.
## Impacts
-Backward compatibility remains with the existing DBUS interface method.
-Minimal performance impact is expected to track timestamps.
+
+Backward compatibility remains with the existing DBUS interface method. Minimal
+performance impact is expected to track timestamps.
## Testing
+
Compliance with Redfish will be tested using the Redfish Service Validator.
diff --git a/designs/redfish-resource-supplement-for-pfr.md b/designs/redfish-resource-supplement-for-pfr.md
index 14c32d4..c6c7daf 100644
--- a/designs/redfish-resource-supplement-for-pfr.md
+++ b/designs/redfish-resource-supplement-for-pfr.md
@@ -9,19 +9,18 @@
## Problem description
The platform is a collection of fundamental hardware and firmware components
-needed to boot and operate a system. The Platform Firmware Resiliency(PFR)
-in NIST SP 800-193 provides technical guidelines and recommendations
-supporting resiliency of platform firmware and data against potentially
-destructive attacks.
+needed to boot and operate a system. The Platform Firmware Resiliency(PFR) in
+NIST SP 800-193 provides technical guidelines and recommendations supporting
+resiliency of platform firmware and data against potentially destructive
+attacks.
-Currently Redfish schema's defined by DMTF doesn't cover properties or
-resources to represent the PFR provisioned and locked states.
+Currently Redfish schema's defined by DMTF doesn't cover properties or resources
+to represent the PFR provisioned and locked states.
-This document covers the new OEM properties under ComputerSystem resource
-to represent the PFR provisioning status such as platform firmware is
-provisioned or not as well as provisioning is locked or not. This also covers
-the Redfish OpenBMC message registry metadata for logging events associated
-with PFR.
+This document covers the new OEM properties under ComputerSystem resource to
+represent the PFR provisioning status such as platform firmware is provisioned
+or not as well as provisioning is locked or not. This also covers the Redfish
+OpenBMC message registry metadata for logging events associated with PFR.
## Background and references
@@ -33,55 +32,52 @@
controller running on server platform can be used to indicate the status of
resiliency and event logs associated with it.
- - [NIST.SP.180-193](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-193.pdf)
- - [Redfish schema supplement](https://www.dmtf.org/sites/default/files/standards/documents/DSP0268_2019.1a.pdf)
- - [Redfish Logging in bmcweb](https://github.com/openbmc/docs/blob/master/architecture/redfish-logging-in-bmcweb.md)
+- [NIST.SP.180-193](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-193.pdf)
+- [Redfish schema supplement](https://www.dmtf.org/sites/default/files/standards/documents/DSP0268_2019.1a.pdf)
+- [Redfish Logging in bmcweb](https://github.com/openbmc/docs/blob/master/architecture/redfish-logging-in-bmcweb.md)
## Requirements
High level requirements:
- - BMC shall provide the way to represent Platform Firmware Resilience
- provisioning status over Redfish.
+- BMC shall provide the way to represent Platform Firmware Resilience
+ provisioning status over Redfish.
- - Event logs should be logged to redfish for Platform Firmware Resilience.
+- Event logs should be logged to redfish for Platform Firmware Resilience.
## Proposed design
Different OEM's has there own way of implementing the Platform Firmware
Resilience by using guidelines provided by NIST SP 800-193. Some of the
-component protected under this includes(not limited) ES/SIO, BMC/ME Flash,
-Host Processors, Trusted Platform Modules(TPM), PSU's, Memory etc...
-For example Intel uses the "Intel PFR" design to resiliency platform
-components.
+component protected under this includes(not limited) ES/SIO, BMC/ME Flash, Host
+Processors, Trusted Platform Modules(TPM), PSU's, Memory etc... For example
+Intel uses the "Intel PFR" design to resiliency platform components.
-NOTE: This document doesn't cover design aspects of how OEM's implements
-the Platform Firmware Resilience. It covers only generic redfish ComputerSystem
-OEM properties and Redfish message registry metadata entries which are
+NOTE: This document doesn't cover design aspects of how OEM's implements the
+Platform Firmware Resilience. It covers only generic redfish ComputerSystem OEM
+properties and Redfish message registry metadata entries which are
implementation agnostic.
-OpenBMC is moving to Redfish as its standard for out of band management.
-The bmcweb implements all the Redfish schema's to represent different
-properties and resources. ComputerSystem schema doesn't cover the properties
-associated with Platform Firmware Resilience but it provides OEM objects for
+OpenBMC is moving to Redfish as its standard for out of band management. The
+bmcweb implements all the Redfish schema's to represent different properties and
+resources. ComputerSystem schema doesn't cover the properties associated with
+Platform Firmware Resilience but it provides OEM objects for
manufacturer/provider specific extension moniker.
-Below are property is defined to represent the Platform Firmware
-Resilience provisioning status.
+Below are property is defined to represent the Platform Firmware Resilience
+provisioning status.
- - ProvisiongStatus: The value of this property indicates the provisioning
- status of platform firmware. It is of Enum Type with below values.
+- ProvisiongStatus: The value of this property indicates the provisioning status
+ of platform firmware. It is of Enum Type with below values.
- 1) NotProvisioned: Indicates platform firmware is not provisioned.
- This is an unsecured state.
+ 1. NotProvisioned: Indicates platform firmware is not provisioned. This is an
+ unsecured state.
- 2) ProvisionedButNotLocked: Indicates that the platform firmware is
- provisioned but not locked. So re-provisioning is allowed in this
- state.
+ 2. ProvisionedButNotLocked: Indicates that the platform firmware is
+ provisioned but not locked. So re-provisioning is allowed in this state.
- 3) ProvisionedAndLocked: Indicates that the platform firmware is
- provisioned and locked. So re-provisioning is not allowed in this
- state.
+ 3. ProvisionedAndLocked: Indicates that the platform firmware is provisioned
+ and locked. So re-provisioning is not allowed in this state.
PFR enabled platforms can provision or re-provision the platform resilience
multiple times when it is in "NotProvisioned" or "ProvisionedButNotLocked"
@@ -92,62 +88,65 @@
[link](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).
+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).
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 and must be extended whenever new firmware modules are supported under PFR.
+redfish events are created for basic firmware components BIOS, BMC, CPLD and ME
+and must be extended whenever new firmware modules are supported under PFR.
- 1) Platform Firmware Resiliency Errors:
- This is used to log the platform firmware resiliency errors.
+1. Platform Firmware Resiliency Errors: This is used to log the platform
+ firmware resiliency errors.
- MessageID's:
- - BIOSFirmwareResiliencyError
- - BMCFirmwareResiliencyError
- - CPLDFirmwareResiliencyError
- - MEFirmwareResiliencyError
- - FirmwareResiliencyError
- Severity: Critical
+ MessageID's:
- Below are some cases, where firmware resiliency error events logged
- for specific components.
- - Boot failure
- - Update Failure
+ - BIOSFirmwareResiliencyError
+ - BMCFirmwareResiliencyError
+ - CPLDFirmwareResiliencyError
+ - MEFirmwareResiliencyError
+ - FirmwareResiliencyError Severity: Critical
- 2) Platform Firmware Panic reason:
- This is used to log the reason for platform firmware panic.
+ Below are some cases, where firmware resiliency error events logged for
+ specific components.
- MessageID's:
- - BIOSFirmwarePanicReason
- - BMCFirmwarePanicReason
- - CPLDFirmwarePanicReason
- - MEFirmwarePanicReason
- Severity: Warning
+ - Boot failure
+ - Update Failure
- Below are some cases, where these events can be logged.
- - Boot time watchdog expired
- - Firmware authentication failure
+2. Platform Firmware Panic reason: This is used to log the reason for platform
+ firmware panic.
- 3) Platform Firmware Recovery reasons:
- This is used to log the reason for last platform firmware
- component recovery.
+ MessageID's:
- MessageID's:
- - BIOSFirmwareRecoveryReason
- - BMCFirmwareRecoveryReason
- - CPLDFirmwareRecoveryReason
- - MEFirmwareRecoveryReason
- Severity: Warning
+ - BIOSFirmwarePanicReason
+ - BMCFirmwarePanicReason
+ - CPLDFirmwarePanicReason
+ - MEFirmwarePanicReason Severity: Warning
- Below are few cases, where these events can be logged.
- - Launch failures
- - Update failures
- - Authentication failures
+ Below are some cases, where these events can be logged.
+
+ - Boot time watchdog expired
+ - Firmware authentication failure
+
+3. Platform Firmware Recovery reasons: This is used to log the reason for last
+ platform firmware component recovery.
+
+ MessageID's:
+
+ - BIOSFirmwareRecoveryReason
+ - BMCFirmwareRecoveryReason
+ - CPLDFirmwareRecoveryReason
+ - MEFirmwareRecoveryReason Severity: Warning
+
+ Below are few cases, where these events can be logged.
+
+ - Launch failures
+ - Update failures
+ - Authentication failures
Event logs associated with BMC component is specified here as example.
+
```
MessageEntry{"BMCFirmwareResiliencyError",
{
@@ -184,7 +183,6 @@
}},
```
-
## Alternatives considered
None
@@ -197,9 +195,10 @@
Provisiong status:
- - User can provision the PFR in OEM specific way and test using below URI
- and Method. Intel uses "Intel PFR" design (via BIOS) to provision and
- lock the PFR provisioning status.
+- User can provision the PFR in OEM specific way and test using below URI and
+ Method. Intel uses "Intel PFR" design (via BIOS) to provision and lock the PFR
+ provisioning status.
+
```
URI: /redfish/v1/Systems/system
METHOD: GET
@@ -226,18 +225,17 @@
Event logs:
- - User can induce security attack and validate the panic event logs as well as
- recovery mechanism using below URI.
+- User can induce security attack and validate the panic event logs as well as
+ recovery mechanism using below URI.
- Few examples to attack Firmware components and validate PFR:
+ 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.
```
URI: /redfish/v1/Systems/system/LogServices/EventLog/Entries
diff --git a/designs/redfish-tls-user-authentication.md b/designs/redfish-tls-user-authentication.md
index c1a3378..dfde1d6 100644
--- a/designs/redfish-tls-user-authentication.md
+++ b/designs/redfish-tls-user-authentication.md
@@ -1,13 +1,10 @@
# Redfish TLS User Authentication
-Author:
- Kamil Kowalski <kamil.kowalski@intel.com>
+Author: Kamil Kowalski <kamil.kowalski@intel.com>
-Other contributors:
- None
+Other contributors: None
-Created:
- June 7, 2019
+Created: June 7, 2019
## Problem Description
@@ -25,6 +22,7 @@
level, and many other security features.
Reference documents:
+
- [Certificate Schema Definition](https://redfish.dmtf.org/schemas/v1/Certificate_v1.xml)
- [CertificateLocations Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateLocations_v1.xml)
- [CertificateService Schema Definition](https://redfish.dmtf.org/schemas/v1/CertificateService_v1.xml)
@@ -33,8 +31,9 @@
- [RFC 8446 - TLS 1.3 Specification](https://tools.ietf.org/html/rfc8446)
### Dictionary
-**Redfish API** - Redfish API as defined by DMTF
-**Redfish** - Redfish API implementation in BMCWeb
+
+**Redfish API** - Redfish API as defined by DMTF **Redfish** - Redfish API
+implementation in BMCWeb
## Requirements
@@ -45,12 +44,11 @@
### Process overview
-Whenever ``CA``'s certificate changes ``User`` shall provide ``Redfish`` with
-it. After that is completed, user should request a **CSR** (**C**ertificate
-**S**igning **R**equest) from ``Redfish`` to get a request allowing to generate
-proper ``user``'s certificate from ``CA``. After this
-certificate is acquired, ``User`` can use this certificate when initializing
-HTTPS sessions.
+Whenever `CA`'s certificate changes `User` shall provide `Redfish` with it.
+After that is completed, user should request a **CSR** (**C**ertificate
+**S**igning **R**equest) from `Redfish` to get a request allowing to generate
+proper `user`'s certificate from `CA`. After this certificate is acquired,
+`User` can use this certificate when initializing HTTPS sessions.
```
┌──┐ ┌────┐ ┌───────┐
@@ -101,32 +99,33 @@
#### Uploading CA Certificate
CA's certificates for user authentication are kept at
-``/redfish/v1/AccountService/TLSAuth/Certificates``. There can be
-more than one, so user must use certificate that is signed by **any CA** that
-have their valid certificate stored there. New certificates can be uploaded
-by *POST*ing new certificate object on CertificateCollection.
+`/redfish/v1/AccountService/TLSAuth/Certificates`. There can be more than one,
+so user must use certificate that is signed by **any CA** that have their valid
+certificate stored there. New certificates can be uploaded by *POST*ing new
+certificate object on CertificateCollection.
Example POST payload:
+
```json
{
- "CertificateString": "... <Certificate String> ...",
- "CertificateType": "PEM"
+ "CertificateString": "... <Certificate String> ...",
+ "CertificateType": "PEM"
}
```
Should CA certificate get invalid (compromised, out-of-date, etc.) it is
-recommended to use ``#CertificateService.ReplaceCertificate`` action at
-``/redfish/v1/CertificateService``, to avoid wasting space and performance
+recommended to use `#CertificateService.ReplaceCertificate` action at
+`/redfish/v1/CertificateService`, to avoid wasting space and performance
unnecessarily for processing invalid certificates.
-Example ``#CertificateService.ReplaceCertificate`` action payload executed on
-``/redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate``:
+Example `#CertificateService.ReplaceCertificate` action payload executed on
+`/redfish/v1/CertificateService/Actions/CertificateService.ReplaceCertificate`:
```json
{
- "CertificateUri": "/redfish/v1/AccountService/TLSAuth/Certificates/1",
- "CertificateString": "... <Certificate String> ...",
- "CertificateType": "PEM"
+ "CertificateUri": "/redfish/v1/AccountService/TLSAuth/Certificates/1",
+ "CertificateString": "... <Certificate String> ...",
+ "CertificateType": "PEM"
}
```
@@ -200,11 +199,12 @@
```
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:
+
- does KeyUsage contain required data ("digitalSignature" and "keyAgreement")
- does ExtendedKeyUsage contain required data (contains "clientAuth")
- public key meets minimal bit length requirement
@@ -217,7 +217,7 @@
- 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``
+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**
@@ -226,9 +226,9 @@
what will be used, otherwise there is no certainty which credential are used
during operation.
-User can configure which methods are available in ``/redfish/v1/AccountService``
-OEM schema. The sequence of credential verification stays the same regardless
-of configuration. Whitelist verification is always-on, because of Redfish
+User can configure which methods are available in `/redfish/v1/AccountService`
+OEM schema. The sequence of credential verification stays the same regardless of
+configuration. Whitelist verification is always-on, because of Redfish
specification and other accessibility requirements.
User certificate does not have to be signed by the exact CAs whose certificates
@@ -267,15 +267,15 @@
confirm that their behavior did not change, and did not suffer any regression.
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
+ and expired ones are not accepted, by both - changing validity periods in
+ certificates themselves, as well as modifying time on BMC itself
3. Removing CA certificate and confirming that user will not be granted access
-after that when using certificate that worked before removal.
+ after that when using certificate that worked before removal.
4. Chain certificates verification - checking that chained certificates are
-accepted as required.
+ accepted as required.
5. Negative tests for breaking user's certificate - invalid username, invalid
-validity period, invalid CA, binary broken certificate, etc.
+ validity period, invalid CA, binary broken certificate, etc.
diff --git a/designs/remote-bios-configuration.md b/designs/remote-bios-configuration.md
index fd06e77..77bab9f 100644
--- a/designs/remote-bios-configuration.md
+++ b/designs/remote-bios-configuration.md
@@ -1,52 +1,50 @@
# Remote BIOS Configuration (RBC) via BMC
-Author:
- Suryakanth Sekar! ssekar
+Author: Suryakanth Sekar! ssekar
-Other contributors:
- Jia Chunhui
- Deepak Kodihalli
- Patrick Williams
+Other contributors: Jia Chunhui Deepak Kodihalli Patrick Williams
Created: 19-Nov-2019
## Problem Description
-Current OpenBMC doesn't provide mechanism to configure the BIOS remotely.
-This is needed in data center to maintain several systems under
-same configuration.
-Remote BIOS Configuration provides ability for the user to view and modify
-BIOS setup configuration parameters remotely via a BMC at any Host state.
-New BIOS configuration parameters take effect immediately or next
-system reboot based on the host firmware support model.
+Current OpenBMC doesn't provide mechanism to configure the BIOS remotely. This
+is needed in data center to maintain several systems under same configuration.
+
+Remote BIOS Configuration provides ability for the user to view and modify BIOS
+setup configuration parameters remotely via a BMC at any Host state. New BIOS
+configuration parameters take effect immediately or next system reboot based on
+the host firmware support model.
## 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
+
1. Mechanism to configure BIOS settings remotely over network interface.
-2. BMC should support the ability to set the value of all BIOS variables
- to the factory default state.
-3. Based on the host firmware support model, BMC should support both
- Immediate Update or Deferred update.
-4. In deferred model, When the system is in S0, S3, S4 or S5 state.
- BMC will send the updated BIOS variables on next BIOS boot only.
- It will not initiate a BIOS boot immediately.
+2. BMC should support the ability to set the value of all BIOS variables to the
+ factory default state.
+3. Based on the host firmware support model, BMC should support both Immediate
+ Update or Deferred update.
+4. In deferred model, When the system is in S0, S3, S4 or S5 state. BMC will
+ send the updated BIOS variables on next BIOS boot only. It will not initiate
+ a BIOS boot immediately.
5. In immediate model, BMC should send message to the system firmware (BIOS)
Whenever settings are changed.
-6. BMC should support BIOS attribute registry in redfish schema for
- BIOS configuration.
+6. BMC should support BIOS attribute registry in redfish schema for BIOS
+ configuration.
7. BMC should provide secure way for updating BIOS setup password settings.
Detailed password handling design -TBD(will be resolve using ARM TrustZone)
-Ex: Updating the BIOS password should be support only before end of post.
+ Ex: Updating the BIOS password should be support only before end of post.
8. Remote BIOS configuration daemon should be independent of interface specific
data format.
9. BMC should able to take default / current settings from host and store &
- expose that for out of band updates.
-10.BMC should provide the new values to the host.
-
+ expose that for out of band updates. 10.BMC should provide the new values to
+ the host.
## Proposed Design
@@ -86,40 +84,36 @@
+----------------------------------------------------------------------------------------------------------------+
```
-
-
##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 full BIOS variables in XML format. (Generated by BIOS)
-Type-1 contain modified BIOS variables in XML format. (Generated by BMC)
+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
+full BIOS variables in XML format. (Generated by BIOS) Type-1 contain modified
+BIOS variables in XML format. (Generated by BMC)
-BIOS must provide BIOS capability via KCS interface in early boot stage.
-BIOS must send compressed proprietary XML type 0 file via
-IPMI command to the BMC.
+BIOS must provide BIOS capability via KCS interface in early boot stage. BIOS
+must send compressed proprietary XML type 0 file via IPMI command to the BMC.
-IPMI interface should decompress & validate the received XML Type 0.
-IPMI interface should convert the XML Type 0 into native to D-bus format
-and send to the RBC daemon.
+IPMI interface should decompress & validate the received XML Type 0. IPMI
+interface should convert the XML Type 0 into native to D-bus format and send to
+the RBC daemon.
-
-During BDS phase in BIOS. BIOS must get the existing XML info from BMC.
-If XML version/checksum is mismatch or XML Type 0 is not present in BMC, then
-BIOS must send XML type 0 to the BMC. If XML version and XML checksum matched
-& pending BIOS attributes list exist (XML Type 1) in BMC then BIOS must get
-pending BIOS configuration (XML Type 1) from BMC & update in BIOS region and
-send updated XML Type 0 to the BMC in order to intact again and then BIOS reset
-the system to reflect the updated values in BIOS boot.
+During BDS phase in BIOS. BIOS must get the existing XML info from BMC. If XML
+version/checksum is mismatch or XML Type 0 is not present in BMC, then BIOS must
+send XML type 0 to the BMC. If XML version and XML checksum matched & pending
+BIOS attributes list exist (XML Type 1) in BMC then BIOS must get pending BIOS
+configuration (XML Type 1) from BMC & update in BIOS region and send updated XML
+Type 0 to the BMC in order to intact again and then BIOS reset the system to
+reflect the updated values in BIOS boot.
BIOS have default BIOS settings in BIOS non-volatile memory. BIOS can restore
the default BIOS configuration based on the flag setting in OEM IPMI command
-issued during BIOS booting.
-So, restore default BIOS configuration can be done by this mechanism.
+issued during BIOS booting. So, restore default BIOS configuration can be done
+by this mechanism.
RBC daemon should preserve the AllBiosTables, PendingAttributes list in
-non-volatile storage.
-Pending attributes list will be cleared whenever new attributes data received.
+non-volatile storage. Pending attributes list will be cleared whenever new
+attributes data received.
```
#Intel uses the following logic for BIOS first boot
@@ -157,6 +151,7 @@
| +----------------------------------------------------------------------------+|
+---------------------------------------+-----------------------------------------------------------------------------+
```
+
```
#Intel uses the following logic for BIOS reset
+---------------------------------------------------------------------------------------------------------------------+
@@ -193,6 +188,7 @@
| +----------------------------------------------------------------------------+|
+---------------------------------------+-----------------------------------------------------------------------------+
```
+
```
#Intel uses the following logic for BIOS reset and BMC have new values
+---------------------------------------------------------------------------------------------------------------------+
@@ -240,18 +236,18 @@
##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.
+BIOS should update the BIOS settings via Set BIOS table PLDM command- BIOS
+string table, Attribute name table, Attribute value table via MCTP.
-RBC daemon should create pending BIOS attributes list based on the
-user input configuration and send PendingAttributesUpdated signal.
+RBC daemon should create pending BIOS attributes list based on the user input
+configuration and send PendingAttributesUpdated signal.
PLDM daemon should register for PendingAttributesUpdated signal & RBC daemon
should generate signal whenever attribute value changed by SetPendingAttributes,
set attribute D-bus call. PLDM should Wait for PendingAttributesUpdated signal
and pull the pending attributes value from RBC daemon. PLDM should delete the
-Pending attributes value table once its not valid or updated in BIOS.
-RBC should clear pending attributes list whenever new attributes data received.
+Pending attributes value table once its not valid or updated in BIOS. RBC should
+clear pending attributes list whenever new attributes data received.
RBC daemon should preserve the AllBaseAttributes, PendingAttributes list in
non-volatile storage. PLDM daemon should preserve BIOS tables in non-volatile
@@ -325,7 +321,9 @@
+---------------------------------------+----------------------------------------------------------------------------+
```
+
##Complete BIOS BMC flow for BIOS configuration in deferred update model
+
```
+----------------------------------------+ +----------------------------------------+
| BIOS | | BMC |
@@ -371,6 +369,7 @@
```
##Complete BIOS BMC flow for BIOS configuration in immediate update model
+
```
+----------------------------------------+ +----------------------------------------+
| BIOS | | BMC |
@@ -409,12 +408,12 @@
| | | |
+----------------------------------------+ +----------------------------------------+
```
-RBC should create the Pending Attribute list whenever SetPendingAttributes &
-SetAttribute Method called and raise the PendingAttributesUpdated signal.
-RBC should preserve the Pending Attributes list across the BMC reset and
-RBC should clear the Pending Attributes list whenever new AllBaseBIOSTables
-received from BIOS.
+RBC should create the Pending Attribute list whenever SetPendingAttributes &
+SetAttribute Method called and raise the PendingAttributesUpdated signal. RBC
+should preserve the Pending Attributes list across the BMC reset and RBC should
+clear the Pending Attributes list whenever new AllBaseBIOSTables received from
+BIOS.
#Redfish interfaces for remote Bios configuration
@@ -450,49 +449,50 @@
| +---------------------------------------------------------------+||
+-----------------------------------------+-----------------------------------------------------------------+
```
-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"
-2. Get Attribute Registry:
- Get the detailed information about Bios Attribute like current value,
- supported value, description, Menupath, Default value.
+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"
+
+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"
-3. Change BIOS password:
- ACTION - "https://<BMC IP address>/redfish/v1/Systems/system/Bios/Actions/Bios.ChangePassword"
+3. Change BIOS password: ACTION -
+ "https://<BMC IP address>/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"
+4. Reset To default settings: ACTION -
+ "https://<BMC IP address>/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}
+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}
-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 only in deferred model. For immediate update model, It will be empty.
- Ex:
- Attribute name and new value : { "DdrFreqLimit" : 2400,"QuietBoot",0x1 }
+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
+ only in deferred model. For immediate update model, It will be empty. Ex:
+ 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 }
+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
+ }
## Alternatives Considered
+
Redfish Host specification definition is not completed and ready BIOS support
-also not available.
-There are 1000+ BIOS variables and storing in phosphor-settingsd is not optimal.
+also not available. There are 1000+ BIOS variables and storing in
+phosphor-settingsd is not optimal.
## Impacts
+
BIOS must support and follow RBC BIOS configuration flow.
## Testing
-Able to change the BIOS configuration via BMC through LAN
-Able to change the BIOS setup password via BMC
-Compliance with Redfish will be tested using the Redfish Service Validator
+
+Able to change the BIOS configuration via BMC through LAN Able to change the
+BIOS setup password via BMC Compliance with Redfish will be tested using the
+Redfish Service Validator
diff --git a/designs/state-management-and-external-interfaces.md b/designs/state-management-and-external-interfaces.md
index 96875d8..072e63d 100644
--- a/designs/state-management-and-external-interfaces.md
+++ b/designs/state-management-and-external-interfaces.md
@@ -2,8 +2,7 @@
Author: Andrew Geissler (geissonator)
-Other contributors:
- Jason Bills (jmbills)
+Other contributors: Jason Bills (jmbills)
Created: Jan 22, 2020
@@ -23,25 +22,27 @@
[phoshor-state-manager][2] implements the xyz.openbmc_project.State.\*
interfaces. These interfaces control and track the state of the BMC, Chassis,
-and Host within an OpenBMC managed system. The README within the repository
-can provide some further background information. [bmcweb][3], OpenBMC's web
-server and front end Redfish interface, then maps commands to the ResetType
-object to the appropriate xyz.openbmc_project.State.* D-Bus interface.
+and Host within an OpenBMC managed system. The README within the repository can
+provide some further background information. [bmcweb][3], OpenBMC's web server
+and front end Redfish interface, then maps commands to the ResetType object to
+the appropriate xyz.openbmc_project.State.\* D-Bus interface.
-The goal with this design is to enhance the xyz.openbmc_project.State.*
-interfaces to support more of the Redfish ResetType. Specifically this design
-is looking to support the capability to reboot an operating system on a system
+The goal with this design is to enhance the xyz.openbmc_project.State.\*
+interfaces to support more of the Redfish ResetType. Specifically this design is
+looking to support the capability to reboot an operating system on a system
without cycling power to the chassis.
Currently phosphor-state-manager supports the following:
- - Chassis: On/Off
- - Host: On/Off/Reboot
+
+- Chassis: On/Off
+- Host: On/Off/Reboot
The `Reboot` to the host currently causes a power cycle to the chassis.
### Redfish
The Redfish [ResetType][1] has the following operations associated with it:
+
```
"ResetType": {
"enum": [
@@ -76,23 +77,23 @@
### IPMI
-The IPMI specification defines a Chassis Control Command with a chassis
-control parameter as follows:
+The IPMI specification defines a Chassis Control Command with a chassis control
+parameter as follows:
-| Option | Description |
-| --- | --- |
-| power down | Force system into soft off (S4/S45) state. This is for ‘emergency’ management power down actions. The command does not initiate a clean shut-down of the operating system prior to powering down the system. |
-| power up | |
-| power cycle | This command provides a power off interval of at least 1 second following the deassertion of the system’s POWERGOOD status from the main power subsystem. It is recommended that no action occur if system power is off (S4/S5) when this action is selected, and that a D5h “Request parameter(s) not supported in present state.” error completion code be returned. |
-| hard reset | In some implementations, the BMC may not know whether a reset will cause any particular effect and will pulse the system reset signal regardless of power state. |
-| pulse Diagnostic Interrupt | Pulse a version of a diagnostic interrupt that goes directly to the processor(s). This is typically used to cause the operating system to do a diagnostic dump (OS dependent). |
-| Initiate a soft-shutdown of OS | |
+| Option | Description |
+| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| power down | Force system into soft off (S4/S45) state. This is for ‘emergency’ management power down actions. The command does not initiate a clean shut-down of the operating system prior to powering down the system. |
+| power up | |
+| power cycle | This command provides a power off interval of at least 1 second following the deassertion of the system’s POWERGOOD status from the main power subsystem. It is recommended that no action occur if system power is off (S4/S5) when this action is selected, and that a D5h “Request parameter(s) not supported in present state.” error completion code be returned. |
+| hard reset | In some implementations, the BMC may not know whether a reset will cause any particular effect and will pulse the system reset signal regardless of power state. |
+| pulse Diagnostic Interrupt | Pulse a version of a diagnostic interrupt that goes directly to the processor(s). This is typically used to cause the operating system to do a diagnostic dump (OS dependent). |
+| Initiate a soft-shutdown of OS | |
## Requirements
- Keep legacy support where `xyz.openbmc_project.State.Host.Transition.Reboot`
- causes a graceful shutdown of the host, a power cycle of the chassis, and
- a starting of the host.
+ causes a graceful shutdown of the host, a power cycle of the chassis, and a
+ starting of the host.
- Support a reboot of the host with chassis power on
- Support `GracefulRestart` (where the host is notified of the reboot)
- Support `ForceRestart` (where the host is not notified of the reboot)
@@ -106,16 +107,19 @@
## Proposed Design
Create two new `xyz.openbmc_project.State.Host.Transition` options:
+
- `ForceWarmReboot`, `GracefulWarmReboot`
Create a new `xyz.openbmc_project.State.Chassis.Transition` option:
+
- `PowerCycle`
-The existing bmcweb code uses some additional xyz.openbmc_project.State.*
+The existing bmcweb code uses some additional xyz.openbmc_project.State.\*
interfaces that are not defined within phosphor-dbus-interfaces. These are
implemented within the x86-power-control repository which is an alternate
-implementation to phosphor-state-manager. It has the following mapping for
-these non-phosphor-dbus-interfaces
+implementation to phosphor-state-manager. It has the following mapping for these
+non-phosphor-dbus-interfaces
+
- `ForceRestart` -> `xyz.openbmc_project.State.Chassis.Transition.Reset`
- `PowerCycle` -> `xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
@@ -126,31 +130,33 @@
A `GracefulRestart` will map to our new host transition:
`xyz.openbmc_project.State.Host.Transition.GracefulWarmReboot`
-The `PowerCycle` operation is dependent on the current state of the host.
-If host is on, it will map to `xyz.openbmc_project.State.Host.Transition.Reboot`
+The `PowerCycle` operation is dependent on the current state of the host. If
+host is on, it will map to `xyz.openbmc_project.State.Host.Transition.Reboot`
otherwise it will map to
`xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
-To summarize the new Redfish to xyz.openbmc_project.State.* mappings:
+To summarize the new Redfish to xyz.openbmc_project.State.\* mappings:
+
- `ForceRestart` -> `xyz.openbmc_project.State.Host.Transition.ForceWarmReboot`
-- `GracefulRestart`-> `xyz.openbmc_project.State.Host.Transition.GracefulWarmReboot`
+- `GracefulRestart`->
+ `xyz.openbmc_project.State.Host.Transition.GracefulWarmReboot`
- `PowerCycle`:
- If host on: `xyz.openbmc_project.State.Host.Transition.Reboot`
- If host off: `xyz.openbmc_project.State.Chassis.Transition.PowerCycle`
-The full mapping of Redfish and IPMI to xyz.openbmc_project.State.* is as
+The full mapping of Redfish and IPMI to xyz.openbmc_project.State.\* is as
follows:
-| Redfish | IPMI | xyz.openbmc_project.State.Transition |
-| --- | --- | --- |
-| ForceOff | power down | Chassis.Off |
-| ForceOn | power up | Host.On |
-| ForceRestart | hard reset | Host.ForceWarmReboot |
-| GracefulRestart | | Host.GracefulWarmReboot |
-| GracefulShutdown | soft off | Host.Off |
-| On | power up | Host.On |
-| PowerCycle (host on) | power cycle | Host.Reboot |
-| PowerCycle (host off) | | Chassis.PowerCycle |
+| Redfish | IPMI | xyz.openbmc_project.State.Transition |
+| --------------------- | ----------- | ------------------------------------ |
+| ForceOff | power down | Chassis.Off |
+| ForceOn | power up | Host.On |
+| ForceRestart | hard reset | Host.ForceWarmReboot |
+| GracefulRestart | | Host.GracefulWarmReboot |
+| GracefulShutdown | soft off | Host.Off |
+| On | power up | Host.On |
+| PowerCycle (host on) | power cycle | Host.Reboot |
+| PowerCycle (host off) | | Chassis.PowerCycle |
## Alternatives Considered
diff --git a/designs/target-fail-monitoring.md b/designs/target-fail-monitoring.md
index ce5e0a9..e598ca8 100644
--- a/designs/target-fail-monitoring.md
+++ b/designs/target-fail-monitoring.md
@@ -1,10 +1,8 @@
# Monitoring and Logging OpenBMC Systemd Target and Service Failures
-Author: Andrew Geissler
- < geissonator >
+Author: Andrew Geissler < geissonator >
-Created: June 18, 2019
-Last Updated: Feb 21, 2022
+Created: June 18, 2019 Last Updated: Feb 21, 2022
## Problem Description
@@ -13,27 +11,26 @@
services, to power on and off the servers it manages, and to perform operations
like firmware updates.
-[openbmc-systemd.md][1] has a good summary of systemd and the basics of how
-it is used within OpenBMC.
+[openbmc-systemd.md][1] has a good summary of systemd and the basics of how it
+is used within OpenBMC.
-At a high level, systemd is composed of units. For OpenBMC, the two key
-unit types are target and service.
+At a high level, systemd is composed of units. For OpenBMC, the two key unit
+types are target and service.
There are situations where OpenBMC systemd targets fail. They fail due to a
target or service within them hitting some sort of error condition. In some
-cases, the unit which caused the failure will log an error to
-phosphor-logging but in some situations (segfault, unhandled exception,
-unhandled error path, ...), there will be no indication to the end user that
-something failed. It is critical that if a systemd target fails within OpenBMC,
-the user be notified.
+cases, the unit which caused the failure will log an error to phosphor-logging
+but in some situations (segfault, unhandled exception, unhandled error path,
+...), there will be no indication to the end user that something failed. It is
+critical that if a systemd target fails within OpenBMC, the user be notified.
-There are also scenarios where a system has successfully started all targets
-but a running service within that target fails. Some services are not all
-that critical, but something like fan-control or a power monitoring service,
-could be very critical. At a minimum, need to ensure the user of the system
-is informed that a critical service has failed. The solution proposed in
-this document does not preclude service owners from doing other recovery, this
-solution just ensures a bare minimum of reporting is done when a failure occurs.
+There are also scenarios where a system has successfully started all targets but
+a running service within that target fails. Some services are not all that
+critical, but something like fan-control or a power monitoring service, could be
+very critical. At a minimum, need to ensure the user of the system is informed
+that a critical service has failed. The solution proposed in this document does
+not preclude service owners from doing other recovery, this solution just
+ensures a bare minimum of reporting is done when a failure occurs.
## Background and References
@@ -43,24 +40,26 @@
systemd provides signals when units complete and provides status on that
completed unit. See the JobNew()/JobRemoved() section in the [systemd dbus
API][3]. The six different results are:
+
```
done, canceled, timeout, failed, dependency, skipped
```
phosphor-state-manager code already monitors for these signals but only looks
-for a status of `done` to know when to mark the corresponding dbus object
-as ready(bmc)/on(chassis)/running(host).
+for a status of `done` to know when to mark the corresponding dbus object as
+ready(bmc)/on(chassis)/running(host).
-The proposal within this document is to monitor for these other results and
-log an appropriate error to phosphor-logging.
+The proposal within this document is to monitor for these other results and log
+an appropriate error to phosphor-logging.
-A systemd unit that is a service will only enter into a `failed` state after
-all systemd defined retries have been executed. For OpenBMC systems, that
-involves 2 restarts within a 30 second window.
+A systemd unit that is a service will only enter into a `failed` state after all
+systemd defined retries have been executed. For OpenBMC systems, that involves 2
+restarts within a 30 second window.
## Requirements
### Systemd Target Units
+
- Must be able to monitor any arbitrary systemd target and log a defined error
based on the type of failure the target encountered
- Must be configurable
@@ -73,10 +72,12 @@
- Error will always be the configured one with additional data indicating the
status that failed (i.e. canceled, timeout, ...)
- Example:
+
```
xyz.openbmc_project.State.BMC.Error.MultiUserTargetFailure
STATUS=timeout
```
+
- By default, enable this monitor and logging service for all critical OpenBMC
targets
- Critical systemd targets are ones used by phosphor-state-manager
@@ -87,10 +88,11 @@
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
- target support)
+ - Fully qualified target name must be input (i.e. no templated / wild card
+ target support)
### Systemd Service Units
+
- Must be able to monitor any arbitrary systemd service within OpenBMC
- Service(s) to monitor must be configurable
- Log an error indicating a service has failed (with service name in log)
@@ -105,6 +107,7 @@
json file(s) on startup.
The json file(s) would have the following format for targets:
+
```
{
"targets" : [
@@ -123,6 +126,7 @@
```
The json (files) would have the following format for services:
+
```
{
"services" : [
@@ -134,24 +138,24 @@
On startup, all input json files will be loaded and monitoring will be setup.
-This application will not register any interfaces on D-Bus but will subscribe
-to systemd dbus signals for JobRemoved. sdeventplus will be used for all
-D-Bus communication.
+This application will not register any interfaces on D-Bus but will subscribe to
+systemd dbus signals for JobRemoved. sdeventplus will be used for all D-Bus
+communication.
For additional debug, the errors may be registered with the BMC Dump function to
ensure the cause of the failure can be determined. This requires the errors
logged by this service be put into `phosphor-debug-errors/errors_watch.yaml`.
-For service failures, a dump will be collected by default because the BMC
-will be moved into a Quisced state.
+For service failures, a dump will be collected by default because the BMC will
+be moved into a Quisced state.
Note that services which are short running applications responsible for
transitioning the system from one target to another (i.e. chassis power on/off,
starting/stopping the host, ...) are critical services, but they are not the
type of services to be monitored. Their failures will cause systemd targets to
fail which will fall into the target monitoring piece of this design. The
-service monitoring is meant for long running services which stay running
-after a target has completed.
+service monitoring is meant for long running services which stay running after a
+target has completed.
## Alternatives Considered
@@ -173,12 +177,13 @@
fail and the code logic defined in this design will also log an error.
The thought is that two errors are better than none. Also, there is a plugin
-architecture being defined for phosphor-logging. The user could monitor for
-that first error within the phosphor-logging plugin architecture and as a
-defined action, cancel the systemd target. A target status of `canceled` will
-not result in phosphor-state-manager generating an error.
+architecture being defined for phosphor-logging. The user could monitor for that
+first error within the phosphor-logging plugin architecture and as a defined
+action, cancel the systemd target. A target status of `canceled` will not result
+in phosphor-state-manager generating an error.
## Testing
+
Need to cause all units mentioned within this design to fail. They should fail
for each of the reasons defined within this design and the error generated for
each scenario should be verified.
diff --git a/designs/telemetry.md b/designs/telemetry.md
index 21a15db..7a646c2 100644
--- a/designs/telemetry.md
+++ b/designs/telemetry.md
@@ -1,49 +1,50 @@
# OpenBMC platform telemetry
-Author:
- Piotr Matuszczak <piotr.matuszczak@intel.com>
+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
+Created: 2019-08-07
## Problem Description
-The BMC on server platform gathers lots of telemetry data, which has to
-be exposed in clean, human readable and standardized format. This document
-focuses on telemetry over the Redfish, since it is standard API
-for platform manageability.
+
+The BMC on server platform gathers lots of telemetry data, which has to be
+exposed in clean, human readable and standardized format. This document focuses
+on telemetry over the Redfish, since it is standard API for platform
+manageability.
## Background and References
-* OpenBMC platform telemetry shall leverage DMTF's [Redfish Telemetry Model][1]
-for exposing platform telemetry over the network.
-* OpenBMC platform telemetry shall leverage the
-[OpenBMC sensors architecture implementation][2].
-* OpenBMC platform telemetry shall implement a service, called Telemetry to deal
-with metrics report and trigger management. This service is described later in
-this document.
-* Although we use the [hwmon][3] to gather readings from physical sensors, this
-architecture does not depend on it, because the Telemetry service component
-relies on the [OpenBMC D-Bus sensors][2].
+- OpenBMC platform telemetry shall leverage DMTF's [Redfish Telemetry Model][1]
+ for exposing platform telemetry over the network.
+- OpenBMC platform telemetry shall leverage the [OpenBMC sensors architecture
+ implementation][2].
+- OpenBMC platform telemetry shall implement a service, called Telemetry to deal
+ with metrics report and trigger management. This service is described later in
+ this document.
+- Although we use the [hwmon][3] to gather readings from physical sensors, this
+ architecture does not depend on it, because the Telemetry service component
+ relies on the [OpenBMC D-Bus sensors][2].
## Requirements
-* [OpenBMC D-Bus sensors][2] support. This is also design limitation, since the
-Telemetry service requires telemetry sources to be implemented as D-Bus sensors.
+- [OpenBMC D-Bus sensors][2] support. This is also design limitation, since the
+ Telemetry service requires telemetry sources to be implemented as D-Bus
+ sensors.
## Proposed Design
+
Redfish Telemetry Model shall implement Telemetry Service with the following
collection resources:
-* Metric Definitions - contains the metadata for metrics (unit, accuracy, etc.)
-* Metric Report Definitions - defines how metric report shall be created
-(which metrics it shall contain, how often it shall be generated etc.)
-* Metric Reports - contains actual metric reports containing telemetry data
-generated according to the Metric Report Definitions
-* Metric Triggers - contains thresholds and actions that apply to specific
-metrics
+
+- Metric Definitions - contains the metadata for metrics (unit, accuracy, etc.)
+- Metric Report Definitions - defines how metric report shall be created (which
+ metrics it shall contain, how often it shall be generated etc.)
+- Metric Reports - contains actual metric reports containing telemetry data
+ generated according to the Metric Report Definitions
+- Metric Triggers - contains thresholds and actions that apply to specific
+ metrics
OpenBMC telemetry architecture is shown on the diagram below.
@@ -93,24 +94,25 @@
The telemetry service component is a part of Redfish and implements the DMTF's
[Redfish Telemetry Model][1]. Metric report definitions uses Redfish sensors
-URIs for metric report creation. Those sensors are also used to get
-URI->D-Bus sensor mapping. Redfish Telemetry Service acts as presentation
-layer for the telemetry, while Telemetry service is responsible for gathering
-metrics from D-Bus sensors and exposing them as D-Bus objects. Telemetry
-service supports different monitoring modes (periodic, on change and on demand)
-along with aggregated operations:
-* SINGLE - current reading value
-* AVERAGE - average value over defined time period
-* MAX - max reading value during defined time period
-* MIN - min reading value during defined time period
-* SUM - sum of reading values over defined time period
+URIs for metric report creation. Those sensors are also used to get URI->D-Bus
+sensor mapping. Redfish Telemetry Service acts as presentation layer for the
+telemetry, while Telemetry service is responsible for gathering metrics from
+D-Bus sensors and exposing them as D-Bus objects. Telemetry service supports
+different monitoring modes (periodic, on change and on demand) along with
+aggregated operations:
+
+- SINGLE - current reading value
+- AVERAGE - average value over defined time period
+- MAX - max reading value during defined time period
+- MIN - min reading value during defined time period
+- SUM - sum of reading values over defined time period
The time period for calculating aggregated metric is taken from the Redfish
Metric Report Definition resource for each sensor's metric.
Telemetry service supports creating and managing metric report, which may
-contain single or multiple metrics from sensors. This metric report is mapped
-to Metric Report for the Redfish Telemetry Service.
+contain single or multiple metrics from sensors. This metric report is mapped to
+Metric Report for the Redfish Telemetry Service.
The diagram below shows the flows for creation and update of metric report.
@@ -260,21 +262,20 @@
| | | |
```
-The Redfish implementation in bmcweb is stateless, thus it is not able to
-store metric reports. All operations on metric reports shall be done in
-the Telemetry service. Sending metric report as SSE or push-style events
-shall be done via the [Redfish Event Service][6]. It is marked as optional
-because metric report does not have to be configured for pushing its data
-through the event.
+The Redfish implementation in bmcweb is stateless, thus it is not able to store
+metric reports. All operations on metric reports shall be done in the Telemetry
+service. Sending metric report as SSE or push-style events shall be done via the
+[Redfish Event Service][6]. It is marked as optional because metric report does
+not have to be configured for pushing its data through the event.
In case of on demand metric report update, Telemetry service performs no
-additional sensor readings because it already has the latest values, since
-they are updated on PropertiesChanged signal from the D-Bus sensors.
+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 exposes specific interfaces on D-Bus. One of them will be
-used for reading report management. The second one will be used for triggers
+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**
@@ -285,25 +286,26 @@
xyz.openbmc_project.Telemetry.ReportManager
/xyz/openbmc_project/Telemetry/Reports
```
+
The `ReportManager` implements D-Bus interface
[`xyz.openbmc_project.Telemetry.ReportManager`][8] for report management. The
interface is described in the phosphor-dbus-interfaces. This interface
implements `AddReport` method, which is used to create a metric report. The
report may contain a single or multiple sensor readings. The way how the report
-will be stored by the BMC is defined by one of this method's parameters.
-The `ReportManager` object implements property that stores the maximum number
-of reports supported simultaneously.
+will be stored by the BMC is defined by one of this method's parameters. The
+`ReportManager` object implements property that stores the maximum number of
+reports supported simultaneously.
-The `AddReport` method returns the path to the newly created report object.
-The report object implements the [`xyz.openbmc_project.Object.Delete`][10]
-and [`xyz.openbmc_project.Telemetry.Report`][9] interfaces. The [`Delete`][10]
+The `AddReport` method returns the path to the newly created report object. The
+report object implements the [`xyz.openbmc_project.Object.Delete`][10] and
+[`xyz.openbmc_project.Telemetry.Report`][9] interfaces. The [`Delete`][10]
interface is defined to add support for removing Report object, while the
-[`Report`][9] interface implements methods and properties for Report
-management along with properties containing telemetry readings. Each report
-object contains the timestamp of its last update. The report object
-contains an array of structures containing reading with its metadata and
-timestamp of last update of this metric. Each report has also the property
-that stores update interval (for periodically updated reports).
+[`Report`][9] interface implements methods and properties for Report management
+along with properties containing telemetry readings. Each report object contains
+the timestamp of its last update. The report object contains an array of
+structures containing reading with its metadata and timestamp of last update of
+this metric. Each report has also the property that stores update interval (for
+periodically updated reports).
**Trigger management**
@@ -313,100 +315,104 @@
xyz.openbmc_project.Telemetry.TriggerManager
/xyz/openbmc_project/Telemetry/Triggers
```
-The `TriggerManager` supports the
-`xyz.openbmc_project.Telemetry.TriggerManager` interface, which implements
-the `AddTrigger` method. This method shall be used to create new trigger for
-the certain metric. The method's parameters allow to define the type of metric
-for which trigger is set (discrete or numeric). Depend on this setting, this
-method accepts different set of trigger parameters.
+
+The `TriggerManager` supports the `xyz.openbmc_project.Telemetry.TriggerManager`
+interface, which implements the `AddTrigger` method. This method shall be used
+to create new trigger for the certain metric. The method's parameters allow to
+define the type of metric for which trigger is set (discrete or numeric). Depend
+on this setting, this method accepts different set of trigger parameters.
For discrete metric type, trigger parameters contain:
-| Field | Type | Description |
-|-------|------|-------------|
-| TriggerCondition | enum | Discrete trigger condition: <br> "Changed" - trigger occurs when value of metric has changed; <br> "Specified" - trigger occurs when value of metric becomes one of the values listed in the discrete triggers. |
-| DiscreteTriggers | array of structures | Array of discrete trigger structures. |
+| Field | Type | Description |
+| ---------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| TriggerCondition | enum | Discrete trigger condition: <br> "Changed" - trigger occurs when value of metric has changed; <br> "Specified" - trigger occurs when value of metric becomes one of the values listed in the discrete triggers. |
+| DiscreteTriggers | array of structures | Array of discrete trigger structures. |
Member of DiscreteTriggers array:
-| Field | Type | Description |
-|-------|------|-------------|
-| TriggerId| string | Unique trigger Id |
-| Severity | enum | Severity: <br> "OK" - normal<br> "Warning" - requires attention<br> "Critical" - requires immediate attention |
-| Value | variant | Value of discrete metric, that constitutes a trigger event. |
-| DwellTime | uint64 | Time in milliseconds that a trigger occurrence persists before the action defined for this trigger is performed. |
+| Field | Type | Description |
+| --------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
+| TriggerId | string | Unique trigger Id |
+| Severity | enum | Severity: <br> "OK" - normal<br> "Warning" - requires attention<br> "Critical" - requires immediate attention |
+| Value | variant | Value of discrete metric, that constitutes a trigger event. |
+| DwellTime | uint64 | Time in milliseconds that a trigger occurrence persists before the action defined for this trigger is performed. |
-For numeric metric type, trigger parameters contain numeric thresholds.
-Numeric thresholds structure shall contain up to 4 thresholds: upper warning, upper critical, lower warning and lower critical. Thus it will contain up to 4 structures shown below:
+For numeric metric type, trigger parameters contain numeric thresholds. Numeric
+thresholds structure shall contain up to 4 thresholds: upper warning, upper
+critical, lower warning and lower critical. Thus it will contain up to 4
+structures shown below:
-| Field | Type | Description |
-|-------|------|-------------|
-| ThresholdType | enum | Numeric trigger type: <br> "UpperCritical" - reading is above normal range and requires immediate attention<br>"UpperWarning" - reading is above normal range and may require attention<br>"LowerCritical" - reading is below normal range and requires immediate attention<br>"LowerWarning" - reading is below normal range and may require attention|
-| DwellTime | uint64 | Time in milliseconds that a trigger occurrence persists before the action defined for this trigger is performed. |
-| Activation | enum | Indicates direction of crossing the threshold value that trigger the threshold's action:<br> "Increasing" - trigger action when reading is changing from below to above the threshold's value<br> "Decreasing" - trigger action when reading is changing from above to below the threshold's value<br> "Either" - trigger action when reading is crossing the threshold's value in either direction described above |
-| ThresholdValue | variant | Value of reading that will trigger the threshold |
+| Field | Type | Description |
+| -------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| ThresholdType | enum | Numeric trigger type: <br> "UpperCritical" - reading is above normal range and requires immediate attention<br>"UpperWarning" - reading is above normal range and may require attention<br>"LowerCritical" - reading is below normal range and requires immediate attention<br>"LowerWarning" - reading is below normal range and may require attention |
+| DwellTime | uint64 | Time in milliseconds that a trigger occurrence persists before the action defined for this trigger is performed. |
+| Activation | enum | Indicates direction of crossing the threshold value that trigger the threshold's action:<br> "Increasing" - trigger action when reading is changing from below to above the threshold's value<br> "Decreasing" - trigger action when reading is changing from above to below the threshold's value<br> "Either" - trigger action when reading is crossing the threshold's value in either direction described above |
+| ThresholdValue | variant | Value of reading that will trigger the threshold |
The `AddTrigger` method also allows to define the specific action when trigger
is activated. Upon the trigger activation, three possible actions are allowed,
-logging event to log service, sending event via event service and triggering
-the metric report update.
+logging event to log service, sending event via event service and triggering the
+metric report update.
In order to assign trigger to specific metric, the metric parameter is defined.
Its structure contains the following data:
-| Field | Type | Description |
-|-------|------|-------------|
-| SensorPath | object path | D-Bus path to sensor, for which trigger is defined. |
-| MetricId | string | Contains unique metric id, that can be mapped to Redfish MetricId. |
+| Field | Type | Description |
+| ---------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| SensorPath | object path | D-Bus path to sensor, for which trigger is defined. |
+| MetricId | string | Contains unique metric id, that can be mapped to Redfish MetricId. |
| ReportPath | object path | D-Bus path to Telemetry's reading report which update shall be triggered when trigger condition occurs. This is optional and shall be filled when trigger's action is set to update metric report. |
The `AddTrigger` method also allows to set trigger's persistency (whether
trigger shall be stored in the BMC's non-volatile memory).
The `AddTrigger` method returns:
+
```ascii
String for created trigger - ie. '/xyz/openbmc_project/Telemetry/Triggers/{Domain}/{Name}'
```
-Such created trigger implements the `xyz.openbmc_project.Object.Delete`
-and the `xyz.openbmc_project.Telemetry.Trigger` interfaces. Each trigger
-object contains read-only information about metric type, for which it was
-created (discrete or numeric). This information determines which triggers
-are stored within trigger object.
+
+Such created trigger implements the `xyz.openbmc_project.Object.Delete` and the
+`xyz.openbmc_project.Telemetry.Trigger` interfaces. Each trigger object contains
+read-only information about metric type, for which it was created (discrete or
+numeric). This information determines which triggers are stored within trigger
+object.
If trigger is defined for discrete metric type, than it contains trigger
information that looks like this:
-| Type | Description |
-|------|-------------|
-| enum | Discrete trigger condition: <br> "Changed" - trigger occurs when value of metric has changed;<br>"Specified" - trigger occurs when value of metric becomes one of the values listed in the discrete triggers. |
-| array of structures | Array of discrete trigger structures. |
+| Type | Description |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| enum | Discrete trigger condition: <br> "Changed" - trigger occurs when value of metric has changed;<br>"Specified" - trigger occurs when value of metric becomes one of the values listed in the discrete triggers. |
+| array of structures | Array of discrete trigger structures. |
Discrete trigger structure:
-| Type | Description |
-|------|-------------|
-| string | Unique trigger Id |
-| enum | Severity: <br> "OK" - normal<br>"Warning" - requires attention<br> "Critical" - requires immediate attention |
-| variant | Value of discrete metric, that constitutes a trigger event. |
-| uint64 | Time in milliseconds that a trigger occurrence persists before the action defined in the ```ActionType``` is performed. |
+| Type | Description |
+| ------- | ------------------------------------------------------------------------------------------------------------------- |
+| string | Unique trigger Id |
+| enum | Severity: <br> "OK" - normal<br>"Warning" - requires attention<br> "Critical" - requires immediate attention |
+| variant | Value of discrete metric, that constitutes a trigger event. |
+| uint64 | Time in milliseconds that a trigger occurrence persists before the action defined in the `ActionType` is performed. |
If trigger is defined for numeric metric type, than it contains information
about numeric triggers that is an array of 4 structures presented below:
-| Type | Description |
-|------|-------------|
-| enum | Numeric trigger type: <br> "UpperWarning"<br>"UpperWarning"<br>"LowerCritical"<br>"LowerWarning"|
-| uint64 | Time in milliseconds that a trigger occurrence persists before the action defined in the ```ActionType``` is performed. |
-| enum | Indicates direction of crossing the threshold value that trigger the threshold's action:<br> "Increasing"<br>"Decreasing"<br>"Either" |
-| variant | Value of reading that will trigger the threshold |
+| Type | Description |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| enum | Numeric trigger type: <br> "UpperWarning"<br>"UpperWarning"<br>"LowerCritical"<br>"LowerWarning" |
+| uint64 | Time in milliseconds that a trigger occurrence persists before the action defined in the `ActionType` is performed. |
+| enum | Indicates direction of crossing the threshold value that trigger the threshold's action:<br> "Increasing"<br>"Decreasing"<br>"Either" |
+| variant | Value of reading that will trigger the threshold |
The trigger object also contains information about reading, for which trigger
was defined. It is in a form of structure consisting of three fields.
-| Field type | Description |
-|------------|--------------|
-| object path | D-Bus path of sensor. This is a path to the sensor, for which reading trigger is defined. |
-| string | Unique metric Id |
+| Field type | Description |
+| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| object path | D-Bus path of sensor. This is a path to the sensor, for which reading trigger is defined. |
+| 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**
@@ -414,10 +420,10 @@
Triggers support three types of operation: Log, Event and Update. For each,
there is a different way of proceeding.
-1. For action Log, the event shall
-be logged to the system journal. In this case the Telemetry service writes
-data to system journal using libjournal. The Redfish log service shall then
-retrieve the data by reading system journal. All is shown on the diagram below.
+1. For action Log, the event shall be logged to the system journal. In this case
+ the Telemetry service writes data to system journal using libjournal. The
+ Redfish log service shall then retrieve the data by reading system journal.
+ All is shown on the diagram below.
```ascii
+---------------------------+
@@ -446,14 +452,15 @@
| |
+------------------------------------+
```
-2. For action Event, the Telemetry service shall send event using the
-[Redfish Event Service][6] either as push-style event or SSE.
+
+2. For action Event, the Telemetry service shall send event using the [Redfish
+ Event Service][6] either as push-style event or SSE.
3. For action Update, the Telemetry service will trigger the update of reading
-report pointed by it's D-Bus path contained in trigger object properties. The
-update shall cause the reading report's D-Bus object to emit property change
-signal. This will cause Redfish Metric Report to be streamed out if it was
-configured to do so.
+ report pointed by it's D-Bus path contained in trigger object properties. The
+ update shall cause the reading report's D-Bus object to emit property change
+ signal. This will cause Redfish Metric Report to be streamed out if it was
+ configured to do so.
**Redfish Telemetry Service API**
@@ -518,9 +525,9 @@
defined to be generated periodically, on demand or on change. Each metric in the
Metric Report contains the URI to its metric definition and Redfish sensor,
which reading value is presented. Nevertheless, under this presentation layer,
-Telemetry is gathering D-Bus sensors readings and exposing them
-in reading reports over D-Bus for the Telemetry Service. Each D-Bus sensor
-is mapped to Redfish sensor.
+Telemetry is gathering D-Bus sensors readings and exposing them in reading
+reports over D-Bus for the Telemetry Service. Each D-Bus sensor is mapped to
+Redfish sensor.
Below examples of Redfish resources for the Telemetry Service are shown.
@@ -562,33 +569,31 @@
```json
{
- "@odata.type": "#MetricReportDefinition.v1_3_0.MetricReportDefinition",
- "Id": "SampleMetric",
- "Name": "Sample Metric Report Definition",
- "MetricReportDefinitionType": "Periodic",
- "Schedule": {
- "RecurrenceInterval": "T00:00:10"
- },
- "ReportActions": [
- "LogToMetricReportsCollection"
- ],
- "ReportUpdates": "Overwrite",
- "MetricReport": {
- "@odata.id": "/redfish/v1/TelemetryService/MetricReports/SampleMetric"
- },
- "Status": {
- "State": "Enabled"
- },
- "Metrics": [
- {
- "MetricId": "Test",
- "MetricProperties": [
- "/redfish/v1/Chassis/NC_Baseboard/Power#/PowerControl/0/PowerConsumedWatts"
- ]
- }
- ],
- "@odata.context": "/redfish/v1/$metadata#MetricReportDefinition.MetricReportDefinition",
- "@odata.id": "/redfish/v1/TelemetryService/MetricReportDefinitions/PlatformPowerUsage"
+ "@odata.type": "#MetricReportDefinition.v1_3_0.MetricReportDefinition",
+ "Id": "SampleMetric",
+ "Name": "Sample Metric Report Definition",
+ "MetricReportDefinitionType": "Periodic",
+ "Schedule": {
+ "RecurrenceInterval": "T00:00:10"
+ },
+ "ReportActions": ["LogToMetricReportsCollection"],
+ "ReportUpdates": "Overwrite",
+ "MetricReport": {
+ "@odata.id": "/redfish/v1/TelemetryService/MetricReports/SampleMetric"
+ },
+ "Status": {
+ "State": "Enabled"
+ },
+ "Metrics": [
+ {
+ "MetricId": "Test",
+ "MetricProperties": [
+ "/redfish/v1/Chassis/NC_Baseboard/Power#/PowerControl/0/PowerConsumedWatts"
+ ]
+ }
+ ],
+ "@odata.context": "/redfish/v1/$metadata#MetricReportDefinition.MetricReportDefinition",
+ "@odata.id": "/redfish/v1/TelemetryService/MetricReportDefinitions/PlatformPowerUsage"
}
```
@@ -596,26 +601,26 @@
```json
{
- "@odata.type": "#MetricReport.v1_2_0.MetricReport",
- "Id": "SampleMetric",
- "Name": "Sample Metric Report",
- "ReportSequence": "0",
- "MetricReportDefinition": {
- "@odata.id": "/redfish/v1/TelemetryService/MetricReportDefinitions/SampleMetric"
- },
- "MetricValues": [
- {
- "MetricDefinition": {
- "@odata.id": "/redfish/v1/TelemetryService/MetricDefinitions/SampleMetricDefinition"
- },
- "MetricId": "Test",
- "MetricValue": "100",
- "Timestamp": "2016-11-08T12:25:00-05:00",
- "MetricProperty": "/redfish/v1/Chassis/Tray_1/Power#/0/PowerConsumedWatts"
- }
- ],
- "@odata.context": "/redfish/v1/$metadata#MetricReport.MetricReport",
- "@odata.id": "/redfish/v1/TelemetryService/MetricReports/AvgPlatformPowerUsage"
+ "@odata.type": "#MetricReport.v1_2_0.MetricReport",
+ "Id": "SampleMetric",
+ "Name": "Sample Metric Report",
+ "ReportSequence": "0",
+ "MetricReportDefinition": {
+ "@odata.id": "/redfish/v1/TelemetryService/MetricReportDefinitions/SampleMetric"
+ },
+ "MetricValues": [
+ {
+ "MetricDefinition": {
+ "@odata.id": "/redfish/v1/TelemetryService/MetricDefinitions/SampleMetricDefinition"
+ },
+ "MetricId": "Test",
+ "MetricValue": "100",
+ "Timestamp": "2016-11-08T12:25:00-05:00",
+ "MetricProperty": "/redfish/v1/Chassis/Tray_1/Power#/0/PowerConsumedWatts"
+ }
+ ],
+ "@odata.context": "/redfish/v1/$metadata#MetricReport.MetricReport",
+ "@odata.id": "/redfish/v1/TelemetryService/MetricReports/AvgPlatformPowerUsage"
}
```
@@ -623,93 +628,91 @@
```json
{
- "@odata.type": "#Triggers.v1_1_1.Triggers",
- "Id": "SampleTrigger",
- "Name": "Sample Trigger",
- "MetricType": "Numeric",
- "Links": {
- "MetricReportDefinitions": [
- "/redfish/v1/TelemetryService/MetricReportDefinitions/SampleMetric"
- ]
+ "@odata.type": "#Triggers.v1_1_1.Triggers",
+ "Id": "SampleTrigger",
+ "Name": "Sample Trigger",
+ "MetricType": "Numeric",
+ "Links": {
+ "MetricReportDefinitions": [
+ "/redfish/v1/TelemetryService/MetricReportDefinitions/SampleMetric"
+ ]
+ },
+ "Status": {
+ "State": "Enabled"
+ },
+ "TriggerActions": ["RedfishMetricReport"],
+ "NumericThresholds": {
+ "UpperCritical": {
+ "Reading": 50,
+ "Activation": "Increasing",
+ "DwellTime": "PT0.001S"
},
- "Status": {
- "State": "Enabled"
- },
- "TriggerActions": [
- "RedfishMetricReport"
- ],
- "NumericThresholds": {
- "UpperCritical": {
- "Reading": 50,
- "Activation": "Increasing",
- "DwellTime": "PT0.001S"
- },
- "UpperWarning": {
- "Reading": 48.1,
- "Activation": "Increasing",
- "DwellTime": "PT0.004S"
- }
- },
- "MetricProperties": [
- "/redfish/v1/Chassis/Tray_1/Power#/0/PowerConsumedWatts"
- ],
- "@odata.context": "/redfish/v1/$metadata#Triggers.Triggers",
- "@odata.id": "/redfish/v1/TelemetryService/Triggers/PlatformPowerCapTriggers"
+ "UpperWarning": {
+ "Reading": 48.1,
+ "Activation": "Increasing",
+ "DwellTime": "PT0.004S"
+ }
+ },
+ "MetricProperties": [
+ "/redfish/v1/Chassis/Tray_1/Power#/0/PowerConsumedWatts"
+ ],
+ "@odata.context": "/redfish/v1/$metadata#Triggers.Triggers",
+ "@odata.id": "/redfish/v1/TelemetryService/Triggers/PlatformPowerCapTriggers"
}
```
**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 statistics are shown in the table below. The reading report is
-mapped into single Metric Report. The runtime data is collected for the
-Telemetry component only. All reports was created with
-```xyz.openbmc_project.Telemetry.Metric.OnChange``` property to
-maximize the workload. In the configuration with 50 reports and 50 sensors
-it is about 200 new readings per second, generating 200 reading reports
-per second. The table shows CPU usage and memory usage. The VSZ is the amount
-of memory mapped into the address space of the process. It includes pages
-backed by the process' executable file and shared libraries, its heap and
-stack, as well as anything else it has mapped.
+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
+statistics are shown in the table below. The reading report is mapped into
+single Metric Report. The runtime data is collected for the Telemetry component
+only. All reports was created with
+`xyz.openbmc_project.Telemetry.Metric.OnChange` property to maximize the
+workload. In the configuration with 50 reports and 50 sensors it is about 200
+new readings per second, generating 200 reading reports per second. The table
+shows CPU usage and memory usage. The VSZ is the amount of memory mapped into
+the address space of the process. It includes pages backed by the process'
+executable file and shared libraries, its heap and stack, as well as anything
+else it has mapped.
+| Telemetry service state | VSZ | %VSZ | %CPU |
+| --------------------------------------------- | ------ | ---- | ------ |
+| Idle (0 reports, 0 sensors) | 5188 B | 1% | 0% |
+| 1 report, 1 sensor | 5188 B | 1% | 1% |
+| 2 reports, 1 sensor | 5188 B | 1% | 1% |
+| 2 reports, 2 sensors (1 sensor per report) | 5188 B | 1% | 1% |
+| 1 report, 10 sensors | 5188 B | 1% | 1% |
+| 10 reports, 10 sensors (same for each report) | 5320 B | 1% | 1-2% |
+| 2 reports, 20 sensors (10 per report) | 5188 B | 1% | 1% |
+| 30 reports, 30 sensors (10 per report) | 5444 B | 1% | 5-9% |
+| 50 reports, 50 sensors (10 per report) | 5572 B | 1% | 11-14% |
-| Telemetry service state | VSZ | %VSZ | %CPU |
-|--------------------------------------------------|------|------|------|
-| Idle (0 reports, 0 sensors) |5188 B| 1% | 0% |
-| 1 report, 1 sensor |5188 B| 1% | 1% |
-| 2 reports, 1 sensor |5188 B| 1% | 1% |
-| 2 reports, 2 sensors (1 sensor per report) |5188 B| 1% | 1% |
-| 1 report, 10 sensors |5188 B| 1% | 1% |
-| 10 reports, 10 sensors (same for each report) |5320 B| 1% | 1-2% |
-| 2 reports, 20 sensors (10 per report) |5188 B| 1% | 1% |
-| 30 reports, 30 sensors (10 per report) |5444 B| 1% | 5-9% |
-| 50 reports, 50 sensors (10 per report) |5572 B| 1% |11-14%|
+The last two configurations use 10 sensors per reading report, which gives 3 or
+5 distinctive configurations. Each such configuration is used to create 10
+reading reports to obtain the desired amount of 30 or 50 reading reports.
-The last two configurations use 10 sensors per reading report, which gives
-3 or 5 distinctive configurations. Each such configuration is used to
-create 10 reading reports to obtain the desired amount of 30 or 50 reading
-reports.
-
-In this architecture reading report is created every time when Redfish
-Metric Report Definition is posted (creating new Metric Report).
+In this architecture reading report is created every time when Redfish Metric
+Report Definition is posted (creating new Metric Report).
## Alternatives Considered
+
The [framework based on collectd/librrd][5] was considered as alternate design.
Although it seems to be versatile and scalable solution, it has some drawbacks
from our point of view:
-* Collectd's footprint in the minimal working configuration is around 2.6 MB,
-while available space for the OpenBMC is limited to 64 MB.
-* In this design, librrd is used to store metrics on the BMC's non-volatile
-storage, which may be an issue, when lots of metrics are captured and stored
-to OpenBMC's limited storage space. Also flash wear-out issue may occur, when
-metrics are captured frequently (like once per second).
-* Telemetry service is directly compatible with Redfish Telemetry Service API,
-which means, that Telemetry's reading reports can be directly mapped to Redfish
-Metric Reports.
-* Telemetry service unifies the way how the BMC's telemetry is exposed over
-the Redfish and may be used with multiple front-ends, thus there is no problem
-to add support telemetry over IPMI or any other API.
+
+- Collectd's footprint in the minimal working configuration is around 2.6 MB,
+ while available space for the OpenBMC is limited to 64 MB.
+- In this design, librrd is used to store metrics on the BMC's non-volatile
+ storage, which may be an issue, when lots of metrics are captured and stored
+ to OpenBMC's limited storage space. Also flash wear-out issue may occur, when
+ metrics are captured frequently (like once per second).
+- Telemetry service is directly compatible with Redfish Telemetry Service API,
+ which means, that Telemetry's reading reports can be directly mapped to
+ Redfish Metric Reports.
+- Telemetry service unifies the way how the BMC's telemetry is exposed over the
+ Redfish and may be used with multiple front-ends, thus there is no problem to
+ add support telemetry over IPMI or any other API.
Since this design assumes flexibility and modularity, there is no obstacles to
use collectd in cooperation with Telemetry. The one of possible configurations
@@ -739,11 +742,11 @@
| |
+--------------+
```
-Here collectd is used as the source of some set of metrics. It exposes them
-as the D-Bus sensors, which can easily be consumed either by the bmcweb and
+
+Here collectd is used as the source of some set of metrics. It exposes them as
+the D-Bus sensors, which can easily be consumed either by the bmcweb and
Telemetry service without any changes in their D-Bus interfaces. In such
-configuration Telemetry service provides metric reports and triggers
-management.
+configuration Telemetry service provides metric reports and triggers management.
Other possible configuration is to use collectd without the Telemetry service,
but in such case, collectd does not provide metric reports and triggers support
@@ -752,25 +755,28 @@
collectd.
## Impacts
-This design impacts the architecture of the bmcweb component, since it adds
-the Redfish Telemetry Service implementation as a component for the existing
-Redfish API implementation.
+
+This design impacts the architecture of the bmcweb component, since it adds the
+Redfish Telemetry Service implementation as a component for the existing Redfish
+API implementation.
## Testing
-This is the very high-level description of the proposed set of tests.
-Testing shall be done on three basic levels:
-* Unit tests
-* Functional tests
-* Performance tests
+
+This is the very high-level description of the proposed set of tests. Testing
+shall be done on three basic levels:
+
+- Unit tests
+- Functional tests
+- Performance 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 committed to make sure, that nothing is broken in existing
-functionality. Also, when new code is introduced, a new set of unit tests shall
-be committed with it according to test-driven development principle. Unit tests
-shall be also carefully reviewed.
+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
+committed to make sure, that nothing is broken in existing functionality. Also,
+when new code is introduced, a new set of unit tests shall be committed with it
+according to test-driven development principle. Unit tests shall be also
+carefully reviewed.
**Functional tests**
@@ -792,19 +798,24 @@
**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 maximum number) along with all possible triggers. Measurements shall
-cover the periodic metric report jitter, delays in event logging or sending,
-BMC's CPU utilization and the performance impact on other services.
+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
+maximum number) along with all possible triggers. Measurements shall cover the
+periodic metric report jitter, delays in event logging or sending, BMC's CPU
+utilization and the performance impact on other services.
-[1]: https://www.dmtf.org/sites/default/files/standards/documents/DSP2051_0.1.0a.zip
-[2]: https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md
+[1]:
+ https://www.dmtf.org/sites/default/files/standards/documents/DSP2051_0.1.0a.zip
+[2]:
+ https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md
[3]: https://www.kernel.org/doc/Documentation/hwmon/
[4]: https://www.freedesktop.org/wiki/Software/dbus/
[5]: https://gerrit.openbmc.org/c/openbmc/docs/+/22257
[6]: https://gerrit.openbmc.org/c/openbmc/docs/+/24749
[7]: https://github.com/google/googletest
-[8]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Telemetry/ReportManager.interface.yaml
-[9]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Telemetry/Report.interface.yaml
-[10]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Object/Delete.interface.yaml
+[8]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Telemetry/ReportManager.interface.yaml
+[9]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Telemetry/Report.interface.yaml
+[10]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Object/Delete.interface.yaml
diff --git a/designs/thermal-control-modes.md b/designs/thermal-control-modes.md
index 3fd409c..163784f 100644
--- a/designs/thermal-control-modes.md
+++ b/designs/thermal-control-modes.md
@@ -1,42 +1,41 @@
# Control.ThermalMode dbus interface with Supported and Current properties
-Author:
- Matthew Barth !msbarth
+Author: Matthew Barth !msbarth
-Other contributors:
- None
+Other contributors: None
-Created:
- 2019-02-06
+Created: 2019-02-06
## Problem Description
+
An issue was discovered where the exhaust heat from the system GPUs causes
-overtemp warnings on optical cables on certain system configurations. The
-issue can be resolved by altering the fan control application's floor table,
+overtemp warnings on optical cables on certain system configurations. The issue
+can be resolved by altering the fan control application's floor table,
effectively raising the floor when these optical cables exist but an interface
is needed to do so. Since the issue revolves around the optical cables
themselves, where no current mechanism exists to detect the presence of the
-optical cables plugged into a card downwind from the GPUs' exhaust,
-an end-user must be presented with an ability to enable this raised floor
-speed table.
+optical cables plugged into a card downwind from the GPUs' exhaust, an end-user
+must be presented with an ability to enable this raised floor speed table.
## Background and References
-The witherspoon system supports pci cards that could have optical cables
-plugged in place of copper cables. These optical cables can report overtemp
-warnings to the OS when high GPU utilization workloads exist. When this occurs
-with low enough CPU utilization, the fans could be kept at a given floor speed
-that sufficiently cools the components within the chassis, but not the optical
-cables with the slow moving hot exhaust.
-Without an available exhaust temp sensor, there's no direct way to determine
-the exhaust temp and include that within the fan control algorithm. A similar
-issue exists on other system where mathematical calculations are done based on
-the overall power dissipation.
+The witherspoon system supports pci cards that could have optical cables plugged
+in place of copper cables. These optical cables can report overtemp warnings to
+the OS when high GPU utilization workloads exist. When this occurs with low
+enough CPU utilization, the fans could be kept at a given floor speed that
+sufficiently cools the components within the chassis, but not the optical cables
+with the slow moving hot exhaust.
+
+Without an available exhaust temp sensor, there's no direct way to determine the
+exhaust temp and include that within the fan control algorithm. A similar issue
+exists on other system where mathematical calculations are done based on the
+overall power dissipation.
Mathematical calculations to logically estimate exit air temps:
https://github.com/openbmc/dbus-sensors/blob/master/src/ExitAirTempSensor.cpp
## Requirements
+
Create the ability for an end-user to enable the use of a thermal control mode
other than the default. In this use-case, the mode is specific to an
undetectable configuration that alters the fan floor speeds unrelated to
@@ -46,33 +45,36 @@
implementation specific to that instance of the application on that platform.
## Proposed Design
+
Create a Control.ThermalMode dbus interface containing a supported list of
available thermal control modes along with what current mode is in use.
-Initially the current mode would be set to "Default" and the implementation
-of the interface would populate the supported list of modes.
+Initially the current mode would be set to "Default" and the implementation of
+the interface would populate the supported list of modes.
As one implementation, phosphor-fan-presence/control would be updated to extend
-this dbus interface object which would fill in the list of supported modes
-from its fan control configuration for the platform. Once the fan control
-application starts, the interface would be added on the zone object and
-available to be queried for supported modes or update the current mode.
-An end-user may set the current mode to any of those supported modes and the
-current mode would be persisted each time it is updated. This is to ensure
-each time the fan control application zone objects are started, the last set
-control mode is used.
+this dbus interface object which would fill in the list of supported modes from
+its fan control configuration for the platform. Once the fan control application
+starts, the interface would be added on the zone object and available to be
+queried for supported modes or update the current mode. An end-user may set the
+current mode to any of those supported modes and the current mode would be
+persisted each time it is updated. This is to ensure each time the fan control
+application zone objects are started, the last set control mode is used.
## Alternatives Considered
-Mathematical calculation to create a virtual exhaust temp sensor value based
-on overall power dissipation. However, in the witherspoon situation, using
-this technique would not be reliable in adjusting the floor speeds for only
+
+Mathematical calculation to create a virtual exhaust temp sensor value based on
+overall power dissipation. However, in the witherspoon situation, using this
+technique would not be reliable in adjusting the floor speeds for only
configurations using optical cables. This would instead present the possibility
of raising floor speeds for configurations where its unnecessary.
## Impacts
+
The thermal control application used must be configured to provide what thermal
control modes are supported/available on the interface as well as perform the
associated control changes when a mode is set.
## Testing
+
Trigger the use of an alternative fan floor table based on the thermal control
mode selected on a witherspoon system.
diff --git a/designs/unique-hostname.md b/designs/unique-hostname.md
index 0566db4..14e5c22 100644
--- a/designs/unique-hostname.md
+++ b/designs/unique-hostname.md
@@ -1,21 +1,20 @@
# Setting a unique hostname to the BMC machine on first boot
-Author:
- Asmitha KR
+Author: Asmitha KR
-Other contributors:
- None
+Other contributors: None
-Created:
- 2019-05-07
+Created: 2019-05-07
## Problem Description
+
In OpenBMC, the hostname discovery is done by the avahi Dbus service at the
startup. In a network where there are multiple OpenBMC machines, avahi keeps
-getting the hostname conflict and the service name conflict. Hence, the
-problem is to find a solution that resolves these conflicts.
+getting the hostname conflict and the service name conflict. Hence, the problem
+is to find a solution that resolves these conflicts.
## Background and References
+
The detailed issue regarding the hostname and service name conflicts is
described in the following links.
@@ -24,19 +23,24 @@
https://github.com/lathiat/avahi/issues/117
## Requirements
+
None.
## Proposed Design
-To solve this, we are proposing a service which assigns a unique hostname to
-the BMC and runs on the very first boot. one of the ways to generate the unique
+
+To solve this, we are proposing a service which assigns a unique hostname to the
+BMC and runs on the very first boot. one of the ways to generate the unique
hostname is to append the Serial Number retrieved from Inventory Manager to the
existing default hostname.
## Alternatives Considered
+
None.
## Impacts
+
None.
## Testing
+
None.
diff --git a/designs/virtual-media.md b/designs/virtual-media.md
index 47ee481..f858267 100644
--- a/designs/virtual-media.md
+++ b/designs/virtual-media.md
@@ -1,32 +1,31 @@
# 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
+Created: 6/4/2019
## Problem Description
Virtual Media allows users to remotely mount given ISO/IMG drive images through
BMC to Server HOST. The Remote drive is visible in HOST as USB storage device,
-and operates in RO mode, or RW mode (keeping in mind container limitations,
-and write protection switches). This can even be used to install OS on bare
-metal system. This document focuses on few redirection options, like in-browser
+and operates in RO mode, or RW mode (keeping in mind container limitations, and
+write protection switches). This can even be used to install OS on bare metal
+system. This document focuses on few redirection options, like in-browser
ISO/IMG image mounting, and remote CIFS/HTTPS image mounting.
## References
-* Virtual Media is going to use Network Block Device as primary disk image
-forwarder.
-* NBDkit is being used, to serve images from remote storages over HTTPS/CIFS.
-USBGadget as way to expose Media Storage Device to HOST.
+- Virtual Media is going to use Network Block Device as primary disk image
+ forwarder.
+- NBDkit is being used, to serve images from remote storages over HTTPS/CIFS.
+ USBGadget as way to expose Media Storage Device to HOST.
## Requirements
+
None
## Proposed Design
@@ -34,12 +33,12 @@
Virtual Media splits into two modes of operation, lets call it Proxy, and
Legacy.
-* Proxy mode - works directly from browser and uses JavaScript/HTML5 to
-communicate over Secure WebSockets directly to HTTPS endpoint hosted by bmcweb
-on BMC.
-* Legacy mode - is initiated from browser using Redfish defined VirtualMedia
-schemas, then BMC process connects to external CIFS/HTTPS image pointed during
-initialization.
+- Proxy mode - works directly from browser and uses JavaScript/HTML5 to
+ communicate over Secure WebSockets directly to HTTPS endpoint hosted by bmcweb
+ on BMC.
+- Legacy mode - is initiated from browser using Redfish defined VirtualMedia
+ schemas, then BMC process connects to external CIFS/HTTPS image pointed during
+ initialization.
Both methods inherit from default Redfish/BMCWeb authentication and privileges
mechanisms.
@@ -70,14 +69,12 @@
+------------------+ +----------------------------------+
```
-Virtual Media feature supports multiple, simultaneous connections in both
-modes.
+Virtual Media feature supports multiple, simultaneous connections in both modes.
### Asynchronicity
-Mounting and unmounting of remote device could be time consuming. Virtual
-Media shall support asynchronicity at the level of DBus and optionally Redfish
-API.
+Mounting and unmounting of remote device could be time consuming. Virtual Media
+shall support asynchronicity at the level of DBus and optionally Redfish API.
Default timeouts for DBus (25 seconds) and for Redfish (60 seconds) may be
insufficient to perform mounting and unmounting in some cases.
@@ -90,8 +87,8 @@
Device. After Sourceforge project description:
> With this compiled into your kernel, Linux can use a remote server as one of
-> its block devices. Every time the client computer wants to read /dev/nbd0,
-> it will send a request to the server via TCP, which will reply with the data
+> its block devices. Every time the client computer wants to read /dev/nbd0, it
+> will send a request to the server via TCP, which will reply with the data
> requested. This can be used for stations with low disk space (or even
> diskless - if you use an initrd) to borrow disk space from other computers.
> Unlike NFS, it is possible to put any file system on it. But (also unlike
@@ -106,7 +103,7 @@
### USB Gadget
-Part of Linux kernel that makes *emulation* of certain USB device classes
+Part of Linux kernel that makes _emulation_ of certain USB device classes
possible through USB "On-The-Go", if connect appropriately to Host. In Virtual
Media case it emulates USB mass storage connected to HOST. The source or
redirection is block device created by nbd-client `/dev/nbdXX`
@@ -174,11 +171,10 @@
### Legacy Mode
Legacy Mode uses VirtualMedia schema, defined by DMTF, for mounting external
-CIFS/HTTPS images. The current implementation supports only stream mounting
-as for now. In this case Redfish is only used as mechanism for Virtual Media
-initialization, and is not responsible for data transmission. For data there
-is a separate component responsible for handling CIFS/HTTPS traffic called
-NBDkit.
+CIFS/HTTPS images. The current implementation supports only stream mounting as
+for now. In this case Redfish is only used as mechanism for Virtual Media
+initialization, and is not responsible for data transmission. For data there is
+a separate component responsible for handling CIFS/HTTPS traffic called NBDkit.
Multiple, simultaneous connections are supported through spawning additional
nbkit instances, the number of available instances for CIFS/HTTPS is configured
@@ -237,25 +233,26 @@
defined by DMTF. Here are some examples.
#### Virtual Media Collection schema
+
Members in collection will be defined based on configuration file described in
next sections. And will be visible despite media is inserted or not.
```json
{
- "@odata.type": "#VirtualMediaCollection.VirtualMediaCollection",
- "Name": "Virtual Media Services",
- "Description": "Redfish-BMC Virtual Media Service Settings",
- "Members@odata.count": 2,
- "Members": [
- {
- "@odata.id": "/redfish/v1/Managers/BMC/VirtualMedia/ISO0"
- } ,
- {
- "@odata.id": "/redfish/v1/Managers/BMC/VirtualMedia/1"
- }
- ],
- "@odata.context": "/redfish/v1/$metadata#VirtualMediaCollection.VirtualMediaCollection",
- "@odata.id": "/redfish/v1/Managers/BMC/VirtualMedia"
+ "@odata.type": "#VirtualMediaCollection.VirtualMediaCollection",
+ "Name": "Virtual Media Services",
+ "Description": "Redfish-BMC Virtual Media Service Settings",
+ "Members@odata.count": 2,
+ "Members": [
+ {
+ "@odata.id": "/redfish/v1/Managers/BMC/VirtualMedia/ISO0"
+ },
+ {
+ "@odata.id": "/redfish/v1/Managers/BMC/VirtualMedia/1"
+ }
+ ],
+ "@odata.context": "/redfish/v1/$metadata#VirtualMediaCollection.VirtualMediaCollection",
+ "@odata.id": "/redfish/v1/Managers/BMC/VirtualMedia"
}
```
@@ -263,48 +260,45 @@
```json
{
- "@odata.type": "#VirtualMedia.v1_1_0.VirtualMedia",
- "Id": "ISO0",
- "Name": "Virtual Removable Media",
- "Actions": {
- "#VirtualMedia.InsertMedia": {
- "target": "/redfish/v1/Managers/bmc/VirtualMedia/ISO0/Actions/VirtualMedia.InsertMedia"
- },
- "#VirtualMedia.EjectMedia": {
- "target": "/redfish/v1/Managers/bmc/VirtualMedia/ISO0/Actions/VirtualMedia.EjectMedia"
- }
- },
- "MediaTypes": [
- "CD",
- "USBStick"
- ],
- "Image": "https://192.168.0.1/Images/os.iso",
- "ImageName": "Os",
- "ConnectedVia": "URI",
- "Inserted": true,
- "WriteProtected": false,
- "@odata.context": "/redfish/v1/$metadata#VirtualMedia.VirtualMedia",
- "@odata.id": "/redfish/v1/Managers/BMC/VirtualMedia/ISO0",
- "Oem": {
- "OpenBMC": {
- "@odata.type": "#OemVirtualMedia.v1_0_0.VirtualMedia",
- "WebSocketEndpoint": "/nbd/0"
- }
+ "@odata.type": "#VirtualMedia.v1_1_0.VirtualMedia",
+ "Id": "ISO0",
+ "Name": "Virtual Removable Media",
+ "Actions": {
+ "#VirtualMedia.InsertMedia": {
+ "target": "/redfish/v1/Managers/bmc/VirtualMedia/ISO0/Actions/VirtualMedia.InsertMedia"
},
+ "#VirtualMedia.EjectMedia": {
+ "target": "/redfish/v1/Managers/bmc/VirtualMedia/ISO0/Actions/VirtualMedia.EjectMedia"
+ }
+ },
+ "MediaTypes": ["CD", "USBStick"],
+ "Image": "https://192.168.0.1/Images/os.iso",
+ "ImageName": "Os",
+ "ConnectedVia": "URI",
+ "Inserted": true,
+ "WriteProtected": false,
+ "@odata.context": "/redfish/v1/$metadata#VirtualMedia.VirtualMedia",
+ "@odata.id": "/redfish/v1/Managers/BMC/VirtualMedia/ISO0",
+ "Oem": {
+ "OpenBMC": {
+ "@odata.type": "#OemVirtualMedia.v1_0_0.VirtualMedia",
+ "WebSocketEndpoint": "/nbd/0"
+ }
+ }
}
```
-Schema will look similar for both Proxy and Legacy Mode. Some key
-differences as follows:
+Schema will look similar for both Proxy and Legacy Mode. Some key differences as
+follows:
-| Field Name | Proxy Mode | Legacy Mode | Comment |
-| -------------------- | ---------- | -------------------------------- | ----------------------------------- |
+| 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 | |
+| 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
@@ -312,11 +306,10 @@
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 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.
+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.
### Inactivity timeout
@@ -329,16 +322,16 @@
### Virtual Media Service
-Virtual Media Service is separate application that will coexist on DBus. It
-will be initialized from configuration json file, and expose all available
-for provisioning VirtualMedia objects. Virtual Media is responsible for:
+Virtual Media Service is separate application that will coexist on DBus. It will
+be initialized from configuration json file, and expose all available for
+provisioning VirtualMedia objects. Virtual Media is responsible for:
-* Exposing current Virtual Media configuration to DBus user.
-* Spawning nbdclient, and monitor its lifetime, for Proxy connections.
-* Spawning nbdkit, and monitor its lifetime, for CIFS/HTTPS connections.
-* Monitoring uDEV for all NBD related block device changes, and
+- Exposing current Virtual Media configuration to DBus user.
+- Spawning nbdclient, and monitor its lifetime, for Proxy connections.
+- Spawning nbdkit, and monitor its lifetime, for CIFS/HTTPS connections.
+- Monitoring uDEV for all NBD related block device changes, and
configure/de-configure USB Gadget accordingly.
-* Monitor NBD device inactivity period to support inactivity timeout.
+- Monitor NBD device inactivity period to support inactivity timeout.
### Configuration
@@ -361,8 +354,8 @@
### DBus Interface
-Virtual Media will expose the following object structure. All object paths
-are representation of configuration file described above
+Virtual Media will expose the following object structure. All object paths are
+representation of configuration file described above
```ascii
/xyz/openbmc_project/VirtualMedia/Proxy/ISO0
@@ -371,7 +364,7 @@
/xyz/openbmc_project/VirtualMedia/Legacy/1
```
-Each of object will implement ``xyz.openbmc_project.VirtualMedia.Process``
+Each of object will implement `xyz.openbmc_project.VirtualMedia.Process`
interface, which will be defined as follow:
| Name | type | input | return | description |
@@ -380,7 +373,7 @@
| ExitCode | Property | - | INT32 | If process terminates this property will contain returned exit code |
Each object will also expose configuration of its own under
-``xyz.openbmc_project.VirtualMedia.MountPoint`` (all properties are RO)
+`xyz.openbmc_project.VirtualMedia.MountPoint` (all properties are RO)
| Name | type | input | return | description |
| -------------------------- | -------- | ----- | ------- | ------------------------------------------------------------------------- |
@@ -395,46 +388,49 @@
| WriteProtected | Property | - | BOOLEAN | 'True', if the image is mounted as read only, 'False' otherwise |
Another interface exposed by each object are stats under
-```xyz.openbmc_project.VirtualMedia.Stats``` (all properties are RO):
+`xyz.openbmc_project.VirtualMedia.Stats` (all properties are RO):
| Name | type | input | return | description |
| ------- | -------- | ----- | ------ | ---------------------------------------- |
| ReadIO | Property | - | UINT64 | Number of read IOs since image mounting |
| WriteIO | Property | - | UINT64 | Number of write IOs since image mounting |
-Depends on object path, object will expose different interface for mounting image.
+Depends on object path, object will expose different interface for mounting
+image.
Mounting can be a time consuming task, so event driven mechanism has to be
introduced. Mount and Unmount calls will trigger asynchronous action and will
-end immediately, giving appropriate signal containing status on task
-completion.
+end immediately, giving appropriate signal containing status on task completion.
-For Proxy its ```xyz.openbmc_project.VirtualMedia.Proxy```, defined as follow:
+For Proxy its `xyz.openbmc_project.VirtualMedia.Proxy`, defined as follow:
| Name | type | input | return | description |
-|------------|--------|-------|---------|--------------------------------------------------------------------------------|
+| ---------- | ------ | ----- | ------- | ------------------------------------------------------------------------------ |
| Mount | Method | - | BOOLEAN | Perform an asynchronous operation of mounting to HOST on given object. |
| Unmount | Method | - | BOOLEAN | Perform an asynchronous operation of unmount from HOST on given object |
| Completion | Signal | - | INT32 | Returns 0 for success or errno on failure after background operation completes |
-For Legacy its ```xyz.openbmc_project.VirtualMedia.Legacy```, defined as follow:
+For Legacy its `xyz.openbmc_project.VirtualMedia.Legacy`, defined as follow:
-| Name | type | input | return | description |
-| ---------- | ------ | ------ | ------- | ------------------------------------------------------------------------------------------ |
-| Mount | Method | STRING | BOOLEAN | Perform an asynchronous operation of mounting to HOST on given object, with location given as STRING parameter |
+| Name | type | input | return | description |
+| ---------- | ------ | ----------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Mount | Method | STRING | BOOLEAN | Perform an asynchronous operation of mounting to HOST on given object, with location given as STRING parameter |
| Mount | Method | STRING<br>BOOLEAN<br>VARIANT<UNIX_FD,INT> | BOOLEAN | Perform an asynchronous operation of mounting to HOST on given object, with parameters:<br><br>`STRING` : url to image. It should start with either `smb://` or `https://` prefix<br>`BOOLEAN` : RW flag for mounted gadget (should be consistent with remote image capabilities)<br>`VARIANT<UNIX_FD,INT>` : file descriptor of named pipe used for passing null-delimited secret data (username and password). When there is no data to pass `-1` should be passed as `INT` |
-| Unmount | Method | - | BOOLEAN | Perform an asynchronous operation of unmounting from HOST on given object |
-| Completion | Signal | - | INT32 | Returns 0 for success or errno on failure after background operation completes |
+| Unmount | Method | - | BOOLEAN | Perform an asynchronous operation of unmounting from HOST on given object |
+| Completion | Signal | - | INT32 | Returns 0 for success or errno on failure after background operation completes |
-Mount and unmount operation return true if async operation is started and
-false when preliminary check encountered an error. They may also indicate
-appropriate dbus error.
+Mount and unmount operation return true if async operation is started and false
+when preliminary check encountered an error. They may also indicate appropriate
+dbus error.
## Alternatives Considered
+
Existing implementation in OpenBMC
## Impact
+
Shall not affect usability of current Virtual Media implementation
## Testing
+
TBD
diff --git a/designs/virtual-sensors.md b/designs/virtual-sensors.md
index ef1684f..bda4f8c 100644
--- a/designs/virtual-sensors.md
+++ b/designs/virtual-sensors.md
@@ -1,50 +1,51 @@
### Virtual sensors
-Author:
- Vijay Khemka <vijaykhemka@fb.com>; <vijay!>
+Author: Vijay Khemka <vijaykhemka@fb.com>; <vijay!>
-Created:
- 2020-05-13
+Created: 2020-05-13
## Problem Description
-There are some sensors in the system whose values are derived from actual
-sensor data and some other factor like fan speed for temperature
-sensors, some complex and non standard scale factors or some other algorithmic
-calculations. Some of Virtual sensor examples are:
+
+There are some sensors in the system whose values are derived from actual sensor
+data and some other factor like fan speed for temperature sensors, some complex
+and non standard scale factors or some other algorithmic calculations. Some of
+Virtual sensor examples are:
1. Airflow: Function of Fan RPM reported in units of cubic-feet per second.
2. Voltage delta between two ADC inputs. When the actual diff is what which
should not cross a threshold.
3. Power consumption when we have Energy/time.
-This design will allow to generate a new virtual sensors which are defined to
-be specific manipulation/function of existing sensors.
+This design will allow to generate a new virtual sensors which are defined to be
+specific manipulation/function of existing sensors.
## Background and References
+
None.
## Requirements
+
This should implement a new virtual sensor for every given sensor and update
-them as per changes in existing sensors.
-This implementation should provide
-- a daemon to create and monitor each sensor defined in config file and
- update them based on value change in each given sensor.
+them as per changes in existing sensors. This implementation should provide
+
+- a daemon to create and monitor each sensor defined in config file and update
+ them based on value change in each given sensor.
- Every virtual sensor will be waiting for event for change in dbus value of
each sensor parameter and will update this sensor.
-- Sensor parameter can be any sensor dbus path and it also supports
- chaining of virtual sensors.
-- a dbus interface like other sensors to allow other services to access its
- data
+- Sensor parameter can be any sensor dbus path and it also supports chaining of
+ virtual sensors.
+- a dbus interface like other sensors to allow other services to access its data
- capability to read parameter details from config file
- capability to read a algorithm string from config file and use the same
algorithm in calculating value for new virtual sensor
## Proposed Design
-Create a D-bus service "xyz.openbmc_project.VirtualSensor" with object paths
-for each sensor: "/xyz/openbmc_project/sensor/temperature/sensor_name"
-There is a JSON configuration file for name, old path and algorithm.
-For example,
+Create a D-bus service "xyz.openbmc_project.VirtualSensor" with object paths for
+each sensor: "/xyz/openbmc_project/sensor/temperature/sensor_name"
+
+There is a JSON configuration file for name, old path and algorithm. For
+example,
```json
{
@@ -109,14 +110,17 @@
phosphor-dbus-interfaces.
```
+
## Alternatives Considered
+
None
## Impacts
-This application is monitoring existing sensors whenever they change values
-then only it will update this sensors so impact should be very minimal.
+
+This application is monitoring existing sensors whenever they change values then
+only it will update this sensors so impact should be very minimal.
## Testing
-Testing can be done by monitoring data read from dbus interface over a period
-of time and also can see these data if it changes by comparing with given
-sensors.
+
+Testing can be done by monitoring data read from dbus interface over a period of
+time and also can see these data if it changes by comparing with given sensors.
diff --git a/designs/voltage-regulator-configuration.md b/designs/voltage-regulator-configuration.md
index 394e88d..96d57f6 100644
--- a/designs/voltage-regulator-configuration.md
+++ b/designs/voltage-regulator-configuration.md
@@ -2,242 +2,259 @@
Author: Shawn McCarney (Discord ShawnMcCarney)
-Other contributors: Derek Howard (Discord derekh55), Matt Spinler (Discord mspinler)
+Other contributors: Derek Howard (Discord derekh55), Matt Spinler (Discord
+mspinler)
Created: 2019-07-13
-
## Problem Description
-[Voltage regulators][1] have many configurable properties such as output
-voltage, over-current limit, and pgood thresholds. The configuration is often
-dependent on the system type and rail type. Regulators have a hardware default
-configuration that is defined by hardware engineers early in system design.
-However, this default configuration sometimes must be modified by firmware. A
-new application is needed to configure regulators. It should be data-driven to
-support a variety of regulator types and to avoid hard-coded logic.
+[Voltage regulators][1] have many configurable properties such as output
+voltage, over-current limit, and pgood thresholds. The configuration is often
+dependent on the system type and rail type. Regulators have a hardware default
+configuration that is defined by hardware engineers early in system design.
+However, this default configuration sometimes must be modified by firmware. A
+new application is needed to configure regulators. It should be data-driven to
+support a variety of regulator types and to avoid hard-coded logic.
## Background and References
### Regulator Configuration Data ("Config File")
+
Hardware engineers must specify many low-level configuration values for a
-regulator. Some simple examples include output voltage, over-current limit,
-and pgood thresholds. These values often vary depending on the system type and
-rail type.
+regulator. Some simple examples include output voltage, over-current limit, and
+pgood thresholds. These values often vary depending on the system type and rail
+type.
Depending on the regulator type, the hardware engineer may enter the
configuration values into a tool that produces a "config file".
The regulator configuration information is sent to manufacturing and stored in
-non-volatile memory on the regulator. This provides the hardware/power-on
+non-volatile memory on the regulator. This provides the hardware/power-on
default configuration.
-The default configuration values often need to be changed later. This can be
-due to factors such as the following:
-* New information found during hardware testing. For example, downstream
+The default configuration values often need to be changed later. This can be due
+to factors such as the following:
+
+- New information found during hardware testing. For example, downstream
hardware requires a higher voltage or is drawing more current than expected.
-* Hardware workarounds. Problems in the regulator hardware or related hardware
- sometimes require new configuration values to work around the issue. The
+- Hardware workarounds. Problems in the regulator hardware or related hardware
+ sometimes require new configuration values to work around the issue. The
problem may be resolved in newer versions of the hardware, but firmware still
- must support the older hardware. For this reason, hardware workarounds are
+ must support the older hardware. For this reason, hardware workarounds are
sometimes conditional, applied only to regulators with a certain version
register value or [Vital Product Data (VPD)][2] keyword value.
-* Improve manufacturing yields. Sometimes regulator configuration values must
- be changed to allow more hardware to pass manufacturing tests. For example,
- the voltage may need to be increased to overcome minor manufacturing defects.
+- Improve manufacturing yields. Sometimes regulator configuration values must be
+ changed to allow more hardware to pass manufacturing tests. For example, the
+ voltage may need to be increased to overcome minor manufacturing defects.
### OpenBMC Regulator Configuration Scripts
+
Regulator configuration changes are performed on some OpenBMC systems using
-shell scripts. For example, the following scripts configure regulators on
+shell scripts. For example, the following scripts configure regulators on
Witherspoon systems:
-* [vrm-control.sh][3]
-* [power-workarounds.sh][4]
+
+- [vrm-control.sh][3]
+- [power-workarounds.sh][4]
### Hwmon and IIO Device Driver Frameworks
+
The Linux [Hardware Monitoring Kernel API (hwmon)][5] and [Industrial I/O
-Subsystem (IIO)][6] provide device driver frameworks for monitoring hardware
-and making sensor values available to applications. They do not provide an
-interface for performing low-level regulator configuration.
+Subsystem (IIO)][6] provide device driver frameworks for monitoring hardware and
+making sensor values available to applications. They do not provide an interface
+for performing low-level regulator configuration.
### Voltage and Current Regulator Device Framework
+
The Linux [Voltage and Current Regulator API][7] provides a device driver
-framework for voltage and current regulators. It provides a mechanism for the
+framework for voltage and current regulators. It provides a mechanism for the
device drivers of "consumer" devices to request a voltage or current level from
-the regulator. It does not provide an interface for performing low-level
+the regulator. It does not provide an interface for performing low-level
regulator configuration.
-
## Requirements
-* Provide ability to modify configuration of any voltage regulator with a PMBus
+
+- Provide ability to modify configuration of any voltage regulator with a PMBus
or I2C connection to the BMC.
-* Apply the configuration changes early in the boot before the regulators are
+- Apply the configuration changes early in the boot before the regulators are
enabled.
-* If an error occurs trying to configure a regulator, log the error and
- continue with the next regulator.
-* Read configuration changes from a data file that is read at run-time.
-* Provide a method for testing new configuration changes by copying a new data
+- If an error occurs trying to configure a regulator, log the error and continue
+ with the next regulator.
+- Read configuration changes from a data file that is read at run-time.
+- Provide a method for testing new configuration changes by copying a new data
file to the BMC.
### Non-Requirements
-* Enable/disable voltage regulators and monitor their pgood signals.
- * This is handled by the power sequencer chip and related firmware.
-* Modify regulator configuration after regulator has been enabled.
- * Modifying regulator configuration while the system is running
- is often done by the host using a different bus connection.
-* Validate that the correct number and types of regulators are present in the
- system.
-* Concurrent maintenance or hot-plugging of regulators, where a regulator is
- removed/added/replaced while the system is running.
+- Enable/disable voltage regulators and monitor their pgood signals.
+ - This is handled by the power sequencer chip and related firmware.
+- Modify regulator configuration after regulator has been enabled.
+ - Modifying regulator configuration while the system is running is often done
+ by the host using a different bus connection.
+- Validate that the correct number and types of regulators are present in the
+ system.
+- Concurrent maintenance or hot-plugging of regulators, where a regulator is
+ removed/added/replaced while the system is running.
## Proposed Design
### Application
+
A new application named `phosphor-regulators` will be created to configure
-voltage regulators. The application will be located in the proposed new
+voltage regulators. The application will be located in the proposed new
`phosphor-power` repository.
-*Statement of direction: This application will provide other regulator-based
-functionality in the future, such as detecting redundant phase faults.*
+_Statement of direction: This application will provide other regulator-based
+functionality in the future, such as detecting redundant phase faults._
### Application Data File
+
The application will read a JSON file at runtime that defines the configuration
-changes for all regulators. The JSON file will be specific to a system type,
-so it will be stored in the GitHub repository for the appropriate build layer
-(such as meta-ibm).
+changes for all regulators. The JSON file will be specific to a system type, so
+it will be stored in the GitHub repository for the appropriate build layer (such
+as meta-ibm).
JSON file location on the BMC:
-* Standard directory: `/usr/share/phosphor-regulators` (read-only)
-* Test directory: `/etc/phosphor-regulators` (writable)
+
+- Standard directory: `/usr/share/phosphor-regulators` (read-only)
+- Test directory: `/etc/phosphor-regulators` (writable)
A new version of the JSON file can be tested by copying it to the test
-directory. The application will search both directories, and the file in the
-test directory will override the file in the standard directory. If the
+directory. The application will search both directories, and the file in the
+test directory will override the file in the standard directory. If the
application receives a SIGHUP signal, it will re-read the JSON file.
A document will be provided that describes the objects and properties that can
-appear in the JSON file. A validation tool will also be provided to verify the
+appear in the JSON file. A validation tool will also be provided to verify the
syntax and contents of the JSON file.
-*Statement of direction: This JSON file will be used in the future to define
-other regulator operations, such as how to detect a redundant phase fault.*
+_Statement of direction: This JSON file will be used in the future to define
+other regulator operations, such as how to detect a redundant phase fault._
### D-Bus Interfaces
-The following new D-Bus interface will be created:
-* Name: `xyz.openbmc_project.Regulator.Collection.Configure`
-* Description: Configures all voltage regulators.
-* Properties: None
-* Methods: Configure()
-*Statement of direction: New interfaces that apply to all regulators would use
-the same xyz.openbmc_project.Regulator.Collection namespace. New interfaces
-that apply to a single regulator would use the xyz.openbmc_project.Regulator
-namespace.*
+The following new D-Bus interface will be created:
+
+- Name: `xyz.openbmc_project.Regulator.Collection.Configure`
+- Description: Configures all voltage regulators.
+- Properties: None
+- Methods: Configure()
+
+_Statement of direction: New interfaces that apply to all regulators would use
+the same xyz.openbmc_project.Regulator.Collection namespace. New interfaces that
+apply to a single regulator would use the xyz.openbmc_project.Regulator
+namespace._
### D-Bus Paths
+
The new `xyz.openbmc_project.Regulator.Collection.Configure` interface will be
implemented on the object path `/xyz/openbmc_project/regulators`.
-*Statement of direction: New interfaces that apply to all regulators would be
-implemented on the same object path. Individual regulators would be
-represented by the object path
-`/xyz/openbmc_project/regulators/<regulator_name>`, and interfaces that apply
-to a single regulator would be implemented on that path.*
+_Statement of direction: New interfaces that apply to all regulators would be
+implemented on the same object path. Individual regulators would be represented
+by the object path `/xyz/openbmc_project/regulators/<regulator_name>`, and
+interfaces that apply to a single regulator would be implemented on that path._
### Systemd
-The application will be started using systemd when the BMC is at standby. The
+
+The application will be started using systemd when the BMC is at standby. The
service file will be named `xyz.openbmc_project.Regulators.service`.
During the boot when the chassis is being powered on, the Configure() method on
the new `xyz.openbmc_project.Regulator.Collection.Configure` interface will be
-called. This must be done prior to the systemd target that enables the
+called. This must be done prior to the systemd target that enables the
regulators (powers them on).
### Regulator Device Interface
+
The application will communicate with the voltage regulators directly using the
-[i2c-dev][8] userspace I2C interface. Direct communication will be used rather
+[i2c-dev][8] userspace I2C interface. Direct communication will be used rather
than device drivers because the current Linux device driver frameworks do not
-provide the necessary functionality. See the [Alternatives
-Considered](#alternatives-considered) section for more information.
+provide the necessary functionality. See the
+[Alternatives Considered](#alternatives-considered) section for more
+information.
Voltage regulators that are configured using this application will not be bound
-to device drivers in the Linux device tree. When the system is powered on, the
+to device drivers in the Linux device tree. When the system is powered on, the
application will obtain the regulator sensor values and store them on D-Bus in
the same format as `phosphor-hwmon`.
-*Statement of direction: If a driver framework is developed in the future that
+_Statement of direction: If a driver framework is developed in the future that
supports low-level regulator configuration, then this application will be
-enhanced to utilize those drivers. The goal is for the application to support
-a flexible device interface, where drivers are used if possible and i2c-dev is
-used if necessary.*
-
+enhanced to utilize those drivers. The goal is for the application to support a
+flexible device interface, where drivers are used if possible and i2c-dev is
+used if necessary._
## Alternatives Considered
### Using Standard Linux Device Drivers to Configure Regulators
+
Ideally one of the following device driver frameworks could be used rather than
i2c-dev to configure the regulators:
-* [Hardware Monitoring Kernel API][5]
-* [Industrial I/O Subsystem][6]
-* [Voltage and Current Regulator API][7]
+
+- [Hardware Monitoring Kernel API][5]
+- [Industrial I/O Subsystem][6]
+- [Voltage and Current Regulator API][7]
Unfortunately none of these provide the required functionality:
-* Ability to perform system-specific and rail-specific, low-level
- configuration.
-* Ability to perform dynamic configuration based on regulator version register
+
+- Ability to perform system-specific and rail-specific, low-level configuration.
+- Ability to perform dynamic configuration based on regulator version register
values or [VPD][2] values.
-* Ability to test new configuration values iteratively and quickly without
+- Ability to test new configuration values iteratively and quickly without
needing to modify a device driver or rebuild the kernel.
A meeting was held with Joel Stanley and Andrew Jeffery to discuss this issue.
They believe long term a new driver framework could be designed that would
provide this functionality and would be acceptable to the Linux upstream
-community. If this occurs, this application will be modified to utilize the
-new driver framework rather than performing direct I2C communication from
-userspace.
+community. If this occurs, this application will be modified to utilize the new
+driver framework rather than performing direct I2C communication from userspace.
### Using Shell Scripts to Configure Regulators
+
Currently shell scripts are used to configure regulators on some OpenBMC
-systems, such as Witherspoon. During boot, the shell scripts unbind device
+systems, such as Witherspoon. During boot, the shell scripts unbind device
drivers, perform `i2cset` commands to configure regulators, and then re-bind
device drivers.
Using shell scripts has the following disadvantages:
-* Typically no error checking is performed to verify the `i2cset` command
- worked. If error checking were added based on return code, it would be
- difficult to log an appropriate error with all the necessary information.
-* On a large system with many regulators and register updates, a shell
- script would run more slowly than an application and negatively impact boot
- speed. Each `i2cset` command requires starting a separate child process.
-* Scripts are usually hard-coded to one system type and do not provide a
- common, data-driven solution.
+- Typically no error checking is performed to verify the `i2cset` command
+ worked. If error checking were added based on return code, it would be
+ difficult to log an appropriate error with all the necessary information.
+- On a large system with many regulators and register updates, a shell script
+ would run more slowly than an application and negatively impact boot speed.
+ Each `i2cset` command requires starting a separate child process.
+- Scripts are usually hard-coded to one system type and do not provide a common,
+ data-driven solution.
## Impacts
-* No major impacts are expected to existing APIs, security, documentation,
+
+- No major impacts are expected to existing APIs, security, documentation,
performance, or upgradability.
-* The new D-Bus interface is documented in the [Proposed
- Design](#proposed-design) section.
-* The application should be able to configure regulators using
- i2c-dev as fast or faster than equivalent shell scripts using `i2cset`.
-* The regulator sensor values will be stored on D-Bus in a way that is
+- The new D-Bus interface is documented in the
+ [Proposed Design](#proposed-design) section.
+- The application should be able to configure regulators using i2c-dev as fast
+ or faster than equivalent shell scripts using `i2cset`.
+- The regulator sensor values will be stored on D-Bus in a way that is
consistent with `phosphor-hwmon`.
-
## Testing
-* Automated test cases will be written to test as much of the application code
- as possible.
-* A mock device interface will be used to test that the correct I2C reads and
- writes are occurring without accessing real hardware.
-* End-to-end boot testing will be performed to ensure that the correct I2C
- reads/writes occurred, that the system boots, and that no errors occur.
-* CI tests that boot a system will indirectly test this application.
+- Automated test cases will be written to test as much of the application code
+ as possible.
+- A mock device interface will be used to test that the correct I2C reads and
+ writes are occurring without accessing real hardware.
+- End-to-end boot testing will be performed to ensure that the correct I2C
+ reads/writes occurred, that the system boots, and that no errors occur.
+- CI tests that boot a system will indirectly test this application.
[1]: https://en.wikipedia.org/wiki/Voltage_regulator_module
[2]: https://en.wikipedia.org/wiki/Vital_Product_Data
-[3]: https://github.com/openbmc/meta-ibm/blob/master/meta-witherspoon/recipes-phosphor/chassis/vrm-control/vrm-control.sh
-[4]: https://github.com/openbmc/meta-ibm/blob/master/meta-witherspoon/recipes-phosphor/chassis/power-workarounds/witherspoon/power-workarounds.sh
+[3]:
+ https://github.com/openbmc/meta-ibm/blob/master/meta-witherspoon/recipes-phosphor/chassis/vrm-control/vrm-control.sh
+[4]:
+ https://github.com/openbmc/meta-ibm/blob/master/meta-witherspoon/recipes-phosphor/chassis/power-workarounds/witherspoon/power-workarounds.sh
[5]: https://www.kernel.org/doc/html/latest/hwmon/hwmon-kernel-api.html
[6]: https://www.kernel.org/doc/html/latest/driver-api/iio/index.html
[7]: https://www.kernel.org/doc/html/latest/driver-api/regulator.html
diff --git a/designs/vpd-collection.md b/designs/vpd-collection.md
index 6850fec..1e52b63 100644
--- a/designs/vpd-collection.md
+++ b/designs/vpd-collection.md
@@ -5,12 +5,13 @@
Created: 2019-06-11
## Problem Description
+
On OpenBMC, Vital Product Data (VPD) collection is limited to only one or two
-Field Replaceable Units (FRUs) today - one example is the BMC FRU.
-On OpenPower systems, the BMC also supports just one VPD format, the
-[OpenPower VPD] [1] format. As a part of its enterprise class servers, IBM will
-use the IPZ format VPD, which the BMC currently does not support.
-Certain FRUs also have keyword format VPD.
+Field Replaceable Units (FRUs) today - one example is the BMC FRU. On OpenPower
+systems, the BMC also supports just one VPD format, the [OpenPower VPD] [1]
+format. As a part of its enterprise class servers, IBM will use the IPZ format
+VPD, which the BMC currently does not support. Certain FRUs also have keyword
+format VPD.
The BMC requires to read VPD for all FRUs for several reasons:
@@ -19,21 +20,22 @@
- Several use cases on the BMC require that the applications decide on a certain
code path based on what level of FRU is plugged in. For example, the
- application that controls voltage regulators might need to set
- different registers based on the version of the voltage regulator FRU.
+ application that controls voltage regulators might need to set different
+ registers based on the version of the voltage regulator FRU.
- There are use cases for the BMC to send VPD data to the host
hypervisor/operating system (over PLDM). This is mainly so that the host can
get VPD that is not directly accessible to it.
-The VPD data itself may reside on an EEPROM (typical) or may be
-synthesized out of certain parameters of the FRU (atypical - for FRUs that do
-not have an EEPROM).
+The VPD data itself may reside on an EEPROM (typical) or may be synthesized out
+of certain parameters of the FRU (atypical - for FRUs that do not have an
+EEPROM).
This design document aims to define a high level design for VPD collection and
-VPD access on OpenBMC. It does *not* cover low level API details.
+VPD access on OpenBMC. It does _not_ cover low level API details.
## Background and References
+
Essentially, the IPZ VPD structure consists of key-value pairs called keywords.
Each keyword can be used to contain specific data about the FRU. For example,
the SN keyword will contain a serial number that can uniquely identify an
@@ -59,6 +61,7 @@
format VPD is simply a CRC.
## Requirements
+
The following are requirements for the VPD function on OpenBMC:
- The BMC must collect VPD for all FRUs that it has direct access to by the time
@@ -70,8 +73,8 @@
Some of the VPD will need to be exchanged with the host.
- Manufacturing and Service engineers need the ability to view and program
- the FRU VPD without powering the system ON.
+ Manufacturing and Service engineers need the ability to view and program the
+ FRU VPD without powering the system ON.
Certain system level VPD is also used by applications on the BMC to determine
the system type, model on which it is running.
@@ -104,6 +107,7 @@
collects VPD for)
## Proposed Design
+
This document covers the architectural, interface, and design details. It
provides recommendations for implementations, but implementation details are
outside the scope of this document.
@@ -111,8 +115,8 @@
The proposal here is to build upon the existing VPD collection design used by
open power. The current implementation consists of the following entities:
-- [op-vpd-parser] [2] service, which parses the contents of an EEPROM
- containing VPD in the OpenPower VPD format.
+- [op-vpd-parser] [2] service, which parses the contents of an EEPROM containing
+ VPD in the OpenPower VPD format.
- A udev [rule] [3] that is used by systemd to launch the above service as
EEPROM devices are connected.
@@ -137,22 +141,22 @@
would have to filter out non-VPD EEPROMs somehow.
- Each udev rule will be setup to launch an instance of one of the VPD parser
- services (The format of the VPD in any given EEPROM are known at build time
- as they are system specific)
+ services (The format of the VPD in any given EEPROM are known at build time as
+ they are system specific)
- The service (one instance of ipz-vpd-parser or keyword-vpd-parser), when
- launched, will read the EEPROM, parse its contents and use config files
- to determine what VPD contents to store in the inventory.
+ launched, will read the EEPROM, parse its contents and use config files to
+ determine what VPD contents to store in the inventory.
- The service will update the inventory D-Bus object with the contents of the
- VPD in the following format: There will be one interface per
- record (ex, VINI record) which will have each keyword as a property
- (ex, FN, PN). This will allow us to support multiple records that can have the
- same keyword and will also serve as means to logically group keywords in the
- inventory, quite similar to how they are grouped in the actual VPD.
- For example (some names here are made up, but they help illustrate the point),
- for the VINI record containing keywords SN, FN and CCIN, the representation in
- D-Bus would look like:
+ VPD in the following format: There will be one interface per record (ex, VINI
+ record) which will have each keyword as a property (ex, FN, PN). This will
+ allow us to support multiple records that can have the same keyword and will
+ also serve as means to logically group keywords in the inventory, quite
+ similar to how they are grouped in the actual VPD. For example (some names
+ here are made up, but they help illustrate the point), for the VINI record
+ containing keywords SN, FN and CCIN, the representation in D-Bus would look
+ like:
```
Interface: com.ibm.ipzvpd.VINI
@@ -176,19 +180,23 @@
manage parallel writes to EEPROMs. The VPD writer service will expose D-bus
interfaces to update VPD for a FRU given its inventory path.
-- Generation of the udev rules and configs shall be layered such that
- they can be tweaked on a per-system basis.
+- Generation of the udev rules and configs shall be layered such that they can
+ be tweaked on a per-system basis.
### Open topics
+
Some open questions:
- Some more thought is needed on how concurrent maintenance (replacing a FRU
- when the host is up and running) will be handled. That will be presented in
+ when the host is up and running) will be handled. That will be presented in
its own design document.
## Alternatives Considered
+
The following alternative designs were considered:
+
### Write a standalone VPD server app
+
One option considered was to develop a standalone, do-it-all VPD application on
the BMC that collects all of the VPD by BMC standby. The application has to be a
daemon that will expose a set of D-bus interfaces to:
@@ -213,11 +221,13 @@
option allows us to do.
### 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:
+
- Add support for other VPD formats such as the IPZ and keyword format.
- Perhaps update a different set of data into a different DBUS object, like the
Inventory manager.
@@ -236,7 +246,9 @@
entire /dev/ tree to pick out EEPROMs.
## Impacts
+
The following impacts have been identified:
+
- The services to parse VPD and store it in the inventory will add some time to
the BMC boot flow. The impact should be kept to a minimum by achieving maximum
possible parallelism in the launching of these services.
@@ -245,17 +257,21 @@
interested in.
## Testing
+
VPD parsing function can be tested by faking out the VPD EEPROMs as files on the
filesystem. Such testing can also ensure that the right set of VPD data makes
its way into the OpenBMC Inventory. There is also a proposal to build in a file
mode into the application. The file mode will not need real hardware to test the
code functions, but can use files on the BMC to mimic the EEPROMs.
-VPD writes can be tested by writing a small command line utility
-that can invoke the VPD write application's APIs to write VPD.
+VPD writes can be tested by writing a small command line utility that can invoke
+the VPD write application's APIs to write VPD.
-[1]:https://www-355.ibm.com/systems/power/openpower/posting.xhtml?postingId=1D060729AC96891885257E1B0053BC95
-[2]:https://github.com/openbmc/meta-openpower/blob/master/recipes-phosphor/vpd/openpower-fru-vpd/op-vpd-parser.service
-[3]:https://github.com/openbmc/meta-openpower/blob/master/recipes-phosphor/vpd/openpower-fru-vpd/70-op-vpd.rules
-[4]:https://github.com/openbmc/meta-openpower/blob/master/recipes-phosphor/vpd/openpower-fru-vpd-layout/layout.yaml
-
+[1]:
+ https://www-355.ibm.com/systems/power/openpower/posting.xhtml?postingId=1D060729AC96891885257E1B0053BC95
+[2]:
+ https://github.com/openbmc/meta-openpower/blob/master/recipes-phosphor/vpd/openpower-fru-vpd/op-vpd-parser.service
+[3]:
+ https://github.com/openbmc/meta-openpower/blob/master/recipes-phosphor/vpd/openpower-fru-vpd/70-op-vpd.rules
+[4]:
+ https://github.com/openbmc/meta-openpower/blob/master/recipes-phosphor/vpd/openpower-fru-vpd-layout/layout.yaml
diff --git a/development/README.md b/development/README.md
index 7435a4c..2280802 100644
--- a/development/README.md
+++ b/development/README.md
@@ -1,4 +1,5 @@
# OpenBMC Developer Documentation
+
This directory is focused on providing OpenBMC developers with the instructions
they need to get up and going with OpenBMC development. This can be reviewed in
any order you like, but the recommended flow can be found below.
diff --git a/development/add-new-system.md b/development/add-new-system.md
index 0406e54..9fe2abc 100644
--- a/development/add-new-system.md
+++ b/development/add-new-system.md
@@ -11,37 +11,37 @@
**Please note:** This document is no longer officially supported by the OpenBMC
team. It still contains a lot of useful information so it has been left here.
Ideally this guide would become a standalone document (outside of the
-development tree) and would cover all of the different areas that must
-be updated to add a new system.
+development tree) and would cover all of the different areas that must be
+updated to add a new system.
This document will describe the following:
-* Review background about Yocto and BitBake
-* Creating a new system layer
-* Populating this new layer
-* Building the new system and testing in QEMU
-* Adding configs for sensors, LEDs, inventories, etc.
+- Review background about Yocto and BitBake
+- Creating a new system layer
+- Populating this new layer
+- Building the new system and testing in QEMU
+- Adding configs for sensors, LEDs, inventories, etc.
## Background
The OpenBMC distribution is based on [Yocto](https://www.yoctoproject.org/).
Yocto is a project that allows developers to create custom Linux distributions.
-OpenBMC uses Yocto to create their embedded Linux distribution to run on
-a variety of devices.
+OpenBMC uses Yocto to create their embedded Linux distribution to run on a
+variety of devices.
Yocto has a concept of hierarchical layers. When you build a Yocto-based
distribution, you define a set of layers for that distribution. OpenBMC uses
many common layers from Yocto as well as some of its own layers. The layers
-defined within OpenBMC can be found with the meta-* directories in OpenBMC
+defined within OpenBMC can be found with the meta-\* directories in OpenBMC
[GitHub](https://github.com/openbmc/openbmc).
Yocto layers are a combination of different files that define packages to
incorporate in that layer. One of the key file types used in these layers is
[BitBake](https://github.com/openembedded/bitbake/blob/master/README) recipes.
-BitBake is a fully functional language in itself. For this lesson, we will
-focus on only the aspects of BitBake required to understand the process of
-adding a new system.
+BitBake is a fully functional language in itself. For this lesson, we will focus
+on only the aspects of BitBake required to understand the process of adding a
+new system.
## Start the Initial BitBake
@@ -53,7 +53,8 @@
So before we do anything else, let's get that first build going.
-Follow the direction on the OpenBMC GitHub [page](https://github.com/openbmc/openbmc/blob/master/README.md#2-download-the-source)
+Follow the direction on the OpenBMC GitHub
+[page](https://github.com/openbmc/openbmc/blob/master/README.md#2-download-the-source)
for the Romulus system (steps 2-4).
## Create a New System
@@ -63,8 +64,8 @@
system will be called romulus-prime.
From your openbmc repository you cloned above, the Romulus layer is defined
-within `meta-ibm/meta-romulus/`. The Romulus layer is defined within the
-`conf` subdirectory. Under `conf` you will see a layout like this:
+within `meta-ibm/meta-romulus/`. The Romulus layer is defined within the `conf`
+subdirectory. Under `conf` you will see a layout like this:
```
meta-ibm/meta-romulus/conf/
@@ -76,8 +77,9 @@
└── romulus.conf
```
-To create our new romulus-prime system we are going to start out by copying
-our romulus layer.
+To create our new romulus-prime system we are going to start out by copying our
+romulus layer.
+
```
cp -R meta-ibm/meta-romulus meta-ibm/meta-romulus-prime
```
@@ -106,9 +108,9 @@
The main purpose of this file is to tell BitBake where to look for recipes
(\*.bb files). Recipe files end with a `.bb` extension and are what contain
all of the packaging logic for the different layers. `.bbappend` files are
- also recipe files but provide a way to append onto `.bb` files.
- `.bbappend` files are commonly used to add or remove something from a
- corresponding `.bb` file in a different layer.
+ also recipe files but provide a way to append onto `.bb` files. `.bbappend`
+ files are commonly used to add or remove something from a corresponding `.bb`
+ file in a different layer.
The only change you need in here is to find/replace the "romulus-layer" to
"romulus-prime-layer"
@@ -125,18 +127,18 @@
This file describes the specifics for your machine. You define the kernel
device tree to use, any overrides to specific features you will be pulling
- in, and other system specific pointers. This file is a good reference for
- the different things you need to change when creating a new system (kernel
- device tree, MRW, LED settings, inventory access, ...)
+ in, and other system specific pointers. This file is a good reference for the
+ different things you need to change when creating a new system (kernel device
+ tree, MRW, LED settings, inventory access, ...)
The first thing you need to do is rename the file to `romulus-prime.conf`.
- **Note** If our new system really was just a variant of Romulus,
- with the same hardware configuration, then we could have just created a
- new machine in the Romulus layer. Any customizations for that system
- could be included in the corresponding .conf file for that new machine. For
- the purposes of this exercise we are assuming our romulus-prime system has
- at least a few hardware changes requiring us to create this new layer.
+ **Note** If our new system really was just a variant of Romulus, with the
+ same hardware configuration, then we could have just created a new machine in
+ the Romulus layer. Any customizations for that system could be included in
+ the corresponding .conf file for that new machine. For the purposes of this
+ exercise we are assuming our romulus-prime system has at least a few hardware
+ changes requiring us to create this new layer.
## Build New System
@@ -151,6 +153,7 @@
Within the shell you did the initial "bitbake" operation you need to reset
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:
+
```
cd ..
rm -r ./build/conf
@@ -165,7 +168,8 @@
against your new system.
The openbmc/skeleton repository was used for initial prototyping of OpenBMC.
- Within this repository is a [configs](https://github.com/openbmc/skeleton/tree/master/configs) directory.
+ Within this repository is a
+ [configs](https://github.com/openbmc/skeleton/tree/master/configs) directory.
The majority of this config data is no longer used but until it is all
completely removed, you need to provide it.
@@ -174,6 +178,7 @@
workaround for this issue.
Create a config files as follows:
+
```
cp meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-config.bb meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb
@@ -209,6 +214,7 @@
additional kernel config parameters. For our purposes here, just modify
romulus-prime to use the romulus.cfg file. We just need to add the `-prime`
to the prepend path.
+
```
vi ./meta-ibm/meta-romulus-prime/recipes-kernel/linux/linux-aspeed_%.bbappend
@@ -221,11 +227,13 @@
4. No rule to make target arch/arm/boot/dts/aspeed-bmc-opp-romulus-prime.dtb
The .dtb file is a device tree blob file. It is generated during the Linux
- kernel build based on its corresponding .dts file. When you introduce a
- new OpenBMC system, you need to send these kernel updates upstream. The
- linked email [thread](https://lists.ozlabs.org/pipermail/openbmc/2018-September/013260.html)
+ kernel build based on its corresponding .dts file. When you introduce a new
+ OpenBMC system, you need to send these kernel updates upstream. The linked
+ email
+ [thread](https://lists.ozlabs.org/pipermail/openbmc/2018-September/013260.html)
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.
+
```
vi ./meta-ibm/meta-romulus-prime/conf/machine/romulus-prime.conf
# Replace the ${MACHINE} variable in the KERNEL_DEVICETREE
@@ -238,26 +246,29 @@
## Boot New System
-And you've finally built your new system's image! There are more
-customizations to be done but let's first verify what you have boots.
+And you've finally built your new system's image! There are more customizations
+to be done but let's first verify what you have boots.
Your new image will be in the following location from where you ran your
"bitbake" command:
+
```
./tmp/deploy/images/romulus-prime/obmc-phosphor-image-romulus-prime.static.mtd
```
-Copy this image to where you've set up your QEMU session and re-run the
-command to start QEMU (`qemu-system-arm` command from
-[dev-environment.md][32]), giving your new file as input.
+
+Copy this image to where you've set up your QEMU session and re-run the command
+to start QEMU (`qemu-system-arm` command from [dev-environment.md][32]), giving
+your new file as input.
Once booted, you should see the following for the login:
+
```
romulus-prime login:
```
There you go! You've done the basics of creating, booting, and building a new
-system. This is by no means a complete system but you now have the base for
-the customizations you'll need to do for your new system.
+system. This is by no means a complete system but you now have the base for the
+customizations you'll need to do for your new system.
## Further Customizations
@@ -265,41 +276,39 @@
### Kernel changes
-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:
+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:
1. Add the new machine device tree:
- * Describe the GPIOs, e.g. LED, FSI, gpio-keys, etc. You should get such
- info from schematic.
- * Describe the i2c buses and devices, which usually include various hwmon
+ - Describe the GPIOs, e.g. LED, FSI, gpio-keys, etc. You should get such info
+ from schematic.
+ - Describe the i2c buses and devices, which usually include various hwmon
sensors.
- * Describe the other devices, e.g. uarts, mac.
- * Usually the flash layout does not need to change. Just include
+ - Describe the other devices, e.g. uarts, mac.
+ - Usually the flash layout does not need to change. Just include
`openbmc-flash-layout.dtsi`.
2. Modify Makefile to build the device tree.
3. Reference to [openbmc kernel doc][31] on submitting patches to mailing list.
Note:
-* In `dev-4.10`, there is common and machine-specific initialization code in
- `arch/arm/mach-aspeed/aspeed.c` which is used to do common initializations
- and perform specific settings in each machine.
- Starting in branch `dev-4.13`, there is no such initialization code. Most of
- the inits are done with the upstream clock and reset driver.
-* If the machine needs specific settings (e.g. uart routing), please
- send mail to [the mailing list][2] for discussion.
+- In `dev-4.10`, there is common and machine-specific initialization code in
+ `arch/arm/mach-aspeed/aspeed.c` which is used to do common initializations and
+ perform specific settings in each machine. Starting in branch `dev-4.13`,
+ there is no such initialization code. Most of the inits are done with the
+ upstream clock and reset driver.
+- If the machine needs specific settings (e.g. uart routing), please send mail
+ to [the mailing list][2] for discussion.
### Workbook
In legacy OpenBMC, there is a "workbook" to describe the machine's services,
-sensors, FRUs, etc.
-This workbook is a python configuration file and it is used by other services
-in [skeleton][3].
-In the latest OpenBMC, the skeleton services are mostly replaced by
-phosphor-xxx services and thus skeleton is deprecated.
+sensors, FRUs, etc. This workbook is a python configuration file and it is used
+by other services in [skeleton][3]. In the latest OpenBMC, the skeleton services
+are mostly replaced by phosphor-xxx services and thus skeleton is deprecated.
But the workbook is still needed for now to make the build.
[meta-quanta][4] is an example that defines its own config in OpenBMC tree, so
@@ -326,12 +335,13 @@
},
}
```
+
The PowerUp and PowerOK GPIOs are needed for the build to power on the chassis
and check the power state.
-After that, the GPIO related configs are removed from the workbook, and
-replaced by `gpio_defs.json`, e.g. [2a80da2][27] introduces the GPIO json
-config for Romulus.
+After that, the GPIO related configs are removed from the workbook, and replaced
+by `gpio_defs.json`, e.g. [2a80da2][27] introduces the GPIO json config for
+Romulus.
```json
{
@@ -365,80 +375,77 @@
Each machine shall define the similar json config to describe the GPIO
configurations.
-
### Hwmon Sensors
-Hwmon sensors include sensors on board (e.g. temperature sensors, fans) and
-OCC sensors.
-The config files path and name shall match the devices in device tree.
+Hwmon sensors include sensors on board (e.g. temperature sensors, fans) and OCC
+sensors. The config files path and name shall match the devices in device tree.
There is detailed document in openbmc [doc/architecture/sensor-architecture][6].
-Here let's take Romulus as an example.
-The config files are in [meta-romulus/recipes-phosphor/sensors][7] which
-includes sensors on board and sensors of OCC, where on board sensors are via
-i2c and occ sensors are via FSI.
+Here let's take Romulus as an example. The config files are in
+[meta-romulus/recipes-phosphor/sensors][7] which includes sensors on board and
+sensors of OCC, where on board sensors are via i2c and occ sensors are via FSI.
-* [w83773g@4c.conf][8] defines the `w83773` temperature sensor containing 3
-temperatures:
- ```
- 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.
- ```
- /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 config is a bit different, that it shall tell `phosphor-hwmon` to read
- the 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.
- ```
- MODE_temp1 = "label"
- MODE_temp2 = "label"
- ...
- MODE_temp31 = "label"
- MODE_temp32 = "label"
- LABEL_temp91 = "p0_core0_temp"
- LABEL_temp92 = "p0_core1_temp"
- ...
- LABEL_temp33 = "dimm6_temp"
- 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.
-
+- [w83773g@4c.conf][8] defines the `w83773` temperature sensor containing 3
+ temperatures:
+ ```
+ 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.
+ ```
+ /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
+ config is a bit different, that it shall tell `phosphor-hwmon` to read the
+ 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.
+ ```
+ MODE_temp1 = "label"
+ MODE_temp2 = "label"
+ ...
+ MODE_temp31 = "label"
+ MODE_temp32 = "label"
+ LABEL_temp91 = "p0_core0_temp"
+ LABEL_temp92 = "p0_core1_temp"
+ ...
+ LABEL_temp33 = "dimm6_temp"
+ 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.
### LEDs
Several parts are involved for LED.
-1. In kernel dts, LEDs shall be described, e.g. [romulus dts][12] describes
- 3 LEDs, `fault`, `identify` and `power`.
+1. In kernel dts, LEDs shall be described, e.g. [romulus dts][12] describes 3
+ LEDs, `fault`, `identify` and `power`.
+
```
leds {
compatible = "gpio-leds";
@@ -456,6 +463,7 @@
};
};
```
+
2. In machine layer, LEDs shall be configured via yaml to describe how it
functions, e.g. [Romulus led yaml][28]:
```
@@ -478,42 +486,43 @@
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
- ```
+ - 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
+ ```
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
- generated;
- * De-assert the related fault LED group when the log is marked as
- "Resolved" or deleted.
+ - Assert the related fault LED group when a log with the CALLOUT path is
+ generated;
+ - De-assert the related fault LED group when the log is marked as "Resolved"
+ or deleted.
**Note**: This yaml config can be automatically generated by
[phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14].
-
### Inventories and other sensors
-Inventories, other sensors (e.g. CPU/DIMM temperature), and FRUs are defined
-in ipmi's yaml config files.
+Inventories, other sensors (e.g. CPU/DIMM temperature), and FRUs are defined in
+ipmi's yaml config files.
E.g. [meta-romulus/recipes-phosphor/ipmi][15]
-* `romulus-ipmi-inventory-map` defines regular inventories, e.g. CPU, memory,
- motherboard.
-* `phosphor-ipmi-fru-properties` defines extra properties of the inventories.
-* `phosphor-ipmi-sensor-inventory` defines the sensors from IPMI.
-* `romulus-ipmi-inventory-sel` defines inventories used for IPMI SEL.
+
+- `romulus-ipmi-inventory-map` defines regular inventories, e.g. CPU, memory,
+ motherboard.
+- `phosphor-ipmi-fru-properties` defines extra properties of the inventories.
+- `phosphor-ipmi-sensor-inventory` defines the sensors from IPMI.
+- `romulus-ipmi-inventory-sel` defines inventories used for IPMI SEL.
For inventory map and fru-properties, they are similar between different
systems, you can refer to this example and make one for your system.
-For ipmi-sensor-inventory, the sensors from IPMI are different between
-systems, so you need to define your own sensors, e.g.
+For ipmi-sensor-inventory, the sensors from IPMI are different between systems,
+so you need to define your own sensors, e.g.
+
```
0x08:
sensorType: 0x07
@@ -527,35 +536,37 @@
sensorType: 0x07
path: /system/chassis/motherboard/cpu0/core0
```
+
The first value `0x08`, `0x1e` and `0x22` are the sensor id of IPMI, which is
-defined in MRW.
-You should follow the system's MRW to define the above config.
+defined in MRW. You should follow the system's MRW to define the above config.
**Note**: The yaml configs can be automatically generated by
[phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14].
-
### Fans
-[phosphor-fan-presence][16] manages all the services about fan:
-* `phosphor-fan-presence` checks if a fan is present, creates the fan DBus
- objects in inventory and update the `Present` property.
-* `phosphor-fan-monitor` checks if a fan is functional, and update the
- `Functional` property of the fan Dbus object.
-* `phosphor-fan-control` controls the fan speed by setting the fan speed target
- based on conditions, e.g. temperatures.
-* `phosphor-cooling-type` checks and sets if the system is air-cooled or
- water-cooled by setting properties of
- `/xyz/openbmc_project/inventory/system/chassis` object.
-All the above services are configurable, e.g. by yaml config.
-So the machine specific configs shall be written when porting OpenBMC to a new
-machine.
+[phosphor-fan-presence][16] manages all the services about fan:
+
+- `phosphor-fan-presence` checks if a fan is present, creates the fan DBus
+ objects in inventory and update the `Present` property.
+- `phosphor-fan-monitor` checks if a fan is functional, and update the
+ `Functional` property of the fan Dbus object.
+- `phosphor-fan-control` controls the fan speed by setting the fan speed target
+ based on conditions, e.g. temperatures.
+- `phosphor-cooling-type` checks and sets if the system is air-cooled or
+ water-cooled by setting properties of
+ `/xyz/openbmc_project/inventory/system/chassis` object.
+
+All the above services are configurable, e.g. by yaml config. So the machine
+specific configs shall be written when porting OpenBMC to a new machine.
Taking Romulus as an example, it is air-cooled and has 3 fans without GPIO
presence detection.
#### Fan presence
+
Romulus has no GPIO detection for fans, so it checks fan tach sensor:
+
```
- name: fan0
path: /system/chassis/motherboard/fan0
@@ -564,15 +575,19 @@
sensors:
- fan0
```
+
The yaml config tells that
-* It shall create `/system/chassis/motherboard/fan0` object in inventory.
-* It shall check fan0 tach sensor (`/sensors/fan_tach/fan0`) to set `Present`
- property on the fan0 object.
+
+- It shall create `/system/chassis/motherboard/fan0` object in inventory.
+- It shall check fan0 tach sensor (`/sensors/fan_tach/fan0`) to set `Present`
+ property on the fan0 object.
#### Fan monitor
+
Romulus fans use pwm to control the fan speed, where pwm ranges from 0 to 255,
-and the fan speed ranges from 0 to about 7000.
-So it needs a factor and offset to mapping the pwm to fan speed:
+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
@@ -585,114 +600,117 @@
factor: 21
offset: 1600
```
+
The yaml config tells that:
+
1. It shall use `FanPwm` as target interface of the tach sensor.
2. It shall calculate the expected fan speed as `target * 21 + 1600`.
-3. The deviation is `15%`, so if the fan speed is out of the expected range
- for more than 30 seconds, fan0 shall be set as non-functional.
+3. The deviation is `15%`, so if the fan speed is out of the expected range for
+ more than 30 seconds, fan0 shall be set as non-functional.
#### Fan control
-The fan control service requires 4 yaml configuration files:
-* `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.
- ```
- - name: air_cooled_chassis
- type: getProperty
- properties:
- - property: WaterCooled
- interface: xyz.openbmc_project.Inventory.Decorator.CoolingType
- 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.
-* `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.
- ```
- - 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.
-With above configs, phosphor-fan will run the fan presence/monitor/control
-logic as configured specifically for the machine.
+The fan control service requires 4 yaml configuration files:
+
+- `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.
+ ```
+ - name: air_cooled_chassis
+ type: getProperty
+ properties:
+ - property: WaterCooled
+ interface: xyz.openbmc_project.Inventory.Decorator.CoolingType
+ 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.
+- `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.
+ ```
+ - 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.
+
+With above configs, phosphor-fan will run the fan presence/monitor/control logic
+as configured specifically for the machine.
**Note**: Romulus fans are simple. For a more complicated example, refer to
-[Witherspoon fan configurations][18]. The following are the additional
-functions of Witherspoon fan configuration:
+[Witherspoon fan configurations][18]. The following are the additional functions
+of Witherspoon fan configuration:
-* It checks GPIO for fan presence.
-* It checks GPIO to determine if the system is air or water cooled.
-* It has more sensors and more events in fan control.
-
+- It checks GPIO for fan presence.
+- It checks GPIO to determine if the system is air or water cooled.
+- It has more sensors and more events in fan control.
### GPIOs
-This section mainly focuses on the GPIOs in device tree that shall be
-monitored.
+
+This section mainly focuses on the GPIOs in device tree that shall be monitored.
E.g.:
-* A GPIO may represent a signal of host checkstop.
-* A GPIO may represent a button press.
-* A GPIO may represent if a device is attached or not.
+
+- A GPIO may represent a signal of host checkstop.
+- A GPIO may represent a button press.
+- A GPIO may represent if a device is attached or not.
They are categorized as `phosphor-gpio-presence` for checking presences of a
device, and `phosphor-gpio-monitor` for monitoring a GPIO.
#### GPIOs in device tree
-All the GPIOs to be monitored shall be described in the device tree.
-E.g.
+
+All the GPIOs to be monitored shall be described in the device tree. E.g.
+
```
gpio-keys {
compatible = "gpio-keys";
@@ -708,8 +726,10 @@
};
};
```
+
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]:
+
```
#define ASPEED_GPIO_PORT_A 0
#define ASPEED_GPIO_PORT_B 1
@@ -724,90 +744,112 @@
```
#### GPIO Presence
+
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.
-* [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.
+- [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.
+- [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.
#### GPIO monitor
+
Typical usage of GPIO monitor is to monitor the checkstop event from the host,
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.
-* [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.
+- [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.
+- [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.
-[1]: https://github.com/openbmc/linux/blob/dev-4.13/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts
+[1]:
+ https://github.com/openbmc/linux/blob/dev-4.13/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts
[2]: https://lists.ozlabs.org/listinfo/openbmc
[3]: https://github.com/openbmc/skeleton
-[4]: https://github.com/openbmc/openbmc/tree/master/meta-quanta/meta-q71l/recipes-phosphor/workbook
+[4]:
+ https://github.com/openbmc/openbmc/tree/master/meta-quanta/meta-q71l/recipes-phosphor/workbook
[5]: https://github.com/openbmc/skeleton/blob/master/configs/Romulus.py
-[6]: https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md
-[7]: https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/sensors
-[8]: https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/i2c%401e78a000/i2c-bus%40440/w83773g%404c.conf
-[9]: https://github.com/openbmc/linux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L208
-[10]: https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/pwm-tacho-controller%401e786000.conf
-[11]: https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/devices/platform/gpio-fsi/fsi0/slave%4000--00/00--00--00--06/sbefifo1-dev0/occ-hwmon.1.conf
-[12]: https://github.com/openbmc/linux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L42
+[6]:
+ https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md
+[7]:
+ https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/sensors
+[8]:
+ https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/i2c%401e78a000/i2c-bus%40440/w83773g%404c.conf
+[9]:
+ https://github.com/openbmc/linux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L208
+[10]:
+ https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/pwm-tacho-controller%401e786000.conf
+[11]:
+ https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/devices/platform/gpio-fsi/fsi0/slave%4000--00/00--00--00--06/sbefifo1-dev0/occ-hwmon.1.conf
+[12]:
+ https://github.com/openbmc/linux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L42
[13]: https://github.com/openbmc/phosphor-mrw-tools
-[14]: https://github.com/openbmc/openbmc/blob/764b88f4056cc98082e233216704e94613499e64/meta-ibm/meta-witherspoon/conf/distro/openbmc-witherspoon.conf#L4
-[15]: https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/ipmi
+[14]:
+ https://github.com/openbmc/openbmc/blob/764b88f4056cc98082e233216704e94613499e64/meta-ibm/meta-witherspoon/conf/distro/openbmc-witherspoon.conf#L4
+[15]:
+ https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/ipmi
[16]: https://github.com/openbmc/phosphor-fan-presence
-[17]: https://github.com/openbmc/phosphor-fan-presence/blob/master/control/example/events.yaml
-[18]: https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-witherspoon/recipes-phosphor/fans
-[19]: https://github.com/openbmc/openbmc/blob/master/meta-ibm/meta-witherspoon/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc/gpio/phosphor-power-supply-0.conf
-[20]: https://github.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc/gpio/phosphor-pcie-card-e2b.conf
-[21]: https://github.com/openbmc/openbmc/blob/master/meta-openpower/recipes-phosphor/host/checkstop-monitor.bb
-[22]: https://github.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/host/checkstop-monitor/obmc/gpio/checkstop
-[23]: 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
+[17]:
+ https://github.com/openbmc/phosphor-fan-presence/blob/master/control/example/events.yaml
+[18]:
+ https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-witherspoon/recipes-phosphor/fans
+[19]:
+ https://github.com/openbmc/openbmc/blob/master/meta-ibm/meta-witherspoon/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc/gpio/phosphor-power-supply-0.conf
+[20]:
+ https://github.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc/gpio/phosphor-pcie-card-e2b.conf
+[21]:
+ https://github.com/openbmc/openbmc/blob/master/meta-openpower/recipes-phosphor/host/checkstop-monitor.bb
+[22]:
+ https://github.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/host/checkstop-monitor/obmc/gpio/checkstop
+[23]:
+ 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]: https://github.com/openbmc/openbmc/commit/2a80da2262bf13aa1ddb589cf3f2b672d26b0975
-[28]: https://github.com/openbmc/openbmc/blob/3cce45a96f0416b4c3d8f2b698cb830662a29227/meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config/led.yaml
+[26]:
+ https://github.com/openbmc/openbmc/commit/e0e69beab7c268e4ad98972016c78b0d7d5769ac
+[27]:
+ https://github.com/openbmc/openbmc/commit/2a80da2262bf13aa1ddb589cf3f2b672d26b0975
+[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
diff --git a/development/dev-environment.md b/development/dev-environment.md
index 40e61b7..d2fad46 100644
--- a/development/dev-environment.md
+++ b/development/dev-environment.md
@@ -9,13 +9,13 @@
## Overview
OpenBMC uses the [Yocto](https://www.yoctoproject.org/) Project as its
-underlying building and distribution generation framework. The main
-OpenBMC [README](https://github.com/openbmc/openbmc/blob/master/README.md)
-provides information on getting up and going with Yocto and OpenBMC.
-There are mechanisms to use this process to build your changes but it can be
-slow and cumbersome for initial debug and validation of your software. This
-guide focuses on how to test new changes quickly using the OpenBMC Software
-Development Kit (SDK) and [QEMU](https://www.qemu.org/).
+underlying building and distribution generation framework. The main OpenBMC
+[README](https://github.com/openbmc/openbmc/blob/master/README.md) provides
+information on getting up and going with Yocto and OpenBMC. There are mechanisms
+to use this process to build your changes but it can be slow and cumbersome for
+initial debug and validation of your software. This guide focuses on how to test
+new changes quickly using the OpenBMC Software Development Kit (SDK) and
+[QEMU](https://www.qemu.org/).
The SDK is a group of packages that are built during a BitBake operation.
BitBake is the tool used to build Yocto based distributions. The SDK provides
@@ -43,38 +43,38 @@
virtualization tool to run the development environment.
1. Install either [VirtualBox](https://www.virtualbox.org/wiki/Downloads) or
-[VMware](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html)
-onto your computer (Mac, Windows, Linux)
+ [VMware](https://www.vmware.com/products/workstation-player/workstation-player-evaluation.html)
+ onto your computer (Mac, Windows, Linux)
- Both have free versions available for what you need. VirtualBox is what the
- majority of core OpenBMC development is using. **Note:** If you want to use
- this VM to BitBake a full OpenBMC image, you'll want to allocate as many
- resources as possible. Ideal minimum resources are 8 threads, 16GB memory,
- 200GB hard drive. Just using for SDK builds and QEMU should work fine with the
- normal defaults on a VM.
+Both have free versions available for what you need. VirtualBox is what the
+majority of core OpenBMC development is using. **Note:** If you want to use this
+VM to BitBake a full OpenBMC image, you'll want to allocate as many resources as
+possible. Ideal minimum resources are 8 threads, 16GB memory, 200GB hard drive.
+Just using for SDK builds and QEMU should work fine with the normal defaults on
+a VM.
2. Install the latest Ubuntu LTS release
- The majority of OpenBMC development community uses Ubuntu. The qemu below
- is built on [18.04](http://releases.ubuntu.com/18.04/) but whatever is most
- recent *should* work. The same goes for other Linux distributions like
- Fedora but again, these are not tested nearly as much by the core OpenBMC
- team as Ubuntu.
+The majority of OpenBMC development community uses Ubuntu. The qemu below is
+built on [18.04](http://releases.ubuntu.com/18.04/) but whatever is most recent
+_should_ work. The same goes for other Linux distributions like Fedora but
+again, these are not tested nearly as much by the core OpenBMC team as Ubuntu.
- **VirtualBox Tips** - You'll want copy/paste working between your VM and Host.
- To do that, once you have your VM up and running:
- - Devices -> Insert Guest Additions CD Image (install)
- - Devices -> Shared Clipboard -> Bidirectional
- - reboot (the VM)
+**VirtualBox Tips** - You'll want copy/paste working between your VM and Host.
+To do that, once you have your VM up and running:
+
+- Devices -> Insert Guest Additions CD Image (install)
+- Devices -> Shared Clipboard -> Bidirectional
+- reboot (the VM)
3. Install required packages
- Refer to
- [Prerequisite](https://github.com/openbmc/openbmc/blob/master/README.md#1-prerequisite)
- link.
+Refer to
+[Prerequisite](https://github.com/openbmc/openbmc/blob/master/README.md#1-prerequisite)
+link.
- **Note** - In Ubuntu, a "sudo apt-get update" will probably be needed before
- installing the packages.
+**Note** - In Ubuntu, a "sudo apt-get update" will probably be needed before
+installing the packages.
## Download and Install SDK
@@ -92,49 +92,49 @@
To begin working with the SDK:
1. Download the latest SDK to your system. It's recommended that you create a
- directory to store your SDK scripts and installation directories to keep your
- workspace organised.
+ directory to store your SDK scripts and installation directories to keep your
+ workspace organised.
- ```
- mkdir -p ~/sdk
- cd ~/sdk
+```
+mkdir -p ~/sdk
+cd ~/sdk
- wget https://jenkins.openbmc.org/job/latest-master-sdk/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/deploy/sdk/oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
- chmod u+x oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
- ```
+wget https://jenkins.openbmc.org/job/latest-master-sdk/label=docker-builder,target=romulus/lastSuccessfulBuild/artifact/deploy/sdk/oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
+chmod u+x oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
+```
2. Install the SDK
- Choose an appropriate location and name. It's a good idea to include the date
- and system supported by that SDK in the directory name. For example:
+Choose an appropriate location and name. It's a good idea to include the date
+and system supported by that SDK in the directory name. For example:
- ```
- mkdir -p ~/sdk/romulus-`date +%F`
- ```
+```
+mkdir -p ~/sdk/romulus-`date +%F`
+```
- Run the following command to install the SDK. When command asks you to
- "Enter target directory for SDK", enter the directory you created in the
- previous step.
+Run the following command to install the SDK. When command asks you to "Enter
+target directory for SDK", enter the directory you created in the previous step.
- ```
- ./oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
- ```
+```
+./oecore-x86_64-arm1176jzs-toolchain-nodistro.0.sh
+```
- The installation script will indicate progress and give completion messages
- like this:
- ```
- SDK has been successfully set up and is ready to be used.
- Each time you wish to use the SDK in a new shell session, you need to source
- the environment setup script e.g. $ . /...path-to-sdk.../environment-setup-arm1176jzs-openbmc-linux-gnueabi
- ```
+The installation script will indicate progress and give completion messages like
+this:
+
+```
+SDK has been successfully set up and is ready to be used.
+Each time you wish to use the SDK in a new shell session, you need to source
+the environment setup script e.g. $ . /...path-to-sdk.../environment-setup-arm1176jzs-openbmc-linux-gnueabi
+```
3. Source yourself into the SDK
- Ensure no errors. The command to do this will be provided at the end of
- installation. To make your shell use the new SDK environment, you must source
- its `environment-setup` script which was created in the previous step. You
- may wish to save the required command, for example, cut/paste the text above
- into a README.
+Ensure no errors. The command to do this will be provided at the end of
+installation. To make your shell use the new SDK environment, you must source
+its `environment-setup` script which was created in the previous step. You may
+wish to save the required command, for example, cut/paste the text above into a
+README.
That's it, you now have a working development environment for OpenBMC!
@@ -142,91 +142,102 @@
1. Download latest openbmc/qemu fork of QEMU application
- ```
- wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm
+```
+wget https://jenkins.openbmc.org/job/latest-qemu-x86/lastSuccessfulBuild/artifact/qemu/build/qemu-system-arm
- chmod u+x qemu-system-arm
- ```
+chmod u+x qemu-system-arm
+```
2. Download the Romulus image.
- ```
- wget 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
- ```
+```
+wget 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
+```
3. Start QEMU with downloaded Romulus image
- **Note** - For REST, SSH and IPMI to work into your QEMU session, you must connect
- up some host ports to the REST, SSH and IPMI ports in your QEMU session. In this
- example, it just uses 2222, 2443, 2623. You can use whatever you prefer.
- ```
- ./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
- ```
+ **Note** - For REST, SSH and IPMI to work into your QEMU session, you must
+ connect up some host ports to the REST, SSH and IPMI ports in your QEMU
+ session. In this example, it just uses 2222, 2443, 2623. You can use whatever
+ you prefer.
- **Note** - By default, Jenkins and openbmc-test-automation use SSH and HTTPS
- ports 22 and 443, respectively. For the IPMI port 623 is used. SSH connection
- to use a user-defined port 2222 might not be successful. To use SSH port 22,
- HTTPS port 443 and IPMI port 623:
- ```
- ./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
- ```
+```
+./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
+```
+
+**Note** - By default, Jenkins and openbmc-test-automation use SSH and HTTPS
+ports 22 and 443, respectively. For the IPMI port 623 is used. SSH connection to
+use a user-defined port 2222 might not be successful. To use SSH port 22, HTTPS
+port 443 and IPMI port 623:
+
+```
+./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
+```
4. Wait for your QEMU-based BMC to boot
- Login using default root/0penBmc login (Note the 0 is a zero).
+Login using default root/0penBmc login (Note the 0 is a zero).
5. Check the system state
- You'll see a lot of services starting in the console, you can start running
- 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.
+You'll see a lot of services starting in the console, you can start running 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.
- ```
- root@openbmc:~# obmcutil state
- CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready
- CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off
- CurrentHostState : xyz.openbmc_project.State.Host.HostState.Off
- ```
+```
+root@openbmc:~# obmcutil state
+CurrentBMCState : xyz.openbmc_project.State.BMC.BMCState.Ready
+CurrentPowerState : xyz.openbmc_project.State.Chassis.PowerState.Off
+CurrentHostState : xyz.openbmc_project.State.Host.HostState.Off
+```
- **Note** To exit (and kill) your QEMU session run: `ctrl+a x`
+**Note** To exit (and kill) your QEMU session run: `ctrl+a x`
## Alternative yocto QEMU
- yocto has tools for building and running qemu. These tools avoid some of the
- configuration issues that come from downloading a prebuilt image, and
- modifying binaries. Using yocto qemu also uses the [TAP
- interface](https://www.kernel.org/doc/Documentation/networking/tuntap.txt)
- which some find be more stable. This is particularly useful when debugging
- at the application level.
+yocto has tools for building and running qemu. These tools avoid some of the
+configuration issues that come from downloading a prebuilt image, and modifying
+binaries. Using yocto qemu also uses the
+[TAP interface](https://www.kernel.org/doc/Documentation/networking/tuntap.txt)
+which some find be more stable. This is particularly useful when debugging at
+the application level.
- - set up a bmc build environment
- ```
- source setup romulus myBuild/build
- ```
- - add the qemu x86 open embedded machine for testing
- ```
- MACHINE ??= "qemux86"
- ```
- - Make the changes to the build (ie devtool modify bmcweb, devtool add gdb)
- ```
- devtool modify bmcweb myNewLocalbmcweb/
- ```
- - build open bmc for the qemu x86 machine
- ```
- MACHINE=qemux86 bitbake obmc-phosphor-image
- ```
- - run qemu they way yocto provides
- ```
- runqemu myBuild/build/tmp/deploy/images/qemux86/ nographic \
- qemuparams="-m 2048"
- ```
- - after that the all the a TAP network interface is added, and protocol like
+- set up a bmc build environment
+
+```
+source setup romulus myBuild/build
+```
+
+- add the qemu x86 open embedded machine for testing
+
+```
+MACHINE ??= "qemux86"
+```
+
+- Make the changes to the build (ie devtool modify bmcweb, devtool add gdb)
+
+```
+devtool modify bmcweb myNewLocalbmcweb/
+```
+
+- build open bmc for the qemu x86 machine
+
+```
+MACHINE=qemux86 bitbake obmc-phosphor-image
+```
+
+- run qemu they way yocto provides
+
+```
+runqemu myBuild/build/tmp/deploy/images/qemux86/ nographic \
+ qemuparams="-m 2048"
+```
+
+- after that the all the a TAP network interface is added, and protocol like
ssh, scp, http work well.
-
-
diff --git a/development/gerrit-setup.md b/development/gerrit-setup.md
index 7b55971..ad829b2 100644
--- a/development/gerrit-setup.md
+++ b/development/gerrit-setup.md
@@ -1,96 +1,109 @@
# OpenBMC Gerrit Setup/Integration
**Document Purpose:** Walkthrough configuring your workstation and a Gerrit
- account. This is needed to participate in OpenBMC's
- Gerrit-based code reviews.
+account. This is needed to participate in OpenBMC's Gerrit-based code reviews.
**Prerequisites:** Current Linux, Mac, or Windows system. Git packages
- installed. E-mail account (recommended to use the same e-mail
- address for both Gerrit and GitHub).
+installed. E-mail account (recommended to use the same e-mail address for both
+Gerrit and GitHub).
## Initial Setup
##### 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)`
-
+- `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
-Create keys: ```ssh-keygen -t ed25519 -C "your_email@your-domain"```
-* Recommended to use the defaults instead of picking your own directory/file
+
+Create keys: `ssh-keygen -t ed25519 -C "your_email@your-domain"`
+
+- Recommended to use the defaults instead of picking your own directory/file
names.
Add Keys to GitHub:
-* <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>
+
+- <https://help.github.com/articles/adding-a-new-ssh-key-to-your-github-account/>
Add Keys to OpenBMC's Gerrit Server:
-* Login to [Gerrit](https://gerrit.openbmc.org/) with your GitHub
- account.
-* Go to
- <https://gerrit.openbmc.org/plugins/github-plugin/static/account.html>
-* Your information should be auto-filled, so click "Next".
-* If successful you should see a blank screen, feel free to exit out.
+
+- Login to [Gerrit](https://gerrit.openbmc.org/) with your GitHub account.
+- Go to <https://gerrit.openbmc.org/plugins/github-plugin/static/account.html>
+- Your information should be auto-filled, so click "Next".
+- If successful you should see a blank screen, feel free to exit out.
##### 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
+
+- 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
-* Enter your full name in Settings -> Profile -> Full name
+
+- Enter your full name in Settings -> Profile -> Full name
##### Add SSH config entry
+
Add the following to `~/.ssh/config`:
+
```
Host openbmc.gerrit
Hostname gerrit.openbmc.org
Port 29418
User <Your Gerrit Username>
```
-* **NOTE**: There is a bug in AFS that requires `AFSTokenPassing no` to be
- added to the SSH entry if using AFS.
-* Your Gerrit Username can be found in Gerrit under Settings -> Profile -> Username
-* Ensure proper permissions for for your .ssh directory: `chmod 600 ~/.ssh/*`
+
+- **NOTE**: There is a bug in AFS that requires `AFSTokenPassing no` to be added
+ to the SSH entry if using AFS.
+- Your Gerrit Username can be found in Gerrit under Settings -> Profile ->
+ Username
+- Ensure proper permissions for for your .ssh directory: `chmod 600 ~/.ssh/*`
##### Confirm Setup Success
+
Test connectivity to Gerrit by attempting to clone a repo
-* `git clone ssh://openbmc.gerrit/openbmc/docs`
-* If successful you should see something like:
- `Checking out files: 100% (45/45), done.`
+
+- `git clone ssh://openbmc.gerrit/openbmc/docs`
+- If successful you should see something like:
+ `Checking out files: 100% (45/45), done.`
##### Add Hooks
+
Inside the repo you just cloned, enter the following commands:
+
```
gitdir=$(git rev-parse --git-dir)
scp -p -P 29418 openbmc.gerrit:hooks/commit-msg ${gitdir}/hooks
```
+
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
+
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
will look like.
-* Make your code changes
-* Add those files to the index to be committed:
+
+- Make your code changes
+- Add those files to the index to be committed:
`git add [file1 file2 ... fileN]`
-* Commit your changes, adding a Signed-off-by line to it (more on
+- Commit your changes, adding a Signed-off-by line to it (more on
[writing good commit messages](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes)):
`git commit --signoff`
-* Push your changes to Gerrit for code review:
+- Push your changes to Gerrit for code review:
`git push origin HEAD:refs/for/master`
-* Go to [Gerrit web interface](https://gerrit.openbmc.org/), click on
- your new review, and add reviewers based on `OWNERS` file in the repo.
+- 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
+
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!
Submitting changes for review is just one of many steps in the contributing
process. Please see
-[CONTRIBUTING](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md)
-for best practices.
+[CONTRIBUTING](https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md) for
+best practices.
diff --git a/development/sdk-hello-world.md b/development/sdk-hello-world.md
index 1839a30..d432382 100644
--- a/development/sdk-hello-world.md
+++ b/development/sdk-hello-world.md
@@ -3,7 +3,8 @@
**Document Purpose:** Walk through compiling and running an OpenBMC application
in QEMU.
-**Prerequisites:** Completed Development Environment Setup [Document](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
+**Prerequisites:** Completed Development Environment Setup
+[Document](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
## Clone and Build a Repo
@@ -13,114 +14,125 @@
common directory like ~/Code/.
1. Clone the Repository
- ```
- git clone https://github.com/openbmc/phosphor-state-manager.git
- ```
+
+```
+git clone https://github.com/openbmc/phosphor-state-manager.git
+```
2. Add code to print out a Hello World
- ```
- cd phosphor-state-manager
- vi bmc_state_manager_main.cpp
- ```
- Your diff should look something like this:
- ```
- +#include <iostream>
+```
+cd phosphor-state-manager
+vi bmc_state_manager_main.cpp
+```
- int main(int argc, char**)
- {
- @@ -17,6 +18,8 @@ int main(int argc, char**)
+Your diff should look something like this:
- bus.request_name(BMC_BUSNAME);
+```
++#include <iostream>
- + std::cout<<"Hello World" <<std::endl;
- +
- while (true)
- {
- ```
+ int main(int argc, char**)
+ {
+@@ -17,6 +18,8 @@ int main(int argc, char**)
+
+ bus.request_name(BMC_BUSNAME);
+
++ std::cout<<"Hello World" <<std::endl;
++
+ while (true)
+ {
+```
3. Build the Repository
- This is a meson based repository
- ```
- meson build
- ninja -C build
- ```
+This is a meson based repository
+
+```
+meson build
+ninja -C build
+```
## Load the Application Into QEMU
- 1. Strip the binary you generated
+1. Strip the binary you generated
- OpenBMC is an embedded environment so always best to load on the smallest size
- application/library
- ```
- arm-openbmc-linux-gnueabi-strip phosphor-bmc-state-manager
- ```
+OpenBMC is an embedded environment so always best to load on the smallest size
+application/library
- 2. Create a safe file system for your application
+```
+arm-openbmc-linux-gnueabi-strip phosphor-bmc-state-manager
+```
- Now is time to load your Hello World application in to QEMU virtual hardware.
- The OpenBMC overrides the PATH variable to always look in /usr/local/bin/
- first so you could simply scp your application in to /usr/local/bin, run it
- and be done. That works fine for command line tests, but when you start
- launching your applications via systemd services you will hit problems since
- application paths are hardcoded in the service files. Let's start our journey
- doing what the professionals do and create an overlay file system. Overlays
- will save you time and grief. No more renaming and recovering original files,
- no more forgetting which files you messed with during debug, and of course, no
- more bricking the system. Log in to the QEMU instance and run these commands.
- ```
- 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
- ```
+2. Create a safe file system for your application
- 3. scp this binary onto your QEMU instance
+Now is time to load your Hello World application in to QEMU virtual hardware.
+The OpenBMC overrides the PATH variable to always look in /usr/local/bin/ first
+so you could simply scp your application in to /usr/local/bin, run it and be
+done. That works fine for command line tests, but when you start launching your
+applications via systemd services you will hit problems since application paths
+are hardcoded in the service files. Let's start our journey doing what the
+professionals do and create an overlay file system. Overlays will save you time
+and grief. No more renaming and recovering original files, no more forgetting
+which files you messed with during debug, and of course, no more bricking the
+system. Log in to the QEMU instance and run these commands.
- If you used the default ports when starting QEMU then here is the scp command
- to run from your phosphor-state-manager directory. If you chose your own port
- then substitute that here for the 2222.
- ```
- scp -P 2222 phosphor-bmc-state-manager root@127.0.0.1:/usr/bin/
- ```
+```
+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
+```
+
+3. scp this binary onto your QEMU instance
+
+If you used the default ports when starting QEMU then here is the scp command to
+run from your phosphor-state-manager directory. If you chose your own port then
+substitute that here for the 2222.
+
+```
+scp -P 2222 phosphor-bmc-state-manager root@127.0.0.1:/usr/bin/
+```
## Run the Application in QEMU
- 1. Stop the BMC state manager service
- ```
- systemctl stop xyz.openbmc_project.State.BMC.service
- ```
+1. Stop the BMC state manager service
- 2. Run the application in your QEMU session:
- ```
- phosphor-bmc-state-manager
- ```
+```
+systemctl stop xyz.openbmc_project.State.BMC.service
+```
- You'll see your "Hello World" message displayed. Ctrl^C to end that
- application. In general, this is not how you will test new applications.
- Instead, you'll be using systemd services.
+2. Run the application in your QEMU session:
- 3. Start application via systemd service
+```
+phosphor-bmc-state-manager
+```
- OpenBMC uses systemd to manage its applications. There will be later tutorials
- on this, but for now just run the following to restart the BMC state service
- and have it pick up your new application:
- ```
- systemctl restart xyz.openbmc_project.State.BMC.service
- ```
+You'll see your "Hello World" message displayed. Ctrl^C to end that application.
+In general, this is not how you will test new applications. Instead, you'll be
+using systemd services.
- Since systemd started your service, the
- "Hello World" will not be output to the console, but it will be in the
- journal. Later tutorials will discuss the journal but for now just run:
- ```
- journalctl | tail
- ```
+3. Start application via systemd service
- You should see something like this in one of the journal
- entries:
- ```
- <date> romulus phosphor-bmc-state-manager[1089]: Hello World
- ```
+OpenBMC uses systemd to manage its applications. There will be later tutorials
+on this, but for now just run the following to restart the BMC state service and
+have it pick up your new application:
+
+```
+systemctl restart xyz.openbmc_project.State.BMC.service
+```
+
+Since systemd started your service, the "Hello World" will not be output to the
+console, but it will be in the journal. Later tutorials will discuss the journal
+but for now just run:
+
+```
+journalctl | tail
+```
+
+You should see something like this in one of the journal entries:
+
+```
+<date> romulus phosphor-bmc-state-manager[1089]: Hello World
+```
That's it! You customized an existing BMC application, built it using the SDK,
and ran it within QEMU!
diff --git a/development/web-ui.md b/development/web-ui.md
index c5c3210..7ae1df8 100644
--- a/development/web-ui.md
+++ b/development/web-ui.md
@@ -8,20 +8,22 @@
# Webui-vue
-The [webui-vue](https://github.com/openbmc/webui-vue) repository
-will replace phosphor-webui once it is deprecated. Webui-vue uses the
-[Vue.js](https://vuejs.org/) framework to interact with the BMC via the
-Redfish API.
+The [webui-vue](https://github.com/openbmc/webui-vue) repository will replace
+phosphor-webui once it is deprecated. Webui-vue uses the
+[Vue.js](https://vuejs.org/) framework to interact with the BMC via the Redfish
+API.
Visit [README.md](https://github.com/openbmc/webui-vue/blob/master/README.md) to
-learn more about why the Vue.js application was created, features needed to reach parity and why it is
-replacing the Angular.JS application.
+learn more about why the Vue.js application was created, features needed to
+reach parity and why it is replacing the Angular.JS application.
-Visit [CONTRIBUTING.md](https://github.com/openbmc/webui-vue/blob/master/CONTRIBUTING.md)
-to find information on project set-up, design information, and contributing processes.
+Visit
+[CONTRIBUTING.md](https://github.com/openbmc/webui-vue/blob/master/CONTRIBUTING.md)
+to find information on project set-up, design information, and contributing
+processes.
-Visit the [OpenBMC Web UI Style Guide](https://openbmc.github.io/webui-vue/)
-to find information on:
+Visit the [OpenBMC Web UI Style Guide](https://openbmc.github.io/webui-vue/) to
+find information on:
- Coding Standards
- Guidelines
@@ -29,7 +31,8 @@
- Components Usage
- Quick Start References
-Visit the [OpenBMC Web UI Themes Guide - How to customize](https://openbmc.github.io/webui-vue/themes/customize.html)
+Visit the
+[OpenBMC Web UI Themes Guide - How to customize](https://openbmc.github.io/webui-vue/themes/customize.html)
to learn how to create custom builds to meet your branding and customization
needs for:
@@ -42,8 +45,8 @@
Connect to Web UI in QEMU
-1. You will need the QEMU session running per instructions in the
- "Download and Start QEMU Session" section of
+1. You will need the QEMU session running per instructions in the "Download and
+ Start QEMU Session" section of
[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
@@ -59,15 +62,15 @@
The [phosphor-webui](https://github.com/openbmc/phosphor-webui) 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.
+[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.
-See directions below to learn [how to customize
-phosphor-webui](#customize-phosphor-webui).
+See directions below to learn
+[how to customize phosphor-webui](#customize-phosphor-webui).
-Phosphor-webui was built on AngularJS and AngularJS goes End of Life June 30,
-2021.
+Phosphor-webui was built on AngularJS and AngularJS goes End of Life June
+30, 2021.
## Customize Phosphor-webui
@@ -79,9 +82,11 @@
2. Install appropriate packages and start web UI
- Follow the directions in the phosphor-webui [README](https://github.com/openbmc/phosphor-webui/blob/master/README.md)
- to install the required packages and start the web UI. You can use the
- development environment created in [dev-environment](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
+ Follow the directions in the phosphor-webui
+ [README](https://github.com/openbmc/phosphor-webui/blob/master/README.md) to
+ install the required packages and start the web UI. You can use the
+ development environment created in
+ [dev-environment](https://github.com/openbmc/docs/blob/master/development/dev-environment.md)
or your own system assuming you install the required packages noted in the
README.
@@ -120,9 +125,9 @@
Kill your npm run using Ctrl^C.
-4. Customize the header with the new image and verify
- The header is on every page in the web UI. It has a smaller version of the
- logo in it which we are changing with this step.
+4. Customize the header with the new image and verify The header is on every
+ page in the web UI. It has a smaller version of the logo in it which we are
+ changing with this step.
Similar to the previous step, modify the appropriate HTML for the header:
@@ -140,14 +145,14 @@
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 "BMC HOST
- OR BMC IP ADDRESS" field.
+ 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
+ "BMC HOST OR BMC IP ADDRESS" field.
Note that in the HTML where you're replacing the images, there is also the
- corresponding text that goes with the images. Changing the text to match
- with your logo is also something you can easily do to customize your creation
- of an OpenBMC system.
+ corresponding text that goes with the images. Changing the text to match with
+ 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!
diff --git a/features.md b/features.md
index 1d561a1..6963e1d 100644
--- a/features.md
+++ b/features.md
@@ -2,71 +2,98 @@
Follow links to learn more about OpenBMC features:
-* [BMCWeb][] HTTP/Web server
-* [WebUI Vue][] web application
-* REST Management: [BMCWeb Redfish][], [Phosphor REST APIs][] includes
- [Host management REST APIs][]
-* [D-Bus interfaces][] describes internal interfaces
-* [D-Bus Object Mapper][]
-* [Remote KVM][]
-* [IPMI in band][] and [IPMI out of band][]
-* Full IPMI 2.0 Compliance with DCMI
-* SSH based SOL: [How to use][SOL How to use]
-* Power and Cooling Management: [Phosphor Fan Control][]
-* [Logging][Phosphor Logging] and [Callouts][Logging Callouts]
-* Zeroconf discoverable through `systemd-networkd`
-* [Sensors][]
-* Inventory: [Entity manager][], [Phosphor inventory manager][] and its [MSL application][]
-* [LEDs][]: see also [LED Groups][]
-* Host Watchdog: [Phosphor Watchdog Implementation][]
-* [Power State management] and [Chassis Power control][]
-* [Network management][]
-* [Factory reset][]
-* [User management][Phosphor User Management]
-* Time (time of day clock) management
-* [Certificate management][]: [Phosphor Certificate Manager][]
-* [Simulation][] via QEMU
-* [Firmware update support][]
-* [Automated Testing][]
-* LDAP
-* Remote syslog
+- [BMCWeb][] HTTP/Web server
+- [WebUI Vue][] web application
+- REST Management: [BMCWeb Redfish][], [Phosphor REST APIs][] includes [Host
+ management REST APIs][]
+- [D-Bus interfaces][] describes internal interfaces
+- [D-Bus Object Mapper][]
+- [Remote KVM][]
+- [IPMI in band][] and [IPMI out of band][]
+- Full IPMI 2.0 Compliance with DCMI
+- SSH based SOL: [How to use][sol how to use]
+- Power and Cooling Management: [Phosphor Fan Control][]
+- [Logging][phosphor logging] and [Callouts][logging callouts]
+- Zeroconf discoverable through `systemd-networkd`
+- [Sensors][]
+- Inventory: [Entity manager][], [Phosphor inventory manager][] and its [MSL
+ application][]
+- [LEDs][]: see also [LED Groups][]
+- Host Watchdog: [Phosphor Watchdog Implementation][]
+- [Power State management] and [Chassis Power control][]
+- [Network management][]
+- [Factory reset][]
+- [User management][phosphor user management]
+- Time (time of day clock) management
+- [Certificate management][]: [Phosphor Certificate Manager][]
+- [Simulation][] via QEMU
+- [Firmware update support][]
+- [Automated Testing][]
+- LDAP
+- Remote syslog
## OpenPOWER Features
-* [POWER OCC Support][POWER OCC Implementation] (On Chip Controller)
-* [Hardware Diagnostics][] for POWER Systems fatal hardware errors.
+- [POWER OCC Support][power occ implementation] (On Chip Controller)
+- [Hardware Diagnostics][] for POWER Systems fatal hardware errors.
-[Automated Testing]: https://github.com/openbmc/openbmc-test-automation/blob/master/README.md
-[BMCWeb]: https://github.com/openbmc/bmcweb/blob/master/README.md
-[BMCWeb Redfish]: https://github.com/openbmc/bmcweb/blob/master/DEVELOPING.md#redfish
-[Certificate management]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Certs/README.md
-[Chassis Power control]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Chassis/README.md
-[D-Bus interfaces]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/README.md
-[D-Bus Object Mapper]: https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md
-[Entity manager]: https://github.com/openbmc/entity-manager/blob/master/README.md
-[Factory reset]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Common/FactoryReset/README.md
-[Firmware update support]: 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]: https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md
-[IPMI out of band]: https://github.com/openbmc/ipmitool/blob/master/README
-[LED Groups]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/README.md
-[LEDs]: https://github.com/openbmc/docs/blob/master/architecture/LED-architecture.md
-[Logging Callouts]: https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Common/Callout/README.md
-[MSL application]: https://github.com/openbmc/phosphor-dbus-monitor/blob/master/mslverify/README.md
-[Network management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Network/README.md
-[Phosphor Certificate Manager]: https://github.com/openbmc/phosphor-certificate-manager/blob/master/README.md
-[Phosphor Fan Control]: https://github.com/openbmc/phosphor-fan-presence/blob/master/README.md
-[Phosphor inventory manager]: https://github.com/openbmc/phosphor-inventory-manager/blob/master/README.md
-[Phosphor Logging]: https://github.com/openbmc/phosphor-logging/blob/master/README.md
-[Phosphor REST APIs]: https://github.com/openbmc/docs/blob/master/rest-api.md
-[Phosphor User Management]: https://github.com/openbmc/docs/blob/master/architecture/user-management.md
-[Phosphor Watchdog Implementation]: https://github.com/openbmc/phosphor-watchdog
-[Power OCC Implementation]: https://github.com/openbmc/openpower-occ-control
-[Remote KVM]: https://github.com/openbmc/obmc-ikvm/blob/master/README.md
-[Sensors]: https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md
-[Simulation]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md
-[Power State management]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/README.md
-[SOL How to use]: https://github.com/openbmc/docs/blob/master/console.md
-[WebUI Vue]: https://github.com/openbmc/webui-vue/blob/master/README.md
+[automated testing]:
+ https://github.com/openbmc/openbmc-test-automation/blob/master/README.md
+[bmcweb]: https://github.com/openbmc/bmcweb/blob/master/README.md
+[bmcweb redfish]:
+ https://github.com/openbmc/bmcweb/blob/master/DEVELOPING.md#redfish
+[certificate management]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Certs/README.md
+[chassis power control]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Chassis/README.md
+[d-bus interfaces]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/README.md
+[d-bus object mapper]:
+ https://github.com/openbmc/docs/blob/master/architecture/object-mapper.md
+[entity manager]:
+ https://github.com/openbmc/entity-manager/blob/master/README.md
+[factory reset]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Common/FactoryReset/README.md
+[firmware update support]:
+ 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]:
+ https://github.com/openbmc/docs/blob/master/architecture/ipmi-architecture.md
+[ipmi out of band]: https://github.com/openbmc/ipmitool/blob/master/README
+[led groups]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Led/README.md
+[leds]:
+ https://github.com/openbmc/docs/blob/master/architecture/LED-architecture.md
+[logging callouts]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/tree/master/yaml/xyz/openbmc_project/Common/Callout/README.md
+[msl application]:
+ https://github.com/openbmc/phosphor-dbus-monitor/blob/master/mslverify/README.md
+[network management]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Network/README.md
+[phosphor certificate manager]:
+ https://github.com/openbmc/phosphor-certificate-manager/blob/master/README.md
+[phosphor fan control]:
+ https://github.com/openbmc/phosphor-fan-presence/blob/master/README.md
+[phosphor inventory manager]:
+ https://github.com/openbmc/phosphor-inventory-manager/blob/master/README.md
+[phosphor logging]:
+ https://github.com/openbmc/phosphor-logging/blob/master/README.md
+[phosphor rest apis]: https://github.com/openbmc/docs/blob/master/rest-api.md
+[phosphor user management]:
+ https://github.com/openbmc/docs/blob/master/architecture/user-management.md
+[phosphor watchdog implementation]: https://github.com/openbmc/phosphor-watchdog
+[power occ implementation]: https://github.com/openbmc/openpower-occ-control
+[remote kvm]: https://github.com/openbmc/obmc-ikvm/blob/master/README.md
+[sensors]:
+ https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md
+[simulation]:
+ https://github.com/openbmc/docs/blob/master/development/dev-environment.md
+[power state management]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/README.md
+[sol how to use]: https://github.com/openbmc/docs/blob/master/console.md
+[webui vue]: https://github.com/openbmc/webui-vue/blob/master/README.md
diff --git a/glossary.md b/glossary.md
index c6b437a..4fde704 100644
--- a/glossary.md
+++ b/glossary.md
@@ -1,42 +1,40 @@
# Glossary
Guidelines:
- - Include terms specific to the OpenBMC project, OpenBMC reference
- platforms (like OpenPower or ASpeed), BMCs, or platform management.
- - Include terms needed to disambiguate. For example, "image" may refer to
- a visual (e.g., JPEG) image or a firmware (e.g. UBIFS) image.
- - Treat acronyms the same as terms.
-BMC - Baseboard management controller. A device designed to enable
-remote out of band management access to a host, generally a computer
-system.
+- Include terms specific to the OpenBMC project, OpenBMC reference platforms
+ (like OpenPower or ASpeed), BMCs, or platform management.
+- Include terms needed to disambiguate. For example, "image" may refer to a
+ visual (e.g., JPEG) image or a firmware (e.g. UBIFS) image.
+- Treat acronyms the same as terms.
-D-Bus - Provides the primary mechanisms for inter-process
-communication with an OpenBMC system. OpenBMC D-Bus APIs are
-documented in `https://github.com/openbmc/phosphor-dbus-interfaces`.
-For example, see the tree under `/xyz/openbmc_project/Led`.
+BMC - Baseboard management controller. A device designed to enable remote out of
+band management access to a host, generally a computer system.
-IPMI - Intelligent Platform Management Interface. OpenBMC implements
-a subset of the IPMI spec.
+D-Bus - Provides the primary mechanisms for inter-process communication with an
+OpenBMC system. OpenBMC D-Bus APIs are documented in
+`https://github.com/openbmc/phosphor-dbus-interfaces`. For example, see the tree
+under `/xyz/openbmc_project/Led`.
-ODM - Original design manufacturer. In OpenBMC, ODM generally refers
-to the manufacturer of the host system.
+IPMI - Intelligent Platform Management Interface. OpenBMC implements a subset of
+the IPMI spec.
-OEM - Original equipment manufacturer. In OpenBMC, OEM generally
-refers to the manufacturer of the host system.
+ODM - Original design manufacturer. In OpenBMC, ODM generally refers to the
+manufacturer of the host system.
-Phosphor - Informally designates OpenBMC software or APIs designed for
-use across many systems, as distinct from platform or vendor-specific
-elements.
+OEM - Original equipment manufacturer. In OpenBMC, OEM generally refers to the
+manufacturer of the host system.
-Redfish - The Distributed Management Task Force (DTMF) Redfish
-specification. OpenBMC provides Redfish REST APIs for platform
-management.
+Phosphor - Informally designates OpenBMC software or APIs designed for use
+across many systems, as distinct from platform or vendor-specific elements.
-REST - Representational State Transfer. OpenBMC provides REST APIs.
+Redfish - The Distributed Management Task Force (DTMF) Redfish specification.
+OpenBMC provides Redfish REST APIs for platform management.
+
+REST - Representational State Transfer. OpenBMC provides REST APIs.
SDR - IPMI Sensor Data Record.
-SEL - IMPI System Event Log. The BMC stores SEL events.
+SEL - IMPI System Event Log. The BMC stores SEL events.
Server - A computing device, generally the one served by the BMC.
diff --git a/host-management.md b/host-management.md
index 1805639..74fcf93 100644
--- a/host-management.md
+++ b/host-management.md
@@ -5,7 +5,8 @@
Note: Authentication
-See the details on authentication at [REST-cheatsheet](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md#establish-rest-connection-session).
+See the details on authentication at
+[REST-cheatsheet](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md#establish-rest-connection-session).
This document uses token based authentication method:
@@ -17,22 +18,24 @@
## Inventory
-The system inventory structure is under the `/xyz/openbmc_project/inventory` hierarchy.
+The system inventory structure is under the `/xyz/openbmc_project/inventory`
+hierarchy.
In OpenBMC the inventory is represented as a path which is hierarchical to the
physical system topology. Items in the inventory are referred to as inventory
items and are not necessarily FRUs (field-replaceable units). If the system
-contains one chassis, a motherboard, and a CPU on the motherboard, then the
-path to that inventory item would be:
+contains one chassis, a motherboard, and a CPU on the motherboard, then the path
+to that inventory item would be:
- `inventory/system/chassis0/motherboard0/cpu0`
+`inventory/system/chassis0/motherboard0/cpu0`
-The properties associated with an inventory item are specific to that item.
-Some common properties are:
+The properties associated with an inventory item are specific to that item. Some
+common properties are:
- * `Version`: A code version associated with this item.
- * `Present`: Indicates whether this item is present in the system (True/False).
- * `Functional`: Indicates whether this item is functioning in the system (True/False).
+- `Version`: A code version associated with this item.
+- `Present`: Indicates whether this item is present in the system (True/False).
+- `Functional`: Indicates whether this item is functioning in the system
+ (True/False).
The usual `list` and `enumerate` REST queries allow the system inventory
structure to be accessed. For example, to enumerate all inventory items and
@@ -60,17 +63,17 @@
These are some common properties:
- * `Value`: Current value of the sensor
- * `Unit`: Unit of the value and "Critical" and "Warning" values
- * `Scale`: The scale of the value and "Critical" and "Warning" values
- * `CriticalHigh` & `CriticalLow`: Sensor device upper/lower critical threshold
-bound
- * `CriticalAlarmHigh` & `CriticalAlarmLow`: True if the sensor has exceeded the
-critical threshold bound
- * `WarningHigh` & `WarningLow`: Sensor device upper/lower warning threshold
-bound
- * `WarningAlarmHigh` & `WarningAlarmLow`: True if the sensor has exceeded the
-warning threshold bound
+- `Value`: Current value of the sensor
+- `Unit`: Unit of the value and "Critical" and "Warning" values
+- `Scale`: The scale of the value and "Critical" and "Warning" values
+- `CriticalHigh` & `CriticalLow`: Sensor device upper/lower critical threshold
+ bound
+- `CriticalAlarmHigh` & `CriticalAlarmLow`: True if the sensor has exceeded the
+ critical threshold bound
+- `WarningHigh` & `WarningLow`: Sensor device upper/lower warning threshold
+ bound
+- `WarningAlarmHigh` & `WarningAlarmLow`: True if the sensor has exceeded the
+ warning threshold bound
A temperature sensor might look like:
@@ -96,7 +99,7 @@
"status": "ok"
}
-Note the value of this sensor is 34.625C (34625 * 10^-3).
+Note the value of this sensor is 34.625C (34625 \* 10^-3).
Unlike IPMI, there are no "functional" sensors in OpenBMC; functional states are
represented in the inventory.
@@ -121,11 +124,12 @@
The properties associated with an event log are as follows:
- * `Message`: The type of event log (e.g. "xyz.openbmc_project.Inventory.Error.NotPresent").
- * `Resolved` : Indicates whether the event has been resolved.
- * `Severity`: The level of problem ("Info", "Error", etc.).
- * `Timestamp`: The date of the event log in epoch time.
- * `Associations`: A URI to the failing inventory part.
+- `Message`: The type of event log (e.g.
+ "xyz.openbmc_project.Inventory.Error.NotPresent").
+- `Resolved` : Indicates whether the event has been resolved.
+- `Severity`: The level of problem ("Info", "Error", etc.).
+- `Timestamp`: The date of the event log in epoch time.
+- `Associations`: A URI to the failing inventory part.
To list all reported event logs:
@@ -165,7 +169,8 @@
"status": "ok"
}
-To delete an event log (log 1 in this example), call the `Delete` method on the event:
+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
@@ -179,39 +184,43 @@
`control/host0/boot` path. Properties include
[`BootMode`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Boot/Mode.interface.yaml),
[`BootSource`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Boot/Source.interface.yaml)
-and if the host is based on x86 CPU also [`BootType`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Boot/Type.interface.yaml).
+and if the host is based on x86 CPU also
+[`BootType`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Control/Boot/Type.interface.yaml).
- * 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"}'
- ```
+ ```
+ $ 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:
+- 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"}'
- ```
+ ```
+ $ 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):
+- 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"}'
- ```
+ ```
+ $ 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) properties that control if the boot source override is persistent or one-time, and if the override is enabled or not.
+Also there are boolean
+[`Enable`](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/Object/Enable.interface.yaml)
+properties that control if the boot source override is persistent or one-time,
+and if the override is enabled or not.
- * Set boot override one-time flag:
+- 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"}'
- ```
+ ```
+ $ 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:
+- 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"}'
- ```
+ ```
+ $ 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
@@ -243,7 +252,6 @@
$ 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
@@ -256,19 +264,19 @@
The BMC implements a function that simply clears this partition. This function
can be called as follows:
- * Method 1: From the BMC command line:
+- Method 1: From the BMC command line:
- ```
- busctl call org.open_power.Software.Host.Updater \
- /org/open_power/control/gard \
- xyz.openbmc_project.Common.FactoryReset Reset
- ```
+ ```
+ 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:
+- 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
- ```
+ ```
+ $ 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
@@ -300,8 +308,8 @@
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 the `obmc-host-startmin@.target`. Service dependencies ensure the service is
+`obmc-enable-host-watchdog` starts the watchdog timer. Both are run as a part of
+the `obmc-host-startmin@.target`. Service dependencies ensure the service is
started before the enable is called.
The default watchdog timeout can be found within the [dbus interface
@@ -310,4 +318,5 @@
The host controls the watchdog timeout and enable/disable once it starts.
[1]: https://github.com/openbmc/phosphor-watchdog
-[2]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Watchdog.interface.yaml
+[2]:
+ https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/yaml/xyz/openbmc_project/State/Watchdog.interface.yaml
diff --git a/kernel-development.md b/kernel-development.md
index 45bfa58..ed092f2 100644
--- a/kernel-development.md
+++ b/kernel-development.md
@@ -1,54 +1,92 @@
# OpenBMC kernel development
-The OpenBMC project maintains a kernel tree for use by the project. The tree's general development policy is that code must be upstream first. This is a strong 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 project maintains a kernel tree for use by the project. The tree's
+general development policy is that code must be upstream first. This is a strong
+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 contains the set of patches that we carry. Ideally there would be no patches carried, as everything should be upstream.
+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.
-Your code will make it into the OpenBMC tree in these ways, from most to least desirable:
+Your code will make it into the OpenBMC tree in these ways, from most to least
+desirable:
1. When the OpenBMC kernel moves to a new upstream release
-2. By backporting upstream commits from a newer kernel version to the OpenBMC kernel
+2. By backporting upstream commits from a newer kernel version to the OpenBMC
+ kernel
3. Patches included in the OpenBMC tree temporarily
## TL;DR
If you require a patch added to the tree, follow these steps:
-1. Submit your patch upstream. It doesn't need to be upstream, but it should be on it's way
-2. Use ```git format-patch --subject-prefix="PATCH linux dev-4.7" --to=openbmc@lists.ozlabs.org --to=joel@jms.id.au``` to create a formatted patch
+1. Submit your patch upstream. It doesn't need to be upstream, but it should be
+ on it's way
+2. Use
+ `git format-patch --subject-prefix="PATCH linux dev-4.7" --to=openbmc@lists.ozlabs.org --to=joel@jms.id.au`
+ to create a formatted patch
## Developing a new driver
-When developing a new driver, your goal is to have the code accepted upstream. The first step should be to check that there is no existing driver for the hardware you wish to support. Check the OpenBMC `-dev` tree, check upstream, and if you do not find support there ask on the mailing list.
+When developing a new driver, your goal is to have the code accepted upstream.
+The first step should be to check that there is no existing driver for the
+hardware you wish to support. Check the OpenBMC `-dev` tree, check upstream, and
+if you do not find support there ask on the mailing list.
-Once you are sure a driver needs to be written, you should develop and test the driver, before sending it upstream to the relevant maintainers. You should feel welcome to cc the OpenBMC list when sending upstream, so other kernel developers can provide input where appropriate. Be sure to follow the (upstream development process)[https://www.kernel.org/doc/Documentation/process/submitting-patches.rst].
+Once you are sure a driver needs to be written, you should develop and test the
+driver, before sending it upstream to the relevant maintainers. You should feel
+welcome to cc the OpenBMC list when sending upstream, so other kernel developers
+can provide input where appropriate. Be sure to follow the (upstream development
+process)[https://www.kernel.org/doc/Documentation/process/submitting-patches.rst].
-In the past patches underwent 'pre-review' on the OpenBMC mailing list. While this is useful for developers who are not familiar with writing kernel code, it has lead to confusion about the upstreaming process, so now we do all of our development in the community.
+In the past patches underwent 'pre-review' on the OpenBMC mailing list. While
+this is useful for developers who are not familiar with writing kernel code, it
+has lead to confusion about the upstreaming process, so now we do all of our
+development in the community.
-Once the driver has been accepted upstream, send the good news to the OpenBMC list with a reference to the upstream tree. This may be Linus' tree, or it might be one of the subsystem maintainers. From there the OpenBMC kernel team can decide how best to include your code in the OpenBMC tree.
+Once the driver has been accepted upstream, send the good news to the OpenBMC
+list with a reference to the upstream tree. This may be Linus' tree, or it might
+be one of the subsystem maintainers. From there the OpenBMC kernel team can
+decide how best to include your code in the OpenBMC tree.
### Exceptions
-There are cases where waiting for upstream acceptance will delay the bring-up of a new system. This should be avoided through careful planning and early development of the features upstream, but where this has not happened we can chose to carry the patches in the OpenBMC tree while the upstream development is ongoing.
+There are cases where waiting for upstream acceptance will delay the bring-up of
+a new system. This should be avoided through careful planning and early
+development of the features upstream, but where this has not happened we can
+chose to carry the patches in the OpenBMC tree while the upstream development is
+ongoing.
-Another exception to the upstream first rule is where patches are modifying files that are not upstream. This currently includes the aspeed board file `arch/arm/mach-aspeed/aspeed.c`, and the device tree source files `dts`. The board file should go away when we get drivers written for all of the functionality; for now it contains some hacks relating to LPC and early init.
+Another exception to the upstream first rule is where patches are modifying
+files that are not upstream. This currently includes the aspeed board file
+`arch/arm/mach-aspeed/aspeed.c`, and the device tree source files `dts`. The
+board file should go away when we get drivers written for all of the
+functionality; for now it contains some hacks relating to LPC and early init.
-If you find yourself adding to `arch/arm/mach-aspeed/aspeed.c`, first send an email to the OpenBMC list to get the opinion of the kernel developers. Patches to `aspeed.c` will be treated with some prejudice as the file will be removed once we have drivers for all of the Aspeed peripherals.
+If you find yourself adding to `arch/arm/mach-aspeed/aspeed.c`, first send an
+email to the OpenBMC list to get the opinion of the kernel developers. Patches
+to `aspeed.c` will be treated with some prejudice as the file will be removed
+once we have drivers for all of the Aspeed peripherals.
## Getting existing code in the tree
-The OpenBMC kernel is currently based on the 4.7 series. If there is upstream code you would like backported, send it to the list. Be sure to include the upstream commit SHA in the commit message.
+The OpenBMC kernel is currently based on the 4.7 series. If there is upstream
+code you would like backported, send it to the list. Be sure to include the
+upstream commit SHA in the commit message.
## Testing
When modifying the tree we currently test on the following platforms:
- - Palmetto, an OpenPower Power8 box containing an ast2400 with NCSI networking
- - ast2500-evb, the Aspeed dev board with two PHYs
- - Witherspoon, an OpenPower Power9 box containing an ast2500 with NCSI networking
- - qemu-plametto and qemu-romulus
+- Palmetto, an OpenPower Power8 box containing an ast2400 with NCSI networking
+- ast2500-evb, the Aspeed dev board with two PHYs
+- Witherspoon, an OpenPower Power9 box containing an ast2500 with NCSI
+ networking
+- qemu-plametto and qemu-romulus
-Before submitting patches it is recommended you boot test on at least the Qemu platforms, and whatever hardware you have available.
+Before submitting patches it is recommended you boot test on at least the Qemu
+platforms, and whatever hardware you have available.
# Tips and Tricks
diff --git a/maintainer-workflow.md b/maintainer-workflow.md
index 907c613..cdd92ea 100644
--- a/maintainer-workflow.md
+++ b/maintainer-workflow.md
@@ -1,44 +1,45 @@
# OpenBMC Maintainer/CLA Workflow
-OpenBMC contributors are required to execute an OpenBMC CLA (Contributor
-License Agreement) before their contributions can be accepted. This page is a
-checklist for sub-project maintainers to follow before approving patches.
-* Manually verify the contributor has signed the ICLA (individual) or is
-listed 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.
- * 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.
- * 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].
+OpenBMC contributors are required to execute an OpenBMC CLA (Contributor License
+Agreement) before their contributions can be accepted. This page is a checklist
+for sub-project maintainers to follow before approving patches.
-An executed OpenBMC CLA is _not_ required to accept contributions to
-OpenBMC forks of upstream projects, like the Linux kernel or U-Boot.
+- Manually verify the contributor has signed the ICLA (individual) or is listed
+ 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.
+ - 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.
+ - 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].
-Review the maintainers' responsibilities in the [contributing
-guidelines](./CONTRIBUTING.md). Maintainers are ultimately
-responsible for sorting out open source license issues, issues with
-using code copied from the web, and maintaining the quality of the
-code.
+An executed OpenBMC CLA is _not_ required to accept contributions to OpenBMC
+forks of upstream projects, like the Linux kernel or U-Boot.
-Repository maintainers ought to have the following traits as
-recognized by a consensus of their peers:
- - responsible: have a continuing desire to ensure only high-quality
- code goes into the repo
- - leadership: foster open-source aware practices such as [FOSS][4]
- - expertise: typically demonstrated by significant contributions to
- the code or code reviews
+Review the maintainers' responsibilities in the
+[contributing guidelines](./CONTRIBUTING.md). Maintainers are ultimately
+responsible for sorting out open source license issues, issues with using code
+copied from the web, and maintaining the quality of the code.
+
+Repository maintainers ought to have the following traits as recognized by a
+consensus of their peers:
+
+- responsible: have a continuing desire to ensure only high-quality code goes
+ into the repo
+- leadership: foster open-source aware practices such as [FOSS][4]
+- expertise: typically demonstrated by significant contributions to the code or
+ code reviews
(1) The semantics of accepting a patch depend on the sub-project contribution
process.
-* GitHub pull requests - Merging the pull request.
-* Gerrit - +2.
-* email - Merging the patch.
+- GitHub pull requests - Merging the pull request.
+- Gerrit - +2.
+- email - Merging the patch.
Ensure that accepted changes actually merge into OpenBMC repositories.
diff --git a/meta-layer-guidelines.md b/meta-layer-guidelines.md
index 25e5487..9323386 100644
--- a/meta-layer-guidelines.md
+++ b/meta-layer-guidelines.md
@@ -1,24 +1,24 @@
# OpenBMC meta layer guidelines
While most of these could be called "rules", in specific scenarios might be
-actively against the intended goals. This is why each guideline has a very
-large "Why" section, to ensure that the intent is being met, and that if
-exceptions to the rules exist, then can be understood and managed by the
-project. In general, if there's a question, and the community agrees, these
-guidelines can be overridden on a case by case basis.
+actively against the intended goals. This is why each guideline has a very large
+"Why" section, to ensure that the intent is being met, and that if exceptions to
+the rules exist, then can be understood and managed by the project. In general,
+if there's a question, and the community agrees, these guidelines can be
+overridden on a case by case basis.
## Meta layers should not patch projects that exist within the openBMC tree
**Why?**
-In general, keeping the codebase building in the long term is difficult.
-Opening the possibility that patches exist that repo maintainers aren't aware
-of makes it much more likely that a single machine breaks, or we have behavior
+In general, keeping the codebase building in the long term is difficult. Opening
+the possibility that patches exist that repo maintainers aren't aware of makes
+it much more likely that a single machine breaks, or we have behavior
differences between two repos.
Also, in general, the maintainer is there to ensure that the greater community,
features, and codebase are prioritized over any one patch, and generally does so
-in code review. If patches are checked into meta layers, generally the
+in code review. If patches are checked into meta layers, generally the
maintainer is not a reviewer, thereby defeating most of the purpose of the role
of the maintainer.
@@ -26,7 +26,7 @@
Discuss with the project maintainers and the community about whether or not the
feature you're building needs to be configurable, or if it can be applied to all
-projects. If it can be applied to all, simply check it into the master branch
+projects. If it can be applied to all, simply check it into the master branch
through a gerrit review, and follow the processes outlined for the repository.
If it needs to be per-project or per-machine configurable, check it in under a
compile time option, at the suggestion of the maintainer, and add a
@@ -36,18 +36,18 @@
**Why?**
-Yocto itself is an open source project that accepts contributions. The more
+Yocto itself is an open source project that accepts contributions. The more
changes that OpenBMC stacks against Yocto recipes, the more unmaintainable it
-becomes, and the longer it takes to rebase to new Yocto versions. In general,
+becomes, and the longer it takes to rebase to new Yocto versions. In general,
the Yocto community is as responsive (sometimes much faster) than the OpenBMC
community in regards to pull requests.
**What should I do instead?**
Submit any changes needed to the Yocto upstream repositories, using their
-process. If the Yocto process has gone several weeks without responses,
+process. If the Yocto process has gone several weeks without responses,
cherry-pick the commit into the OpenBMC tree, with a pointer to the review in
-the commit message, and documentation. The patch commit message should follow
+the commit message, and documentation. The patch commit message should follow
the Yocto requirements for patch comments, including a statement of the patch
upstream status.
[yocto patch requirements](https://wiki.yoctoproject.org/wiki/Best_Known_Methods_%28BKMs%29_for_Package_Updating#Patch_Comments)
@@ -56,14 +56,14 @@
**Why?**
-There are some OpenBMC projects that are utilized outside of OpenBMC. As such,
+There are some OpenBMC projects that are utilized outside of OpenBMC. As such,
there are configuration items that are not intended to be used in OpenBMC, or
-configuration items that would pose a security risk. Also, as options change
-and are deprecated, the project needs a single place to update the available
-config items and dependencies.
+configuration items that would pose a security risk. Also, as options change and
+are deprecated, the project needs a single place to update the available config
+items and dependencies.
In addition, subprojects might change their build tooling, for example from
-autotools to meson, in pursuit of other goals. Having tool-specific
+autotools to meson, in pursuit of other goals. Having tool-specific
configurations makes that change far more difficult to do.
**What should I do instead?**
@@ -76,7 +76,7 @@
**Why?**
OpenBMC is an open source project, and is intended to be built from source, with
-appropriate distribution licenses such that it can be reused. Pointing to
+appropriate distribution licenses such that it can be reused. Pointing to
commercially licensed repositories actively opposes that goal.
**What should I do instead?**
@@ -90,7 +90,7 @@
Without this guideline, a loophole is present that allows OpenBMC developers to
bypass code review by pointing the upstream recipe to a public repository that
-they control, but which OpenBMC has no input on the content of. This splits the
+they control, but which OpenBMC has no input on the content of. This splits the
discussion forums in unproductive ways, and prevents all the other good
processes within OpenBMC like bug tracking and continuous integration from
having an effect.
@@ -100,47 +100,49 @@
The advice tends to be on a case by case basis, but if the code is only intended
for use on OpenBMC, then push a design doc, and push the code to openbmc gerrit
under the openbmc/openbmc repository where it can be reviewed, along with an
-OWNERS file, signaling your willingness to maintain this project. Then, once
-the community has looked through your design, a repo will be created for code to
-be pushed to. If you're pulling in code from a dead project, inquire to the
+OWNERS file, signaling your willingness to maintain this project. Then, once the
+community has looked through your design, a repo will be created for code to be
+pushed to. If you're pulling in code from a dead project, inquire to the
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
+
+https://github.com/openbmc
**What defines an OpenBMC specific repository?**
Generally an OpenBMC specific repository is something that does any of the
following:
-* Relies on or implements on OpenBMC defined Dbus interfaces.
-* Is not designed with configurability to be used outside of OpenBMC
-* Relies on OpenBMC specific layouts, configuration information to accomplish
+
+- Relies on or implements on OpenBMC defined Dbus interfaces.
+- Is not designed with configurability to be used outside of OpenBMC
+- Relies on OpenBMC specific layouts, configuration information to accomplish
its primary function.
**Why?**
-OpenBMC as a codebase needs to remain buildable in the long term. Companies,
+OpenBMC as a codebase needs to remain buildable in the long term. Companies,
maintainers, and contributors come and go over the course of the project.
Keeping all long-term-supported code in the OpenBMC github ensures that the
-project will remain useful. In addition, having significant portions of
-OpenBMC-specific code outside of github limits the ability of the project to
-do refactoring that might be necessary to keep up with the latest best
-practices, Yocto updates, and package revisions, as there isn't always a clear
-path to getting patches accepted when repositories are not within the OpenBMC
-github project
+project will remain useful. In addition, having significant portions of
+OpenBMC-specific code outside of github limits the ability of the project to do
+refactoring that might be necessary to keep up with the latest best practices,
+Yocto updates, and package revisions, as there isn't always a clear path to
+getting patches accepted when repositories are not within the OpenBMC github
+project
**What should I do instead?**
Discuss the code you'd like to write with the community using the mailing list
-and/or discord. If the design would require a new repository, request one using
+and/or discord. If the design would require a new repository, request one using
the OpenBMC technical oversight committee process.
## Don't use SRCREV="${AUTOREV}" in a recipe
**Why?**
-Repository branches can change at any time. Pointing to an autorev revision
+Repository branches can change at any time. Pointing to an autorev revision
increases the likelihood that builds break, and makes builds far less
reproducible.
diff --git a/openbmc-conversion.md b/openbmc-conversion.md
index e43b905..32214a6 100644
--- a/openbmc-conversion.md
+++ b/openbmc-conversion.md
@@ -1,14 +1,16 @@
-# Converting to OpenBMC from AMI firmware #
+# Converting to OpenBMC from AMI firmware
Often a number of steps are required to convert from the AMI firmware to
OpenBMC. These steps are documented for various machines below.
-## Palmetto ##
+## Palmetto
-1. Upgrade the firmware flash chip to 256Mb (32MB) part (MX25L25635E or equivalent)
-2. [Build](cheatsheet.md#building-for-palmetto) and flash the `image-bmc`
- output to the 256Mb flash chip
-3. Replace existing flash chip on the motherboard (cradle closest to the battery)
+1. Upgrade the firmware flash chip to 256Mb (32MB) part (MX25L25635E or
+ equivalent)
+2. [Build](cheatsheet.md#building-for-palmetto) and flash the `image-bmc` output
+ to the 256Mb flash chip
+3. Replace existing flash chip on the motherboard (cradle closest to the
+ battery)
4. Manufacture a cable to connect to the COM2 header for the BMC console. COM2
is wired for a DB-9-style pin-out.
5. Reconfigure both `BMC_DEBUG1` (TX) and `BMC_DEBUG2` (RX) jumpers to short
diff --git a/release/release-notes.md b/release/release-notes.md
index 3944e60..1d7d3d2 100644
--- a/release/release-notes.md
+++ b/release/release-notes.md
@@ -1,8 +1,8 @@
# OpenBMC Release Notes
The OpenBMC project now has a regular release cycle with stable branches
-starting with the 2.6 release. Prior release tag notes are also listed here
-for completeness.
+starting with the 2.6 release. Prior release tag notes are also listed here for
+completeness.
Read more about the release process here:
https://github.com/openbmc/docs/blob/master/release/release-process.md
@@ -10,86 +10,101 @@
For information on how to checkout a particular branch or tag, see:
https://github.com/openbmc/openbmc/wiki/Releases
-
## OpenBMC Releases
+
### 2.9 January, 2021
+
#### Features:
- - Yocto refresh to "Gatesgarth" 3.2
- - Partial Redfish support for properties from the 2020.1, 2020.2, and 2020.3 Schemas
- - Redfish support for: Dump, Multiple Firmware Image Support
- - Added webui-vue, a web-based user interface built of Vue.js
- - A replacement for phosphor-webui
- - Uses Redfish
- - Ability to easily theme to meet brand guidelines
- - Language translation-ready
- - Improved user experience
+
+- Yocto refresh to "Gatesgarth" 3.2
+- Partial Redfish support for properties from the 2020.1, 2020.2, and 2020.3
+ Schemas
+- Redfish support for: Dump, Multiple Firmware Image Support
+- Added webui-vue, a web-based user interface built of Vue.js
+ - A replacement for phosphor-webui
+ - Uses Redfish
+ - Ability to easily theme to meet brand guidelines
+ - Language translation-ready
+ - Improved user experience
+
#### Fixes and Known Issues/Limitations:
+
#### Security audit results:
### 2.8 June, 2020
+
#### Features:
- - Yocto refresh to "Dunfell" version 3.1
- - Redfish support for:
- - full certificate management
- - complete LDAP management
- - full sensor support
- - event service schema
- - task schema
- - Move to Redfish Specification 1.9.0
- - Redfish support for 2020.1 Schemas
- - GUI enhancements:
- - LDAP
- - certificate management
- - mTLS HTTPS authentication
- - Partial PLDM Support
- - Partial MCTP Support
+
+- Yocto refresh to "Dunfell" version 3.1
+- Redfish support for:
+ - full certificate management
+ - complete LDAP management
+ - full sensor support
+ - event service schema
+ - task schema
+- Move to Redfish Specification 1.9.0
+- Redfish support for 2020.1 Schemas
+- GUI enhancements:
+ - LDAP
+ - certificate management
+- mTLS HTTPS authentication
+- Partial PLDM Support
+- Partial MCTP Support
#### Fixes and Known Issues/Limitations:
- - Enabling and disabling DHCP via Redfish is not working (openbmc/bmcweb #127)
- - LDAP login will fail for users belonging to the redfish group
- - Unable to configure IP address on VLAN interface (openbmc/openbmc #3668)
- - Unable create VLAN via IPMI (openbmc/phosphor-net-ipmid #12)
+
+- Enabling and disabling DHCP via Redfish is not working (openbmc/bmcweb #127)
+- LDAP login will fail for users belonging to the redfish group
+- Unable to configure IP address on VLAN interface (openbmc/openbmc #3668)
+- Unable create VLAN via IPMI (openbmc/phosphor-net-ipmid #12)
#### Security audit results:
- - IPMI RMCP+ cipher suite 3 was removed, leaving only cipher suite 17
-(https://github.com/openbmc/phosphor-net-ipmid/commit/4c494398a36d9f1bdc4f256f937487c7ebcc4e95)
- - The fix for CVE-2020-14156 is present. This affects images that have IPMI
-users (https://github.com/openbmc/openbmc/issues/3670)
+
+- IPMI RMCP+ cipher suite 3 was removed, leaving only cipher suite 17
+ (https://github.com/openbmc/phosphor-net-ipmid/commit/4c494398a36d9f1bdc4f256f937487c7ebcc4e95)
+- The fix for CVE-2020-14156 is present. This affects images that have IPMI
+ users (https://github.com/openbmc/openbmc/issues/3670)
### 2.7 Aug 5, 2019
+
#### Features:
- - Yocto refresh to "Warrior" version 2.7
- - Removal of Python for footprint reduction: python is no longer required
-for the meta-phosphor layer and its defaults
- - Finished up KVM over IP: adds the infrastructure to allow KVM sessions
-through the webui
- - NVMe-MI over SMBus
- - ECC logging for BMC: service to monitor EDAC driver and BMC log
- - Partial PLDM Support
- - Partial MCTP Support
- - Redfish support for: partial Certificates, local user management, partial
-LDAP, network, event logging, DateTime, boot devices, firmware update,
-inventory and sensors
- - phosphor-ipmi-flash support: sending firmware images over IPMI, pci-aspeed,
-and other mechanisms for host-driven updates
- - GUI enhancements: multiple user support, virtual media, KVM
+
+- Yocto refresh to "Warrior" version 2.7
+- Removal of Python for footprint reduction: python is no longer required for
+ the meta-phosphor layer and its defaults
+- Finished up KVM over IP: adds the infrastructure to allow KVM sessions through
+ the webui
+- NVMe-MI over SMBus
+- ECC logging for BMC: service to monitor EDAC driver and BMC log
+- Partial PLDM Support
+- Partial MCTP Support
+- Redfish support for: partial Certificates, local user management, partial
+ LDAP, network, event logging, DateTime, boot devices, firmware update,
+ inventory and sensors
+- phosphor-ipmi-flash support: sending firmware images over IPMI, pci-aspeed,
+ and other mechanisms for host-driven updates
+- GUI enhancements: multiple user support, virtual media, KVM
#### Fixes and Known Issues/Limitations:
- - Yocto Warrior subtree refresh applied (24230)
+
+- Yocto Warrior subtree refresh applied (24230)
### 2.6 Feb 4, 2019
-***First Release as Linux Foundation Project***
+
+**_First Release as Linux Foundation Project_**
#### Features:
- - Yocto refresh to "Thud" version 2.6
- - GUI enhancements: SNMP and Date/Time
- - Serial over Lan
- - IPMI 2.0 support
- - Partial Redfish support
- - Kernel updated to 4.19 LTS
+
+- Yocto refresh to "Thud" version 2.6
+- GUI enhancements: SNMP and Date/Time
+- Serial over Lan
+- IPMI 2.0 support
+- Partial Redfish support
+- Kernel updated to 4.19 LTS
#### Known Issues/Limitations:
- - Support dropped for the ipmitool nameless option
+
+- Support dropped for the ipmitool nameless option
## Release tags with notes prior to release branching
@@ -97,200 +112,200 @@
#### Updates:
- - Cache all inventory properties and preserve inventory during BMC firmware
- update (#487)
- - Update the power button behavior on Barreleye to:
- - Short press: Only power on. Remove the power off action
- - Long press (>3 seconds): Hard power off
+- Cache all inventory properties and preserve inventory during BMC firmware
+ update (#487)
+- Update the power button behavior on Barreleye to:
+ - Short press: Only power on. Remove the power off action
+ - Long press (>3 seconds): Hard power off
### v1.0.4 Aug 8, 2016
#### Changes:
- - Kernel version update:
- - Stable release 4.4.16
- - Power button debounce fix for Barreleye
- - Fix for an NCSI race condition that caused the device to not come up
- (openbmc/phosphor-networkd#18)
- - Load inventory from cache (#487)
- - Start host watchdog timer after magic sequence (openbmc/skeleton#127)
- - Restart REST server when network configuration changes
- (openbmc/phosphor-rest-server#24)
+- Kernel version update:
+ - Stable release 4.4.16
+ - Power button debounce fix for Barreleye
+ - Fix for an NCSI race condition that caused the device to not come up
+ (openbmc/phosphor-networkd#18)
+- Load inventory from cache (#487)
+- Start host watchdog timer after magic sequence (openbmc/skeleton#127)
+- Restart REST server when network configuration changes
+ (openbmc/phosphor-rest-server#24)
### v1.0.3 Jul 18, 2016
#### Updates:
- - Fix issue in Host IPMI inventory due to versioned shared libraries (#423)
+- Fix issue in Host IPMI inventory due to versioned shared libraries (#423)
### v1.0.2 Jul 5, 2016
#### Updates:
- - Add ability to perform BMC code update at runtime and get the BMC code
- update progress through REST
- - Fix event log directory duplication during BMC code update
- - Fix hwmon attribute not being polled after failure
+- Add ability to perform BMC code update at runtime and get the BMC code update
+ progress through REST
+- Fix event log directory duplication during BMC code update
+- Fix hwmon attribute not being polled after failure
### v1.0.1 Jun 27, 2016
#### Release Notes:
- - Fix encode firmware version in BCD format
- - Handle floating point sensor values
- - Performance improvements to prevent services from failing to start
- - Extend the mapper service startup timeout to ensure it starts up
- - Enable DNS resolution from DHCP
+- Fix encode firmware version in BCD format
+- Handle floating point sensor values
+- Performance improvements to prevent services from failing to start
+- Extend the mapper service startup timeout to ensure it starts up
+- Enable DNS resolution from DHCP
### v1.0 Jun 20, 2016
#### Features:
- - Enable one-time vs permanent host boot option
- - Enable handling of host checkstop gpio
- - Handle endianness in IPMI eSEL function
- - Improve IPMI error handling
- - Add IPMI Travis CI
- - Fix host hanging due to inventory upload
- - Fix i2c-tools SRC url syntax
- - Fix sensor attribute reading
- - Fix limit of number of event logs
- - Add adm1278 driver into the Linux kernel by default
- - Automatically restart phosphor service processes
- - Enable out-of-tree kernel device trees
- - Update pflash version
- - Update u-boot version
- - Fix memory corruption
- - Update kernel version
- - Stable 4.4.12 release
- - Pick up i2c completion fix
- - Add power button debounce function for Barreleye
- - Remove development tool rest-dbus from Barreleye image
- - BMC performance improvements
+- Enable one-time vs permanent host boot option
+- Enable handling of host checkstop gpio
+- Handle endianness in IPMI eSEL function
+- Improve IPMI error handling
+- Add IPMI Travis CI
+- Fix host hanging due to inventory upload
+- Fix i2c-tools SRC url syntax
+- Fix sensor attribute reading
+- Fix limit of number of event logs
+- Add adm1278 driver into the Linux kernel by default
+- Automatically restart phosphor service processes
+- Enable out-of-tree kernel device trees
+- Update pflash version
+- Update u-boot version
+ - Fix memory corruption
+- Update kernel version
+ - Stable 4.4.12 release
+ - Pick up i2c completion fix
+ - Add power button debounce function for Barreleye
+- Remove development tool rest-dbus from Barreleye image
+- BMC performance improvements
### v0.8 May 20, 2016
#### Updates:
- - Update pflash version
- - Host console support for local tty mirroring
- - Cap number of event logs at 128
- - BMC boot performance improvements
- - Linux updates:
- - Update to 4.4.10 release
- - Fix network cable link detection
- - Support for VOUT sampling to the adm1275 driver
- - Add eeprom to barreleye device tree
- - Fix OCC sensor activation
+- Update pflash version
+- Host console support for local tty mirroring
+- Cap number of event logs at 128
+- BMC boot performance improvements
+- Linux updates:
+ - Update to 4.4.10 release
+ - Fix network cable link detection
+ - Support for VOUT sampling to the adm1275 driver
+ - Add eeprom to barreleye device tree
+ - Fix OCC sensor activation
### v0.7 May 5, 2016
#### Updates:
- - Update to kernel 4.4
- - Update to yocto 2.0.1
- - Use upstream pflash
+- Update to kernel 4.4
+- Update to yocto 2.0.1
+- Use upstream pflash
#### Features:
- - Device tree
- - New host console.
- - Documentation: https://github.com/openbmc/docs/blob/master/console.md
- - REST association support
- - Dmidecode support
- - New REST interface to query network type (dhcp/static) under
- NetworkManager->GetAddressType
+- Device tree
+- New host console.
+ - Documentation: https://github.com/openbmc/docs/blob/master/console.md
+- REST association support
+- Dmidecode support
+- New REST interface to query network type (dhcp/static) under
+ NetworkManager->GetAddressType
#### Fix:
- - Add CPU1 fru data to inventory
+- Add CPU1 fru data to inventory
### v0.6.1 Mar 22, 2016
#### Fixes:
- - JFFS2 corruption
- - random segmentation faults
- - keep event logs from filling up flash. They are limited to 200K
- - OCC 12core fix
- - PCIe slot presence detect
- - SCU fix for networking issue
+- JFFS2 corruption
+- random segmentation faults
+- keep event logs from filling up flash. They are limited to 200K
+- OCC 12core fix
+- PCIe slot presence detect
+- SCU fix for networking issue
### v0.6 Mar 7, 2016
#### New features:
- - Immediate MAC address set via IPMI and REST; no reboot necessary
- - full user setup via REST
- - Boot to RAM filesystem so SOCFlash and pflash can be used from host
- - ADM1278 support
- - Custom LED blink rate
- - inARP support
+- Immediate MAC address set via IPMI and REST; no reboot necessary
+- full user setup via REST
+- Boot to RAM filesystem so SOCFlash and pflash can be used from host
+- ADM1278 support
+- Custom LED blink rate
+- inARP support
#### Fixes:
- - ipmid memory leak
- - SBE reboot issue
+- ipmid memory leak
+- SBE reboot issue
### v0.5 Feb 17, 2016
#### New Features:
- - Automatically run fsck to avoid file system corrupt
- - Full LAN get/set support via REST and ipmitool
- - User setup via REST support
- - NCSI driver enhancements
- - Virtual UART; improved hconsole
- - Persistent event logs
- - Persistent UUID based on /etc/machine-id
- - Full LED support
+- Automatically run fsck to avoid file system corrupt
+- Full LAN get/set support via REST and ipmitool
+- User setup via REST support
+- NCSI driver enhancements
+- Virtual UART; improved hconsole
+- Persistent event logs
+- Persistent UUID based on /etc/machine-id
+- Full LED support
### v0.4 Feb 4, 2016
#### New Features:
- - Persistent file system
- - network configuration is persistent across boots and flashing
- - LAN set functions
- - Selectable flash update (u-boot, initramfs, kernel, settings)
- - fw utils for update u-boot environment variables
- - power capping and measurements
- - power restore policy
+- Persistent file system
+- network configuration is persistent across boots and flashing
+- LAN set functions
+- Selectable flash update (u-boot, initramfs, kernel, settings)
+- fw utils for update u-boot environment variables
+- power capping and measurements
+- power restore policy
#### Notes/Limitations:
- - Currently using ext4 for R/W file system. Need to migrate to JFFS which is
- designed for flashes and more resilient to AC power loss. Please 'poweroff'
- BMC before pulling AC power for now
+- Currently using ext4 for R/W file system. Need to migrate to JFFS which is
+ designed for flashes and more resilient to AC power loss. Please 'poweroff'
+ BMC before pulling AC power for now
#### Missing Functions:
- - Persistent event logs
- - LAN get functions
- - User set/get functions
- - Proper LED representation
+- Persistent event logs
+- LAN get functions
+- User set/get functions
+- Proper LED representation
### v0.2 Dec 4, 2015
#### Release Notes:
- - Added CPU thermal sensors (/org/openbmc/sensors/temperature/cpu0 and 1)
- - Added full soft power off and reset support from host or BMC
- - Reboot issue fixed
- - Power button fixed
- - Network crash issue fixed
- - Added delete event log from REST
- - Cleaned up inventory
- - consistent states
- - io_board fru is populated from eeprom
+- Added CPU thermal sensors (/org/openbmc/sensors/temperature/cpu0 and 1)
+- Added full soft power off and reset support from host or BMC
+- Reboot issue fixed
+- Power button fixed
+- Network crash issue fixed
+- Added delete event log from REST
+- Cleaned up inventory
+- consistent states
+- io_board fru is populated from eeprom
#### Known issues:
- - OCC driver unloading and loading prints harmless error messages to console
- - About 1 out of every 5 boots you will see the ftgmac driver print out a
-trace stack. This appears to be harmless, but we are investigating
+- OCC driver unloading and loading prints harmless error messages to console
+- About 1 out of every 5 boots you will see the ftgmac driver print out a trace
+ stack. This appears to be harmless, but we are investigating
#### Not supported:
- - Sensor thresholds
- - Setting boot options through REST
+- Sensor thresholds
+- Setting boot options through REST
diff --git a/release/release-process.md b/release/release-process.md
index 762e5d5..1299df4 100644
--- a/release/release-process.md
+++ b/release/release-process.md
@@ -1,25 +1,27 @@
# OpenBMC Release Process
-The OpenBMC release process document is the output of the Release Planning
-work group. This documents the set of topics that have been discussed and
-agreed upon to date, defining such things as the release process and schedule,
-milestones, content definition and feature prioritization. All the decisions
-were made in the work group meetings, with representatives from each member
-company.
+
+The OpenBMC release process document is the output of the Release Planning work
+group. This documents the set of topics that have been discussed and agreed upon
+to date, defining such things as the release process and schedule, milestones,
+content definition and feature prioritization. All the decisions were made in
+the work group meetings, with representatives from each member company.
https://github.com/openbmc/openbmc/wiki/Release-Planning
## Release Cycle
### Schedule
-OpenBMC has its initial formal release branch as a Linux Foundation project
-in February 2019, with a new release branch following every 6 months. Releases
-are purposefully offset from Yocto releases by a few weeks to allow for
-integration and testing. Member companies are expected to test a release
-candidate on their platform and report their findings.
+
+OpenBMC has its initial formal release branch as a Linux Foundation project in
+February 2019, with a new release branch following every 6 months. Releases are
+purposefully offset from Yocto releases by a few weeks to allow for integration
+and testing. Member companies are expected to test a release candidate on their
+platform and report their findings.
### Versioning
-The OpenBMC release will follow the Yocto numbering with slight modification
-to allow for build information. The release version will follow the form:
+
+The OpenBMC release will follow the Yocto numbering with slight modification to
+allow for build information. The release version will follow the form:
Major.Minor.Fix.obmc-build. For example:
`2.6.4.obmc-2`
@@ -28,28 +30,32 @@
build 2.
### Milestones
+
Milestones are important dates within a release cycle. The milestone dates
-agreed to are as follows: Design, Code, Freeze, and Release. The milestones
-will each have entry and exit criteria. Milestone dates currently are not
-yet implemented.
+agreed to are as follows: Design, Code, Freeze, and Release. The milestones will
+each have entry and exit criteria. Milestone dates currently are not yet
+implemented.
#### Design
+
This is the date in the release cycle when a feature's design must be discussed
-openly and completed. The design should follow the published design template
-and be merged before this milestone. If this is not met, then the feature is
-at risk for not being merged for the forming release cycle.
+openly and completed. The design should follow the published design template and
+be merged before this milestone. If this is not met, then the feature is at risk
+for not being merged for the forming release cycle.
The Design Template can be found here:
https://github.com/openbmc/docs/blob/master/designs/design-template.md
#### Code
+
This milestone represents some major functionality that has to be completed by
this date in order for the feature to be delivered on time. It is a checkpoint
-for the developers doing the work to evaluate and commit to for having that
-part complete. Globally there can be one or more code milestones established,
-but currently these are TBD.
+for the developers doing the work to evaluate and commit to for having that part
+complete. Globally there can be one or more code milestones established, but
+currently these are TBD.
#### Freeze
+
This is the date where the release content is frozen, that is, no new major
content will be accepted. This is necessary to allow time for the new features
to be fully tested. Any defects found will be evaluated to be included or not,
@@ -58,36 +64,39 @@
release milestone. Release tagging/branching can accommodate master development
efforts to continue while a release candidate is being tested.
-The [security working group][] should provide guidance to the
-community about security aspects of the planned release. The idea is
-to provide input for the [release notes][] and actionable advice to the
-[test work group][].
+The [security working group][] should provide guidance to the community about
+security aspects of the planned release. The idea is to provide input for the
+[release notes][] and actionable advice to the [test work group][].
-The [test work group][] should indicate what testing was performed and
-the results of that testing. The idea is to fix problems and provide
-input to the [release notes][].
+The [test work group][] should indicate what testing was performed and the
+results of that testing. The idea is to fix problems and provide input to the
+[release notes][].
-[security working group]: https://github.com/openbmc/openbmc/wiki/Security-working-group
+[security working group]:
+ https://github.com/openbmc/openbmc/wiki/Security-working-group
[test work group]: https://github.com/openbmc/openbmc/wiki/Test-work-group
-[release notes]: https://github.com/openbmc/docs/blob/master/release/release-notes.md
+[release notes]:
+ https://github.com/openbmc/docs/blob/master/release/release-notes.md
#### Release
-The release milestone is the release date. It is defined as happening some
-time within a targeted release week. It is desired to have the release happen
-as soon as possible within the release week, but the week is given to allow
-for typical infrastructure problems to occur and be fixed in order for the
-release to happen.
-The release date is a fixed time frame and cannot be moved. If a feature is
-not done by the freeze milestone, then it will not be in that release, it will
-have to be included in the next release cycle. The release date will not float
-out until the feature is complete.
+The release milestone is the release date. It is defined as happening some time
+within a targeted release week. It is desired to have the release happen as soon
+as possible within the release week, but the week is given to allow for typical
+infrastructure problems to occur and be fixed in order for the release to
+happen.
+
+The release date is a fixed time frame and cannot be moved. If a feature is not
+done by the freeze milestone, then it will not be in that release, it will have
+to be included in the next release cycle. The release date will not float out
+until the feature is complete.
The updated [release notes][] should be merged into the project.
## Release Content
### Content Input
+
Community members define release content by inputting needed work into the
release management tool(s) specified below. Typically the content is a feature
that a particular company needs and one that they are willing to allocate some
@@ -101,9 +110,10 @@
feature.
### Prioritization
-Prioritization happens naturally with listing the content proposed for a
-release cycle. If every community member participating in the Release Planning
-work group wants a particular feature and agree to help staff the effort, it
+
+Prioritization happens naturally with listing the content proposed for a release
+cycle. If every community member participating in the Release Planning work
+group wants a particular feature and agree to help staff the effort, it
automatically becomes a higher priority than an item that is mildly needed and
not staffed.
@@ -112,6 +122,7 @@
area that a new community member would like to start working on.
### Work Group Formation
+
Work groups form in the open around features for a release, not around company
boundaries. Work groups would definitely be needed for work spanning releases,
or high priority features with multiple community members. These work groups
@@ -123,12 +134,14 @@
weekly meetings via Discord or call to discuss designs and progress.
### Backlog
+
The backlog is simply the proposed release features that did not make the
-release plan. They will be additional input for the next release cycle. They
-are also available for new community members looking for a new project to
-drive if none of the current work is within their expertise.
+release plan. They will be additional input for the next release cycle. They are
+also available for new community members looking for a new project to drive if
+none of the current work is within their expertise.
### Release Management Tools
+
Initially a Google spreadsheet was used, then Github issues/labels, but neither
found acceptance or traction in the community. Currently broad features are
listed in the wiki:
diff --git a/rest-api.md b/rest-api.md
index 96bad92..9cef970 100644
--- a/rest-api.md
+++ b/rest-api.md
@@ -12,7 +12,8 @@
## Authentication
-See the details on authentication at [REST-cheatsheet](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md#establish-rest-connection-session).
+See the details on authentication at
+[REST-cheatsheet](https://github.com/openbmc/docs/blob/master/REST-cheatsheet.md#establish-rest-connection-session).
This tutorial uses token based authentication method:
@@ -27,139 +28,140 @@
There are a few conventions on the URL structure of the OpenBMC rest interface.
They are:
- - To query the attributes of an object, perform a GET request on the object
- name, with no trailing slash. For example:
+- 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
- {
- "data": {
- "AssetTag": "",
- "BuildDate": "",
- "Cached": true,
- "FieldReplaceable": true,
- "Manufacturer": "",
- "Model": "",
- "PartNumber": "",
- "Present": true,
- "PrettyName": "",
- "SerialNumber": ""
- },
- "message": "200 OK",
+ ```
+ $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system
+ {
+ "data": {
+ "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"
+ }
+ ```
+
+- 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"
- }
- ```
+ }
+ ```
- - To query a single attribute, use the `attr/<name>` path. Using the
- `system` object from above, we can query just the `Name` value:
+ 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.
- ```
- $ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/inventory/system/attr/Cached
- {
- "data": true,
- "message": "200 OK",
- "status": "ok"
- }
- ```
+- Performing the same query with `/list` will list the child objects
+ _recursively_.
- - 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",
+ ```
+ $ 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"
+ }
+ ```
+
+- 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"
}
- ```
-
- 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"
- }
- ```
-
- - 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"
- }
- ```
+ },
+ "message": "200 OK",
+ "status": "ok"
+ }
+ ```
## HTTP PUT operations
PUT operations are for updating an existing resource (an object or property), or
-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:
+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:
```
$ curl -k -H "X-Auth-Token: $token" https://${bmc}/xyz/openbmc_project/state/host0 > host.json
@@ -210,28 +212,35 @@
{"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
```
+
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
```
+
When using '-d' just remember that json requires quoting.
## HTTP POST operations
+
POST operations are for calling methods, but also for creating new resources
when the client doesn't know where to put it. OpenBMC does not support creating
new resources via REST so any attempt to create a new resource will result in a
-HTTP 403 (Forbidden).
-These also require a json formatted payload.
-To delete logging entries:
+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
```
+
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
```
+
## HTTP DELETE operations
+
DELETE operations are for removing instances. Only D-Bus objects (instances) can
be removed. If the underlying D-Bus object implements the
`xyz.openbmc_project.Object.Delete` interface the REST server will call it. If
@@ -253,6 +262,7 @@
```
## Uploading images
+
It is possible to upload software upgrade images (for example to upgrade the BMC
or host software) via REST. The content-type should be set to
"application/octet-stream".
@@ -273,7 +283,8 @@
In above example, the file foo will be saved with the name bar on the BMC.
-The operation will either return the version id (hash) of the uploaded file on success:
+The operation will either return the version id (hash) of the uploaded file on
+success:
```
{
@@ -299,95 +310,98 @@
https://github.com/openbmc/docs/tree/master/architecture/code-update
## Event subscription protocol
-It is possible to subscribe to events, of interest, occurring on the BMC.
-The implementation on the BMC uses WebSockets for this purpose, so that clients
-don't have do employ polling. Instead, the rest server on the BMC can push
-data to clients over a websocket.
-The BMC can push out information pertaining to D-Bus InterfacesAdded and PropertiesChanged signals.
-Following is a description of the event subscription protocol, with example
-JS code snippets denoting client-side code.
+It is possible to subscribe to events, of interest, occurring on the BMC. The
+implementation on the BMC uses WebSockets for this purpose, so that clients
+don't have do employ polling. Instead, the rest server on the BMC can push data
+to clients over a websocket. The BMC can push out information pertaining to
+D-Bus InterfacesAdded and PropertiesChanged signals.
-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.
+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.
```
var ws = new WebSocket("wss://<BMC IP>/subscribe")
```
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.
+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.
- One of the supported keys is "paths". The corresponding value is an array of
- D-Bus paths. The InterfacesAdded and PropertiesChanged D-Bus signals
- emanating from any of these path(s) alone, and not from any other paths, will
- be included in the event message going out of the BMC.
+One of the supported keys is "paths". The corresponding value is an array of
+D-Bus paths. The InterfacesAdded and PropertiesChanged D-Bus signals emanating
+from any of these path(s) alone, and not from any other paths, will be included
+in the event message going out of the BMC.
- The other supported key is "interfaces". The corresponding value is an
- array of D-Bus interfaces. The InterfacesAdded and PropertiesChanged D-Bus
- signal messages comprising of any of these interfaces will be included in
- the event message going out of the BMC.
+The other supported key is "interfaces". The corresponding value is an array of
+D-Bus interfaces. The InterfacesAdded and PropertiesChanged D-Bus signal
+messages comprising of any of these interfaces will be included in the event
+message going out of the BMC.
- All of the following are valid:
+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"]
- });
- ws.onopen = function() {
- ws.send(data);
- };
- ```
+```
+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);
+};
+```
- ```
- var data = JSON.stringify(
- {
- "paths": ["/xyz/openbmc_project/logging", "/xyz/openbmc_project/sensors"],
- });
- ws.onopen = function() {
- ws.send(data);
- };
- ```
+```
+var data = JSON.stringify(
+{
+ "paths": ["/xyz/openbmc_project/logging", "/xyz/openbmc_project/sensors"],
+});
+ws.onopen = function() {
+ ws.send(data);
+};
+```
- ```
- var data = JSON.stringify(
- {
- "interfaces": ["xyz.openbmc_project.Logging.Entry", "xyz.openbmc_project.Sensor.Value"]
- });
- ws.onopen = function() {
- ws.send(data);
- };
- ```
+```
+var data = JSON.stringify(
+{
+ "interfaces": ["xyz.openbmc_project.Logging.Entry", "xyz.openbmc_project.Sensor.Value"]
+});
+ws.onopen = function() {
+ ws.send(data);
+};
+```
- ```
- var data = JSON.stringify(
- {
- });
- ws.onopen = function() {
- ws.send(data);
- };
- ```
+```
+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
- occurs, considering the client supplied filters. The rest servers notifies
- about InterfacesAdded and PropertiesChanged events. The response is a JSON
- dictionary as follows :
+occurs, considering the client supplied filters. The rest servers notifies about
+InterfacesAdded and PropertiesChanged events. The response is a JSON dictionary
+as follows :
- InterfacesAdded
- ```
- "event": InterfacesAdded
- "path": <string : new D-Bus path that was created>
- "interfaces": <dict : a dictionary of interfaces> (similar to org.freedesktop.DBus.ObjectManager.InterfacesAdded )
- ```
+InterfacesAdded
- PropertiesChanged
- ```
- "event": PropertiesChanged
- "path": <string : D-Bus path whose property changed>
- "interface": <string : D-Bus interface to which the changed property belongs>
- "properties": <dict : a dictionary of properties> (similar to org.freedesktop.DBus.Properties.PropertiesChanged)
- ```
+```
+"event": InterfacesAdded
+"path": <string : new D-Bus path that was created>
+"interfaces": <dict : a dictionary of interfaces> (similar to org.freedesktop.DBus.ObjectManager.InterfacesAdded )
+```
+
+PropertiesChanged
+
+```
+"event": PropertiesChanged
+"path": <string : D-Bus path whose property changed>
+"interface": <string : D-Bus interface to which the changed property belongs>
+"properties": <dict : a dictionary of properties> (similar to org.freedesktop.DBus.Properties.PropertiesChanged)
+```
diff --git a/security/TLS-configuration.md b/security/TLS-configuration.md
index 431c419..1ad819c 100644
--- a/security/TLS-configuration.md
+++ b/security/TLS-configuration.md
@@ -1,50 +1,52 @@
# How to configure the server TLS certificates for authentication
-Author:
- Zbigniew Kurzynski <zbigniew.kurzynski@intel.com>
-Created:
- May 8, 2020
+Author: Zbigniew Kurzynski <zbigniew.kurzynski@intel.com>
+
+Created: May 8, 2020
Related documents:
-* [Redfish TLS User Authentication](https://github.com/openbmc/docs/blob/master/designs/redfish-tls-user-authentication.md)
+
+- [Redfish TLS User Authentication](https://github.com/openbmc/docs/blob/master/designs/redfish-tls-user-authentication.md)
## Introduction
-With help of this guidebook you should be able to create both client and
-server certificates signed by a CA that can be used to authenticate user
-requests to an OpenBMC server. You will also learn how to enable and test
-the OpenBMC TLS authentication.
+
+With help of this guidebook you should be able to create both client and server
+certificates signed by a CA that can be used to authenticate user requests to an
+OpenBMC server. You will also learn how to enable and test the OpenBMC TLS
+authentication.
## Certificates
-For a certificate to be marked as valid, it (and every certificate in the
-chain) has to meet these conditions:
-* `KeyUsage` contains required purpose `digitalSignature` and `keyAgreement`
-(see rfc 3280 4.2.1.3)
-* `ExtendedKeyUsage` contains required purpose `clientAuth` for client
-certificate and `serverAuth` for server certificate (see rfc 3280 4.2.1.13)
-* public key meets minimal bit length requirement
-* certificate has to be in its validity period
-* `notBefore` and `notAfter` fields have to contain valid time
-* has to be properly signed by certificate authority
-* certificate is well-formed according to X.509
-* issuer name has to match CA's subject name for client certificate
-* issuer name has to match the fully qualified domain name of your OpenBMC
-host
+For a certificate to be marked as valid, it (and every certificate in the chain)
+has to meet these conditions:
-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 requirements.
+- `KeyUsage` contains required purpose `digitalSignature` and `keyAgreement`
+ (see rfc 3280 4.2.1.3)
+- `ExtendedKeyUsage` contains required purpose `clientAuth` for client
+ certificate and `serverAuth` for server certificate (see rfc 3280 4.2.1.13)
+- public key meets minimal bit length requirement
+- certificate has to be in its validity period
+- `notBefore` and `notAfter` fields have to contain valid time
+- has to be properly signed by certificate authority
+- certificate is well-formed according to X.509
+- issuer name has to match CA's subject name for client certificate
+- 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
+requirements.
### Prepare configuration files
-To generate certificates with required parameters some modification must be
-made to the default openssl configuration file.
+To generate certificates with required parameters some modification must be made
+to the default openssl configuration file.
-First create a new folder named `ca` and create a configuration file using
-the default configuration as a template (we do not want to change the
-original one). The location of the configuration file may vary depending on
-the operating system. For Ubuntu it is usually `/usr/lib/ssl/openssl.cnf`,
-but can also can be at `/etc/ssl/openssl.cnf`. For Cygwin it might be
+First create a new folder named `ca` and create a configuration file using the
+default configuration as a template (we do not want to change the original one).
+The location of the configuration file may vary depending on the operating
+system. For Ubuntu it is usually `/usr/lib/ssl/openssl.cnf`, but can also can be
+at `/etc/ssl/openssl.cnf`. For Cygwin it might be
`/etc/defaults/etc/pki/tls/openssl.cnf` or `/etc/pki/tls/openssl.cnf`.
```
@@ -53,8 +55,8 @@
cp /usr/lib/ssl/openssl.cnf openssl-client.cnf
```
-Then open the client `~/ca/openssl-client.cnf` file in your favorite editor,
-for example `vi`.
+Then open the client `~/ca/openssl-client.cnf` file in your favorite editor, for
+example `vi`.
```
vi ~/ca/openssl-client.cnf
@@ -92,8 +94,8 @@
```
Create two additional configuration files `myext-client.cnf` and
-`myext-server.cnf` for the client and server certificates respectively.
-Without these files no extensions are added to the certificate.
+`myext-server.cnf` for the client and server certificates respectively. Without
+these files no extensions are added to the certificate.
```
cat << END > myext-client.cnf
@@ -103,6 +105,7 @@
authorityKeyIdentifier = keyid
END
```
+
```
cat << END > myext-server.cnf
[ my_ext_section ]
@@ -113,32 +116,37 @@
```
### Create a new CA certificate
+
First we need to create a private key to sign the CA certificate.
+
```
openssl genrsa -out CA-key.pem 2048
```
-Now we can create a CA certificate, using the previously generated key.
-You will be prompted for information which will be incorporated into the
-certificate, such as Country, City, Company Name, etc.
+Now we can create a CA certificate, using the previously generated key. You will
+be prompted for information which will be incorporated into the certificate,
+such as Country, City, Company Name, etc.
```
openssl req -new -config openssl-client.cnf -key CA-key.pem -x509 -days 1000 -out CA-cert.pem
```
### Create client certificate signed by given CA certificate
+
To create a client certificate, a signing request must be created first. For
this another private key will be needed.
Generate a new key that will be used to sign the certificate signing request:
+
```
openssl genrsa -out client-key.pem 2048
```
+
Generate a certificate signing request.
You will be prompted for the same information as during CA generation, but
-provide **the OpenBMC system user name** for the `CommonName` attribute of
-this certificate. In this example, use **root**.
+provide **the OpenBMC system user name** for the `CommonName` attribute of this
+certificate. In this example, use **root**.
```
openssl req -new -config openssl-client.cnf -key client-key.pem -out signingReqClient.csr
@@ -146,26 +154,31 @@
Sign the certificate using your `CA-cert.pem` certificate with following
command:
+
```
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
```
+
The file `client-cert.pem` now contains a signed client certificate.
### 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 different one could
-be used.
+
+For convenience we will use the same CA generated in paragraph
+[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:
+
```
openssl genrsa -out server-key.pem 2048
```
+
Generate a certificate signing request. You will be prompted for the same
-information as during CA generation, but provide **the fully qualified
-domain 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
+information as during CA generation, but provide **the fully qualified domain
+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,
blog.example.com, and others.
@@ -175,12 +188,15 @@
Sign the certificate using your `CA-cert.pem` certificate with following
command:
+
```
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
```
+
The file `server-cert.pem` now contains a signed server certificate.
### Verify certificates
+
To verify the signing request and both certificates you can use following
commands.
@@ -194,19 +210,20 @@
Below are example listings that you can compare with your results. Pay special
attention to attributes like:
- * Validity in both certificates,
- * `Issuer` in `client-cert.pem`, it must match to `Subject` in `CA-cert.pem`,
- * Section *X509v3 extensions* in `client-cert.pem` it should contain proper
-values,
- * `Public-Key` length, it cannot be less than 2048 bits.
- * `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 constraints)
+
+- Validity in both certificates,
+- `Issuer` in `client-cert.pem`, it must match to `Subject` in `CA-cert.pem`,
+- Section _X509v3 extensions_ in `client-cert.pem` it should contain proper
+ values,
+- `Public-Key` length, it cannot be less than 2048 bits.
+- `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
+ constraints)
Below are fragments of generated certificates that you can compare with.
+
```
CA-cert.pem
Data:
@@ -241,6 +258,7 @@
45:47:91:62:10:bd:3e:a8:da:98:33:65:cc:11:23:95:06:1b:
ee:d3:78:84
```
+
```
client-cert.pem
Data:
@@ -275,6 +293,7 @@
25:cb:5e:0a:37:fb:a1:ab:b0:c4:62:fe:51:d3:1c:1b:fb:11:
56:57:4c:6a
```
+
```
server-cert.pem
Data:
@@ -313,11 +332,11 @@
## Installing CA certificate on OpenBMC
The CA certificate can be installed via Redfish Service. The file `CA-cert.pem`
-can not be uploaded directly but must be sent embedded in a valid JSON
-string, which requires `\`, `"`, and control characters must be escaped.
-This means all content is placed in a single string on a single line by
-encoding the line endings as `\n`. The command below prepares a whole POST
-body and puts it into a file named: `install_ca.json`.
+can not be uploaded directly but must be sent embedded in a valid JSON string,
+which requires `\`, `"`, and control characters must be escaped. This means all
+content is placed in a single string on a single line by encoding the line
+endings as `\n`. The command below prepares a whole POST body and puts it into a
+file named: `install_ca.json`.
```
cat << END > install_ca.json
@@ -331,8 +350,8 @@
To install the CA certificate on the OpenBMC server post the content of
`install_ca.json` with this command:
-Where `${bmc}` should be `bmc.example.com`. It is convenient to export it
-as an environment variable.
+Where `${bmc}` should be `bmc.example.com`. It is convenient to export it as an
+environment variable.
```
curl --user root:0penBmc -d @install_ca.json -k -X POST https://${bmc}/redfish/v1/Managers/bmc/Truststore/Certificates
@@ -342,20 +361,18 @@
Credentials `root:0penBmc` can be replaced with any system user name and
password of your choice but with proper access rights to resources used here.
+After successful certificate installation you should get positive HTTP response
+and a new certificate should be available under this resource collection.
-After successful certificate installation you should get positive HTTP
-response and a new certificate should be available under this resource
-collection.
```
curl --user root:0penBmc -k https://${bmc}/redfish/v1/Managers/bmc/Truststore/Certificates
```
-An auto-generated self-signed server certificate is already present on
-OpenBMC by default. To use the certificate signed by our CA it must be
-replaced. 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:
+An auto-generated self-signed server certificate is already present on OpenBMC
+by default. To use the certificate signed by our CA it must be replaced.
+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:
```
cat << END > replace_cert.json
@@ -385,6 +402,7 @@
```
curl --user root:0penBmc -k https://${bmc}/redfish/v1/AccountService
```
+
and verify that the attribute `Oem->OpenBMC->AuthMethods->TLS` is set to true.
To enable TLS authentication use this command:
@@ -400,30 +418,31 @@
```
Other authentication methods like basic authentication can be enabled or
-disabled as well using the same mechanism. All supported authentication
-methods are available under attribute `Oem->OpenBMC->AuthMethods` of the
+disabled as well using the same mechanism. All supported authentication methods
+are available under attribute `Oem->OpenBMC->AuthMethods` of the
`/redfish/v1/AccountService` resource.
## Using TLS to access OpenBMC resources
-If TLS is enabled, valid CA certificate was uploaded and the server
-certificate was replaced it should be possible to execute curl requests
-using only client certificate, key, and CA like below.
+If TLS is enabled, valid CA certificate was uploaded and the server certificate
+was replaced it should be possible to execute curl requests using only client
+certificate, key, and CA like below.
```
curl --cert client-cert.pem --key client-key.pem -vvv --cacert CA-cert.pem https://${bmc}/redfish/v1/SessionService/Sessions
```
+
## Common mistakes during TLS configuration
-* Invalid date and time on OpenBMC,
+- Invalid date and time on OpenBMC,
-* Testing Redfish resources, like `https://${bmc}/redfish/v1` which are
-always available without any authentication will always result with success,
-even when TLS is disabled or certificates are invalid.
+- Testing Redfish resources, like `https://${bmc}/redfish/v1` which are always
+ available without any authentication will always result with success, even
+ when TLS is disabled or certificates are invalid.
-* Certificates do not meet the requirements. See paragraphs
-[Verify certificates](#Verify-certificates).
+- Certificates do not meet the requirements. See paragraphs
+ [Verify certificates](#Verify-certificates).
-* Attempting to load the same certificate twice will end up with an error.
+- Attempting to load the same certificate twice will end up with an error.
-* Not having phosphor-bmcweb-cert-config in the build.
+- Not having phosphor-bmcweb-cert-config in the build.
diff --git a/security/how-to-report-a-security-vulnerability.md b/security/how-to-report-a-security-vulnerability.md
index c242778..3bc3589 100644
--- a/security/how-to-report-a-security-vulnerability.md
+++ b/security/how-to-report-a-security-vulnerability.md
@@ -1,70 +1,77 @@
# How to report a security vulnerability
-This describes how you can report an OpenBMC security vulnerability
-privately to give the project time to address the problem before
-public disclosure.
+This describes how you can report an OpenBMC security vulnerability privately to
+give the project time to address the problem before public disclosure.
The main ideas are:
- - You have information about a security problem or vulnerability which is not
- yet publicly available.
- - You want the problem fixed before public disclosure and
- you are willing to help make that happen.
- - You understand the problem will eventually be publicly disclosed.
+
+- You have information about a security problem or vulnerability which is not
+ yet publicly available.
+- You want the problem fixed before public disclosure and you are willing to
+ help make that happen.
+- You understand the problem will eventually be publicly disclosed.
To begin the process: Privately contact the OpenBMC security response team and
(if known) the project maintainer:
- - Suggest sending an email. Use `openbmc-security at lists.ozlabs.org`.
- - If you know which source code repository is affected, find the repository
- owner or maintainer contact information in the OWNERS or MAINTAINERS file.
- If not, the security response team will help route the problem.
- - Include details about the security problem such as:
- - The version and configuration of OpenBMC the problem appears in.
- - How to reproduce the problem.
- - What are the symptoms.
- - As the problem reporter, you will be included in the problem response.
-Please note the OpenBMC project has multiple source code repositories. Each
-has separate owners. If you do not know which repository is affected, the
-owner or the security response team can help you route the problem.
+- Suggest sending an email. Use `openbmc-security at lists.ozlabs.org`.
+- If you know which source code repository is affected, find the repository
+ owner or maintainer contact information in the OWNERS or MAINTAINERS file. If
+ not, the security response team will help route the problem.
+- Include details about the security problem such as:
+ - The version and configuration of OpenBMC the problem appears in.
+ - How to reproduce the problem.
+ - What are the symptoms.
+- As the problem reporter, you will be included in the problem response.
+
+Please note the OpenBMC project has multiple source code repositories. Each has
+separate owners. If you do not know which repository is affected, the owner or
+the security response team can help you route the problem.
When the project owners get a new security problem, they will create a [GitHub
-security advisory][] in their repository and begin work. The advisory has
-draft status which means only the collaborators can see it. Collaborators
-should be added as follows:
- - The problem reporter.
- - The OpenBMC security response team.
- - Developers responsible for fixing the problem.
+security advisory][] in their repository and begin work. The advisory has draft
+status which means only the collaborators can see it. Collaborators should be
+added as follows:
-The collaborators work to resolve the problem. Activities may include:
- - The OpenBMC [CVE Numbering Authority (CNA)][] (members of the OpenBMC
- security response team) will help clarify the problem and assign CVEs.
- - Privately engage community members to understand and address the
- problem. Anyone brought onboard should be given a link to the
- OpenBMC [security response team guidelines][].
- - Work to determine the scope and severity of the problem,
- such as [CVSS metrics][].
- - Coordinate workarounds and fixes with you and the community.
- - 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.
+- The problem reporter.
+- The OpenBMC security response team.
+- Developers responsible for fixing the problem.
+
+The collaborators work to resolve the problem. Activities may include:
+
+- The OpenBMC [CVE Numbering Authority (CNA)][] (members of the OpenBMC security
+ response team) will help clarify the problem and assign CVEs.
+- Privately engage community members to understand and address the problem.
+ Anyone brought onboard should be given a link to the OpenBMC [security
+ response team guidelines][].
+- Work to determine the scope and severity of the problem, such as [CVSS
+ metrics][].
+- Coordinate workarounds and fixes with you and the community.
+- 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.
Please refer to the [CERT Guide to Coordinated Vulnerability Disclosure][],
(SPECIAL REPORT CMU/SEI-2017-SR-022) for additional considerations.
Alternatives to this process:
- - If the problem is not severe, please write an issue to the affected
- repository or email the list.
- - Join the OpenBMC community and fix the problem yourself.
- - If you are unsure if the error is in OpenBMC (contrasted with
- upstream projects such as the Linux kernel or downstream projects
- such as a customized version of OpenBMC), please report it and we
- will help you route it to the correct area.
- - Discuss your topic in other [OpenBMC communication channels](https://github.com/openbmc/openbmc).
+
+- If the problem is not severe, please write an issue to the affected repository
+ or email the list.
+- Join the OpenBMC community and fix the problem yourself.
+- If you are unsure if the error is in OpenBMC (contrasted with upstream
+ projects such as the Linux kernel or downstream projects such as a customized
+ version of OpenBMC), please report it and we will help you route it to the
+ correct area.
+- Discuss your topic in other
+ [OpenBMC communication channels](https://github.com/openbmc/openbmc).
[security response team guidelines]: ./obmc-security-response-team-guidelines.md
-[CVSS metrics]: https://www.first.org/cvss/calculator/3.0
-[CVE]: http://cve.mitre.org/about/index.html
-[CERT Guide to Coordinated Vulnerability Disclosure]: https://resources.sei.cmu.edu/asset_files/SpecialReport/2017_003_001_503340.pdf
-[GitHub security advisory]: https://docs.github.com/en/code-security/repository-security-advisories/creating-a-repository-security-advisory
-[CVE Numbering Authority (CNA)]: https://www.cve.org/ProgramOrganization/CNAs
+[cvss metrics]: https://www.first.org/cvss/calculator/3.0
+[cve]: http://cve.mitre.org/about/index.html
+[cert guide to coordinated vulnerability disclosure]:
+ https://resources.sei.cmu.edu/asset_files/SpecialReport/2017_003_001_503340.pdf
+[github security advisory]:
+ https://docs.github.com/en/code-security/repository-security-advisories/creating-a-repository-security-advisory
+[cve numbering authority (cna)]: https://www.cve.org/ProgramOrganization/CNAs
diff --git a/security/network-security-considerations.md b/security/network-security-considerations.md
index e2189ba..e9ebff3 100644
--- a/security/network-security-considerations.md
+++ b/security/network-security-considerations.md
@@ -1,241 +1,241 @@
# Network Security Considerations
-This describes network services provided by OpenBMC-based systems,
-some threats the BMC faces from its network interfaces, and steps
-OpenBMC takes to address these threats.
+This describes network services provided by OpenBMC-based systems, some threats
+the BMC faces from its network interfaces, and steps OpenBMC takes to address
+these threats.
-This is only intended to be a guide; security is ultimately the
-responsibility of projects which choose to incorporate OpenBMC into
-their project. If you find a security vulnerability, please
-consider [how to report a security vulnerability][].
+This is only intended to be a guide; security is ultimately the responsibility
+of projects which choose to incorporate OpenBMC into their project. If you find
+a security vulnerability, please consider [how to report a security
+vulnerability][].
-[how to report a security vulnerability]: https://github.com/openbmc/docs/blob/master/security/how-to-report-a-security-vulnerability.md
+[how to report a security vulnerability]:
+ https://github.com/openbmc/docs/blob/master/security/how-to-report-a-security-vulnerability.md
-Threats to the BMC are classified using the [CIA triad][]. All threat
-types are significant; here is an example of each:
- - Confidentiality: If an attacker can get data from the BMC, they may
- be able to chain other vulnerabilities to establish a covert
- information channel to get sensitive information from the host.
- - Integrity: If an attacker can modify BMC settings or data, they may
- be able to gain additional access, and launch more attacks.
- - Availability: If an agent can overwhelm the BMC's resources, either
- by accident or on purpose, the BMC will not be available to service
- its host (denial of service).
+Threats to the BMC are classified using the [CIA triad][]. All threat types are
+significant; here is an example of each:
-[CIA triad]: https://en.wikipedia.org/wiki/Information_security#Key_concepts
+- Confidentiality: If an attacker can get data from the BMC, they may be able to
+ chain other vulnerabilities to establish a covert information channel to get
+ sensitive information from the host.
+- Integrity: If an attacker can modify BMC settings or data, they may be able to
+ gain additional access, and launch more attacks.
+- Availability: If an agent can overwhelm the BMC's resources, either by
+ accident or on purpose, the BMC will not be available to service its host
+ (denial of service).
-This document is organized by how OpenBMC services connect to the
-network. The general flow is:
- - The BMC is presumed to have a network adapter. The security
- considerations of the NIC are important to the BMC security, but
- are outside the scope of this document.
- - Network traffic then flows through the kernel, detailed below.
- - Finally, connections flow to various OpenBMC services.
+[cia triad]: https://en.wikipedia.org/wiki/Information_security#Key_concepts
-OpenBMC provides services on TCP and UDP ports. For example, the
-HTTPS protocol on port 443 is used to provide REST APIs and serve Web
-applications. These services are detailed below. Implicit is that
-all other ports are inactive.
+This document is organized by how OpenBMC services connect to the network. The
+general flow is:
-OpenBMC also initiates network communications, for example, NTP, LDAP,
-etc. These are covered with their associated functions.
+- The BMC is presumed to have a network adapter. The security considerations of
+ the NIC are important to the BMC security, but are outside the scope of this
+ document.
+- Network traffic then flows through the kernel, detailed below.
+- Finally, connections flow to various OpenBMC services.
+OpenBMC provides services on TCP and UDP ports. For example, the HTTPS protocol
+on port 443 is used to provide REST APIs and serve Web applications. These
+services are detailed below. Implicit is that all other ports are inactive.
+
+OpenBMC also initiates network communications, for example, NTP, LDAP, etc.
+These are covered with their associated functions.
## Kernel and ICMP messages
-Network traffic is handled by the Linux kernel. The exact kernel and
-device driver have security considerations which are important to BMC
-security, but are better addressed by the Linux kernel community.
-You can learn which kernel and patches are used from the kernel
-recipes typically found in the board support packages for the BMC
-referenced by your machine's configuration. For example, in the
-`https://github.com/openbmc/meta-aspeed` repository under
+Network traffic is handled by the Linux kernel. The exact kernel and device
+driver have security considerations which are important to BMC security, but are
+better addressed by the Linux kernel community. You can learn which kernel and
+patches are used from the kernel recipes typically found in the board support
+packages for the BMC referenced by your machine's configuration. For example, in
+the `https://github.com/openbmc/meta-aspeed` repository under
`recipes-kernel/linux/linux-aspeed_git.bb`.
-Per [CVE 1999-0524][], responding to certain ICMP packets can give an
-attacker more information about the BMC's clock or subnet, which can
-help with subsequent attacks. OpenBMC responds to all ICMP requests.
+Per [CVE 1999-0524][], responding to certain ICMP packets can give an attacker
+more information about the BMC's clock or subnet, which can help with subsequent
+attacks. OpenBMC responds to all ICMP requests.
-[CVE 1999-0524]: https://nvd.nist.gov/vuln/detail/CVE-1999-0524
+[cve 1999-0524]: https://nvd.nist.gov/vuln/detail/CVE-1999-0524
-General considerations for ICMP messages apply. For example, packet
+General considerations for ICMP messages apply. For example, packet
fragmentation and packet flooding vulnerabilities.
-It is sometimes useful to filter and log network messages for debug and
-other diagnostic purposes. OpenBMC provides no support for this.
-
+It is sometimes useful to filter and log network messages for debug and other
+diagnostic purposes. OpenBMC provides no support for this.
## General considerations for services
Several services perform user identification and authentication:
- - Phosphor REST APIs
- - Redfish REST API SessionService
- - Network IPMI
- - SSH secure shell
-OpenBMC's [phosphor-user-manager][] provides the underlying
-authentication and authorization functions and ties into IPMI, Linux
-PAM, LDAP, and logging. Some of OpenBMC services use phosphor-user-manager.
+- Phosphor REST APIs
+- Redfish REST API SessionService
+- Network IPMI
+- SSH secure shell
-[phosphor-user-manager]: https://github.com/openbmc/docs/blob/master/architecture/user-management.md
+OpenBMC's [phosphor-user-manager][] provides the underlying authentication and
+authorization functions and ties into IPMI, Linux PAM, LDAP, and logging. Some
+of OpenBMC services use phosphor-user-manager.
-Transport layer security (TLS) protocols are configured for each
-service at compile time, become part of the image, and cannot be
-changed dynamically. The protocols which use TLS include:
- - RAKP for IPMI.
- - SSH for ssh and scp.
- - HTTPS for Web and REST APIs.
+[phosphor-user-manager]:
+ https://github.com/openbmc/docs/blob/master/architecture/user-management.md
-Automated network agents (such as hardware management consoles) may
-malfunction in a way that the BMC continuously gets authentication
-failures, which may lead to denial of service. For example, a brief
-delay before reporting the failure, for example, of one second, may
-help prevent this problem or lessen its severity. See [OWASP Blocking
-Brute Force Attacks][].
+Transport layer security (TLS) protocols are configured for each service at
+compile time, become part of the image, and cannot be changed dynamically. The
+protocols which use TLS include:
-[OWASP Blocking Brute Force Attacks]: https://www.owasp.org/index.php/Blocking_Brute_Force_Attacks
+- RAKP for IPMI.
+- SSH for ssh and scp.
+- HTTPS for Web and REST APIs.
-Network agents may fail to end a session properly, which causes the
-service to use resources to keep track of orphaned sessions. To help
-prevent this, services may limit the maximum number of concurrent
-sessions, or have a session inactivity timeout.
+Automated network agents (such as hardware management consoles) may malfunction
+in a way that the BMC continuously gets authentication failures, which may lead
+to denial of service. For example, a brief delay before reporting the failure,
+for example, of one second, may help prevent this problem or lessen its
+severity. See [OWASP Blocking Brute Force Attacks][].
-Services which are not required should be disabled to limit the BMC's
-attack 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'.
+[owasp blocking brute force attacks]:
+ https://www.owasp.org/index.php/Blocking_Brute_Force_Attacks
-[Redfish ManagerNetworkProtocol]: https://redfish.dmtf.org/schemas/ManagerNetworkProtocol.v1_4_0.json
+Network agents may fail to end a session properly, which causes the service to
+use resources to keep track of orphaned sessions. To help prevent this, services
+may limit the maximum number of concurrent sessions, or have a session
+inactivity timeout.
-Network services should log all authentication attempts with their
-outcomes to satisfy basic monitoring and forensic analysis
-requirements. For example, as part of a real-time monitoring service,
-or to answer who accessed which services at what times.
+Services which are not required should be disabled to limit the BMC's attack
+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'.
+
+[redfish managernetworkprotocol]:
+ https://redfish.dmtf.org/schemas/ManagerNetworkProtocol.v1_4_0.json
+
+Network services should log all authentication attempts with their outcomes to
+satisfy basic monitoring and forensic analysis requirements. For example, as
+part of a real-time monitoring service, or to answer who accessed which services
+at what times.
OpenBMC does not have a firewall.
-Laws may require products built on OpenBMC to have reasonable security
-built into them, for example, by not having a default password. See,
-for example, [CA Law SB-327].
+Laws may require products built on OpenBMC to have reasonable security built
+into them, for example, by not having a default password. See, for example, [CA
+Law SB-327].
-[CA Law SB-327]: https://leginfo.legislature.ca.gov/faces/billTextClient.xhtml?bill_id=201720180SB327
+[ca law sb-327]:
+ https://leginfo.legislature.ca.gov/faces/billTextClient.xhtml?bill_id=201720180SB327
## Services provided on TCP and UDP ports
### TCP port 22 - Secure Shell (SSH) access to the BMC
-The Secure Shell (SSH) protocol is provided, including secure shell
-(ssh command) access to the BMC's shell, and secure copy (scp command)
-to the BMC's file system.
+The Secure Shell (SSH) protocol is provided, including secure shell (ssh
+command) access to the BMC's shell, and secure copy (scp command) to the BMC's
+file system.
-The default SSH server implementation is provided by Dropbear.
-All configuration is at compile-time with defaults for:
- - Authentication provided by Linux PAM, where methods include
- username and password, and SSH certificates (the `ssh-keygen`
- command).
- - Transport layer security (TLS) protocols offered.
+The default SSH server implementation is provided by Dropbear. All configuration
+is at compile-time with defaults for:
-SSH access to the BMC's shell is not the intended way to operate the
-BMC, gives the operator more privilege than is needed, and may not be
-allowed on BMCs which service hosts that process sensitive data.
-However, BMC shell access may be needed to provision the BMC or to
-help diagnose problems during its operation.
+- Authentication provided by Linux PAM, where methods include username and
+ password, and SSH certificates (the `ssh-keygen` command).
+- Transport layer security (TLS) protocols offered.
+SSH access to the BMC's shell is not the intended way to operate the BMC, gives
+the operator more privilege than is needed, and may not be allowed on BMCs which
+service hosts that process sensitive data. However, BMC shell access may be
+needed to provision the BMC or to help diagnose problems during its operation.
### TCP port 443 - HTTPS REST APIs and Web application
BMCWeb is the Web server for:
- - The Redfish REST APIs.
- - The webui-vue Web interface.
- - The Phosphor D-Bus REST interface.
-And initiates WebSockets for:
- - Host KVM.
- - Virtual media.
- - Host serial console.
+
+- The Redfish REST APIs.
+- The webui-vue Web interface.
+- The Phosphor D-Bus REST interface. And initiates WebSockets for:
+- Host KVM.
+- Virtual media.
+- Host serial console.
The [BMCWeb configuration][] controls which services are provided.
-General security considerations for HTTP servers apply such as given
-by [OWASP Application Security][].
+General security considerations for HTTP servers apply such as given by [OWASP
+Application Security][].
-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.
+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.
-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.
+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.
-[BMCWeb configuration]: https://github.com/openbmc/bmcweb#configuration
-[OWASP Application Security]: https://www.owasp.org/index.php/Category:OWASP_Application_Security_Verification_Standard_Project
+[bmcweb configuration]: https://github.com/openbmc/bmcweb#configuration
+[owasp application security]:
+ https://www.owasp.org/index.php/Category:OWASP_Application_Security_Verification_Standard_Project
#### REST APIs
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.
-The first two methods create the same kind of session but return
-different credentials. For example, you can create a Redfish session,
-and use your credentials to invoke Phosphor D-Bus REST APIs. Note,
-however, that the X-Auth tokens are required to use POST, PUT, PATCH,
-or DELETE methods.
+The first two methods create the same kind of session but return different
+credentials. For example, you can create a Redfish session, and use your
+credentials to invoke Phosphor D-Bus REST APIs. Note, however, that the X-Auth
+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
-Redfish provides security considerations in the "Security Detail"
-section of the "Redfish Specification" (document ID DSP0266) available
-from https://www.dmtf.org/standards/redfish.
+Redfish provides security considerations in the "Security Detail" section of the
+"Redfish Specification" (document ID DSP0266) available from
+https://www.dmtf.org/standards/redfish.
#### The webui-vue Web application
-General considerations for Web applications such as given by [OWASP
-Web Application Security Guidance][] apply to OpenBMC. The
-webui-vue uses username and password-based authentication, and
-REST APIs for subsequent access.
+General considerations for Web applications such as given by [OWASP Web
+Application Security Guidance][] apply to OpenBMC. The webui-vue uses username
+and password-based authentication, and REST APIs for subsequent access.
-[OWASP Web Application Security Guidance]: https://www.owasp.org/index.php/Web_Application_Security_Guidance
+[owasp web application security guidance]:
+ https://www.owasp.org/index.php/Web_Application_Security_Guidance
-The web app also provides interfaces to use the host serial console,
-virtual media, and host KVM.
+The web app also provides interfaces to use the host serial console, virtual
+media, and host KVM.
### TCP port 2200
-Access to the BMC's [host serial console][] is provided via the SSH
-protocol on port 2200.
+Access to the BMC's [host serial console][] is provided via the SSH protocol on
+port 2200.
[host serial console]: https://github.com/openbmc/docs/blob/master/console.md
-This uses the same server implementation as port 22, including the
-same TLS mechanisms.
+This uses the same server implementation as port 22, including the same TLS
+mechanisms.
-How the host secures its console (for example, username and password
-prompts) is outside the scope of this document.
+How the host secures its console (for example, username and password prompts) is
+outside the scope of this document.
### 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/
+General security considerations for service discovery apply. For example,
+described here: https://attack.mitre.org/techniques/T1046/
### UDP port 427 - SLP, Avahi
@@ -244,20 +244,20 @@
### UDP port 623 - IPMI RCMP
The IPMI network-facing design is described here:
-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 the scope of this document.
+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
+the scope of this document.
-General security considerations for IPMI apply. For example,
-described here: https://www.us-cert.gov/ncas/alerts/TA13-207A
+General security considerations for IPMI apply. For example, described here:
+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.
+OpenBMC implements RCMP+ and IPMI 2.0. The phosphor-user-manager provides the
+underlying authentication mechanism.
-Supported IPMI ciphers can be found in the code, for example, by
-searching for function `isAlgorithmSupported`, or from the `ipmitool`
-command such as `ipmitool channel getciphers ipmi`.
+Supported IPMI ciphers can be found in the code, for example, by searching for
+function `isAlgorithmSupported`, or from the `ipmitool` command such as
+`ipmitool channel getciphers ipmi`.
OpenBMC supports IPMI "serial over LAN" (SOL) connections (via
`impitool sol activate`) which shares the host serial console socket.
diff --git a/security/obmc-github-security-advisory-template.md b/security/obmc-github-security-advisory-template.md
index 04366f4..76a8448 100644
--- a/security/obmc-github-security-advisory-template.md
+++ b/security/obmc-github-security-advisory-template.md
@@ -7,52 +7,64 @@
Note that the sections under the "Description" section are intended for the
security advisory "Description" field
-[Security response team guidelines]: ./obmc-security-response-team-guidelines.md
+[security response team guidelines]: ./obmc-security-response-team-guidelines.md
### 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
+
Assess the severity using CVSS.
## CWE
+
<TBD>
## CVE identifier
+
Please coordinate with the security response team
## Credits
+
Attribution to those that discovered and mitigated the vulnerability.
### Title
+
Title goes here...
### Description
+
The description will be used by vulnerability analysts and should include the
-area or the function affected, and a description of the issue. There should
-be enough details to differentiate this from similar problems, but not enough
+area or the function affected, and a description of the issue. There should be
+enough details to differentiate this from similar problems, but not enough
detail to help an attacker exploit the problem.
### Proof Of Concept
+
If provided, insert proof of concept here.
### Vulnerability Description
+
...can cause denial of service.
### Affected Release
+
OpenBMC 2.9
### Fixed in Release
+
Please include the commit-id in the affected repo, the commit id for the
metadata, or the version number.
### Mitigation
-If available, describe or provide a link to the mitigation needed until the
-fix can be applied.
+
+If available, describe or provide a link to the mitigation needed until the fix
+can be applied.
### For more information
+
If you have any questions or comments about this advisory:
-* Email openbmc-security at lists.ozlabs.org
+
+- Email openbmc-security at lists.ozlabs.org
diff --git a/security/obmc-security-response-team-guidelines.md b/security/obmc-security-response-team-guidelines.md
index 08844e0..2a3f615 100644
--- a/security/obmc-security-response-team-guidelines.md
+++ b/security/obmc-security-response-team-guidelines.md
@@ -1,118 +1,124 @@
# Security response team guidelines
-These are the guidelines for OpenBMC security responders, including the
-security response team, project owners, and community members who are
-responding to problems reported by the [security vulnerability reporting
-process][].
+These are the guidelines for OpenBMC security responders, including the security
+response team, project owners, and community members who are responding to
+problems reported by the [security vulnerability reporting process][].
Each project within OpenBMC works independently to resolve security
-vulnerabilities. The security response team helps the maintainers, provides
+vulnerabilities. The security response team helps the maintainers, provides
consistency within the OpenBMC project, and helps to get CVEs assigned.
Here are the primary expectations:
- - Keep problems private until announce.
- - Work with diligence.
- - Keep stakeholders informed.
+
+- Keep problems private until announce.
+- Work with diligence.
+- Keep stakeholders informed.
Workflow highlights:
1. Handle new problem reports.
- - Within a day, acknowledge you received the report.
- Note that reports are archived in the mailing list.
- - Communicate by opening the GitHub draft security advistory as soon as
- the problem is known.
-2. Analyze the problem and engage collaborators as needed (upstream,
- downstream, and OpenBMC).
- - Determine if the problem is new or known.
- - Determine if the problem is in OpenBMC.
- - If the problem is in a project that OpenBMC uses, re-route
- the problem to that upstream project.
- - Note that the problem may be in a customized version of
- OpenBMC but not in OpenBMC itself.
- - Determine which OpenBMC areas should address the problem.
- - [Create the draft security advisory][] and populate its fields.
- - The Ecosystem would normally be "OpenBMC" and the package name
- is normally the repository.
- - Please describe when the problem was introduced to help users
- learn if they are affected. Use Git tags and commit IDs if
- known. It also may be helpful to say what OpenBMC version is
- affected. For example, if the problem in the original code
- through OpenBMC release 2.9, the affected version is "<= 2.9".
- See [OpenBMC releases][].
- - Use private channels, for example, email, GitHub draft security
- advistory, or private direct messaging.
- - Inform contacts this is private work as part of the OpenBMC
- security response team. For example, link to these guidelines.
- - Coordinate with all collaborators and keep them informed.
+ - Within a day, acknowledge you received the report. Note that reports are
+ archived in the mailing list.
+ - Communicate by opening the GitHub draft security advistory as soon as the
+ problem is known.
- Considerations in the [CERT Guide to Coordinated Vulnerability
- Disclosure][] (SPECIAL REPORT CMU/SEI-2017-SR-022) may guide the process.
+2. Analyze the problem and engage collaborators as needed (upstream, downstream,
+ and OpenBMC).
+
+ - Determine if the problem is new or known.
+ - Determine if the problem is in OpenBMC.
+ - If the problem is in a project that OpenBMC uses, re-route the problem to
+ that upstream project.
+ - Note that the problem may be in a customized version of OpenBMC but not
+ in OpenBMC itself.
+ - Determine which OpenBMC areas should address the problem.
+ - [Create the draft security advisory][] and populate its fields.
+ - The Ecosystem would normally be "OpenBMC" and the package name is
+ normally the repository.
+ - Please describe when the problem was introduced to help users learn if
+ they are affected. Use Git tags and commit IDs if known. It also may be
+ helpful to say what OpenBMC version is affected. For example, if the
+ problem in the original code through OpenBMC release 2.9, the affected
+ version is "<= 2.9". See [OpenBMC releases][].
+ - Use private channels, for example, email, GitHub draft security advistory,
+ or private direct messaging.
+ - Inform contacts this is private work as part of the OpenBMC security
+ response team. For example, link to these guidelines.
+ - Coordinate with all collaborators and keep them informed.
+
+ Considerations in the [CERT Guide to Coordinated Vulnerability Disclosure][]
+ (SPECIAL REPORT CMU/SEI-2017-SR-022) may guide the process.
Example collaborations:
- - Submit the problem to another security response team, for example, the
- [UEFI Security Response Team (USRT)][].
- - Privately engage an OpenBMC maintainer or subject matter expert.
+
+ - Submit the problem to another security response team, for example, the
+ [UEFI Security Response Team (USRT)][].
+ - 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.
- 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.
- 3. Negotiate how the code review will proceed.
- - Consider [contributing][] using a Gerrit [private change][] if
- everyone has access to Gerrit.
- - Consider using [Patch set][] emails to make reviews accessible to
- all stakeholders.
- 4. When agreed:
- - Publish a security advisory to the affected OpenBMC repository.
- - Make the Gerrit review publicly viewable.
- - Publish the CVE in the CVE database.
- 5. Improve OpenBMC processes to avoid future 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.
+ 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.
+ 3. Negotiate how the code review will proceed.
+ - Consider [contributing][] using a Gerrit [private change][] if everyone
+ has access to Gerrit.
+ - Consider using [Patch set][] emails to make reviews accessible to all
+ stakeholders.
+ 4. When agreed:
+ - Publish a security advisory to the affected OpenBMC repository.
+ - Make the Gerrit review publicly viewable.
+ - Publish the CVE in the CVE database.
+ 5. Improve OpenBMC processes to avoid future problems.
-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 [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.
- If you are unsure what counts as a vulnerability, please consult with the SRT.
- For example, independent bugs should have separate CVEs. A security advisory
- can reference multiple CVEs.
- When the CVE is known, add it to the security advisory, and reference
- it in the commit message, stating how the fix relates to the CVE. For
- example: This fixes CVE-yyyy-nnnnn. Doing so helps downstream security
- responders. If the commit is a partial fix, please explain that and
- provide references to the other parts of the fix.
- 5. If stakeholders negotiate for coordinated disclosure, plan to release
- the fix and the security advisory on the negotiated day.
- 6. When the code fix and the advisory are both ready (subject to coordinated
- disclosure), please merge the fixes (and make any private review be public)
- publish the security advisory, and email the security-response team.
+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
+[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.
+If you are unsure what counts as a vulnerability, please consult with the SRT.
+For example, independent bugs should have separate CVEs. A security advisory can
+reference multiple CVEs. When the CVE is known, add it to the security advisory,
+and reference it in the commit message, stating how the fix relates to the CVE.
+For example: This fixes CVE-yyyy-nnnnn. Doing so helps downstream security
+responders. If the commit is a partial fix, please explain that and provide
+references to the other parts of the fix. 5. If stakeholders negotiate for
+coordinated disclosure, plan to release the fix and the security advisory on the
+negotiated day. 6. When the code fix and the advisory are both ready (subject to
+coordinated disclosure), please merge the fixes (and make any private review be
+public) publish the security advisory, and email the security-response team.
[security vulnerability reporting process]: ./obmc-security-response-team.md
-[CVSS metrics]: https://www.first.org/cvss/calculator/3.0
-[UEFI Security Response Team (USRT)]: https://uefi.org/security
-[CERT Guide to Coordinated Vulnerability Disclosure]: https://resources.sei.cmu.edu/asset_files/SpecialReport/2017_003_001_503340.pdf
-[contributing]: https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes-via-gerrit-server
-[OpenBMC releases]: https://github.com/openbmc/docs/blob/master/release/release-notes.md
-[private change]: https://gerrit-review.googlesource.com/Documentation/intro-user.html#private-changes
-[Patch set]: https://en.wikipedia.org/wiki/Patch_(Unix)
-[Create the draft security advisory]: https://docs.github.com/en/code-security/repository-security-advisories/creating-a-repository-security-advisory
-[OpenBMC Security Advisory Template]: obmc-github-security-advisory-template.md
+[cvss metrics]: https://www.first.org/cvss/calculator/3.0
+[uefi security response team (usrt)]: https://uefi.org/security
+[cert guide to coordinated vulnerability disclosure]:
+ https://resources.sei.cmu.edu/asset_files/SpecialReport/2017_003_001_503340.pdf
+[contributing]:
+ https://github.com/openbmc/docs/blob/master/CONTRIBUTING.md#submitting-changes-via-gerrit-server
+[openbmc releases]:
+ https://github.com/openbmc/docs/blob/master/release/release-notes.md
+[private change]:
+ https://gerrit-review.googlesource.com/Documentation/intro-user.html#private-changes
+[patch set]: https://en.wikipedia.org/wiki/Patch_(Unix)
+[create the draft security advisory]:
+ https://docs.github.com/en/code-security/repository-security-advisories/creating-a-repository-security-advisory
+[openbmc security advisory template]: obmc-github-security-advisory-template.md
## Template: Initial response to the problem submitter
+
The OpenBMC security response team has received the problem.
+
- Thank you for reporting this.
- Share preliminary results of the analysis.
- Share preliminary OpenBMC plans or that we are analyzing the problem.
- Set expectations for follow-up communications.
## Template: OpenBMC Security Advisory
+
```
OpenBMC Security Advisory
Title: ...
@@ -133,8 +139,9 @@
```
## Template: Security Advisory notice
-When the Security Advisory is created, inform the OpenBMC community by
-sending email like this:
+
+When the Security Advisory is created, inform the OpenBMC community by sending
+email like this:
```
TO: openbmc-security@lists.ozlabs.org, openbmc@lists.ozlabs.org
@@ -150,58 +157,60 @@
```
## Reference
+
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
- - [ISO/IEC 29147:2018 vulnerability disclosure](https://www.iso.org/standard/72311.html)
+
+- 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
-The security response team (SRT) is controlled by the OpenBMC Technical
-Steering Committee, including membership on the team. General
-considerations for SRT membership:
+The security response team (SRT) is controlled by the OpenBMC Technical Steering
+Committee, including membership on the team. General considerations for SRT
+membership:
+
- Although individuals join the SRT, it is really organizations which join as
- represented by their SRT members. The SRT members are expected to:
- - Participate in their organization's SRT.
- - Designate backup OpenBMC SRT members.
- - Share OpenBMC security vulnerability information within their organization
- with the same care as stated in this document.
+ represented by their SRT members. The SRT members are expected to:
+ - Participate in their organization's SRT.
+ - Designate backup OpenBMC SRT members.
+ - Share OpenBMC security vulnerability information within their organization
+ with the same care as stated in this document.
- Membership is intended for organizations which have a vested interest in
- OpenBMC security response. Here are some examples to consider:
- - Organizations which have products or services built on OpenBMC which are
- publicly available and disclose security bugs to their users. This
- includes systems directly built on OpenBMC, and larger systems such as
- data centers.
- - Organizations which focus on BMC security research or security response.
+ OpenBMC security response. Here are some examples to consider:
+ - Organizations which have products or services built on OpenBMC which are
+ publicly available and disclose security bugs to their users. This includes
+ systems directly built on OpenBMC, and larger systems such as data centers.
+ - Organizations which focus on BMC security research or security response.
- Evaluation of an organization may be based on its members' OpenBMC community
roles, technical skills, and expertise responding to security incidents.
-- Membership should not be granted without compelling reason. The intention
- is to avoid premature disclosure of security vulnerabilities by limiting
+- Membership should not be granted without compelling reason. The intention is
+ to avoid premature disclosure of security vulnerabilities by limiting
membership to those with vested interest.
-The security response team uses the `openbmc-security at
-lists.ozlabs.org` private email list as a channel for confidential
-communication, so its membership reflects the composition of the
-security response team. The list membership should be reviewed
-periodically and can be managed from
+The security response team uses the `openbmc-security at lists.ozlabs.org`
+private email list as a channel for confidential communication, so its
+membership reflects the composition of the security response team. The list
+membership should be reviewed periodically and can be managed from
`https://lists.ozlabs.org/listinfo/openbmc-security`.
-The email list subscribers should be reminded periodically to protect
-access to the emails from the list because of the sensitive
-information they contain.
+The email list subscribers should be reminded periodically to protect access to
+the emails from the list because of the sensitive information they contain.
-The email list membership is not intended to be secret. For example,
-we can discuss it a public forum. However, no effort is made to make
-the list's membership public.
+The email list membership is not intended to be secret. For example, we can
+discuss it a public forum. However, no effort is made to make the list's
+membership public.
-The email list identification is `for privately reporting OpenBMC security
-vulnerabilities` with description: This email list is for privately reporting
-OpenBMC security vulnerabilities. List membership is limited to the OpenBMC
-security response team. For more information, see
+The email list identification is
+`for privately reporting OpenBMC security vulnerabilities` with description:
+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
Sample response for denying list membership:
+
```
Thanks for your interest in OpenBMC security. Subscriptions to the
openbmc-security@lists.ozlabs.org email list are by invitation only
diff --git a/security/obmc-security-response-team.md b/security/obmc-security-response-team.md
index 0093852..d2605a9 100644
--- a/security/obmc-security-response-team.md
+++ b/security/obmc-security-response-team.md
@@ -1,42 +1,44 @@
# The OpenBMC security vulnerability reporting process
-This describes the OpenBMC security vulnerability reporting process
-which is intended to give the project time to address security
-problems before public disclosure.
+This describes the OpenBMC security vulnerability reporting process which is
+intended to give the project time to address security problems before public
+disclosure.
The main pieces are:
- - a procedure to privately report security vulnerabilities
- - a security response team to address reported vulnerabilities
- - the openbmc-security email address for the response team
- - guidelines for security response team members
+
+- a procedure to privately report security vulnerabilities
+- a security response team to address reported vulnerabilities
+- the openbmc-security email address for the response team
+- guidelines for security response team members
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.
-Note that the OpenBMC security response team is distinct from the
-OpenBMC security working group which remains completely open.
+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.
-The [How to privately report a security vulnerability](./how-to-report-a-security-vulnerability.md)
+Note that the OpenBMC security response team is distinct from the OpenBMC
+security working group which remains completely open.
+
+The
+[How to privately report a security vulnerability](./how-to-report-a-security-vulnerability.md)
web page explains how OpenBMC community members can report a security
vulnerability and get a fix for it before public announcement of the
vulnerability.
The `openbmc-security at lists.ozlabs.org` email address is the primary
-communication vehicle between the person who reported the problem and
-the security response team, and the initial communication between the
-security response team members.
+communication vehicle between the person who reported the problem and the
+security response team, and the initial communication between the security
+response team members.
-The [Guidelines for security response team members](./obmc-security-response-team-guidelines.md)
-contain collected wisdom for the response team and community members
-who are working to fix the problem.
+The
+[Guidelines for security response team members](./obmc-security-response-team-guidelines.md)
+contain collected wisdom for the response team and community members who are
+working to fix the problem.
diff --git a/subtree.md b/subtree.md
index ecf2f22..d84ab31 100644
--- a/subtree.md
+++ b/subtree.md
@@ -1,7 +1,7 @@
# Subtree Architecture
-In the past, meta-layer repositories were added to the repo as subtrees. This
-is no longer the case. Although the individual meta-\* trees still exist in
-gerrit and github for the sake of keeping a complete history, they should not be
-used, and new meta layers will simply be checked in within the openbmc/openbmc
-code tree.
+In the past, meta-layer repositories were added to the repo as subtrees. This is
+no longer the case. Although the individual meta-\* trees still exist in gerrit
+and github for the sake of keeping a complete history, they should not be used,
+and new meta layers will simply be checked in within the openbmc/openbmc code
+tree.
diff --git a/testing/local-ci-build.md b/testing/local-ci-build.md
index 92ffcc6..08fdfd4 100644
--- a/testing/local-ci-build.md
+++ b/testing/local-ci-build.md
@@ -9,8 +9,8 @@
[Docker Docs](https://docs.docker.com/install/) are a good place to start
looking.
-Check that the installation was successful by running `sudo docker run
-hello-world`.
+Check that the installation was successful by running
+`sudo docker run hello-world`.
Each repository is built locally within the CI using the bootstrap.sh and
automake toolchain.
@@ -66,8 +66,8 @@
./openbmc-build-scripts/run-unit-test-docker.sh
```
-`NO_FORMAT_CODE=1` tells the script to skip the `format-code.sh` so that it
-will not format the code and thus your repo could contain un-committed changes.
+`NO_FORMAT_CODE=1` tells the script to skip the `format-code.sh` so that it will
+not format the code and thus your repo could contain un-committed changes.
## Run CI for testing purposes only
diff --git a/testing/run-test-docker.md b/testing/run-test-docker.md
index afb5328..b87ac30 100644
--- a/testing/run-test-docker.md
+++ b/testing/run-test-docker.md
@@ -3,128 +3,129 @@
Running OpenBMC automation using Docker involves creating a Docker image and
then running automation tests inside the Docker container.
-
## Build Docker Image
`Note: Prerequisite is to have Docker installed.`
1. Create a workspace directory.
- `mkdir ${HOME}/OpenBMC_Automation`
+ `mkdir ${HOME}/OpenBMC_Automation`
2. Change directory to workspace created.
- `cd ${HOME}/OpenBMC_Automation`
+ `cd ${HOME}/OpenBMC_Automation`
3. Clone openbmc-build-scripts repository.
- `git clone https://github.com/openbmc/openbmc-build-scripts`
+ `git clone https://github.com/openbmc/openbmc-build-scripts`
4. Change directory to openbmc-build-scripts.
- `cd openbmc-build-scripts`
+ `cd openbmc-build-scripts`
-5. Build the Docker image required to execute the robot tests (it may take
- close to 15 mins for the first time). The default Docker image name is
+5. Build the Docker image required to execute the robot tests (it may take close
+ to 15 mins for the first time). The default Docker image name is
"openbmc/ubuntu-robot-qemu". You can check images using "docker images"
command.
- `./scripts/build-qemu-robot-docker.sh`
+ `./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.)_
- ```
- --build-arg http_proxy=<IP>:<PORT> --build-arg https_proxy=<IP>:<PORT>
- ```
+ ```
+ --build-arg http_proxy=<IP>:<PORT> --build-arg https_proxy=<IP>:<PORT>
+ ```
## Code update process using robot test code
1. Change directory to HOME workspace.
- `cd ${HOME}/OpenBMC_Automation`
+ `cd ${HOME}/OpenBMC_Automation`
2. Clone openbmc-test-automation repository.
- `git clone https://github.com/openbmc/openbmc-test-automation`
+ `git clone https://github.com/openbmc/openbmc-test-automation`
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.
- ```
- 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
- ```
+ ###### _Note: Download BMC fw image file (_.all.tar) before executing this. BMC_IMG_PATH below points to this downloaded file.
- 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:
+ ```
+ 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
+ ```
- ```
- 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
- ```
+ 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:
-4. On code update completion, logs generated from robot framework execution
- will be available in the following location:
+ ```
+ 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
+ ```
- ```
- ${HOME}/OpenBMC_Automation/log.html
- ${HOME}/OpenBMC_Automation/report.html
- ${HOME}/OpenBMC_Automation/output.xml
- ```
+4. On code update completion, logs generated from robot framework execution will
+ be available in the following location:
+ ```
+ ${HOME}/OpenBMC_Automation/log.html
+ ${HOME}/OpenBMC_Automation/report.html
+ ${HOME}/OpenBMC_Automation/output.xml
+ ```
## Executing Automation Test
1. Execute docker run to execute OpenBMC automation test cases.
- ###### *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.*
- ```
- 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
- ```
- Example to run entire test suite:
+ ###### _Note: This runs a Docker container using openbmc/ubuntu-robot-qemu image._
- ```
- 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
- ```
+ ###### _Robot test code is extracted and ran on this container using run-robot.sh script._
+
+ ```
+ 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
+ ```
+
+ Example to run entire test suite:
+
+ ```
+ 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
+ ```
2. After the execution, test results will be available in below files.
- ```
- ${HOME}/OpenBMC_Automation/log.html
- ${HOME}/OpenBMC_Automation/report.html
- ${HOME}/OpenBMC_Automation/output.xml`
- ```
+ ```
+ ${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 2aef629..fedde9a 100644
--- a/tof/contract.md
+++ b/tof/contract.md
@@ -1,35 +1,39 @@
# OpenBMC Technical Oversight Forum (TOF)
+
This is a working document and subject to change.
-The OpenBMC TOF or Technical Oversight Forum represents the technical
-leadership of the OpenBMC project.
+The OpenBMC TOF or Technical Oversight Forum represents the technical leadership
+of the OpenBMC project.
The TOF handles the processes around accepting new features into OpenBMC,
creating new subprojects (git repositories), approving subproject maintainers,
handling and enforcement of subproject maintainer issues, and many other
-technical leadership concerns related to OpenBMC. This source of this document
+technical leadership concerns related to OpenBMC. This source of this document
is in the [OpenBMC documentation repository](https://github.com/openbmc/docs).
The TOF updates and maintains this document, using the process documented
-within, and it can be considered authoritative unless directly overridden by
-the TSC.
+within, and it can be considered authoritative unless directly overridden by the
+TSC.
## Working Principles
+
- Decision making is a spectrum between building broad consensus, in which
everyone has agreement, and providing guidance quickly, even when there are
- strongly differing view-points. This group should intend to work towards
- broad consensus, with a balance towards moving forward when there is minor
+ strongly differing view-points. This group should intend to work towards broad
+ consensus, with a balance towards moving forward when there is minor
disagreement.
- Members within this forum are representatives of the development community as
- a whole and not as representatives for the entities they are employed by. As
- such, decisions should be made based on merits of the decision at hand and
- not on impacts to various member entities.
+ a whole and not as representatives for the entities they are employed by. As
+ such, decisions should be made based on merits of the decision at hand and not
+ on impacts to various member entities.
- Encouraging progress, experimentation, and decision making within the project
is the core purpose of the TOF and not to create processes and barriers to
- development. Velocity should be favored over perfection, except as a
- rationale for ignoring well-reasoned issues.
+ development. Velocity should be favored over perfection, except as a rationale
+ for ignoring well-reasoned issues.
## Role and responsibilities
+
Issues the TOF handle include:
+
- Approval of new bitbake meta layers.
- Approval of new subprojects.
- Supervising subproject maintainers.
@@ -38,19 +42,21 @@
## 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
+[here](https://github.com/openbmc/docs/blob/master/tof/membership-and-voting.md#terms-and-elections).
The TOF shall have a minimum of 5 and maximum of 9 members at any given time.
The chair rotates month to month.
Chair responsibilities:
+
- Preparing the agenda.
- Taking meeting minutes.
- Documenting decisions on GitHub.
-Members are elected by community contributors yearly. The voting process will
-be determined by the TOF at a later date and updated in this document. TOF
+Members are elected by community contributors yearly. The voting process will be
+determined by the TOF at a later date and updated in this document. TOF
candidates should have a breadth of knowledge about the OpenBMC project. Ideal
candidates will also have a public history of fostering collaboration between
teams.
@@ -59,29 +65,32 @@
next voting session.
## Github issues
+
The TOF tracks any ongoing decisions using GitHub issues in the
[TOF repository](https://github.com/openbmc/technical-oversight-forum/issues).
-Issues can be opened by anyone, including TOF members themselves. Issues
-can be requests for process or technical changes, or solicitations for the
-opinion of the TOF. When an issue is opened the TOF will respond to a proposal
-or a solicitation, or add it to the next TOF meeting agenda for TOF discussion.
+Issues can be opened by anyone, including TOF members themselves. Issues can be
+requests for process or technical changes, or solicitations for the opinion of
+the TOF. When an issue is opened the TOF will respond to a proposal or a
+solicitation, or add it to the next TOF meeting agenda for TOF discussion.
-Once an issue has a proposal, TOF members have 8 days to vote on the proposal
-in one of three ways: for, against, or “needs discussion”. After 8 days, if
-the proposal has at least three votes for and no other votes, the proposal is
-approved. Alternatively, if the proposal has at least three votes against and
-no other votes, the proposal is rejected and closed. Any other vote count
-results in the issue being put on the next TOF meeting agenda. To ensure
-proposals do not stagnate, if the initial 8 days elapses and the minimum number
-of votes has not been met, the proposal is extended by an additional 6 days and
-then put onto the next TOF meeting agenda after 2 weeks.
+Once an issue has a proposal, TOF members have 8 days to vote on the proposal in
+one of three ways: for, against, or “needs discussion”. After 8 days, if the
+proposal has at least three votes for and no other votes, the proposal is
+approved. Alternatively, if the proposal has at least three votes against and no
+other votes, the proposal is rejected and closed. Any other vote count results
+in the issue being put on the next TOF meeting agenda. To ensure proposals do
+not stagnate, if the initial 8 days elapses and the minimum number of votes has
+not been met, the proposal is extended by an additional 6 days and then put onto
+the next TOF meeting agenda after 2 weeks.
Issue vote indicators by reacting to the top post:
- - For - 👍 (`:+1:`)
- - Against - 👎 (`:-1:`)
- - Needs discussion - 👀 (`:eyes:`)
+
+- For - 👍 (`:+1:`)
+- Against - 👎 (`:-1:`)
+- Needs discussion - 👀 (`:eyes:`)
## Meetings
+
The TOF meets bi-weekly. Any requests for consideration by the TOF should be
submitted via a GitHub issue using the process documented earlier in this
document.
@@ -89,24 +98,25 @@
Meetings require a quorum of the TOF to be present; quorum is defined as:
| Active TOF membership | Quorum |
-| --- | --- |
+| --------------------- | ------ |
| 5 | 4 |
| 6 | 5 |
| 7 | 5 |
| 8 | 5 |
| 9 | 6 |
-During the meeting, the TOF discusses proposals under dispute and votes on
-them. A proposal is rejected if it does not reach majority approval or there is
-more than one dissenting vote.
+During the meeting, the TOF discusses proposals under dispute and votes on them.
+A proposal is rejected if it does not reach majority approval or there is more
+than one dissenting vote.
It is the responsibility of the TOF chairperson to make a public record of the
decisions of the meeting.
## Discord channel
-The TOF has a private Discord channel for forum member coordination and, in
-rare situations, potentially sensitive topics. Sensitive topics would be
-topics having security or privacy concerns, such as those involving actions of
-an individual developer. The TOF chairperson is responsible for coordinating
-the public posting of any information or decisions that do not need to remain
+
+The TOF has a private Discord channel for forum member coordination and, in rare
+situations, potentially sensitive topics. Sensitive topics would be topics
+having security or privacy concerns, such as those involving actions of an
+individual developer. The TOF chairperson is responsible for coordinating the
+public posting of any information or decisions that do not need to remain
private, using the same process as public issues.
diff --git a/tof/membership-and-voting.md b/tof/membership-and-voting.md
index 54bb84d..f60672e 100644
--- a/tof/membership-and-voting.md
+++ b/tof/membership-and-voting.md
@@ -5,7 +5,7 @@
### Members
The TOF body shall consist of between 5 and 9 members selected by the OpenBMC
-Development Community by vote. The current number of members is **7** and this
+Development Community by vote. The current number of members is **7** and this
shall only be changed, prior to a TOF election, by a unanimous decision at a
regular meeting of the current TOF body.
@@ -14,81 +14,82 @@
be elected a member of the TOF if they are eligible to vote in their own
election.
-To encourage a diverse viewpoint, no more than 2 TOF members may be employed
-by, or working under a contract relationship for, the same entity
-unless (one of):
+To encourage a diverse viewpoint, no more than 2 TOF members may be employed by,
+or working under a contract relationship for, the same entity unless (one of):
+
- The entity is the Linux Foundation.
- The TOF members have been unopposed in an election.
### Terms and Elections
-Members are elected by Ranked Choice Voting of the OpenBMC Development
-Community at twice yearly elections. Members of the TOF typically serve a 1
-year term before their seat is up for re-election; members have no term limits.
+
+Members are elected by Ranked Choice Voting of the OpenBMC Development Community
+at twice yearly elections. Members of the TOF typically serve a 1 year term
+before their seat is up for re-election; members have no term limits.
To facilitate continuity of the TOF body, these elections are held every 6
-months in which half (+/- 1) of the seats are re-elected. Due to additions or
+months in which half (+/- 1) of the seats are re-elected. Due to additions or
subtractions in seats and membership resignations, more than half (+1) of the
-seats may need to be filled in a single election. Prior to the election the
+seats may need to be filled in a single election. Prior to the election the
current TOF may determine a certain number of seats will be 6 month terms, to
return the number of seats per election to a more equal number, and these seats
will be given to the individuals with the later results in the RCV.
Elections are to begin on March 1st and September 1st at 00:00 UTC and conclude
-seven days later. Election schedule is as follows:
+seven days later. Election schedule is as follows:
-| Q1 Elections | Q3 Elections | Action on or by 00:00 UTC. |
-|:------------:|:------------:|:---------------------------|
-| Jan 1st | July 1st | Developer contributions close for OpenBMC Development Community membership eligibility (See “Metrics”). |
-| Jan 15th | July 15th | Current TOF must publish a list of eligible voting members. |
-| Jan 30th | July 30th | Nominations (self or peer) for TOF seats must be sent to the mailing list. |
-| Jan 30th | July 30th | Developers disputing membership eligibility must submit a petition request to the current TOF. |
-| Feb 15th | Aug 15th | Current TOF must publish a final list of eligible voting members and upcoming candidates for TOF seats. |
-| March 1st | Sept 1st | Election begins. |
-| March 7th | Sept 7th | Election concludes. |
-| March 15th | Sept 15th | Current TOF publishes election results and updates the TOF membership document with new members and terms. |
-| Apr 1st | Oct 1st | TOF member terms conclude / begin. |
+| Q1 Elections | Q3 Elections | Action on or by 00:00 UTC. |
+| :----------: | :----------: | :--------------------------------------------------------------------------------------------------------- |
+| Jan 1st | July 1st | Developer contributions close for OpenBMC Development Community membership eligibility (See “Metrics”). |
+| Jan 15th | July 15th | Current TOF must publish a list of eligible voting members. |
+| Jan 30th | July 30th | Nominations (self or peer) for TOF seats must be sent to the mailing list. |
+| Jan 30th | July 30th | Developers disputing membership eligibility must submit a petition request to the current TOF. |
+| Feb 15th | Aug 15th | Current TOF must publish a final list of eligible voting members and upcoming candidates for TOF seats. |
+| March 1st | Sept 1st | Election begins. |
+| March 7th | Sept 7th | Election concludes. |
+| March 15th | Sept 15th | Current TOF publishes election results and updates the TOF membership document with new members and terms. |
+| Apr 1st | Oct 1st | TOF member terms conclude / begin. |
This document shall be maintained with a list of current members and their term
end (sorted by term conclusion followed by alphabetically by preferred name):
-| Name | Term Conclusion |
-|:-----|:---------------:|
-| Andrew Jeffery | 2023-04-01 |
-| Jason Bills | 2023-04-01 |
-| Patrick Williams | 2023-04-01 |
-| William Kennington | 2023-04-01 |
-| Brad Bishop | 2023-10-01 |
-| Ed Tanous | 2023-10-01 |
-| Zev Weiss | 2023-10-01 |
+| Name | Term Conclusion |
+| :----------------- | :-------------: |
+| Andrew Jeffery | 2023-04-01 |
+| Jason Bills | 2023-04-01 |
+| Patrick Williams | 2023-04-01 |
+| William Kennington | 2023-04-01 |
+| Brad Bishop | 2023-10-01 |
+| Ed Tanous | 2023-10-01 |
+| Zev Weiss | 2023-10-01 |
## OpenBMC Development Community
Membership in the OpenBMC development community is determined by development
-contributions to the project. By contributing to the project, developers gain
-a voice in the technical direction of the project by shaping the membership in
-the TOF.
+contributions to the project. By contributing to the project, developers gain a
+voice in the technical direction of the project by shaping the membership in the
+TOF.
Membership is determined using data from the previous 6 months of development
-contributions. Using this data, the TOF will publish a list of Active Members
-of the two tiers. An individual who was an Active Member of a tier in the
-preceding 6 months, but does not qualify in the most recent 6 months, will be
-listed as an Member Emeritus for 6 months. Both Active and Emertius members
-are eligible for elections.
+contributions. Using this data, the TOF will publish a list of Active Members of
+the two tiers. An individual who was an Active Member of a tier in the preceding
+6 months, but does not qualify in the most recent 6 months, will be listed as an
+Member Emeritus for 6 months. Both Active and Emertius members are eligible for
+elections.
There are two tiers of membership in the development community: normal and
-highly-productive. It is the responsibility of the TOF to set metrics for
-determining community and tier membership. The normal membership tier is
+highly-productive. It is the responsibility of the TOF to set metrics for
+determining community and tier membership. The normal membership tier is
expected to maintain a low-bar to encourage a diverse and vibrant membership,
while the highly-productive membership tier is expected to represent between
-12.5% (1/8) and 20% (1/5) of the community. (Whenever the highly-productive tier
+12.5% (1/8) and 20% (1/5) of the community. (Whenever the highly-productive tier
has representation outside of this percentage, the TOF should adjust the
-determining metrics for the next election / membership cycle.) In any election
+determining metrics for the next election / membership cycle.) In any election
cycle, normal developers are given a vote weight of 1 and highly-productive
developers are given a vote weight of 3.
Any individual who feels their contributions to the project were not recognized
by the existing metrics may petition the TOF for inclusion in either tier and
-the TOF will make a determination. Examples of these types of contributions
+the TOF will make a determination. Examples of these types of contributions
might be: development in upstream Open Source communities not directly
controlled by OpenBMC, but for features leveraged by the OpenBMC codebase, and
significant support activities in areas not covered by existing metrics such as
@@ -97,27 +98,29 @@
Currently, work on the following projects requires an explicit petition for
recognition of ToF membership eligibility:
-* Linux
-* u-boot
-* QEMU
-* bitbake
-* open-embedded
-* Poky
+- Linux
+- u-boot
+- QEMU
+- bitbake
+- open-embedded
+- Poky
### Metrics
Determination of membership in the community is made by a point system for
activities.
+
- Development of a non-trivial commit (10+ lines) - 3 points.
- Non-trivial code review (3 or more code suggestions) - 1 point.
The TOF may decide to exempt commits which are only machine configuration or
-sub-sections of a repository only intended for use by one entity. For example
+sub-sections of a repository only intended for use by one entity. For example
repositories named `company-ipmi-oem-provider`, subdirectories named
`oem/company`, Yocto recipes in `meta-company`, and entity-manager configuration
-might all be exempted. Any such exemptions should be applied consistently to
-all members.
+might all be exempted. Any such exemptions should be applied consistently to all
+members.
Points required for Active membership (in the preceding 6 months):
+
- Normal - 15 points.
- Highly-Productive - 100 points.
diff --git a/yocto-development.md b/yocto-development.md
index 94f19e8..9cf2040 100644
--- a/yocto-development.md
+++ b/yocto-development.md
@@ -4,8 +4,7 @@
templates, tools and methods to help you create custom Linux-based systems for
embedded products regardless of the hardware architecture.
-OpenBMC uses the Yocto tools to manage configuration and creation of BMC
-images.
+OpenBMC uses the Yocto tools to manage configuration and creation of BMC images.
## Developing with Yocto
@@ -21,52 +20,51 @@
[cheatsheet](cheatsheet.md).
The second case can be helped with Yocto's `devtool`. After running
-`. setup <machine>`, a tool called `devtool` will be in your path, and can be
+`. setup <machine>`, a tool called `devtool` will be in your path, and can be
applied in several ways.
If you have an existing source tree you'd like to integrate, running
`devtool modify -n ${PACKAGE} ${SRCTREE}` first creates a new Yocto layer in
your build directory where devtool stores recipe modifications. It then
-constructs a `.bbappend` for the package recipe and uses the
-`externalsource` class to replace the download, fetch, and patch steps with
-no-ops. The result is that when you build the package, it will use the local
-source directory as is. Keep in mind that the package recipe may not perform a
-clean and depending on what you are doing, you may need to run `${PACKAGE}`
-build system's clean command in `${SRCTREE}` to clear any built objects. Also
-if you change the source, you may need to run
-`bitbake -c cleansstate ${PACKAGE}` to clear BitBake's caches.
+constructs a `.bbappend` for the package recipe and uses the `externalsource`
+class to replace the download, fetch, and patch steps with no-ops. The result is
+that when you build the package, it will use the local source directory as is.
+Keep in mind that the package recipe may not perform a clean and depending on
+what you are doing, you may need to run `${PACKAGE}` build system's clean
+command in `${SRCTREE}` to clear any built objects. Also if you change the
+source, you may need to run `bitbake -c cleansstate ${PACKAGE}` to clear
+BitBake's caches.
Alternatively, if you don't already have a local source tree but would still
-like to modify the package, invoking `devtool modify ${PACKAGE}` will handle
-the fetch, unpack and patch phases for you and drop a source tree into your
-default workspace location.
+like to modify the package, invoking `devtool modify ${PACKAGE}` will handle the
+fetch, unpack and patch phases for you and drop a source tree into your default
+workspace location.
When you are all done, run `devtool reset ${PACKAGE}` to remove the `.bbappend`
from the devtool Yocto layer.
Further information on [devtool][0] can be found in the [Yocto Mega Manual][1].
-
### Adding a file to your image
-There are a lot of examples of working with BitBake out there. The [recipe
+There are a lot of examples of working with BitBake out there. The [recipe
example][2] from OpenEmbedded is a great one and the premise of this OpenBMC
tailored section.
-So you wrote some code. You've been scp'ing the compiled binary on to the
-OpenBMC system for a while and you know there is a better way. Have it built
-as part of your flash image.
+So you wrote some code. You've been scp'ing the compiled binary on to the
+OpenBMC system for a while and you know there is a better way. Have it built as
+part of your flash image.
-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.
+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.
```
devtool add welcome https://github.com/causten/hello.git
```
-Now edit the bb file it created for you. You can just use `vim` but
-`devtool` can also edit the recipe `devtool edit-recipe welcome` without
-having to type the complete path.
+Now edit the bb file it created for you. You can just use `vim` but `devtool`
+can also edit the recipe `devtool edit-recipe welcome` without having to type
+the complete path.
Add/Modify these lines.
@@ -92,11 +90,10 @@
That's it, recompile and boot your system, the binary `hello` will be in
`/usr/bin` and the `README.md` will be in `/usr/shared/doc/welcome`.
-
### Know what your image has
Sure you could flash and boot your system to see if your file made it, but there
-is a faster way. The `rootfs` directory down in the depths of the `build/tmp`
+is a faster way. The `rootfs` directory down in the depths of the `build/tmp`
path is the staging area where files are placed to be packaged.
In my example to check if README.md was going to be added just do...
@@ -112,6 +109,12 @@
bitbake -g obmc-phosphor-image && cat pn-depends.dot |grep welcome
```
-[0]: https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#using-devtool-in-your-sdk-workflow "devtool"
-[1]: http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html "Yocto Mega Manual"
-[2]: http://www.embeddedlinux.org.cn/OEManual/recipes_examples.html "Recipe Example"
+[0]:
+ https://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html#using-devtool-in-your-sdk-workflow
+ "devtool"
+[1]:
+ http://www.yoctoproject.org/docs/latest/mega-manual/mega-manual.html
+ "Yocto Mega Manual"
+[2]:
+ http://www.embeddedlinux.org.cn/OEManual/recipes_examples.html
+ "Recipe Example"