Documenting hardware support (was: Repository Growth)

Thu Sep 20 04:39:48 AEST 2018

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: joseph-reynolds at charter.net
Cc: "OpenBMC Maillist", "Patrick Venture"
Sent: Wednesday September 19 2018 1:09:52PM
Subject: Re: Repository Growth

 On Wed, Sep 19, 2018 at 12:56 PM  wrote:
 >
 >
 > Date: Wed, 19 Sep 2018 09:42:16 -0700
 > From: Patrick Venture 
 > To: anoo at linux.ibm.com
 > Cc: OpenBMC Maillist , Brad Bishop
 > , Nancy Yuen ,
 > openbmc-bounces+anoo=linux.ibm.com at lists.ozlabs.org
 > Subject: Re: Repository Growth
 > Message-ID:
 > 
 > Content-Type: text/plain; charset="UTF-8"
 >
 > On Wed, Sep 19, 2018 at 9:03 AM Adriana Kobylak  wrote:
 > >
 > > On 2018-09-19 10:47, Patrick Venture wrote:
 > > > With the growth of number of repositories, it might be
overwhelming to
 > > > someone who wants to set things up.
 > > >
 > > > I'd like to write up a directory that groups the repositories
by
 > > > purpose. I wasn't sure if this made sense, so I wanted early
feedback
 > > > before I started. The maintenance of it would be horrible for
one
 > > > person, but if someone wants their repository to have details
and so
 > > > on they can add it.
 > > >
 > > > I think it's important or useful to know what's out there and
how
 > > > 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
 > daemons don't really fit into a category. Maybe that's fine, maybe
 > then it'd be uncategorized.
 >
 > I was imagining:
 >
 > {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.
 > works with: phosphor-host-ipmid
 > """
 >
 > You don't need to run phosphor-host-ipmid to use phosphor-hwmon,
and
 > 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
 > just want to present a better interface to the set of repositories
and
 > how they work together (or don't) than github has.
 >
 > >
 > > > Thoughts?
 >
 > I had the same idea from reading through the presentations recently
linked to on this mailing list.
 >
 > 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):
 > - 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 repo
 >
 > I would start with the features listed in openbmc/README, and add
features (or interfaces?) from James's presentation:
 > - 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, ...

 >
 > So, the proposal is to group repos by feature and interface.
 >
 > > >
 > > > Patrick
 > >
 >

Links:
------
[1] https://github.com/openbmc/openbmc
[2] https://github.com/openbmc/docs.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.ozlabs.org/pipermail/openbmc/attachments/20180919/453ddb5f/attachment-0001.html>