Re: Seeking guidance to start to work on OpenBMC

[Johannes Truschnigg <johannes@truschnigg.info>]

[-- Attachment #1: Type: text/plain, Size: 10047 bytes --]

Hi Kavya!

I cannot speak on OpenBMC's behalf of course, but I might have a few useful
answers to your questions. I did try (and partly succeed, mostly thanks to the
great support from kind people in this community) to port OpenBMC onto a more
consumer-focused board, the Gigabyte MC12-LE0 (with an AST2500). The port is
not ready for production use and most userspace component configs are still
missing, but it *does* work in principle.

I had pretty much the same situation that you seem to face going in - no
manufacturer-internal docs, an existing BMC firmware image (that has many
AMI-specific patches on top of Linux 3.x and predates/avoids Device Trees, for
instance), and an appetite for some hacking ;)

My fork lives at https://github.com/jtru/openbmc/tree/gigabyte-mc12-le0
The installer at https://github.com/jtru/openbmc_gigabyte_mc12-le0_installer

I'll try to answer your questions inline.


On Thu, Oct 22, 2026 at 09:48:34AM +0530, KAVYA M M wrote:
> [...]
> I have the following questions:
> 
> 1. Hardware documentation required
> • What documents are normally required before starting an OpenBMC port for
> a new motherboard?

"Required" is an elastic term. From my experience, what I would have most
appreciated and what took the longest to reverse engineer would have been a
document detailing the mapping of GPIO pins.


> • Is the motherboard user manual sufficient, or do we also need the
> motherboard schematic, BMC datasheet, hardware design guide, component
> datasheets, and board-specific signal mappings?

The normal user manual is not going to be sufficient and probably not very
useful for what you intend to do in the first place. It's just a very
different target audience and use case that it covers. It *might* help you
locate UART debug pins for BMC console access on the board (if these exist),
but you'll probably have better results just looking for them on the PCB with
your own eyes :)


> • for example the CPU schematic and AST(BmC) reference schematic are
> available but the motherboard schematic is missing, how much of the
> required hardware configuration can be established from them?

Mind you that I only have experience with the AST2500; this might not apply to
you board/platform!) GPIOs and their purpose and polarity is, I think, what
will matter most.


> • Since my target board uses the ASTs BmC, which specific datasheets or
> hardware design documents should I obtain?

Anything you can get! :) But don't fret if you cannot get everything or even
most/many documents; having access to the running firmware (or an unencrypted
image of the firmware) will probably carry you most of the way, if you put
enough effort in. I guess that these days, some LLM-assisted reverse
engineering would carry you a long way rather quickly.


> 2. Extracting information from existing BMC firmware
> • If the original BMC firmware is available only as a binary and its Linux
> shell or source code is restricted, what information can reliably be
> extracted from the image?

Depends a lot on the firmware. With the AMI MegaRAC stuff, it was a mix of arm
ELF binaries, some (partly obfuscated) Lua stuff, data going in and out of
Redis, and shell scripts that held everything together. The latter parts were
easier to digest than those earlier in that list, but it's probably going to
be different for your board anyways. You will (have to :)) figure it out as
you explore the image/firmware.


> • Can we identify the flash layout, device tree, GPIO configuration, I²C
> devices, sensor definitions, fan configuration, Ethernet settings, and
> board identity?

Even AMI's very old Linux-based firmware foundation had to interface with all
these hardware facilities capabilities; the trouble was finding that
information in all kinds of non-standard places, and then translating these to
a "modern" DTS/DTB-based setup that OpenBMC requires. All the info is
certainly in there; HOW you will be able to obtain it, I cannot predict.


> • Which details can be confirmed from firmware, and which require the
> motherboard schematic or physical measurements?

I just can say that I did not need any special docs or even use of any special
electronic device to get as far as I managed to. What helped the most were
some Free and Open Source software tools to revive the BMC whenever I did
manage to brick it (culvert, flashrom), and the ability/equipment to short
certain pins on the BMC to prevent it from reading its ROM via SPI. That was
only required for device recovery when things had gone very bad.


> 3. GPIO and hardware configuration
> • How can we verify GPIO connections, signal polarity, direction, timing,
> and safe initial states without the motherboard schematic?

By reversing what the official, original firmware does. After that, trial and
error.


> • How can we identify the actual I²C bus routing, multiplexers, device
> addresses, and peripheral protocols?

Same as above.


> • What is the recommended method for verifying voltage-divider values, ADC
> scaling, and temperature sensor configuration?

Same as above.


> • How should fan PWM/tachometer mappings, fan zones, minimum safe speeds,
> and failsafe behavior be established?

Same as above.


> • How can the LED wiring, Ethernet PHY address/reset configuration, and
> NCSI connections be verified?

Same as above.


> 4. OpenBMC image development
> • What is the recommended workflow for creating a new OpenBMC machine
> configuration, device tree, Yocto layer, sensor configuration, and required
> services?

It's been such a long while since I started this adventure, and I am not very
familiar with Yocto regardless, so I do not feel like I can give very good
advice here. I did start with a new meta-$(manufacturer) sub-directory, and
cherry-pick (not in the git-commit-sense) components that I discovered were
needed to advance :)


> • Are there existing OpenBMC reference boards or porting guides that would
> be useful for this type of project?

I did draw some info from existing boards (AST2500 EVB and Facebook's
tiogapass machine), but I did that without having access to either of these in
hardware. YMMV.


> • Can we proceed with firmware analysis and QEMU testing while some
> hardware details remain unknown?

I never managed to boot the original AMI BMC firmware on QEMU, and did most
(if not all) of my porting work on the actual hardware. That might be a bad
idea if your board's implementation closely matches the QEMU example machines;
I imagine having a virtualized testing platform for this kind of dev work to
be an absolute boon.


> • Which functions can be validated in QEMU, and which must be tested on the
> physical motherboard?

I don't know, sorry.


> 5. Flashing and recovery
> • If the original BMC firmware source code is unavailable, can a custom
> OpenBMC image still be developed and flashed safely?

Yes, I think I have demonstrated that with my project.


> • How should the original SPI flash be backed up, the flash layout and
> image size verified, and a recovery procedure prepared?

You can use the manufacturer-specific update tooling to obtain a backup, or
try your luck with flashrom, via culvert, or by using a hardware flash
programmer. The backups have not been very important in my case, since just
flashing any stock firmware image onto the board's flash restored that in an
orderly, working fashion.


> • What checks should be completed before writing the image to the physical
> BMC?

I don't have any advice for that... but I would try to re-flash the
manufacturer's original firmware image at least once using a recovery-style
procedure (say, by using the EFI-shell based utility provided by most
manufacturers), so that you do not venture in blind in case you break the BMC
(and are lucky enough that the host still POSTs anyway, of course :))


> • If the image boots but networking, fan control, sensors, or other
> hardware functions do not work correctly, what is the recommended debugging
> and recovery process?

That is too general and broad a question to answer, I am afraid. I guess you
collect the information, and with it, return to this mailing list? :)


> 6. Validation and safety
> 
> • What validation checklist should be completed before enabling host power
> control or testing other GPIO outputs?

I had no such thing.


> • How should fan control and cooling failsafe behavior be validated before
> using the image on a live server?

I do not have such a thing yet, which is one of the things that keep me from
using my fork on one of the in-prod boards that I have ;)


> • What are the minimum hardware details that must be verified before
> proceeding with physical-board testing?

As I said, focus on your ability to restore the vendor's firmware image. If
you have the ability to restore, all other concerns are less important.


> My current goal is to continue testing the image in QEMU, document the
> confirmed and unverified hardware mappings, and determine the correct
> procedure before flashing the physical board.

That sounds great if the QEMU-based workflow is already working for you!


> I would be grateful for any recommended documentation, reference
> schematics, OpenBMC porting guides, practical experience, or advice from
> engineers who have worked on similar BMC porting projects.
> 
> Thank you for your time and guidance.

I did my best in answering you questions, documenting how I stumbled and tried
to get such a thing done. I hope you find some of the information shared
useful. I'd be happy to continue the conversation if you feel it's productive.

Best of luck on your OpenBMC adventure! :)

-- 
with best regards:
- Johannes Truschnigg ( johannes@truschnigg.info )

www:   https://johannes.truschnigg.info/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]