docs/development/add-new-system.md

1 # Add a New System to OpenBMC
3 **Document Purpose:** How to add a new system to the OpenBMC distribution
15 updated to add a new system.
19 - Review background about Yocto and BitBake
20 - Creating a new system layer
21 - Populating this new layer
22 - Building the new system and testing in QEMU
23 - Adding configs for sensors, LEDs, inventories, etc.
32 Yocto has a concept of hierarchical layers. When you build a Yocto-based
35 defined within OpenBMC can be found with the meta-\* directories in OpenBMC
44 new system.
56 Follow the direction on the OpenBMC GitHub
57 [page](https://github.com/openbmc/openbmc/blob/master/README.md#2-download-the-source)
58 for the Romulus system (steps 2-4).
60 ## Create a New System
62 While the BitBake operation is going above, let's start creating our new system.
64 system will be called romulus-prime.
67 within `meta-ibm/meta-romulus/`. The Romulus layer is defined within the `conf`
71 meta-ibm/meta-romulus/conf/
73 ├── conf-notes.txt
80 To create our new romulus-prime system we are going to start out by copying our
84 cp -R meta-ibm/meta-romulus meta-ibm/meta-romulus-prime
89 1. meta-ibm/meta-romulus-prime/conf/bblayers.conf.sample
91    This file defines the layers to pull into the meta-romulus-prime
92    distribution. You can see in it a variety of Yocto layers (meta, meta-poky,
93    meta-openembedded/meta-oe, ...). It also has OpenBMC layers like
94    meta-phosphor, meta-openpower, meta-ibm, and meta-ibm/meta-romulus.
97    meta-romulus to meta-romulus-prime. This will ensure your new layer is used
98    when building your new system.
100 2. meta-ibm/meta-romulus-prime/conf/conf-notes.txt
106 3. meta-ibm/meta-romulus-prime/conf/layer.conf
115    The only change you need in here is to find/replace the "romulus-layer" to
116    "romulus-prime-layer"
118 4. meta-ibm/meta-romulus-prime/conf/local.conf.sample
124    `romulus-prime`.
126 5. meta-ibm/meta-romulus-prime/conf/machine/romulus.conf
130    in, and other system specific pointers. This file is a good reference for the
131    different things you need to change when creating a new system (kernel device
134    The first thing you need to do is rename the file to `romulus-prime.conf`.
136    **Note** If our new system really was just a variant of Romulus, with the
138    the Romulus layer. Any customizations for that system could be included in
140    exercise we are assuming our romulus-prime system has at least a few hardware
143 ## Build New System
159    rm -r ./build/conf
160    . setup romulus-prime
165 2. Nothing RPROVIDES 'romulus-prime-config'
167    This will be your first error after running "bitbake obmc-phosphor-image"
168    against your new system.
177    Since this repository and file are on there way out, we'll simply do a quick
183 …cp meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-config.bb meta-ibm/meta-romulus-p…
185    vi meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb
188    DESCRIPTION = "Board wiring information for the Romulus OpenPOWER system."
191    inherit config-in-skeleton
209    Re-run your "bitbake" command.
215    romulus-prime to use the romulus.cfg file. We just need to add the `-prime`
219    vi ./meta-ibm/meta-romulus-prime/recipes-kernel/linux/linux-aspeed_%.bbappend
221    FILESEXTRAPATHS_prepend_romulus-prime := "${THISDIR}/${PN}:"
225    Re-run your "bitbake" command.
227 4. No rule to make target arch/arm/boot/dts/aspeed-bmc-opp-romulus-prime.dtb
231    OpenBMC system, you need to send these kernel updates upstream. The linked
233    [thread](https://lists.ozlabs.org/pipermail/openbmc/2018-September/013260.html)
238    vi ./meta-ibm/meta-romulus-prime/conf/machine/romulus-prime.conf
242    KERNEL_DEVICETREE = "${KMACHINE}-bmc-opp-romulus.dtb"
245    Re-run your "bitbake" command.
247 ## Boot New System
249 And you've finally built your new system's image! There are more customizations
256 ./tmp/deploy/images/romulus-prime/obmc-phosphor-image-romulus-prime.static.mtd
259 Copy this image to where you've set up your QEMU session and re-run the command
260 to start QEMU (`qemu-system-arm` command from [dev-environment.md][32]), giving
266 romulus-prime login:
270 system. This is by no means a complete system but you now have the base for the
271 customizations you'll need to do for your new system.
275 There are a lot of other areas to customize when creating a new system.
281 <https://github.com/openbmc/linux/tree/dev-4.13/arch/arm/boot/dts>. For
282 examples, see [aspeed-bmc-opp-romulus.dts][1] or a similar machine. Complete the
286    - Describe the GPIOs, e.g. LED, FSI, gpio-keys, etc. You should get such info
288    - Describe the i2c buses and devices, which usually include various hwmon
290    - Describe the other devices, e.g. uarts, mac.
291    - Usually the flash layout does not need to change. Just include
292      `openbmc-flash-layout.dtsi`.
298 - In `dev-4.10`, there is common and machine-specific initialization code in
299   `arch/arm/mach-aspeed/aspeed.c` which is used to do common initializations and
300   perform specific settings in each machine. Starting in branch `dev-4.13`,
302   upstream clock and reset driver.
303 - If the machine needs specific settings (e.g. uart routing), please send mail
311 are mostly replaced by phosphor-xxx services and thus skeleton is deprecated.
314 [meta-quanta][4] is an example that defines its own config in OpenBMC tree, so
323         {'gpio_pin': 'D1', 'direction': 'out'}
325         {'gpio_pin': 'D2', 'direction': 'in'}
363       "direction": "out"
368       "direction": "out"
382 There is detailed document in openbmc [doc/architecture/sensor-architecture][6].
385 [meta-romulus/recipes-phosphor/sensors][7] which includes sensors on board and
388 - [w83773g@4c.conf][8] defines the `w83773` temperature sensor containing 3
400 the udev rule will start `phosphor-hwmon` and it will create temperature sensors
409 - [pwm-tacho-controller@1e786000.conf][10] defines the fans and the config is
411 - [occ-hwmon.1.conf][11] defines the occ hwmon sensor for master CPU. This
412   config is a bit different, that it shall tell `phosphor-hwmon` to read the
415   pulled out.
432 - The `MODE_temp* = "label"` tells that if it sees `tempX`, it shall read the
434 - And `LABEL_temp* = "xxx"` tells the sensor name for the corresponding sensor
436 - For example, if `temp1_input` is 37000 and `temp1_label` is 91 in sysfs,
437   `phosphor-hwmon` knows `temp1_input` is for sensor id 91, which is
441 - For Romulus, the power sensors do not need to read label since all powers are
442   available on a system.
443 - For Witherspoon, the power sensors are similar to temperature sensors, that it
456       compatible = "gpio-leds";
498     curl -b cjar -k https://$bmc/xyz/openbmc_project/led/physical/identify
504 …curl -b cjar -k -X PUT -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.Led.P…
508    with a CALLOUT path. [phosphor-fru-fault-monitor][29] monitors the logs:
509    - Assert the related fault LED group when a log with the CALLOUT path is
511    - De-assert the related fault LED group when the log is marked as "Resolved"
515 [phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14].
522 E.g. [meta-romulus/recipes-phosphor/ipmi][15]
524 - `romulus-ipmi-inventory-map` defines regular inventories, e.g. CPU, memory,
526 - `phosphor-ipmi-fru-properties` defines extra properties of the inventories.
527 - `phosphor-ipmi-sensor-inventory` defines the sensors from IPMI.
528 - `romulus-ipmi-inventory-sel` defines inventories used for IPMI SEL.
530 For inventory map and fru-properties, they are similar between different
531 systems, you can refer to this example and make one for your system.
533 For ipmi-sensor-inventory, the sensors from IPMI are different between systems,
543   path: /system/chassis/motherboard/dimm0
547   path: /system/chassis/motherboard/cpu0/core0
551 defined in MRW. You should follow the system's MRW to define the above config.
554 [phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14].
558 [phosphor-fan-presence][16] manages all the services about fan:
560 - `phosphor-fan-presence` checks if a fan is present, creates the fan DBus
562 - `phosphor-fan-monitor` checks if a fan is functional, and update the
564 - `phosphor-fan-control` controls the fan speed by setting the fan speed target
566 - `phosphor-cooling-type` checks and sets if the system is air-cooled or
567   water-cooled by setting properties of
568   `/xyz/openbmc_project/inventory/system/chassis` object.
573 Taking Romulus as an example, it is air-cooled and has 3 fans without GPIO
581 - name: fan0
582   path: /system/chassis/motherboard/fan0
584     - type: tach
586         - fan0
591 - It shall create `/system/chassis/motherboard/fan0` object in inventory.
592 - It shall check fan0 tach sensor (`/sensors/fan_tach/fan0`) to set `Present`
602 - inventory: /system/chassis/motherboard/fan0
607     - name: fan0
618 3. The deviation is `15%`, so if the fan speed is out of the expected range for
619    more than 30 seconds, fan0 shall be set as non-functional.
625 - `zone-condition` defines the cooling zone conditions. Romulus is always
626   air-cooled, so this config is as simple as defining an `air_cooled_chassis`
630   - name: air_cooled_chassis
633      - property: WaterCooled
635        path: /xyz/openbmc_project/inventory/system/chassis
640 - `zone-config` defines the cooling zones. Romulus has only one zone:
644   - zone: 0
655 - `fan-config` defines which fans are controlled in which zone and which target
660   - inventory: /system/chassis/motherboard/fan0
663      - fan0
668 - `events-config` defines the various events and its handlers, e.g. which fan
673 - name: set_air_cooled_speed_boundaries_based_on_ambient
675     - name: zone0_ambient
681     - name: propertiesChanged
683     - name: set_floor_from_average_sensor_value
686           - 27000: 85
687           - 32000: 112
688           - 37000: 126
689           - 40000: 141
691     - name: set_ceiling_from_average_sensor_value
694           - 25000: 175
695           - 27000: 255
707 With above configs, phosphor-fan will run the fan presence/monitor/control logic
714 - It checks GPIO for fan presence.
715 - It checks GPIO to determine if the system is air or water cooled.
716 - It has more sensors and more events in fan control.
723 - A GPIO may represent a signal of host checkstop.
724 - A GPIO may represent a button press.
725 - A GPIO may represent if a device is attached or not.
727 They are categorized as `phosphor-gpio-presence` for checking presences of a
728 device, and `phosphor-gpio-monitor` for monitoring a GPIO.
735   gpio-keys {
736     compatible = "gpio-keys";
743     id-button {
744       label = "id-button";
752 for `id-button`, where the key code is calculated from [aspeed-gpio.h][24]:
771 - [Witherspoon][19]:
774 INVENTORY=/system/chassis/motherboard/powersupply0
775 DEVPATH=/dev/input/by-path/platform-gpio-keys-event
778 DRIVERS=/sys/bus/i2c/drivers/ibm-cffps,3-0069
784 - [Zaius][20]:
787 INVENTORY=/system/chassis/pcie_card_e2b
788 DEVPATH=/dev/input/by-path/platform-gpio-keys-event
801 - [checkstop monitor][21] is a common service for OpenPOWER machines.
804 DEVPATH=/dev/input/by-path/platform-gpio-keys-event
807 TARGET=obmc-host-crash@0.target
811 start `obmc-host-crash@0.target`. For systems using a different GPIO pin for
813 in meta-machine layer. E.g. [Zaius's checkstop config][22]. **Note**: when the
814 key is pressed, `phosphor-gpio-monitor` starts the target unit and exits.
816 - [id-button monitor][23] is an example service on Romulus to monitor ID button
820 DEVPATH=/dev/input/by-path/platform-gpio-keys-event
823 TARGET=id-button-pressed.service
824 EXTRA_ARGS=--continue
828 `id-button-pressed.service`, that handles the event by setting the identify LED
829 group's `Assert` property. **Note**: It has an extra argument, `--continue`,
830 that tells `phosphor-gpio-monitor` to not exit and continue running when the key
834   https://github.com/openbmc/linux/blob/dev-4.13/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts
838   https://github.com/openbmc/openbmc/tree/master/meta-quanta/meta-q71l/recipes-phosphor/workbook
841   https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md
843   https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/sensors
845 …45da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/a…
847 …nux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L208
849 …fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hw…
851 …ta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/devices/platform/gpio-fsi/f…
853 …inux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L42
854 [13]: https://github.com/openbmc/phosphor-mrw-tools
856 …nbmc/blob/764b88f4056cc98082e233216704e94613499e64/meta-ibm/meta-witherspoon/conf/distro/openbmc-w…
858   https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/ipmi
859 [16]: https://github.com/openbmc/phosphor-fan-presence
861   https://github.com/openbmc/phosphor-fan-presence/blob/master/control/example/events.yaml
863   https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-witherspoon/recipes-phosphor/fans
865 …mc/openbmc/blob/master/meta-ibm/meta-witherspoon/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc/…
867 …nbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc…
869 …https://github.com/openbmc/openbmc/blob/master/meta-openpower/recipes-phosphor/host/checkstop-moni…
871 …ttps://github.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/host/check…
873   https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/gpio
875   https://github.com/openbmc/linux/blob/dev-4.13/include/dt-bindings/gpio/aspeed-gpio.h
881 …/3cce45a96f0416b4c3d8f2b698cb830662a29227/meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-…
882 [29]: https://github.com/openbmc/phosphor-led-manager/tree/master/fault-monitor
883 [31]: https://github.com/openbmc/docs/blob/master/kernel-development.md
884 [32]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md