1*11ddfd42SAndrew Geissler# Hardware Vendor Repository Policy 2*11ddfd42SAndrew Geissler 3*11ddfd42SAndrew GeisslerAuthor: Andrew Geissler @geissonator 4*11ddfd42SAndrew Geissler 5*11ddfd42SAndrew GeisslerOther contributors: 6*11ddfd42SAndrew Geissler 7*11ddfd42SAndrew GeisslerCreated: May 13, 2024 8*11ddfd42SAndrew Geissler 9*11ddfd42SAndrew Geissler## Introduction 10*11ddfd42SAndrew Geissler 11*11ddfd42SAndrew GeisslerThis document covers the criteria from the TOF (Technical Oversight Forum) when 12*11ddfd42SAndrew Geisslera request for a new repository or a bitbake recipe to be hosted under the 13*11ddfd42SAndrew GeisslerOpenBMC Github project is made. It starts with the requirements and then some 14*11ddfd42SAndrew Geisslerinformation on how those requirements were created. 15*11ddfd42SAndrew Geissler 16*11ddfd42SAndrew Geissler## Requirements 17*11ddfd42SAndrew Geissler 18*11ddfd42SAndrew GeisslerNote that there is an expectation the reader of this document is familiar with 19*11ddfd42SAndrew GeisslerOpenBMC architecture (bitbake, d-bus, phosphor-dbus-interfaces, ...). 20*11ddfd42SAndrew Geissler 21*11ddfd42SAndrew GeisslerWriting hard rules for anything is hard without defeating intent, these are 22*11ddfd42SAndrew Geisslerguidelines to be used by the OpenBMC TOF in their decision to approve or not 23*11ddfd42SAndrew Geisslerapprove new recipes or repos. 24*11ddfd42SAndrew Geissler 25*11ddfd42SAndrew GeisslerBoth hardware-specific and vendor-specific repositories should meet the 26*11ddfd42SAndrew Geisslerfollowing requirements to be eligible for a repository under OpenBMC: 27*11ddfd42SAndrew Geissler 28*11ddfd42SAndrew Geissler1. It is compatible with the Apache 2.0 license 29*11ddfd42SAndrew Geissler2. If an existing repository, it has an active maintainer 30*11ddfd42SAndrew Geissler3. It has no external dependencies which would fail the requirements defined 31*11ddfd42SAndrew Geissler within this document 32*11ddfd42SAndrew Geissler4. The new repository will not break others (i.e. providing new APIs utilized by 33*11ddfd42SAndrew Geissler a common repository that are not protected by compile flags, etc) 34*11ddfd42SAndrew Geissler5. It is a feature that is believed to be generally useful to the OpenBMC 35*11ddfd42SAndrew Geissler organization 36*11ddfd42SAndrew Geissler - Determination made by the TOF 37*11ddfd42SAndrew Geissler - Reference: "Create a new repository" TOF [process][tof] 38*11ddfd42SAndrew Geissler6. It has an active OpenBMC community member that is willing to be a maintainer 39*11ddfd42SAndrew Geissler 40*11ddfd42SAndrew GeisslerNote that the first option should always be to look into hosting the repository 41*11ddfd42SAndrew Geisslerunder OpenBMC (vs. a recipe in OpenBMC that points to an external repository). 42*11ddfd42SAndrew Geissler 43*11ddfd42SAndrew GeisslerA repository must be hosted under OpenBMC if: 44*11ddfd42SAndrew Geissler 45*11ddfd42SAndrew Geissler1. The repository depends on other OpenBMC-hosted repositories 46*11ddfd42SAndrew Geissler 47*11ddfd42SAndrew GeisslerIf someone wishes to create a recipe within OpenBMC to point to an external 48*11ddfd42SAndrew Geisslerrepository, the following could be a valid reason for this: 49*11ddfd42SAndrew Geissler 50*11ddfd42SAndrew Geissler1. If the repository is utilized by other projects outside of OpenBMC then it 51*11ddfd42SAndrew Geissler may be better suited outside of OpenBMC and utilized via a bitbake recipe 52*11ddfd42SAndrew Geissler 53*11ddfd42SAndrew GeisslerIf a recipe is created within OpenBMC (in any meta-X layer) to point to an 54*11ddfd42SAndrew Geisslerexternal repository then that repository must fulfill the following 55*11ddfd42SAndrew Geisslerrequirements: 56*11ddfd42SAndrew Geissler 57*11ddfd42SAndrew Geissler1. It should meet all of the quality-based requirements for hosting a repository 58*11ddfd42SAndrew Geissler within OpenBMC 59*11ddfd42SAndrew Geissler2. The external repository must never have its git history rewritten 60*11ddfd42SAndrew Geissler3. The maintainer of the repository must commit to quick turnaround on critical 61*11ddfd42SAndrew Geissler fixes for things such as new compiler updates 62*11ddfd42SAndrew Geissler 63*11ddfd42SAndrew GeisslerNote that when a recipe is non-OpenBMC specific, but useful to OpenBMC, it 64*11ddfd42SAndrew Geisslershould be pushed upstream into meta-openembedded. 65*11ddfd42SAndrew Geissler 66*11ddfd42SAndrew Geissler### Hardware Specific Feature 67*11ddfd42SAndrew Geissler 68*11ddfd42SAndrew GeisslerA hardware vendor feature is defined as one of the following: 69*11ddfd42SAndrew Geissler 70*11ddfd42SAndrew Geissler1. A function that is specific to the vendor hardware 71*11ddfd42SAndrew Geissler - For example, PECI, FSI, hardware diagnostics (specific to the processor) 72*11ddfd42SAndrew Geissler2. A device attached to the BMC (MCTP/PLDM/I2C/...) that is specific to the 73*11ddfd42SAndrew Geissler vendor which the BMC must interact with 74*11ddfd42SAndrew Geissler 75*11ddfd42SAndrew GeisslerTo add a hardware specific repository to OpenBMC, it should meet the following 76*11ddfd42SAndrew Geissleradditional criteria: 77*11ddfd42SAndrew Geissler 78*11ddfd42SAndrew Geissler1. If it requires specific kernel APIs, they are available or in progress via 79*11ddfd42SAndrew Geissler the [upstream][upstream] guidelines 80*11ddfd42SAndrew Geissler 81*11ddfd42SAndrew GeisslerSome hardware vendor features which have no real synergy with OpenBMC, for 82*11ddfd42SAndrew Geisslerexample a CPLD code base that's only relevant to a particular vendors system, 83*11ddfd42SAndrew Geisslermay be better suited to be hosted externally to OpenBMC. 84*11ddfd42SAndrew Geissler 85*11ddfd42SAndrew Geissler### Vendor Specific Feature 86*11ddfd42SAndrew Geissler 87*11ddfd42SAndrew GeisslerA vendor-specific feature is defined as one of the following: 88*11ddfd42SAndrew Geissler 89*11ddfd42SAndrew Geissler1. A vendor-specific data format or protocol 90*11ddfd42SAndrew Geissler - For example, a dump collection of the host firmware, or a special format of 91*11ddfd42SAndrew Geissler SPD/VPD 92*11ddfd42SAndrew Geissler2. A function that requires a specific hardware vendor feature 93*11ddfd42SAndrew Geissler 94*11ddfd42SAndrew GeisslerTo add a vendor-specific repository to OpenBMC, it should meet the following 95*11ddfd42SAndrew Geissleradditional criteria: 96*11ddfd42SAndrew Geissler 97*11ddfd42SAndrew Geissler1. It consumes OpenBMC D-Bus APIs 98*11ddfd42SAndrew Geissler - This indicates a synergy between this feature and OpenBMC 99*11ddfd42SAndrew Geissler 100*11ddfd42SAndrew Geissler## Background and References 101*11ddfd42SAndrew Geissler 102*11ddfd42SAndrew GeisslerAs OpenBMC has grown, so has the need for software function that is tied to 103*11ddfd42SAndrew Geisslerspecific hardware families. For example, [OpenPOWER][openpower] was one of the 104*11ddfd42SAndrew Geisslerfirst users of OpenBMC and a search for "openpower" in the openbmc github 105*11ddfd42SAndrew Geisslerorganization will show many repositories with that name in it. You will get a 106*11ddfd42SAndrew Geisslersimilar result if you search for "intel". 107*11ddfd42SAndrew Geissler 108*11ddfd42SAndrew GeisslerOpenBMC in general is to be agnostic of the hardware it is managing, but that is 109*11ddfd42SAndrew Geisslernot always possible due to specific features or functions only provided by 110*11ddfd42SAndrew Geisslercertain hardware. 111*11ddfd42SAndrew Geissler 112*11ddfd42SAndrew GeisslerFor example, OpenPOWER systems have a separate power management device within 113*11ddfd42SAndrew Geisslerthe processor called an OCC. This OCC has its own protocol and functions. This 114*11ddfd42SAndrew Geissleris why OpenBMC has a openpower-occ-control repository. 115*11ddfd42SAndrew Geissler 116*11ddfd42SAndrew GeisslerAnother example, Intel has a communication interface called PECI, it provides 117*11ddfd42SAndrew Geissleruseful information (like temperatures) but only on Intel based systems. This is 118*11ddfd42SAndrew Geisslerwhy OpenBMC has a peci-pcie repository. 119*11ddfd42SAndrew Geissler 120*11ddfd42SAndrew GeisslerThe goal of this document is to clearly state the requirements and expectations 121*11ddfd42SAndrew Geisslerfor hosting a hardware/vendor specific repository within the openbmc github 122*11ddfd42SAndrew Geisslerorganization. This document aims to answer the following questions: 123*11ddfd42SAndrew Geissler 124*11ddfd42SAndrew Geissler1. Where does the OpenBMC community draw the line between what goes into the 125*11ddfd42SAndrew Geissler OpenBMC organization and what should not? 126*11ddfd42SAndrew Geissler 127*11ddfd42SAndrew Geissler2. If a repository doesn't belong in the OpenBMC organization, what determines 128*11ddfd42SAndrew Geissler if a bitbake recipe can be added to OpenBMC to point to a vendors repository 129*11ddfd42SAndrew Geissler outside of the OpenBMC org? 130*11ddfd42SAndrew Geissler 131*11ddfd42SAndrew GeisslerThis document is based on a TOF meeting on Jan 9th, 2024. 132*11ddfd42SAndrew Geissler 133*11ddfd42SAndrew Geissler## Philosophy 134*11ddfd42SAndrew Geissler 135*11ddfd42SAndrew GeisslerOpenBMC wants to enable as many machines as possible with as many common paths 136*11ddfd42SAndrew Geisslershared between machines as possible, under the hope of keeping stability in its 137*11ddfd42SAndrew Geisslerimplementation between systems. 138*11ddfd42SAndrew Geissler 139*11ddfd42SAndrew GeisslerWithin OpenBMC there are two areas of "vendor specific" repositories: 140*11ddfd42SAndrew Geissler 141*11ddfd42SAndrew Geissler- A Hardware specific feature (implementation for a driver, support for 142*11ddfd42SAndrew Geissler hardware, or other things that only exist on that platform). 143*11ddfd42SAndrew Geissler- Support for a vendor-specific feature. (OEM extensions, debug APIs, Redfish, 144*11ddfd42SAndrew Geissler etc). 145*11ddfd42SAndrew Geissler 146*11ddfd42SAndrew GeisslerYocto differentiates between the above with the "machine" and "distro" concepts. 147*11ddfd42SAndrew GeisslerWe need a policy within OpenBMC on how we handle each of these types of 148*11ddfd42SAndrew Geisslerfeatures. 149*11ddfd42SAndrew Geissler 150*11ddfd42SAndrew GeisslerThe OpenBMC project has a fairly extensive CI process, it has many great code 151*11ddfd42SAndrew Geisslerreviewers, and it follows the tip of upstream yocto master. All of these things 152*11ddfd42SAndrew Geisslerensure a solid code base for others to use, and sets a certain standard for 153*11ddfd42SAndrew Geisslerrepositories that are hosted within OpenBMC. Having the source under the OpenBMC 154*11ddfd42SAndrew Geisslerumbrella ensure it gets global updates (like upstream poky/bitbake changes) and 155*11ddfd42SAndrew Geisslerother things like the latest compiler. 156*11ddfd42SAndrew Geissler 157*11ddfd42SAndrew GeisslerThere are times where big updates come in from yocto that break multiple 158*11ddfd42SAndrew Geisslerrepositories utilized by OpenBMC. It is always going to be easier to coordinate 159*11ddfd42SAndrew Geisslerbig changes like that on repositories hosted within OpenBMC directly (vs. trying 160*11ddfd42SAndrew Geisslerto coordinate with externally hosted repositories.) 161*11ddfd42SAndrew Geissler 162*11ddfd42SAndrew GeisslerOpenBMC already hosts 100+ repositories, which can be very daunting to someone 163*11ddfd42SAndrew Geisslernew joining the project. New repositories should be added in the case where they 164*11ddfd42SAndrew Geisslercan be maintained over the long term without taking resources away from other 165*11ddfd42SAndrew Geisslerproject efforts. Having a set of guidelines for this process helps to speed up 166*11ddfd42SAndrew Geisslernew code development within the project. How useful is the feature, how many 167*11ddfd42SAndrew Geisslerother people could make use of it, how active has the person who will maintain 168*11ddfd42SAndrew Geisslerthe new repository been in the community? These are just a few of the questions 169*11ddfd42SAndrew Geisslerwe need to articulate into a vetting process. 170*11ddfd42SAndrew Geissler 171*11ddfd42SAndrew GeisslerIn a perfect world, only hardware-specific features would be in the meta machine 172*11ddfd42SAndrew Geisslerlayers, and vendor specific features should be in distro features. OpenBMC is 173*11ddfd42SAndrew Geisslernot there yet but is something the community should strive towards. 174*11ddfd42SAndrew Geissler 175*11ddfd42SAndrew Geissler## Conclusion 176*11ddfd42SAndrew Geissler 177*11ddfd42SAndrew GeisslerThis document was written to be a reference for people looking where to put 178*11ddfd42SAndrew Geisslervendor specific features and also as a reference for the TOF team to review when 179*11ddfd42SAndrew Geisslerassessing a request for a vendor specific repository within OpenBMC. 180*11ddfd42SAndrew Geissler 181*11ddfd42SAndrew Geissler[openpower]: https://openpowerfoundation.org/ 182*11ddfd42SAndrew Geissler[upstream]: https://github.com/openbmc/docs/blob/master/kernel-development.md 183*11ddfd42SAndrew Geissler[tof]: https://github.com/openbmc/technical-oversight-forum/issues 184