Improving people's experience with technical engagement in OpenBMC

[Andrew Jeffery]

On Tue, 2024-09-17 at 21:39 +0200, Johannes Truschnigg wrote:
> Hi Andrew,
> hi list,
> 
> I hope it's OK for me - an outsider, a private individual, and an amateur
> hobbyist - to comment and try to contribute to your thread.
> 

Oh, please don't consider yourself an outsider :)

>  For better or
> worse, I might be able to offer a perspective that is (I think) somewhat
> different from what most people concerned with OpenBMC perceive and experienced
> when starting to concern themselves with the project and its intricacies.
> 
> A little background info on my (admittedly very limited so far) involvement
> with OpenBMC is probably needed, so that you can better make sense of my input.
> 
> I started looking into the project in detail around May this year, because I
> had bought a "prosumer" mainboard from Gigabyte (the MC12-LE0) with an
> AST2500-based BMC, and the AMI-supplied BMC firmware seemed a bit half-baked
> and definitely far too proprietary for my FOSS-loving tastes. Since I'd been
> using OpenWrt on my networking gear for more than a decade, I had (incorrectly,
> I know ;)) assumed that OpenBMC was kind of a similar endeavor, but for BMCs
> instead of for routers et al.

Well, from a pretty zoomed-out perspective, perhaps it is. But I think
the details differ quite a bit, not the least the complexity of things
to which the BMC is attached, setting aside OpenBMC's implementation
complexities.

> 
> In my day job, I am what people these days call SRE, but I've started out as a
> humble sysop nearly 20 years ago. I've been using BMCs in all their
> incarnations and from different vendors since the early 2000s, but I had little
> idea what makes them tick on the BMC's side. (I've always been an avid fan of
> `ipmitool`, and had some ideas about what was going when I used it to make a
> lanplus connection, but what kind of magic made the host and the BMC interact
> the way they did and do has always been a mystery to me). Also, I have
> basically zero background knowledge in embedded devices (apart from using
> OpenWrt and some userspace-only development targeting it), and a far too feeble
> understanding of all things electronics to be any less than a considerable
> danger for any ICs on which I bring my multimeter to bear.

Relatable.

> All I got going for
> me in this was an above-average understanding of the Linux (and even there,
> mostly userspace) software side of things - in other words, really not much of
> relevance for what I was about to try. I am rather sure it is not really
> representative of OpenBMC's target group for technical engagement :)

I think that if you're playing with it at all you're the target group,
so don't discount yourself too quickly.

> 
> Several months later, I've now had chances to dip my toes into the official
> OpenBMC mailing lists, had some friendly email conversations with subscribers
> both on- and off-list, and interacted with OpenBMC-involved individuals (such as
> you, btw!) on Github issues. I have to say, the social experience has been
> absolutely stellar - the people involved are so very friendly, willing to help
> and welcoming that all these interactions have been an absolute delight!

Thanks for sharing that.

> 
> 
> What I've had trouble with is... well, the more technical side of things...
> 
> I had quickly discovered the openbmc/docs repo and read through most of its
> contents, but I mostly felt overwhelmed by most parts during my irregular
> evening lecture.
> 
> There are some commendable and promising documents in there that,
> unfortunately, don't always push as far as it's needed (for me, personally) to
> connect all the oh so many dots - for instance, the glossary.md document[0].
> It's great that it's there, and it explains a number of acronyms and concepts
> that are crucial to have heard of, but I think it could and should be several
> times as long as it is! ;) If the OpenBMC community could come together and
> extend that document (and other resources similar in spirit) by as much as
> possible/feasible, the next person like me - with mostly a severe lack of
> relevant background - would have a much easier time becoming somewhat
> productive with this whole BMC-understanding and eventually -crafting affair, I
> think.

Okay, that's a good practical suggestion.

> 
> A few weeks after I had started looking at OpenBMC, I somehow managed to
> stumble over the youtube-hosted recordings[1] of a number of OpenBMC-related
> presentations that were given during the earlier days of the Covid19 pandemic,
> and that stuff helped me understand a *lot* of things a *lot* more clearly. I
> think it would be amazing if that series could be extended upon, but I think it
> also really just needs to be more prominently featured in the docs/on the
> project site so that it's not like the twenty-third, but second or maybe even
> first thing to find when just starting out.

Ah, I'd forgotten about the youtube series. Great to hear that it was
helpful, I'll try to work a link to that into the documentation.

> 
> More "OpenBMC - The Big Picture (for the Uninitiated)"-content - be it written
> prose or video (or, ideally, both) would certainly be great to have. I think a
> kind of "OpenBMC Tech Tree", where both mandatory and optional components for
> the operations of a BMC system, are presented and explained on a high-ish
> level, with included (lists of) available implementations in OpenBMC would make
> for a terrific "map" to have handy, because it's very easy to get lost in the
> woods without.
> 
> And finally, these days, after I've been toiling away for months during the
> evenings at my still-secret git branch that shall one fine day make the
> MC12-LE0 a fully-featured OpenBMC board, I find myself wishing for two things
> quite often:
> 
> 1.) For each project/software artifact under the OpenBMC umbrella to have an
> up-to-date, (at least) top-level README.md that explains what the thing I am
> looking at is about and useful for, and ...

Ideally, yeah. This needs some maintainer action, I suspect. I don't
think it's feasible to have one person go around and update all the
READMEs. But following from that, we have to motivate maintainers to do
the work.

Maybe this discussion is a bit of a nudge.

> 
> 2.) (if possible, without breaking backwards compatibility) to have all
> executables built by OpenBMC conform to basic getopt(3)/getopt_long(3)
> conventions when invoked with (e.g.) `--help` and/or `--version` on the
> argument vector, and give me glimpse at their purpose without having to look at
> the source. I realize that this might sound a bit silly, but it would help me
> very much when doing triage, and deciding on which kind of failing/non-working
> service to focus on first.

Ah, we're trying for consistency there, but there's some historical
baggage. At least, we have the following:

 * https://github.com/openbmc/docs/blob/master/anti-patterns.md#custom-
   argumentparser-object
 * https://github.com/openbmc/docs/blob/master/anti-patterns.md#non-
   standard-debug-application-options-and-logging

Maybe something further for adding `--help` and `--version` is
warranted (though `--version` might not be super helpful with the way
the project currently approaches versioning things).
> 
> 
> In closing, to extend your list of "personality profiles"/perspectives near the
> end of your message with another possible kind, I will put forward this attempt
> at a definition/characterization of myself in regard to my interest in OpenBMC:
> 
>  6. I'm not affiliated with any corporate or commercial entity, and would
>  like to help make use of OpenBMC on COTS hardware that is capable of
>  running OpenBMC, but effectively cannot run it yet.

We had a suggestion on Discord for a "enthusiast" category, so you're
not the only one thinking along those lines:

https://discord.com/channels/775381525260664832/867820390406422538/1285234749979230259

> 
> 
> If you think that's a perspective worth taking into account (and I could
> totally understand if that weren't the case - I get that it's kind of an
> outlier, esp. given the project's obvious industry/corporate focus), I think my
> wishlist would go a long way in meeting that demographic's (maybe not even
> overly specific) needs.

My main trouble with it was figuring out how to narrow down the
documentation to link to for this category. I didn't immediately come
up with any ideas, all of it seems kinda hard to exclude for this case.
Do you have any thoughts?

Andrew