Documenting hardware support (was: Repository Growth)
I apologize in advance if this is not formatted as plain text and for "top posting"... I'll try to improve my email etiquette.
Idea: Explain OpenBMC hardware environments
I would like to see a brief explanation of OpenBMC's relationship to its BMC and host server. In my (limited) understanding, the relationship between the two hardware platforms (how the BMC services its host) is the essence of what OpenBMC adds to the openembedded project, so it deserves an explanation in the docs repo.
Specifically, this is required background to discuss OpenBMC support for various BMCs and host machines. - I understand BMC hardware support is in the form of Board Support Packages (BSP) which come from the openembedded project.
- I understand host machines are supported from meta-layers.
I propose to enhance the openbmc/docs docs to include talk about how to find board support layers (e.g., meta-aspeed), and machine layers (e.g., meta-intel). For each supported BMC and each supported host, I want to understand:
- where to find more information about the device (e.g., its proper
name, manufacturer or specs)
- how OpenBMC supports that hardware. Example: OpenPower systems use
the meta-openpower layer and various openpower-* layers such as openpower-power-control.
I have a limited hardware background, but I presume such a document would be a good place to introduce any hardware-facing features that BMCs typically provide (i.e., added to the openembedded layer). For example:
- firmware update
- event log processing
- host console or video
Also, I believe such a document would be a good place to anchor the guide for how to add a new BMC or host machine.
-----------------------------------------From: "Andrew Geissler"
To: [email protected]
Cc: "OpenBMC Maillist", "Patrick Venture"
Sent: Wednesday September 19 2018 1:09:52PM
Subject: Re: Repository Growth
Quoted 11 lines · On Wed, Sep 19, 2018 at 12:56 PM wrote:
Date: Wed, 19 Sep 2018 09:42:16 -0700
From: Patrick Venture
To: [email protected]
Cc: OpenBMC Maillist , Brad Bishop
, Nancy Yuen , [email protected]
Subject: Re: Repository Growth
Message-ID:
Quoted 6 lines
Content-Type: text/plain; charset="UTF-8"
Quoted 3 lines · Adriana Kobylak
Quoted 1 line · Patrick Venture
With the growth of number of repositories, it might be
overwhelming to
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
someone who wants to set things up.
I'd like to write up a directory that groups the repositories
by
Quoted 1 line
Quoted 1 line
Quoted 1 line
purpose. I wasn't sure if this made sense, so I wanted early
feedback
Quoted 1 line
Quoted 1 line
Quoted 1 line
before I started. The maintenance of it would be horrible for
one
Quoted 1 line
Quoted 1 line
Quoted 1 line
person, but if someone wants their repository to have details
and so
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
on they can add it.
I think it's important or useful to know what's out there and
how
Quoted 8 lines
Quoted 5 lines
Quoted 3 lines
things work together or don't, and what options there are for developers.
+1 . Do you have a template in mind on how this could look like?
I've been toying around with some ideas on how to organize the information. Grouping the subtrees together is a no-brainer, but
many
Quoted 5 lines
daemons don't really fit into a category. Maybe that's fine, maybe then it'd be uncategorized.
I was imagining:
Quoted 8 lines
{repository name}
{short description}
works with: {list of related pieces}for instance:
"""
### phosphor-hwmon
phosphor-hwmon periodically reads and reports hwmon sensor values
to dbus.
Quoted 4 lines
works with: phosphor-host-ipmid
"""You don't need to run phosphor-host-ipmid to use phosphor-hwmon,
and
Quoted 5 lines
phosphor-pid-control and other daemons can also listen to sensor values or read them over dbus, so I don't know how complete such a list would need to be. So maybe the list should be less explicit. I realize that the recipes themselves reveal the true dependencies, either virtual or specific and I don't want to repost information.
I
Quoted 1 line
just want to present a better interface to the set of repositories
and
Quoted 6 lines
how they work together (or don't) than github has.
Quoted 2 lines
Quoted 2 lines
Thoughts?
I had the same idea from reading through the presentations recently
linked to on this mailing list.
Quoted 2 lines
OpenBMC lists its features on its front page
(https://github.com/openbmc/openbmc [1] README) and suggests there is more information in https://github.com/openbmc/docs. [2] However, the information is not structured as well as it could be for someone to learn about each feature. I propose to list each feature along with the following information (as applicable):
Quoted 8 lines
- reference an external website or standard
- categorize: host-facing, management network facing, application
- explain terminology (give synonyms)
- explain 1 or 2 use cases
- link to the docs (which should explain customizations)
- link to the source code repoI would start with the features listed in openbmc/README, and add
features (or interfaces?) from James's presentation:
Quoted 3 lines
- Host interfaces: KCS, BT, mbox, IPMB, USB, VGA
- Network Interfaces: Redfish, https, ssh, rmcp+
- Applications: EWS, KVM, IPMI, FSC, SEL, SOL, Chassis Control,
ASD, Firmware Update, Configuration Manager, Sensor Monitor
Makes sense to me.
Per the mailing list discussion yesterday on the hackathon, I'm also starting to work on some "digging into openbmc coding" type docs. That will probably deserve it's own directory?
- Getting Started: Dev env setup, hello world via SDK/QEMU, adding a new system/layer, customizing webui and other items for new system, bitbake using local repos, ...
Quoted 7 lines
So, the proposal is to group repos by feature and interface.
Quoted 3 lines
Quoted 2 lines
Patrick
Links:
------
[1] https://github.com/openbmc/openbmc
[2] https://github.com/openbmc/docs.