184 lines
8.0 KiB
Markdown
184 lines
8.0 KiB
Markdown
# Hardware Vendor Repository Policy
|
|
|
|
Author: Andrew Geissler @geissonator
|
|
|
|
Other contributors:
|
|
|
|
Created: May 13, 2024
|
|
|
|
## Introduction
|
|
|
|
This document covers the criteria from the TOF (Technical Oversight Forum) when
|
|
a request for a new repository or a bitbake recipe to be hosted under the
|
|
OpenBMC Github project is made. It starts with the requirements and then some
|
|
information on how those requirements were created.
|
|
|
|
## Requirements
|
|
|
|
Note that there is an expectation the reader of this document is familiar with
|
|
OpenBMC architecture (bitbake, d-bus, phosphor-dbus-interfaces, ...).
|
|
|
|
Writing hard rules for anything is hard without defeating intent, these are
|
|
guidelines to be used by the OpenBMC TOF in their decision to approve or not
|
|
approve new recipes or repos.
|
|
|
|
Both hardware-specific and vendor-specific repositories should meet the
|
|
following requirements to be eligible for a repository under OpenBMC:
|
|
|
|
1. It is compatible with the Apache 2.0 license
|
|
2. If an existing repository, it has an active maintainer
|
|
3. It has no external dependencies which would fail the requirements defined
|
|
within this document
|
|
4. The new repository will not break others (i.e. providing new APIs utilized by
|
|
a common repository that are not protected by compile flags, etc)
|
|
5. It is a feature that is believed to be generally useful to the OpenBMC
|
|
organization
|
|
- Determination made by the TOF
|
|
- Reference: "Create a new repository" TOF [process][tof]
|
|
6. It has an active OpenBMC community member that is willing to be a maintainer
|
|
|
|
Note that the first option should always be to look into hosting the repository
|
|
under OpenBMC (vs. a recipe in OpenBMC that points to an external repository).
|
|
|
|
A repository must be hosted under OpenBMC if:
|
|
|
|
1. The repository depends on other OpenBMC-hosted repositories
|
|
|
|
If someone wishes to create a recipe within OpenBMC to point to an external
|
|
repository, the following could be a valid reason for this:
|
|
|
|
1. If the repository is utilized by other projects outside of OpenBMC then it
|
|
may be better suited outside of OpenBMC and utilized via a bitbake recipe
|
|
|
|
If a recipe is created within OpenBMC (in any meta-X layer) to point to an
|
|
external repository then that repository must fulfill the following
|
|
requirements:
|
|
|
|
1. It should meet all of the quality-based requirements for hosting a repository
|
|
within OpenBMC
|
|
2. The external repository must never have its git history rewritten
|
|
3. The maintainer of the repository must commit to quick turnaround on critical
|
|
fixes for things such as new compiler updates
|
|
|
|
Note that when a recipe is non-OpenBMC specific, but useful to OpenBMC, it
|
|
should be pushed upstream into meta-openembedded.
|
|
|
|
### Hardware Specific Feature
|
|
|
|
A hardware vendor feature is defined as one of the following:
|
|
|
|
1. A function that is specific to the vendor hardware
|
|
- For example, PECI, FSI, hardware diagnostics (specific to the processor)
|
|
2. A device attached to the BMC (MCTP/PLDM/I2C/...) that is specific to the
|
|
vendor which the BMC must interact with
|
|
|
|
To add a hardware specific repository to OpenBMC, it should meet the following
|
|
additional criteria:
|
|
|
|
1. If it requires specific kernel APIs, they are available or in progress via
|
|
the [upstream][upstream] guidelines
|
|
|
|
Some hardware vendor features which have no real synergy with OpenBMC, for
|
|
example a CPLD code base that's only relevant to a particular vendors system,
|
|
may be better suited to be hosted externally to OpenBMC.
|
|
|
|
### Vendor Specific Feature
|
|
|
|
A vendor-specific feature is defined as one of the following:
|
|
|
|
1. A vendor-specific data format or protocol
|
|
- For example, a dump collection of the host firmware, or a special format of
|
|
SPD/VPD
|
|
2. A function that requires a specific hardware vendor feature
|
|
|
|
To add a vendor-specific repository to OpenBMC, it should meet the following
|
|
additional criteria:
|
|
|
|
1. It consumes OpenBMC D-Bus APIs
|
|
- This indicates a synergy between this feature and OpenBMC
|
|
|
|
## Background and References
|
|
|
|
As OpenBMC has grown, so has the need for software function that is tied to
|
|
specific hardware families. For example, [OpenPOWER][openpower] was one of the
|
|
first users of OpenBMC and a search for "openpower" in the openbmc github
|
|
organization will show many repositories with that name in it. You will get a
|
|
similar result if you search for "intel".
|
|
|
|
OpenBMC in general is to be agnostic of the hardware it is managing, but that is
|
|
not always possible due to specific features or functions only provided by
|
|
certain hardware.
|
|
|
|
For example, OpenPOWER systems have a separate power management device within
|
|
the processor called an OCC. This OCC has its own protocol and functions. This
|
|
is why OpenBMC has a openpower-occ-control repository.
|
|
|
|
Another example, Intel has a communication interface called PECI, it provides
|
|
useful information (like temperatures) but only on Intel based systems. This is
|
|
why OpenBMC has a peci-pcie repository.
|
|
|
|
The goal of this document is to clearly state the requirements and expectations
|
|
for hosting a hardware/vendor specific repository within the openbmc github
|
|
organization. This document aims to answer the following questions:
|
|
|
|
1. Where does the OpenBMC community draw the line between what goes into the
|
|
OpenBMC organization and what should not?
|
|
|
|
2. If a repository doesn't belong in the OpenBMC organization, what determines
|
|
if a bitbake recipe can be added to OpenBMC to point to a vendors repository
|
|
outside of the OpenBMC org?
|
|
|
|
This document is based on a TOF meeting on Jan 9th, 2024.
|
|
|
|
## Philosophy
|
|
|
|
OpenBMC wants to enable as many machines as possible with as many common paths
|
|
shared between machines as possible, under the hope of keeping stability in its
|
|
implementation between systems.
|
|
|
|
Within OpenBMC there are two areas of "vendor specific" repositories:
|
|
|
|
- A Hardware specific feature (implementation for a driver, support for
|
|
hardware, or other things that only exist on that platform).
|
|
- Support for a vendor-specific feature. (OEM extensions, debug APIs, Redfish,
|
|
etc).
|
|
|
|
Yocto differentiates between the above with the "machine" and "distro" concepts.
|
|
We need a policy within OpenBMC on how we handle each of these types of
|
|
features.
|
|
|
|
The OpenBMC project has a fairly extensive CI process, it has many great code
|
|
reviewers, and it follows the tip of upstream yocto master. All of these things
|
|
ensure a solid code base for others to use, and sets a certain standard for
|
|
repositories that are hosted within OpenBMC. Having the source under the OpenBMC
|
|
umbrella ensure it gets global updates (like upstream poky/bitbake changes) and
|
|
other things like the latest compiler.
|
|
|
|
There are times where big updates come in from yocto that break multiple
|
|
repositories utilized by OpenBMC. It is always going to be easier to coordinate
|
|
big changes like that on repositories hosted within OpenBMC directly (vs. trying
|
|
to coordinate with externally hosted repositories.)
|
|
|
|
OpenBMC already hosts 100+ repositories, which can be very daunting to someone
|
|
new joining the project. New repositories should be added in the case where they
|
|
can be maintained over the long term without taking resources away from other
|
|
project efforts. Having a set of guidelines for this process helps to speed up
|
|
new code development within the project. How useful is the feature, how many
|
|
other people could make use of it, how active has the person who will maintain
|
|
the new repository been in the community? These are just a few of the questions
|
|
we need to articulate into a vetting process.
|
|
|
|
In a perfect world, only hardware-specific features would be in the meta machine
|
|
layers, and vendor specific features should be in distro features. OpenBMC is
|
|
not there yet but is something the community should strive towards.
|
|
|
|
## Conclusion
|
|
|
|
This document was written to be a reference for people looking where to put
|
|
vendor specific features and also as a reference for the TOF team to review when
|
|
assessing a request for a vendor specific repository within OpenBMC.
|
|
|
|
[openpower]: https://openpowerfoundation.org/
|
|
[upstream]: https://github.com/openbmc/docs/blob/master/kernel-development.md
|
|
[tof]: https://github.com/openbmc/technical-oversight-forum/issues
|