Skip to content

Latest commit

 

History

History
183 lines (133 loc) · 7.97 KB

hw-vendor-repos-policy.md

File metadata and controls

183 lines (133 loc) · 7.97 KB
Raw

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
  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 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 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.