How to Port OpenBMC to a Custom Hardware Platform

Porting OpenBMC to a custom hardware platform means adapting the OpenBMC Linux distribution and its management services so they correctly operate a particular baseboard management controller (BMC) and the host system it manages. It is more than compiling a kernel for a new processor. A working port must describe the board to Linux, package the right drivers and services through Yocto, model platform sensors and inventory, connect power and reset behavior to OpenBMC interfaces, and produce a firmware image that can be safely installed and recovered.

The effort is easiest to manage when hardware facts are collected before recipes are changed. Start with the BMC SoC, memory and flash map, boot chain, buses, GPIO assignments, host interfaces, sensors, and update mechanism. Then bring those pieces up in layers, testing each at the console and on D-Bus before relying on Redfish or a web interface.

What a Platform Port Includes

OpenBMC uses Yocto/OpenEmbedded to assemble a Linux image from reusable layers. A machine configuration selects board-specific build settings; recipes and package groups select software; kernel and bootloader configuration support the hardware; and platform services expose management functions. OpenBMC applications commonly communicate over D-Bus, while systemd controls service startup and dependencies. The upstream project describes this as a customizable distribution built with Yocto, OpenEmbedded, systemd, and D-Bus.

Think of the port as a chain of contracts: the bootloader loads the right kernel and device tree; Linux binds drivers to the actual peripherals; userspace reads and controls those devices; OpenBMC services publish stable D-Bus objects; and external clients consume the resulting Redfish, IPMI, or other interfaces. A gap at any boundary can make the board appear partially functional while hiding important failures.

A Practical Workflow to Port OpenBMC

1. Inventory the Board and Define the Support Boundary

Collect schematics, SoC and board revisions, memory and flash organization, boot straps, console settings, power sequencing, and the management-controller-to-host links. Create a signal map for I2C/SMBus, SPI, UART, GPIO, PWM, tachometer inputs, ADC channels, watchdogs, reset lines, and host communication paths such as LPC, eSPI, PCIe, or MCTP. Record polarity, voltage domain, muxes, bus speeds, and which device owns each signal.

Turn that map into a feature matrix: required sensors and thresholds; fan zones and control policy; chassis and host power states; LEDs and buttons; FRU and inventory data; event logging; network setup; firmware update and rollback; and security requirements. Mark each item as hardware-supported, software-supported upstream, board-specific integration, or explicitly out of scope. This prevents “the image boots” from becoming the completion criterion.

2. Create or Extend the Yocto Machine and Layer

Choose the closest maintained OpenBMC platform as a reference. If the new board is a true variant with the same core design, a machine configuration in an existing vendor layer may be enough. If it adds materially different hardware or has a separate maintenance owner, create a dedicated layer and machine. The upstream “add new system” tutorial illustrates the machine/layer pattern, though individual file names and layer conventions can change over time.

The machine configuration identifies the target architecture, kernel provider and device tree, bootloader or image settings, and board-specific overrides. The layer should declare its compatibility and dependencies, add the layer to the build, and keep local changes in maintainable recipes, appends, configuration fragments, and patches. Avoid editing shared OpenBMC or Yocto files directly: those changes are hard to reproduce and easy to lose during an update.

Initialize the build environment with the OpenBMC setup script for the chosen machine, then build the standard image target. The project README documents the basic pattern: source “. setup <machine>” and run “bitbake obmc-phosphor-image.” Save the exact source revisions, build configuration, and resulting image identifier so later test results can be reproduced.

3. Bring up the Boot Chain, Kernel, and Device Tree

Start with the serial console and confirm bootloader execution, memory initialization, flash access, kernel loading, and root filesystem mounting. Use the platform’s actual flash layout and boot policy; do not assume another board’s partition map or recovery behavior is safe for this design. Confirm that reset causes, watchdog behavior, and power-loss scenarios match the intended update design.

Add or adapt the Linux device tree to describe the BMC SoC and board wiring: enabled controllers, pin multiplexing, I2C buses and muxes, GPIOs, SPI flash, UARTs, regulators, fan and sensor interfaces, and interrupt lines. Use existing upstream bindings and drivers wherever possible. If a device is missing, first determine whether the issue is wiring, pin configuration, kernel configuration, driver support, or a device-tree description error. The OpenBMC kernel guide notes that its Linux tree carries patches and gives guidance on kernel work and device trees.

Validate each peripheral with Linux tools before integrating it into a higher-level daemon. Check bus enumeration, driver probe logs, GPIO line state, PWM output, tachometer readings, and I2C transactions. This separates low-level board issues from service configuration and provides a reliable baseline for later debugging.

4. Integrate Sensors, Inventory, and Platform Services

OpenBMC’s sensor architecture maps hardware readings to D-Bus sensor objects. Depending on the sensor and platform, data may come through Linux hwmon drivers, phosphor-hwmon configuration, dbus-sensors, or a purpose-built service. Configure names, units, scaling, thresholds, and associations deliberately: a plausible temperature value with an incorrect scale can be more dangerous than an unavailable sensor. 

Use Entity Manager configuration where it fits the platform’s runtime hardware discovery and configuration model; its purpose is to describe supported hardware configurations rather than directly manage individual devices. [5] Add FRU and inventory data so operators can identify the chassis, board, processors, fans, and power supplies. Then connect platform-specific behavior to established OpenBMC interfaces for chassis state, host state, LEDs, logging, and software update rather than inventing a private API for functionality already represented upstream.

Next, enable only the services the product needs and verify the dependency graph. A service can be healthy in isolation but start too early, publish an incomplete inventory, or block another daemon while waiting on hardware. OpenBMC services and external interfaces are managed through systemd, and the architecture documentation maps D-Bus services to the network and host-facing interfaces they expose.

5. Validate Management Behavior and Security

Test end-to-end actions, not only individual daemons. A temperature sensor should appear with the correct value and threshold state; a fan fault should produce the intended event and policy response; a host power request should operate the physical control lines and report the resulting state; and an update should be visible through the supported management interface. Confirm that Redfish resources and properties represent the actual board and that any required IPMI commands or OEM extensions behave consistently.

Treat the BMC as a security boundary. Define the required network services and disable interfaces the product does not use. Validate account policy, certificate provisioning, TLS configuration, SSH exposure, update authenticity, debug access, and recovery procedures against the product threat model. OpenBMC documentation describes its interfaces as an attack surface that should be understood as a system, including which services can be disabled. [6] A secure boot or signed update story also depends on the boot ROM, bootloader, key provisioning, manufacturing flow, and recovery design; it cannot be added solely by toggling a userspace build option.

6. Test on Emulator and Physical Hardware

Use QEMU or another supported emulator for rapid build iteration, service configuration, and basic API tests where the emulated machine covers the relevant behavior. Emulator success does not validate the target board’s electrical signals, thermal response, flash layout, timing, or host interface. Move to hardware early for those checks, beginning with a recovery path and a known-good image.

Build a test matrix for cold boot, warm reboot, power removal, watchdog expiry, sensor boundary values, missing peripherals, bus errors, fan failure, host state transitions, network loss, interrupted update, rollback, and factory reset. Capture boot logs and D-Bus state at each step. Run repeatable tests across board revisions and image upgrades; include regression checks when changing a kernel, device tree, or common platform service.

OpenBMC Porting Versus a Generic Linux BSP

A generic Linux board support package gets the kernel and core peripherals running. An OpenBMC port includes that foundation plus the BMC-specific management model: sensors and thresholds, inventory, power and reset state, logging, firmware update, and external interfaces. The Linux bring-up work overlaps, but the expected outcome is broader and has operational and security consequences.

A useful sequence is to establish the kernel and device tree first, then integrate hardware into existing OpenBMC services, and only then add a custom daemon if the platform has behavior that cannot be represented through existing interfaces. This keeps board-specific code small and gives clients a more consistent management interface across product generations.

Common Porting Mistakes

• Starting from a distant reference platform and inheriting unrelated recipes, patches, or policy.
• Treating a successful image build or login prompt as proof that sensors, power control, updates, and recovery work.
• Encoding board behavior in ad hoc scripts when a standard D-Bus interface or service already exists.
• Using sensor labels, units, scale factors, thresholds, or fan direction that do not match the physical hardware.
• Changing shared upstream files directly instead of isolating changes in a vendor layer and tracking revisions.
• Deferring physical testing until late, especially for flash layout, update interruption, GPIO polarity, and host communication.
• Leaving debug interfaces, default credentials, unused network services, or untested recovery paths in the production image.

OpenBMC Porting Checklist

• Board documentation, signal map, feature matrix, and supported board revisions are approved.
• Machine configuration, layer dependencies, kernel, bootloader settings, and device tree build reproducibly.
• Serial console, boot, flash layout, root filesystem, and recovery behavior are verified on hardware.
• Every required sensor, fan, LED, button, FRU, and host control is validated end to end.
• D-Bus objects, systemd dependencies, Redfish resources, and required IPMI behavior are checked.
• Firmware installation, interruption handling, rollback, and image authentication are tested.
• Security configuration, credentials, network exposure, and production debug policy are reviewed.
• Build inputs, source revisions, test results, image hashes, and release procedures are recorded.

Frequently Asked Questions

Can I port OpenBMC to a BMC SoC that is not already supported?

Possibly, if Linux has the required architecture, boot chain, and peripheral support and the OpenBMC userspace can be built for it. Expect work in the Yocto machine configuration, kernel and bootloader integration, and potentially additional upstream or vendor drivers. Verify toolchain, storage, and update constraints before committing to the port.

How long does an OpenBMC port take?

It depends on how much of the SoC and board is already supported, the quality of the hardware documentation, and how much platform behavior is required. A close board variant may need configuration and validation; a new SoC, flash design, or management interface can require substantial kernel, bootloader, and service work. Estimate from the feature matrix and hardware risks rather than from the first successful boot.

Can QEMU replace testing on the target board?

No. QEMU is useful for software iteration and tests supported by the emulator, but it cannot prove electrical behavior, board-specific device-tree accuracy, thermal control, flash reliability, or update recovery on the real hardware.

Should we maintain a private OpenBMC fork?

Keep proprietary board configuration and product-specific changes in focused layers where practical, and upstream broadly reusable fixes. A fork may be required for product policy or release control, but it increases the cost of tracking security fixes and upstream changes. Define ownership, review, and rebase cadence early.

Conclusion

A dependable OpenBMC port begins with a precise hardware map and ends with verified management and recovery behavior on the actual board. Build the Yocto machine and layer cleanly, bring up the boot chain and device tree, represent hardware through established Linux drivers and OpenBMC interfaces, then test failure paths as carefully as normal operation. The result is maintainable when board-specific changes stay isolated, D-Bus contracts remain predictable, and every release can be rebuilt and traced.

For platform-specific support, see Conclusive Engineering’s OpenBMC ecosystem services and its firmware development services.