docs/development/add-new-system.md

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
57 [page](https://github.com/openbmc/openbmc/blob/master/README.md#2-download-the-source)
58 for the Romulus system (steps 2-4).
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
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
134    The first thing you need to do is rename the file to `romulus-prime.conf`.
140    exercise we are assuming our romulus-prime system has at least a few hardware
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"
174    The majority of this config data is no longer used but until it is all
180    Create a config files as follows:
183 … meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-config.bb meta-ibm/meta-romulus-pri…
185    vi meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb
191    inherit config-in-skeleton
193    #Use Romulus config
209    Re-run your "bitbake" command.
213    This is the config file required by the kernel. It's where you can put some
214    additional kernel config parameters. For our purposes here, just modify
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
233    [thread](https://lists.ozlabs.org/pipermail/openbmc/2018-September/013260.html)
235    itself. For this lesson, we will simply use the Romulus kernel config files.
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.
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:
281 https://github.com/openbmc/linux/tree/dev-4.13/arch/arm/boot/dts. For examples,
282 see [aspeed-bmc-opp-romulus.dts][1] or a similar machine. Complete the following
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`,
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
318 configurations related to GPIO. For example, in [Romulus.py][5], the
342 After that, the GPIO related configs are removed from the workbook, and replaced
343 by `gpio_defs.json`, e.g. [2a80da2][27] introduces the GPIO json config for
374 Each machine shall define the similar json config to describe the GPIO
380 sensors. The config files path and name shall match the devices in device tree.
382 There is detailed document in openbmc [doc/architecture/sensor-architecture][6].
384 Here let's take Romulus as an example. The config files are in
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
398   the udev rule will start `phosphor-hwmon` and it will create temperature
405 - [pwm-tacho-controller@1e786000.conf][10] defines the fans and the config is
407 - [occ-hwmon.1.conf][11] defines the occ hwmon sensor for master CPU. This
408   config is a bit different, that it shall tell `phosphor-hwmon` to read the
426   - The `MODE_temp* = "label"` tells that if it sees `tempX`, it shall read the
428   - And `LABEL_temp* = "xxx"` tells the sensor name for the corresponding sensor
430   - For example, if `temp1_input` is 37000 and `temp1_label` is 91 in sysfs,
431     `phosphor-hwmon` knows `temp1_input` is for sensor id 91, which is
435   - For Romulus, the power sensors do not need to read label since all powers
437   - For Witherspoon, the power sensors are similar to temperature sensors, that
450        compatible = "gpio-leds";
453          gpios = <&gpio ASPEED_GPIO(N, 2) GPIO_ACTIVE_LOW>;
457          gpios = <&gpio ASPEED_GPIO(N, 4) GPIO_ACTIVE_HIGH>;
461          gpios = <&gpio ASPEED_GPIO(R, 5) GPIO_ACTIVE_LOW>;
486    above yaml config.
488    - Get identify LED state:
490      curl -b cjar -k https://$bmc/xyz/openbmc_project/led/physical/identify
492    - Set identify LED to blink:
494 …curl -b cjar -k -X PUT -H "Content-Type: application/json" -d '{"data": "xyz.openbmc_project.Led.P…
497    with a CALLOUT path. [phosphor-fru-fault-monitor][29] monitors the logs:
498    - Assert the related fault LED group when a log with the CALLOUT path is
500    - De-assert the related fault LED group when the log is marked as "Resolved"
503 **Note**: This yaml config can be automatically generated by
504 [phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14].
509 ipmi's yaml config files.
511 E.g. [meta-romulus/recipes-phosphor/ipmi][15]
513 - `romulus-ipmi-inventory-map` defines regular inventories, e.g. CPU, memory,
515 - `phosphor-ipmi-fru-properties` defines extra properties of the inventories.
516 - `phosphor-ipmi-sensor-inventory` defines the sensors from IPMI.
517 - `romulus-ipmi-inventory-sel` defines inventories used for IPMI SEL.
519 For inventory map and fru-properties, they are similar between different
522 For ipmi-sensor-inventory, the sensors from IPMI are different between systems,
540 defined in MRW. You should follow the system's MRW to define the above config.
543 [phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14].
547 [phosphor-fan-presence][16] manages all the services about fan:
549 - `phosphor-fan-presence` checks if a fan is present, creates the fan DBus
551 - `phosphor-fan-monitor` checks if a fan is functional, and update the
553 - `phosphor-fan-control` controls the fan speed by setting the fan speed target
555 - `phosphor-cooling-type` checks and sets if the system is air-cooled or
556   water-cooled by setting properties of
559 All the above services are configurable, e.g. by yaml config. So the machine
562 Taking Romulus as an example, it is air-cooled and has 3 fans without GPIO
567 Romulus has no GPIO detection for fans, so it checks fan tach sensor:
570 - name: fan0
573     - type: tach
575         - fan0
578 The yaml config tells that
580 - It shall create `/system/chassis/motherboard/fan0` object in inventory.
581 - It shall check fan0 tach sensor (`/sensors/fan_tach/fan0`) to set `Present`
591   - inventory: /system/chassis/motherboard/fan0
596       - name: fan0
603 The yaml config tells that:
608    more than 30 seconds, fan0 shall be set as non-functional.
614 - `zone-condition` defines the cooling zone conditions. Romulus is always
615   air-cooled, so this config is as simple as defining an `air_cooled_chassis`
618   - name: air_cooled_chassis
621      - property: WaterCooled
627 - `zone-config` defines the cooling zones. Romulus has only one zone:
630    - zone: 0
639 - `fan-config` defines which fans are controlled in which zone and which target
640   interface shall be used, e.g. below yaml config defines fan0 shall be
643   - inventory: /system/chassis/motherboard/fan0
646      - fan0
650 - `events-config` defines the various events and its handlers, e.g. which fan
651   targets shall be set in which temperature. This config is a bit complicated,
654    - name: set_air_cooled_speed_boundaries_based_on_ambient
656          - name: zone0_ambient
662          - name: propertiesChanged
664          - name: set_floor_from_average_sensor_value
667                    - 27000: 85
668                    - 32000: 112
669                    - 37000: 126
670                    - 40000: 141
672          - name: set_ceiling_from_average_sensor_value
675                    - 25000: 175
676                    - 27000: 255
679   The above yaml config defines the fan floor and ceiling speed in
686 With above configs, phosphor-fan will run the fan presence/monitor/control logic
693 - It checks GPIO for fan presence.
694 - It checks GPIO to determine if the system is air or water cooled.
695 - It has more sensors and more events in fan control.
702 - A GPIO may represent a signal of host checkstop.
703 - A GPIO may represent a button press.
704 - A GPIO may represent if a device is attached or not.
706 They are categorized as `phosphor-gpio-presence` for checking presences of a
707 device, and `phosphor-gpio-monitor` for monitoring a GPIO.
714   gpio-keys {
715     compatible = "gpio-keys";
718       gpios = <&gpio ASPEED_GPIO(J, 2) GPIO_ACTIVE_LOW>;
721     id-button {
722       label = "id-button";
723       gpios = <&gpio ASPEED_GPIO(Q, 7) GPIO_ACTIVE_LOW>;
729 The following code describes two GPIO keys, one for `checkstop` and the other
730 for `id-button`, where the key code is calculated from [aspeed-gpio.h][24]:
745 #### GPIO Presence
747 Witherspoon and Zaius have examples for gpio presence.
749 - [Witherspoon][19]:
752   DEVPATH=/dev/input/by-path/platform-gpio-keys-event
755   DRIVERS=/sys/bus/i2c/drivers/ibm-cffps,3-0069
757   It checks GPIO key 104 for `powersupply0`'s presence, creates the inventory
759 - [Zaius][20]:
762   DEVPATH=/dev/input/by-path/platform-gpio-keys-event
766   It checks GPIO key 39 for `pcie_card_e2b`'s presence, and creates the
769 #### GPIO monitor
771 Typical usage of GPIO monitor is to monitor the checkstop event from the host,
774 - [checkstop monitor][21] is a common service for OpenPOWER machines.
776   DEVPATH=/dev/input/by-path/platform-gpio-keys-event
779   TARGET=obmc-host-crash@0.target
781   By default it monitors GPIO key 74, and if it is triggered, it tells systemd
782   to start `obmc-host-crash@0.target`. For systems using a different GPIO pin
784   config file in meta-machine layer. E.g. [Zaius's checkstop config][22].
785   **Note**: when the key is pressed, `phosphor-gpio-monitor` starts the target
787 - [id-button monitor][23] is an example service on Romulus to monitor ID button
790   DEVPATH=/dev/input/by-path/platform-gpio-keys-event
793   TARGET=id-button-pressed.service
794   EXTRA_ARGS=--continue
796   It monitors GPIO key 135 for the button press and starts
797   `id-button-pressed.service`, that handles the event by setting the identify
799   `--continue`, that tells `phosphor-gpio-monitor` to not exit and continue
803   https://github.com/openbmc/linux/blob/dev-4.13/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts
807   https://github.com/openbmc/openbmc/tree/master/meta-quanta/meta-q71l/recipes-phosphor/workbook
810   https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md
812   https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/sensors
814 …45da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/a…
816 …nux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L208
818 …fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hw…
820 …ta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/devices/platform/gpio-fsi/f…
822 …inux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L42
823 [13]: https://github.com/openbmc/phosphor-mrw-tools
825 …nbmc/blob/764b88f4056cc98082e233216704e94613499e64/meta-ibm/meta-witherspoon/conf/distro/openbmc-w…
827   https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/ipmi
828 [16]: https://github.com/openbmc/phosphor-fan-presence
830   https://github.com/openbmc/phosphor-fan-presence/blob/master/control/example/events.yaml
832   https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-witherspoon/recipes-phosphor/fans
834 …mc/openbmc/blob/master/meta-ibm/meta-witherspoon/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc/…
836 …nbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc…
838 …https://github.com/openbmc/openbmc/blob/master/meta-openpower/recipes-phosphor/host/checkstop-moni…
840 …thub.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/host/checkstop-moni…
842   https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/gpio
844   https://github.com/openbmc/linux/blob/dev-4.13/include/dt-bindings/gpio/aspeed-gpio.h
845 [25]: https://github.com/openbmc/docs/blob/master/development/add-new-system.md
851 …ce45a96f0416b4c3d8f2b698cb830662a29227/meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-man…
852 [29]: https://github.com/openbmc/phosphor-led-manager/tree/master/fault-monitor
853 [30]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md
854 [31]: https://github.com/openbmc/docs/blob/master/kernel-development.md
855 [32]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md