Here's a little guide to working on OpenBMC. This document will always be a work-in-progress, feel free to propose changes.
Authors:
Jeremy Kerr jk@ozlabs.org
OpenBMC has quite a modular structure, consisting of small daemons with a limited set of responsibilities. These communicate over D-Bus with other components, to implement the complete BMC system.
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.
For future development, keep this design in mind. Components' functionality should be logically grouped, and keep related parts together where it makes sense.
If you're starting out with OpenBMC, you may want to take a look at the issues tagged with 'bitesize'. These are fixes or enhancements that don't require extensive knowledge of the OpenBMC codebase, and are easier for a newcomer to start working with.
Check out that list here:
https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+user%3Aopenbmc+label%3Abitesize
If you need further details on any of these issues, feel free to add comments.
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 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/
If a repository has a setup.cfg file present in its root directory, then CI will automatically verify the Python code meets the pycodestyle 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, an 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
For C code, we typically use the Linux coding style, which is documented at:
In short:
Indent with tabs instead of spaces, set at 8 columns
80-column lines
Opening braces on the end of a line, except for functions
This style can mostly be verified with 'astyle' as follows:
astyle --style=linux --indent=tab=8 --indent=force-tab=8
See C++ Style and Conventions.
We use git for almost everything. Changes should be sent as patches to their relevant source tree - or a git pull request for convenience.
Each commit should be a self-contained logical unit, and smaller patches are usually better. However, if there is no clear division, a larger patch is okay. During development, it can be useful to consider how your change can be submitted as logical units.
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).
Commit messages are important. They should describe why the change is needed, and what effects it will have on the system. Do not describe the actual code change made by the patch; that's what the patch itself is for.
Use your full name for contributions, and include a "Signed-off-by" line, to indicate that you agree to the Developer's Certificate of Origin (see below).
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.
Ensure that your patch doesn't change unrelated areas. Be careful of accidental whitespace changes - this makes review unnecessarily difficult.
The guidelines in the Linux kernel are very useful:
https://www.kernel.org/doc/html/latest/process/submitting-patches.html
https://www.kernel.org/doc/html/latest/process/submit-checklist.html
Your contribution will generally need to be reviewed before being accepted.
The OpenBMC Gerrit server supports GitHub credentials, its link is:
https://gerrit.openbmc-project.xyz/#/q/status:open
One time only: Execute one of the OpenBMC Contributor License Agreements:
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.
After signing a CLA, send it to openbmc@lists.ozlabs.org.
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-project.xyz/#/settings/
Most repositories are supported by the Gerrit server, the current list can be found under Projects -> List:
https://gerrit.openbmc-project.xyz/#/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-project.xyz
Port 29418
User your_github_id
From your OpenBMC git repository, add a remote to the Gerrit server, where 'openbmc_repo' is the current git repository you're working on, such as phosphor-rest-server, and 'openbmc.gerrit' is the name of the Host previously added:
git remote add gerrit ssh://openbmc.gerrit/openbmc/openbmc_repo
Obtain the git hook commit-msg to automatically add a Change-Id to the commit message, which is needed by Gerrit:
gitdir=$(git rev-parse --git-dir)
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 HEAD:refs/for/master
Code and commit messages should not refer to companies' internal documents or systems (including bug trackers). Other developers may not have access to these, making future maintenance difficult.
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.
New D-Bus interfaces should be documented in the 'docs' repository, at:
https://github.com/openbmc/docs/blob/master/dbus-interfaces.md
See also: http://dbus.freedesktop.org/doc/dbus-api-design.html
There are numerous resources available elsewhere, but a few items that are relevant to OpenBMC work:
You almost never need to 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.
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.
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.
Ensure that your code compiles without warnings, especially for changes to the kernel.
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the best
of my knowledge, is covered under an appropriate open source
license and I have the right under that license to submit that
work with modifications, whether created in whole or in part
by me, under the same open source license (unless I am
permitted to submit under a different license), as indicated
in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including all
personal information I submit with it, including my sign-off) is
maintained indefinitely and may be redistributed consistent with
this project or the open source license(s) involved.