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
40 [BitBake](https://github.com/openembedded/bitbake/blob/master/README) recipes.
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
128    This file describes the specifics for your machine. You define the kernel
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`.
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"
172    [configs](https://github.com/openbmc/skeleton/tree/master/configs) directory.
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.
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
230    kernel build based on its corresponding .dts file. When you introduce a new
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)
234    is an example of this process. Upstreaming to the kernel is a lesson in
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:
277 ### Kernel changes
279 This section describes how you can make changes to the kernel to port OpenBMC to
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
283 steps to make kernel changes:
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`.
294 3. Reference to [openbmc kernel doc][31] on submitting patches to mailing list.
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
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
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
445 1. In kernel dts, LEDs shall be described, e.g. [romulus dts][12] describes 3
450        compatible = "gpio-leds";
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"
504 [phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14].
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,
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
562 Taking Romulus as an example, it is air-cooled and has 3 fans without GPIO
570 - name: fan0
573     - type: tach
575         - fan0
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
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
643   - inventory: /system/chassis/motherboard/fan0
646      - fan0
650 - `events-config` defines the various events and its handlers, e.g. which fan
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
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";
721     id-button {
722       label = "id-button";
730 for `id-button`, where the key code is calculated from [aspeed-gpio.h][24]:
749 - [Witherspoon][19]:
752   DEVPATH=/dev/input/by-path/platform-gpio-keys-event
755   DRIVERS=/sys/bus/i2c/drivers/ibm-cffps,3-0069
759 - [Zaius][20]:
762   DEVPATH=/dev/input/by-path/platform-gpio-keys-event
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
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
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
808 [5]: https://github.com/openbmc/skeleton/blob/master/configs/Romulus.py
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 …/openbmc/openbmc/blob/master/meta-ibm/meta-witherspoon/recipes-phosphor/gpio/phosphor-gpio-monitor…
836 …om/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/gpio/phosphor-gpio-monito…
838 …https://github.com/openbmc/openbmc/blob/master/meta-openpower/recipes-phosphor/host/checkstop-moni…
840 …https://github.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/host/chec…
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 …/3cce45a96f0416b4c3d8f2b698cb830662a29227/meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-…
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