About cookies on this site Our websites require some cookies to function properly (required). In addition, other cookies may be used with your consent to analyze site usage, improve the user experience and for advertising. For more information, please review your options. By visiting our website, you agree to our processing of information as described in IBM’sprivacy statement. To provide a smooth navigation, your cookie preferences will be shared across the IBM web domains listed here.
Tutorial
How to port OpenBMC
With code modifications in the local system
On this page
This tutorial describes how to port OpenBMC to a new machine, including changes to OpenBMC layers, the Linux® kernel, and several related components such as hwmon sensor, LED, and inventory.
It also includes information about how to modify the code in the local system to build OpenBMC with local changes without changing the recipe.
Porting to a new machine
To port OpenBMC to a new machine, complete the following steps:
- Add the layer of the new machine in meta-openbmc.
- Make the kernel changes for the new machine such as configurations and dts.
- Add the workbook of the new machine.
- Make the required changes that are specific to the new machine, for example, to the hwmon sensor and LED.
Adding the machine layer
Let us take an example of adding a machine machine-name-2
in the manufacturer-1
repository.
- To create the layer, you can either reuse the existing repository
meta-manufacturer-1
, or create a new repository. - Create a
meta-machine-name-2
directory in themeta_manufacturer-1
repository for the machine. - Update the configuration files with the machine name
machine-name-2
instead ofmanufacturer-1
. - Create a conf directory in
meta_manufacturer-1
, followingmeta-ibm/conf
.
After you complete these steps, the directory tree is similar to the following structure:
The above directory tree creates a new layer in the machine.
Making kernel changes
This section describes how you can make changes to the kernel to port the OpenBMC to a new machine. The device tree is in https://github.com/openbmc/linux/tree/dev-4.13/arch/arm/boot/dts. For examples, see aspeed-bmc-opp-romulus.dts or a similar machine. Complete the following steps to make kernel changes:
Add the new machine device tree:
- Describe the GPIOs, for example, LED, FSI, and gpio-keys. You can obtain this information from the schematic.
- Describe the i2c buses and devices, which usually include various hwmon sensors.
- Describe the other devices, such as uarts and mac.
- Usually the flash layout does not need a change. Include the openbmc-flash-layout.dtsi file.
Modify the Makefile to build the device tree.
Notes:
- In
dev-4.10
, there is common and machine-specific initialization code inarch/arm/mach-aspeed/aspeed.c
which is used to perform common initializations and specific settings in each machine. - With
dev-4.13
, most of the initializations are done with the upstreamed clock and reset driver. - If the machine requires specific settings such as uart routing, send an mail to the mailing list for discussion.
Adding the workbook
In legacy OpenBMC, the workbook describes the machine's services, sensors, and FRUs. It is a Python configuration and is used by other services in skeleton. In the latest OpenBMC release, phosphor-xxx services are used and thus, skeleton is deprecated. However, workbook is required to make the build.
An example is meta-quanta, that defines its own configuration in the OpenBMC tree, so that it does not rely on the skeleton repository.
For OpenPOWER systems, several configurations are still used in this configuration file. For example, in Romulus.py, the configuration details are as follows:
The PowerUp and PowerOK GPIOs are needed for the build to power on the chassis and check the power state.
Making other miscellaneous changes
Different machines have different devices, such as hwmon sensors, LEDs, and fans.
OpenBMC is designed to be configurable. Hence, you can describe such devices in different configuration files in the machine layer.
Hwmon sensors
Hwmon sensors include sensors on board, such as temperature sensors, fans, and OCC sensors. The path and name in the configuration files must match the devices in the device tree.
Here, Romulus is taken as an example. The configuration files are in the meta-romulus/recipes-phosphor/sensors repository, which includes sensors on board and sensors of OCC, where on-board sensors are through i2c, and OCC sensors are through FSI.
w83773g@4c.conf defines the
w83773
temperature sensor containing three temperatures:This device is defined in its device tree as w83773g@4c. When the BMC starts, the udev rule starts
phosphor-hwmon
and it creates temperature sensors on the following DBus objects based on the sysfs attributes.pwm-tacho-controller@1e786000.conf defines the fans and the configuration is similar as above. The difference is that it creates fan_tach sensors.
occ-hwmon.1.conf defines the OCC hwmon sensor for the master CPU. This configuration is different and
phosphor-hwmon
is instructed to read the label instead of directly getting the index of the sensor, because CPU cores and DIMMs could be dynamic. For example, CPU cores could be disabled and DIMMs could be pulled out.MODE_temp* = "label"
indicates that if tempX is seen, the label is read, which is the sensor ID.LABEL_temp* = "xxx"
indicates the sensor name for the corresponding sensor ID.For example, if the value of
temp1_input
is37000
and the value oftemp1_label
is91
in sysfs,phosphor-hwmon
knowstemp1_input
is for sensor ID 91, which isp0_core0_temp
. Hence, it creates/xyz/openbmc_project/sensors/temperature/p0_core0_temp
with a sensor value of 37000.The power sensors do not need to read the label because all powers are available on a system.
LEDs
Several parts are involved for LEDs.
In kernel dts, LEDs are described. For example, romulus dts describes three LEDs,
fault
,identify
, andpower
.In the machine layer, LEDs are configured through YAML files to describe how it functions. For example,
It tells the LED manager to set the
power
LED to blink when BMC is ready and booted, and set it on when host is powered on.During run time, the LED manager automatically sets LEDs to on/off/blink based on the above YAML configuration file.
LEDs can be accessed manually through /xyz/openbmc_project/led/. For example:
Get identify LED state:
curl -b cjar -k https://$bmc/xyz/openbmc_project/led/physical/identify
Set identify LED to blink:
jar -k -X PUT -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.Led.Physical.Action.Blink" }' https://$bmc/xyz/openbmc_project/led/physical/identify/attr/State
Note: This YAML configuration can be automatically generated by phosphor-mrw-tools from its MRW. See the example of Witherspoon.
Inventories and other sensors
Inventories, other sensors (for example, CPU/DIMM temperature), and FRUs are defined in the IPMIs YAML configuration files.
For example, meta-romulus/recipes-phosphor/ipmi
romulus-ipmi-inventory-map
defines regular inventories, such as CPU, memory, and motherboard.phosphor-ipmi-fru-properties
defines extra properties of the inventories.phosphor-ipmi-sensor-inventory
defines the sensors from IPMI.romulus-ipmi-inventory-sel
defines inventories used for IPMI SEL.
inventory map
and fru-properties
are similar in different systems. Refer to this example and make one for your system.
For ipmi-sensor-inventory
, the sensors from IPMI are different in different systems. Hence, you must define your own sensors. For example:
The first value 0x08
, 0x1e
, and 0x22
are the sensor IDs of IPMI, which is defined in MRW. You should follow the system's MRW to define the above configuration.
Note : The YAML configuration files can be automatically generated by phosphor-mrw-tools from its MRW, see example of Witherspoon.
Fans
phosphor-fan-presence manages all the services about fan:
phosphor-fan-presence
checks if a fan is present, creates the fan DBus objects in the inventory, and updates the Present property.phosphor-fan-monitor
checks if a fan is functional and updates theFunctional
property of the fan Dbus object.phosphor-fan-control
controls the fan speed by setting the fan speed target based on conditions, for example, temperatures.phosphor-cooling-type
checks if the system is air-cooled or water-cooled by setting properties of the/xyz/openbmc_project/inventory/system/chassis
object.
All the above services are configurable, for example, by using the YAML configuration file. Hence, the machine specific configurations are written when porting OpenBMC to a new machine.
Taking Romulus as example, it is air-cooled and has three fans without GPIO presence detection.
Fan presence
Romulus has no GPIO detection for fan. Hence, it checks for the fan tachometer sensor:
The YAML configuration file indicates the following data:
- It creates the
/system/chassis/motherboard/fan0
object in inventory. - It checks that the fan0 tachometer sensor (
/sensors/fan_tach/fan0
) setsPresent
as the property on thefan0
object.
Fan monitor
Romulus fans uses pwm to control the fan speed, where pwm ranges from 0 to 255, and the fan speed ranges from 0 to about 7000. Hence, it needs a factor and offset to map the pwm to fan speed:
The YAML config indicates the following data:
FanPwm
is used as the target interface of the tachometer sensor;- The expected fan speed is calculated with the formula,
target * 21 + 1600
- The deviation is
15%
. Hence, if the fan speed is out of the expected range for more than 30 seconds,fan0
shall be set as non-functional.
Fan control
The fan control service requires four YAML configuration files:
zone-condition
defines the cooling zone conditions. Romulus is always air-cooled. Hence, this configuration involves defining aair_cooled_chassis
condition based on the cooling type property.zone-config
defines the cooling zones. Romulus has only one zone:It defines the zone full speed and default floor speed for the fans. In this example, the fan pwm is set to 255 if it is in full speed, and set to 195 if fans are in default floor speed.
fan-config
defines which fans are controlled in which zone and which target interface shall be used, for example, the following YAML configuration defines that thefan0
is controlled inzone0
and it would use theFanPwm
interface.events-config
defines the various events and its handlers (for example, which fan targets would be set in which temperature). This configuration is described with examples in example event yaml. Romulus example:
The above YAML configuration defines the fan floor and ceiling speed in zone0_ambient
's different temperatures. For example,
- When the temperature is lower than 27-degree celsius, the floor speed (pwm) is set to 85.
- When temperature is between 27 and 32-degree celsius, the floor speed (pwm) is set to 112.
With above configurations, phosphor-fan runs the fan presence/monitor/control logic as configured specifically for the machine.
Note : Romulus fans are simple. The following are the additional functions of Witherspoon fan configuration:
- It checks the GPIO for fan presence.
- It checks the GPIO to determine if the system is air or water cooled.
- It has more sensors and more events in fan control.
GPIOs
This section mainly focuses on the GPIOs that are monitored in the device tree. For example,
- A GPIO might represent a signal of host checkstop.
- A GPIO might represent a button press.
- A GPIO might represent if a device is attached or not.
They are categorized as phosphor-gpio-presence
for checking presences of a device, and phosphor-gpio-monitor
for monitoring a GPIO.
GPIOs in the device tree
All the GPIOs to be monitored are described in the device tree. For example,
The following code describes two GPIO keys, one for checkstop
and the other for id-button
, where the key code is calculated from aspeed-gpio.h:
GPIO presence
Witherspoon and Zaius have examples for GPIO presence.
Witherspoon
It checks GPIO key 104 for
powersupply0
presence, creates the inventory object, and binds or unbinds the driver.
It checks GPIO key 39 for pcie_card_e2b
presence and creates the inventory object.
GPIO monitor
Typical usage of the GPIO monitor is to monitor the checkstop event from host, or button presses.
checkstop monitor is a common service for OpenPOWER machines.
By default, it monitors GPIO key 74, and if it is triggered, it directs systemd to start
obmc-host-crash@0.target
. For systems using a different GPIO pin for checkstop, it simply overrides the default one by specifying its own configuration file in the meta-machine layer. For example, Zaius's checkstop config.Note: When the key is pressed,
phospohr-gpio-monitor
starts the target unit and exits.id-button monitor is an example service on Romulus to monitor ID button press.
It monitors GPIO key 135 for the button press and starts
id-button-pressed.service
, which handles the event by setting the identify LED group'sAssert
property.Note: It has an extra argument
--continue
that tellsphosphor-gpio-monitor
to not exit and continue running when the key is pressed.