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
50 build of an OpenBMC distribution can take hours. Once that first build is done
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
121    documentation in it is well done and it's worth a read.
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
146 initial setup are done correctly.
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"
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
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
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.
250 to be done but let's first verify what you have boots.
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:
269 There you go! You've done the basics of creating, booting, and building a new
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`,
301   there is no such initialization code. Most of the inits are done with the
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
339 The PowerUp and PowerOK GPIOs are needed for the build to power on the chassis
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
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
443 - For Witherspoon, the power sensors are similar to temperature sensors, that it
456       compatible = "gpio-leds";
459         gpios = <&gpio ASPEED_GPIO(N, 2) GPIO_ACTIVE_LOW>;
463         gpios = <&gpio ASPEED_GPIO(N, 4) GPIO_ACTIVE_HIGH>;
467         gpios = <&gpio ASPEED_GPIO(R, 5) GPIO_ACTIVE_LOW>;
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
533 For ipmi-sensor-inventory, the sensors from IPMI are different between systems,
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
573 Taking Romulus as an example, it is air-cooled and has 3 fans without GPIO
581 - name: 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
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
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.
718 ### GPIOs  subsection
720 This section mainly focuses on the GPIOs in device tree that shall be monitored.
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.
730 #### GPIOs in device tree  argument
732 All the GPIOs to be monitored shall be described in the device tree. E.g.
735   gpio-keys {
736     compatible = "gpio-keys";
740       gpios = <&gpio ASPEED_GPIO(J, 2) GPIO_ACTIVE_LOW>;
743     id-button {
744       label = "id-button";
745       gpios = <&gpio ASPEED_GPIO(Q, 7) GPIO_ACTIVE_LOW>;
752 for `id-button`, where the key code is calculated from [aspeed-gpio.h][24]:
771 - [Witherspoon][19]:
775 DEVPATH=/dev/input/by-path/platform-gpio-keys-event
778 DRIVERS=/sys/bus/i2c/drivers/ibm-cffps,3-0069
784 - [Zaius][20]:
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