1a69423d9SAndrew Geissler# Add a New System to OpenBMC 2a69423d9SAndrew Geissler 3a69423d9SAndrew Geissler**Document Purpose:** How to add a new system to the OpenBMC distribution 4a69423d9SAndrew Geissler 5a69423d9SAndrew Geissler**Audience:** Programmer familiar with OpenBMC 6a69423d9SAndrew Geissler 7ace9cd14SLei YU**Prerequisites:** Completed Development Environment Setup [Document][32] 8a69423d9SAndrew Geissler 9a69423d9SAndrew Geissler## Overview 10a69423d9SAndrew Geissler 11*8e677cf7SAndrew Geissler**Please note:** This document is no longer officially supported by the OpenBMC 12*8e677cf7SAndrew Geisslerteam. It still contains a lot of useful information so it has been left here. 13*8e677cf7SAndrew GeisslerIdeally this guide would become a standalone document (outside of the 14*8e677cf7SAndrew Geisslerdevelopment tree) and would cover all of the different areas that must 15*8e677cf7SAndrew Geisslerbe updated to add a new system. 16*8e677cf7SAndrew Geissler 17a69423d9SAndrew GeisslerThis document will describe the following: 18a69423d9SAndrew Geissler 19a69423d9SAndrew Geissler* Review background about Yocto and BitBake 20a69423d9SAndrew Geissler* Creating a new system layer 21a69423d9SAndrew Geissler* Populating this new layer 22a69423d9SAndrew Geissler* Building the new system and testing in QEMU 23ace9cd14SLei YU* Adding configs for sensors, LEDs, inventories, etc. 24a69423d9SAndrew Geissler 25a69423d9SAndrew Geissler## Background 26a69423d9SAndrew Geissler 27a69423d9SAndrew GeisslerThe OpenBMC distribution is based on [Yocto](https://www.yoctoproject.org/). 28a69423d9SAndrew GeisslerYocto is a project that allows developers to create custom Linux distributions. 29a69423d9SAndrew GeisslerOpenBMC uses Yocto to create their embedded Linux distribution to run on 30a69423d9SAndrew Geisslera variety of devices. 31a69423d9SAndrew Geissler 32a69423d9SAndrew GeisslerYocto has a concept of hierarchical layers. When you build a Yocto-based 33a69423d9SAndrew Geisslerdistribution, you define a set of layers for that distribution. OpenBMC uses 34a69423d9SAndrew Geisslermany common layers from Yocto as well as some of its own layers. The layers 35a69423d9SAndrew Geisslerdefined within OpenBMC can be found with the meta-* directories in OpenBMC 36a69423d9SAndrew Geissler[GitHub](https://github.com/openbmc/openbmc). 37a69423d9SAndrew Geissler 38a69423d9SAndrew GeisslerYocto layers are a combination of different files that define packages to 39a69423d9SAndrew Geisslerincorporate in that layer. One of the key file types used in these layers is 40a69423d9SAndrew Geissler[BitBake](https://github.com/openembedded/bitbake/blob/master/README) recipes. 41a69423d9SAndrew Geissler 42a69423d9SAndrew GeisslerBitBake is a fully functional language in itself. For this lesson, we will 43a69423d9SAndrew Geisslerfocus on only the aspects of BitBake required to understand the process of 44a69423d9SAndrew Geissleradding a new system. 45a69423d9SAndrew Geissler 46a69423d9SAndrew Geissler## Start the Initial BitBake 47a69423d9SAndrew Geissler 48a69423d9SAndrew GeisslerFor this work, you will need to have allocated at least 100GB of space to your 49a69423d9SAndrew Geisslerdevelopment environment and as much memory and CPU as possible. The initial 50a69423d9SAndrew Geisslerbuild of an OpenBMC distribution can take hours. Once that first build is done 51a69423d9SAndrew Geisslerthough, future builds will use cached data from the first build, speeding the 52a69423d9SAndrew Geisslerprocess up by orders of magnitude. 53a69423d9SAndrew Geissler 54a69423d9SAndrew GeisslerSo before we do anything else, let's get that first build going. 55a69423d9SAndrew Geissler 56a69423d9SAndrew GeisslerFollow the direction on the OpenBMC GitHub [page](https://github.com/openbmc/openbmc/blob/master/README.md#2-download-the-source) 57a69423d9SAndrew Geisslerfor the Romulus system (steps 2-4). 58a69423d9SAndrew Geissler 59a69423d9SAndrew Geissler## Create a New System 60a69423d9SAndrew Geissler 61a69423d9SAndrew GeisslerWhile the BitBake operation is going above, let's start creating our new system. 62a69423d9SAndrew GeisslerSimilar to previous lessons, we'll be using Romulus as our reference. Our new 63a69423d9SAndrew Geisslersystem will be called romulus-prime. 64a69423d9SAndrew Geissler 65a69423d9SAndrew GeisslerFrom your openbmc repository you cloned above, the Romulus layer is defined 66a69423d9SAndrew Geisslerwithin `meta-ibm/meta-romulus/`. The Romulus layer is defined within the 67a69423d9SAndrew Geissler`conf` subdirectory. Under `conf` you will see a layout like this: 68a69423d9SAndrew Geissler 69a69423d9SAndrew Geissler``` 70a69423d9SAndrew Geisslermeta-ibm/meta-romulus/conf/ 71a69423d9SAndrew Geissler├── bblayers.conf.sample 72a69423d9SAndrew Geissler├── conf-notes.txt 73a69423d9SAndrew Geissler├── layer.conf 74a69423d9SAndrew Geissler├── local.conf.sample 75a69423d9SAndrew Geissler└── machine 76a69423d9SAndrew Geissler └── romulus.conf 77a69423d9SAndrew Geissler``` 78a69423d9SAndrew Geissler 79a69423d9SAndrew GeisslerTo create our new romulus-prime system we are going to start out by copying 80a69423d9SAndrew Geisslerour romulus layer. 81a69423d9SAndrew Geissler``` 82a69423d9SAndrew Geisslercp -R meta-ibm/meta-romulus meta-ibm/meta-romulus-prime 83a69423d9SAndrew Geissler``` 84a69423d9SAndrew Geissler 85a69423d9SAndrew GeisslerLet's review and modify each file needed in our new layer 86a69423d9SAndrew Geissler 87a69423d9SAndrew Geissler1. meta-ibm/meta-romulus-prime/conf/bblayers.conf.sample 88a69423d9SAndrew Geissler 89a69423d9SAndrew Geissler This file defines the layers to pull into the meta-romulus-prime 90a69423d9SAndrew Geissler distribution. You can see in it a variety of Yocto layers (meta, meta-poky, 91a69423d9SAndrew Geissler meta-openembedded/meta-oe, ...). It also has OpenBMC layers like 92a69423d9SAndrew Geissler meta-phosphor, meta-openpower, meta-ibm, and meta-ibm/meta-romulus. 93a69423d9SAndrew Geissler 94a69423d9SAndrew Geissler The only change you need in this file is to change the two instances of 95a69423d9SAndrew Geissler meta-romulus to meta-romulus-prime. This will ensure your new layer is used 96a69423d9SAndrew Geissler when building your new system. 97a69423d9SAndrew Geissler 98a69423d9SAndrew Geissler2. meta-ibm/meta-romulus-prime/conf/conf-notes.txt 99a69423d9SAndrew Geissler 100a69423d9SAndrew Geissler This file simply states the default target the user will build when working 101a69423d9SAndrew Geissler with your new layer. This remains the same as it is common for all OpenBMC 102a69423d9SAndrew Geissler systems. 103a69423d9SAndrew Geissler 104a69423d9SAndrew Geissler3. meta-ibm/meta-romulus-prime/conf/layer.conf 105a69423d9SAndrew Geissler 106a69423d9SAndrew Geissler The main purpose of this file is to tell BitBake where to look for recipes 107a69423d9SAndrew Geissler (\*.bb files). Recipe files end with a `.bb` extension and are what contain 108a69423d9SAndrew Geissler all of the packaging logic for the different layers. `.bbappend` files are 109a69423d9SAndrew Geissler also recipe files but provide a way to append onto `.bb` files. 110a69423d9SAndrew Geissler `.bbappend` files are commonly used to add or remove something from a 111a69423d9SAndrew Geissler corresponding `.bb` file in a different layer. 112a69423d9SAndrew Geissler 113a69423d9SAndrew Geissler The only change you need in here is to find/replace the "romulus-layer" to 114a69423d9SAndrew Geissler "romulus-prime-layer" 115a69423d9SAndrew Geissler 116a69423d9SAndrew Geissler4. meta-ibm/meta-romulus-prime/conf/local.conf.sample 117a69423d9SAndrew Geissler 118a69423d9SAndrew Geissler This file is where all local configuration settings go for your layer. The 119a69423d9SAndrew Geissler documentation in it is well done and it's worth a read. 120a69423d9SAndrew Geissler 121a69423d9SAndrew Geissler The only change required in here is to change the `MACHINE` to 122a69423d9SAndrew Geissler `romulus-prime`. 123a69423d9SAndrew Geissler 124a69423d9SAndrew Geissler5. meta-ibm/meta-romulus-prime/conf/machine/romulus.conf 125a69423d9SAndrew Geissler 126a69423d9SAndrew Geissler This file describes the specifics for your machine. You define the kernel 127a69423d9SAndrew Geissler device tree to use, any overrides to specific features you will be pulling 128a69423d9SAndrew Geissler in, and other system specific pointers. This file is a good reference for 129a69423d9SAndrew Geissler the different things you need to change when creating a new system (kernel 130a69423d9SAndrew Geissler device tree, MRW, LED settings, inventory access, ...) 131a69423d9SAndrew Geissler 132a69423d9SAndrew Geissler The first thing you need to do is rename the file to `romulus-prime.conf`. 133a69423d9SAndrew Geissler 134a69423d9SAndrew Geissler **Note** If our new system really was just a variant of Romulus, 135a69423d9SAndrew Geissler with the same hardware configuration, then we could have just created a 136a69423d9SAndrew Geissler new machine in the Romulus layer. Any customizations for that system 137a69423d9SAndrew Geissler could be included in the corresponding .conf file for that new machine. For 138a69423d9SAndrew Geissler the purposes of this exercise we are assuming our romulus-prime system has 139a69423d9SAndrew Geissler at least a few hardware changes requiring us to create this new layer. 140a69423d9SAndrew Geissler 141a69423d9SAndrew Geissler## Build New System 142a69423d9SAndrew Geissler 143a69423d9SAndrew GeisslerThis will not initially compile but it's good to verify a few things from the 144a69423d9SAndrew Geisslerinitial setup are done correctly. 145a69423d9SAndrew Geissler 146a69423d9SAndrew GeisslerDo not start this step until the build we started at the beginning of this 147a69423d9SAndrew Geisslerlesson has completed. 148a69423d9SAndrew Geissler 149a69423d9SAndrew Geissler1. Modify the conf for your current build 150a69423d9SAndrew Geissler 151a69423d9SAndrew Geissler Within the shell you did the initial "bitbake" operation you need to reset 152a69423d9SAndrew Geissler the conf file for your build. You can manually copy in the new files or just 153a69423d9SAndrew Geissler remove it and let BitBake do it for you: 154a69423d9SAndrew Geissler ``` 155a69423d9SAndrew Geissler cd .. 156a69423d9SAndrew Geissler rm -r ./build/conf 157a69423d9SAndrew Geissler export TEMPLATECONF=meta-ibm/meta-romulus-prime/conf 158a69423d9SAndrew Geissler . openbmc-env 159a69423d9SAndrew Geissler ``` 160a69423d9SAndrew Geissler 161a69423d9SAndrew Geissler Run your "bitbake" command. 162a69423d9SAndrew Geissler 163a69423d9SAndrew Geissler2. Nothing RPROVIDES 'romulus-prime-config' 164a69423d9SAndrew Geissler 165a69423d9SAndrew Geissler This will be your first error after running "bitbake obmc-phosphor-image" 166a69423d9SAndrew Geissler against your new system. 167a69423d9SAndrew Geissler 168a69423d9SAndrew Geissler The openbmc/skeleton repository was used for initial prototyping of OpenBMC. 169a69423d9SAndrew Geissler Within this repository is a [configs](https://github.com/openbmc/skeleton/tree/master/configs) directory. 170a69423d9SAndrew Geissler 171a69423d9SAndrew Geissler The majority of this config data is no longer used but until it is all 172a69423d9SAndrew Geissler completely removed, you need to provide it. 173a69423d9SAndrew Geissler 174a69423d9SAndrew Geissler Since this repository and file are on there way out, we'll simply do a quick 175a69423d9SAndrew Geissler workaround for this issue. 176a69423d9SAndrew Geissler 177a69423d9SAndrew Geissler Create a config files as follows: 178a69423d9SAndrew Geissler ``` 179a69423d9SAndrew Geissler cp meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-config.bb meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb 180a69423d9SAndrew Geissler 181a69423d9SAndrew Geissler vi meta-ibm/meta-romulus-prime/recipes-phosphor/workbook/romulus-prime-config.bb 182a69423d9SAndrew Geissler 183a69423d9SAndrew Geissler SUMMARY = "Romulus board wiring" 184a69423d9SAndrew Geissler DESCRIPTION = "Board wiring information for the Romulus OpenPOWER system." 185a69423d9SAndrew Geissler PR = "r1" 186a69423d9SAndrew Geissler 187a69423d9SAndrew Geissler inherit config-in-skeleton 188a69423d9SAndrew Geissler 189a69423d9SAndrew Geissler #Use Romulus config 190a69423d9SAndrew Geissler do_make_setup() { 191a69423d9SAndrew Geissler cp ${S}/Romulus.py \ 192a69423d9SAndrew Geissler ${S}/obmc_system_config.py 193a69423d9SAndrew Geissler cat <<EOF > ${S}/setup.py 194a69423d9SAndrew Geissler from distutils.core import setup 195a69423d9SAndrew Geissler 196a69423d9SAndrew Geissler setup(name='${BPN}', 197a69423d9SAndrew Geissler version='${PR}', 198a69423d9SAndrew Geissler py_modules=['obmc_system_config'], 199a69423d9SAndrew Geissler ) 200a69423d9SAndrew Geissler EOF 201a69423d9SAndrew Geissler } 202a69423d9SAndrew Geissler 203a69423d9SAndrew Geissler ``` 204a69423d9SAndrew Geissler 205a69423d9SAndrew Geissler Re-run your "bitbake" command. 206a69423d9SAndrew Geissler 207a69423d9SAndrew Geissler3. Fetcher failure for URL: file://romulus.cfg 208a69423d9SAndrew Geissler 209a69423d9SAndrew Geissler This is the config file required by the kernel. It's where you can put some 210a69423d9SAndrew Geissler additional kernel config parameters. For our purposes here, just modify 211a69423d9SAndrew Geissler romulus-prime to use the romulus.cfg file. We just need to add the `-prime` 212a69423d9SAndrew Geissler to the prepend path. 213a69423d9SAndrew Geissler ``` 214a69423d9SAndrew Geissler vi ./meta-ibm/meta-romulus-prime/recipes-kernel/linux/linux-aspeed_%.bbappend 215a69423d9SAndrew Geissler 216a69423d9SAndrew Geissler FILESEXTRAPATHS_prepend_romulus-prime := "${THISDIR}/${PN}:" 217a69423d9SAndrew Geissler SRC_URI += "file://romulus.cfg" 218a69423d9SAndrew Geissler ``` 219a69423d9SAndrew Geissler 220a69423d9SAndrew Geissler Re-run your "bitbake" command. 221a69423d9SAndrew Geissler 222a69423d9SAndrew Geissler4. No rule to make target arch/arm/boot/dts/aspeed-bmc-opp-romulus-prime.dtb 223a69423d9SAndrew Geissler 224a69423d9SAndrew Geissler The .dtb file is a device tree blob file. It is generated during the Linux 225a69423d9SAndrew Geissler kernel build based on its corresponding .dts file. When you introduce a 226a69423d9SAndrew Geissler new OpenBMC system, you need to send these kernel updates upstream. The 227a69423d9SAndrew Geissler linked email [thread](https://lists.ozlabs.org/pipermail/openbmc/2018-September/013260.html) 228a69423d9SAndrew Geissler is an example of this process. Upstreaming to the kernel is a lesson in 229a69423d9SAndrew Geissler itself. For this lesson, we will simply use the Romulus kernel config files. 230a69423d9SAndrew Geissler ``` 231a69423d9SAndrew Geissler vi ./meta-ibm/meta-romulus-prime/conf/machine/romulus-prime.conf 232a69423d9SAndrew Geissler # Replace the ${MACHINE} variable in the KERNEL_DEVICETREE 233a69423d9SAndrew Geissler 234a69423d9SAndrew Geissler # Use romulus device tree 235a69423d9SAndrew Geissler KERNEL_DEVICETREE = "${KMACHINE}-bmc-opp-romulus.dtb" 236a69423d9SAndrew Geissler ``` 237a69423d9SAndrew Geissler 238a69423d9SAndrew Geissler Re-run your "bitbake" command. 239a69423d9SAndrew Geissler 240a69423d9SAndrew Geissler## Boot New System 241a69423d9SAndrew Geissler 242a69423d9SAndrew GeisslerAnd you've finally built your new system's image! There are more 243a69423d9SAndrew Geisslercustomizations to be done but let's first verify what you have boots. 244a69423d9SAndrew Geissler 245a69423d9SAndrew GeisslerYour new image will be in the following location from where you ran your 246a69423d9SAndrew Geissler"bitbake" command: 247a69423d9SAndrew Geissler``` 248a69423d9SAndrew Geissler./tmp/deploy/images/romulus-prime/obmc-phosphor-image-romulus-prime.static.mtd 249a69423d9SAndrew Geissler``` 250a69423d9SAndrew GeisslerCopy this image to where you've set up your QEMU session and re-run the 251a69423d9SAndrew Geisslercommand to start QEMU (`qemu-system-arm` command from 252ace9cd14SLei YU[dev-environment.md][32]), giving your new file as input. 253a69423d9SAndrew Geissler 254a69423d9SAndrew GeisslerOnce booted, you should see the following for the login: 255a69423d9SAndrew Geissler``` 256a69423d9SAndrew Geisslerromulus-prime login: 257a69423d9SAndrew Geissler``` 258a69423d9SAndrew Geissler 259a69423d9SAndrew GeisslerThere you go! You've done the basics of creating, booting, and building a new 260a69423d9SAndrew Geisslersystem. This is by no means a complete system but you now have the base for 261a69423d9SAndrew Geisslerthe customizations you'll need to do for your new system. 262a69423d9SAndrew Geissler 263a69423d9SAndrew Geissler## Further Customizations 264a69423d9SAndrew Geissler 265a69423d9SAndrew GeisslerThere are a lot of other areas to customize when creating a new system. 266a69423d9SAndrew Geissler 267ace9cd14SLei YU### Kernel changes 268a69423d9SAndrew Geissler 269ace9cd14SLei YUThis section describes how you can make changes to the kernel to port OpenBMC 270ace9cd14SLei YUto a new machine. 271ace9cd14SLei YUThe device tree is in https://github.com/openbmc/linux/tree/dev-4.13/arch/arm/boot/dts. 272ace9cd14SLei YUFor examples, see [aspeed-bmc-opp-romulus.dts][1] or a similar machine. 273ace9cd14SLei YUComplete the following steps to make kernel changes: 274ace9cd14SLei YU 275ace9cd14SLei YU1. Add the new machine device tree: 276ace9cd14SLei YU * Describe the GPIOs, e.g. LED, FSI, gpio-keys, etc. You should get such 277ace9cd14SLei YU info from schematic. 278ace9cd14SLei YU * Describe the i2c buses and devices, which usually include various hwmon 279ace9cd14SLei YU sensors. 280ace9cd14SLei YU * Describe the other devices, e.g. uarts, mac. 281ace9cd14SLei YU * Usually the flash layout does not need to change. Just include 282ace9cd14SLei YU `openbmc-flash-layout.dtsi`. 283ace9cd14SLei YU2. Modify Makefile to build the device tree. 284ace9cd14SLei YU3. Reference to [openbmc kernel doc][31] on submitting patches to mailing list. 285ace9cd14SLei YU 286ace9cd14SLei YUNote: 287ace9cd14SLei YU* In `dev-4.10`, there is common and machine-specific initialization code in 288ace9cd14SLei YU `arch/arm/mach-aspeed/aspeed.c` which is used to do common initializations 289ace9cd14SLei YU and perform specific settings in each machine. 290ace9cd14SLei YU Starting in branch `dev-4.13`, there is no such initialization code. Most of 291ace9cd14SLei YU the inits are done with the upstream clock and reset driver. 292ace9cd14SLei YU* If the machine needs specific settings (e.g. uart routing), please 293ace9cd14SLei YU send mail to [the mailing list][2] for discussion. 294ace9cd14SLei YU 295ace9cd14SLei YU 296ace9cd14SLei YU### Workbook 297ace9cd14SLei YU 298ace9cd14SLei YUIn legacy OpenBMC, there is a "workbook" to describe the machine's services, 299ace9cd14SLei YUsensors, FRUs, etc. 300ace9cd14SLei YUThis workbook is a python configuration file and it is used by other services 301ace9cd14SLei YUin [skeleton][3]. 302ace9cd14SLei YUIn the latest OpenBMC, the skeleton services are mostly replaced by 303ace9cd14SLei YUphosphor-xxx services and thus skeleton is deprecated. 304ace9cd14SLei YUBut the workbook is still needed for now to make the build. 305ace9cd14SLei YU 306ace9cd14SLei YU[meta-quanta][4] is an example that defines its own config in OpenBMC tree, so 307ace9cd14SLei YUthat it does not rely on skeleton repo, although it is kind of dummy. 308ace9cd14SLei YU 309ace9cd14SLei YUBefore [e0e69be][26], or before v2.4 tag, OpenPOWER machines use several 310ace9cd14SLei YUconfigurations related to GPIO. For example, in [Romulus.py][5], the 311ace9cd14SLei YUconfiguration details are as follows: 312ace9cd14SLei YU 313ace9cd14SLei YU```python 314ace9cd14SLei YUGPIO_CONFIG['BMC_POWER_UP'] = \ 315ace9cd14SLei YU {'gpio_pin': 'D1', 'direction': 'out'} 316ace9cd14SLei YUGPIO_CONFIG['SYS_PWROK_BUFF'] = \ 317ace9cd14SLei YU {'gpio_pin': 'D2', 'direction': 'in'} 318ace9cd14SLei YU 319ace9cd14SLei YUGPIO_CONFIGS = { 320ace9cd14SLei YU 'power_config' : { 321ace9cd14SLei YU 'power_good_in' : 'SYS_PWROK_BUFF', 322ace9cd14SLei YU 'power_up_outs' : [ 323ace9cd14SLei YU ('BMC_POWER_UP', True), 324ace9cd14SLei YU ], 325ace9cd14SLei YU 'reset_outs' : [ 326ace9cd14SLei YU ], 327ace9cd14SLei YU }, 328ace9cd14SLei YU} 329ace9cd14SLei YU``` 330ace9cd14SLei YUThe PowerUp and PowerOK GPIOs are needed for the build to power on the chassis 331ace9cd14SLei YUand check the power state. 332ace9cd14SLei YU 333ace9cd14SLei YUAfter that, the GPIO related configs are removed from the workbook, and 334ace9cd14SLei YUreplaced by `gpio_defs.json`, e.g. [2a80da2][27] introduces the GPIO json 335ace9cd14SLei YUconfig for Romulus. 336ace9cd14SLei YU 337ace9cd14SLei YU```json 338ace9cd14SLei YU{ 339ace9cd14SLei YU "gpio_configs": { 340ace9cd14SLei YU "power_config": { 341ace9cd14SLei YU "power_good_in": "SYS_PWROK_BUFF", 342ace9cd14SLei YU "power_up_outs": [ 343ace9cd14SLei YU { "name": "SOFTWARE_PGOOD", "polarity": true}, 344ace9cd14SLei YU { "name": "BMC_POWER_UP", "polarity": true} 345ace9cd14SLei YU ], 346ace9cd14SLei YU "reset_outs": [ 347ace9cd14SLei YU ] 348ace9cd14SLei YU } 349ace9cd14SLei YU }, 350ace9cd14SLei YU 351ace9cd14SLei YU "gpio_definitions": [ 352ace9cd14SLei YU { 353ace9cd14SLei YU "name": "SOFTWARE_PGOOD", 354ace9cd14SLei YU "pin": "R1", 355ace9cd14SLei YU "direction": "out" 356ace9cd14SLei YU }, 357ace9cd14SLei YU { 358ace9cd14SLei YU "name": "BMC_POWER_UP", 359ace9cd14SLei YU "pin": "D1", 360ace9cd14SLei YU "direction": "out" 361ace9cd14SLei YU }, 362ace9cd14SLei YU ... 363ace9cd14SLei YU} 364ace9cd14SLei YU``` 365ace9cd14SLei YU 366ace9cd14SLei YUEach machine shall define the similar json config to describe the GPIO 367ace9cd14SLei YUconfigurations. 368ace9cd14SLei YU 369ace9cd14SLei YU 370ace9cd14SLei YU### Hwmon Sensors 371ace9cd14SLei YU 372ace9cd14SLei YUHwmon sensors include sensors on board (e.g. temperature sensors, fans) and 373ace9cd14SLei YUOCC sensors. 374ace9cd14SLei YUThe config files path and name shall match the devices in device tree. 375ace9cd14SLei YU 37699585d46SGunnar MillsThere is detailed document in openbmc [doc/architecture/sensor-architecture][6]. 377ace9cd14SLei YU 378ace9cd14SLei YUHere let's take Romulus as an example. 379ace9cd14SLei YUThe config files are in [meta-romulus/recipes-phosphor/sensors][7] which 380ace9cd14SLei YUincludes sensors on board and sensors of OCC, where on board sensors are via 381ace9cd14SLei YUi2c and occ sensors are via FSI. 382ace9cd14SLei YU 383ace9cd14SLei YU* [w83773g@4c.conf][8] defines the `w83773` temperature sensor containing 3 384ace9cd14SLei YUtemperatures: 385ace9cd14SLei YU ``` 386ace9cd14SLei YU LABEL_temp1 = "outlet" 387ace9cd14SLei YU ... 388ace9cd14SLei YU LABEL_temp2 = "inlet_cpu" 389ace9cd14SLei YU ... 390ace9cd14SLei YU LABEL_temp3 = "inlet_io" 391ace9cd14SLei YU ``` 392ace9cd14SLei YU This device is defined in its device tree as [w83773g@4c][9]. 393ace9cd14SLei YU When BMC starts, the udev rule will start `phosphor-hwmon` and it will create 394ace9cd14SLei YU temperature sensors on below DBus objects based on its sysfs attributes. 395ace9cd14SLei YU ``` 396ace9cd14SLei YU /xyz/openbmc_project/sensors/temperature/outlet 397ace9cd14SLei YU /xyz/openbmc_project/sensors/temperature/inlet_cpu 398ace9cd14SLei YU /xyz/openbmc_project/sensors/temperature/inlet_io 399ace9cd14SLei YU ``` 400ace9cd14SLei YU* [pwm-tacho-controller@1e786000.conf][10] defines the fans and the config is 401ace9cd14SLei YU similar as above, the difference is that it creates `fan_tach` sensors. 402ace9cd14SLei YU* [occ-hwmon.1.conf][11] defines the occ hwmon sensor for master CPU. 403ace9cd14SLei YU This config is a bit different, that it shall tell `phosphor-hwmon` to read 404ace9cd14SLei YU the label instead of directly getting the index of the sensor, because CPU 405ace9cd14SLei YU cores and DIMMs could be dynamic, e.g. CPU cores could be disabled, DIMMs 406ace9cd14SLei YU could be pulled out. 407ace9cd14SLei YU ``` 408ace9cd14SLei YU MODE_temp1 = "label" 409ace9cd14SLei YU MODE_temp2 = "label" 410ace9cd14SLei YU ... 411ace9cd14SLei YU MODE_temp31 = "label" 412ace9cd14SLei YU MODE_temp32 = "label" 413ace9cd14SLei YU LABEL_temp91 = "p0_core0_temp" 414ace9cd14SLei YU LABEL_temp92 = "p0_core1_temp" 415ace9cd14SLei YU ... 416ace9cd14SLei YU LABEL_temp33 = "dimm6_temp" 417ace9cd14SLei YU LABEL_temp34 = "dimm7_temp" 418ace9cd14SLei YU LABEL_power2 = "p0_power" 419ace9cd14SLei YU ... 420ace9cd14SLei YU ``` 421ace9cd14SLei YU * The `MODE_temp* = "label"` tells that if it sees `tempX`, it shall read 422ace9cd14SLei YU the label which is the sensor id. 423ace9cd14SLei YU * And `LABEL_temp* = "xxx"` tells the sensor name for the corresponding 424ace9cd14SLei YU sensor id. 425ace9cd14SLei YU * For example, if `temp1_input` is 37000 and `temp1_label` is 91 in sysfs, 426ace9cd14SLei YU `phosphor-hwmon` knows `temp1_input` is for sensor id 91, which is 427ace9cd14SLei YU `p0_core0_temp`, so it creates 428ace9cd14SLei YU `/xyz/openbmc_project/sensors/temperature/p0_core0_temp` with sensor 429ace9cd14SLei YU value 37000. 430ace9cd14SLei YU * For Romulus, the power sensors do not need to read label since all powers 431ace9cd14SLei YU are available on a system. 432ace9cd14SLei YU * For Witherspoon, the power sensors are similar to temperature sensors, 433ace9cd14SLei YU that it shall tell hwmon to read the `function_id` instead of directly 434ace9cd14SLei YU getting the index of the sensor. 435ace9cd14SLei YU 436ace9cd14SLei YU 437ace9cd14SLei YU### LEDs 438ace9cd14SLei YU 439ace9cd14SLei YUSeveral parts are involved for LED. 440ace9cd14SLei YU 441ace9cd14SLei YU1. In kernel dts, LEDs shall be described, e.g. [romulus dts][12] describes 442ace9cd14SLei YU 3 LEDs, `fault`, `identify` and `power`. 443ace9cd14SLei YU ``` 444ace9cd14SLei YU leds { 445ace9cd14SLei YU compatible = "gpio-leds"; 446ace9cd14SLei YU 447ace9cd14SLei YU fault { 448ace9cd14SLei YU gpios = <&gpio ASPEED_GPIO(N, 2) GPIO_ACTIVE_LOW>; 449ace9cd14SLei YU }; 450ace9cd14SLei YU 451ace9cd14SLei YU identify { 452ace9cd14SLei YU gpios = <&gpio ASPEED_GPIO(N, 4) GPIO_ACTIVE_HIGH>; 453ace9cd14SLei YU }; 454ace9cd14SLei YU 455ace9cd14SLei YU power { 456ace9cd14SLei YU gpios = <&gpio ASPEED_GPIO(R, 5) GPIO_ACTIVE_LOW>; 457ace9cd14SLei YU }; 458ace9cd14SLei YU }; 459ace9cd14SLei YU ``` 460ace9cd14SLei YU2. In machine layer, LEDs shall be configured via yaml to describe how it 461ace9cd14SLei YU functions, e.g. [Romulus led yaml][28]: 462ace9cd14SLei YU ``` 463ace9cd14SLei YU bmc_booted: 464ace9cd14SLei YU power: 465ace9cd14SLei YU Action: 'Blink' 466ace9cd14SLei YU DutyOn: 50 467ace9cd14SLei YU Period: 1000 468ace9cd14SLei YU Priority: 'On' 469ace9cd14SLei YU power_on: 470ace9cd14SLei YU power: 471ace9cd14SLei YU Action: 'On' 472ace9cd14SLei YU DutyOn: 50 473ace9cd14SLei YU Period: 0 474ace9cd14SLei YU Priority: 'On' 475ace9cd14SLei YU ... 476ace9cd14SLei YU ``` 477ace9cd14SLei YU It tells the LED manager to set the `power` LED to blink when BMC is ready 478ace9cd14SLei YU and booted, and set it on when host is powered on. 479ace9cd14SLei YU3. At runtime, LED manager automatically set LEDs on/off/blink based on the 480ace9cd14SLei YU above yaml config. 481ace9cd14SLei YU4. LED can be accessed manually via /xyz/openbmc_project/led/, e.g. 482ace9cd14SLei YU * Get identify LED state: 483ace9cd14SLei YU ``` 484ace9cd14SLei YU curl -b cjar -k https://$bmc/xyz/openbmc_project/led/physical/identify 485ace9cd14SLei YU ``` 486ace9cd14SLei YU * Set identify LED to blink: 487ace9cd14SLei YU ``` 488ace9cd14SLei YU curl -b cjar -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 489ace9cd14SLei YU ``` 490ace9cd14SLei YU5. When an error related to a FRU occurs, an event log is created in logging 491ace9cd14SLei YU with a CALLOUT path. [phosphor-fru-fault-monitor][29] monitors the logs: 492ace9cd14SLei YU * Assert the related fault LED group when a log with the CALLOUT path is 493ace9cd14SLei YU generated; 494ace9cd14SLei YU * De-assert the related fault LED group when the log is marked as 495ace9cd14SLei YU "Resolved" or deleted. 496ace9cd14SLei YU 497ace9cd14SLei YU**Note**: This yaml config can be automatically generated by 498ace9cd14SLei YU[phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14]. 499ace9cd14SLei YU 500ace9cd14SLei YU 501ace9cd14SLei YU### Inventories and other sensors 502ace9cd14SLei YU 503ace9cd14SLei YUInventories, other sensors (e.g. CPU/DIMM temperature), and FRUs are defined 504ace9cd14SLei YUin ipmi's yaml config files. 505ace9cd14SLei YU 506ace9cd14SLei YUE.g. [meta-romulus/recipes-phosphor/ipmi][15] 507ace9cd14SLei YU* `romulus-ipmi-inventory-map` defines regular inventories, e.g. CPU, memory, 508ace9cd14SLei YU motherboard. 509ace9cd14SLei YU* `phosphor-ipmi-fru-properties` defines extra properties of the inventories. 510ace9cd14SLei YU* `phosphor-ipmi-sensor-inventory` defines the sensors from IPMI. 511ace9cd14SLei YU* `romulus-ipmi-inventory-sel` defines inventories used for IPMI SEL. 512ace9cd14SLei YU 513ace9cd14SLei YUFor inventory map and fru-properties, they are similar between different 514ace9cd14SLei YUsystems, you can refer to this example and make one for your system. 515ace9cd14SLei YU 516ace9cd14SLei YUFor ipmi-sensor-inventory, the sensors from IPMI are different between 517ace9cd14SLei YUsystems, so you need to define your own sensors, e.g. 518ace9cd14SLei YU``` 519ace9cd14SLei YU0x08: 520ace9cd14SLei YU sensorType: 0x07 521ace9cd14SLei YU path: /org/open_power/control/occ0 522ace9cd14SLei YU ... 523ace9cd14SLei YU0x1e: 524ace9cd14SLei YU sensorType: 0x0C 525ace9cd14SLei YU path: /system/chassis/motherboard/dimm0 526ace9cd14SLei YU ... 527ace9cd14SLei YU0x22: 528ace9cd14SLei YU sensorType: 0x07 529ace9cd14SLei YU path: /system/chassis/motherboard/cpu0/core0 530ace9cd14SLei YU``` 531ace9cd14SLei YUThe first value `0x08`, `0x1e` and `0x22` are the sensor id of IPMI, which is 532ace9cd14SLei YUdefined in MRW. 533ace9cd14SLei YUYou should follow the system's MRW to define the above config. 534ace9cd14SLei YU 535ace9cd14SLei YU**Note**: The yaml configs can be automatically generated by 536ace9cd14SLei YU[phosphor-mrw-tools][13] from its MRW, see [Witherspoon example][14]. 537ace9cd14SLei YU 538ace9cd14SLei YU 539ace9cd14SLei YU### Fans 540ace9cd14SLei YU[phosphor-fan-presence][16] manages all the services about fan: 541ace9cd14SLei YU* `phosphor-fan-presence` checks if a fan is present, creates the fan DBus 542ace9cd14SLei YU objects in inventory and update the `Present` property. 543ace9cd14SLei YU* `phosphor-fan-monitor` checks if a fan is functional, and update the 544ace9cd14SLei YU `Functional` property of the fan Dbus object. 545ace9cd14SLei YU* `phosphor-fan-control` controls the fan speed by setting the fan speed target 546ace9cd14SLei YU based on conditions, e.g. temperatures. 547ace9cd14SLei YU* `phosphor-cooling-type` checks and sets if the system is air-cooled or 548ace9cd14SLei YU water-cooled by setting properties of 549ace9cd14SLei YU `/xyz/openbmc_project/inventory/system/chassis` object. 550ace9cd14SLei YU 551ace9cd14SLei YUAll the above services are configurable, e.g. by yaml config. 552ace9cd14SLei YUSo the machine specific configs shall be written when porting OpenBMC to a new 553ace9cd14SLei YUmachine. 554ace9cd14SLei YU 555ace9cd14SLei YUTaking Romulus as an example, it is air-cooled and has 3 fans without GPIO 556ace9cd14SLei YUpresence detection. 557ace9cd14SLei YU 558ace9cd14SLei YU#### Fan presence 559ace9cd14SLei YURomulus has no GPIO detection for fans, so it checks fan tach sensor: 560ace9cd14SLei YU``` 561ace9cd14SLei YU- name: fan0 562ace9cd14SLei YU path: /system/chassis/motherboard/fan0 563ace9cd14SLei YU methods: 564ace9cd14SLei YU - type: tach 565ace9cd14SLei YU sensors: 566ace9cd14SLei YU - fan0 567ace9cd14SLei YU``` 568ace9cd14SLei YUThe yaml config tells that 569ace9cd14SLei YU* It shall create `/system/chassis/motherboard/fan0` object in inventory. 570ace9cd14SLei YU* It shall check fan0 tach sensor (`/sensors/fan_tach/fan0`) to set `Present` 571ace9cd14SLei YU property on the fan0 object. 572ace9cd14SLei YU 573ace9cd14SLei YU#### Fan monitor 574ace9cd14SLei YURomulus fans use pwm to control the fan speed, where pwm ranges from 0 to 255, 575ace9cd14SLei YUand the fan speed ranges from 0 to about 7000. 576ace9cd14SLei YUSo it needs a factor and offset to mapping the pwm to fan speed: 577ace9cd14SLei YU``` 578ace9cd14SLei YU - inventory: /system/chassis/motherboard/fan0 579ace9cd14SLei YU allowed_out_of_range_time: 30 580ace9cd14SLei YU deviation: 15 581ace9cd14SLei YU num_sensors_nonfunc_for_fan_nonfunc: 1 582ace9cd14SLei YU sensors: 583ace9cd14SLei YU - name: fan0 584ace9cd14SLei YU has_target: true 585ace9cd14SLei YU target_interface: xyz.openbmc_project.Control.FanPwm 586ace9cd14SLei YU factor: 21 587ace9cd14SLei YU offset: 1600 588ace9cd14SLei YU``` 589ace9cd14SLei YUThe yaml config tells that: 590ace9cd14SLei YU1. It shall use `FanPwm` as target interface of the tach sensor. 591ace9cd14SLei YU2. It shall calculate the expected fan speed as `target * 21 + 1600`. 592ace9cd14SLei YU3. The deviation is `15%`, so if the fan speed is out of the expected range 593ace9cd14SLei YU for more than 30 seconds, fan0 shall be set as non-functional. 594ace9cd14SLei YU 595ace9cd14SLei YU#### Fan control 596ace9cd14SLei YUThe fan control service requires 4 yaml configuration files: 597ace9cd14SLei YU* `zone-condition` defines the cooling zone conditions. Romulus is always 598ace9cd14SLei YU air-cooled, so this config is as simple as defining an `air_cooled_chassis` 599ace9cd14SLei YU condition based on the cooling type property. 600ace9cd14SLei YU ``` 601ace9cd14SLei YU - name: air_cooled_chassis 602ace9cd14SLei YU type: getProperty 603ace9cd14SLei YU properties: 604ace9cd14SLei YU - property: WaterCooled 605ace9cd14SLei YU interface: xyz.openbmc_project.Inventory.Decorator.CoolingType 606ace9cd14SLei YU path: /xyz/openbmc_project/inventory/system/chassis 607ace9cd14SLei YU type: bool 608ace9cd14SLei YU value: false 609ace9cd14SLei YU ``` 610ace9cd14SLei YU* `zone-config` defines the cooling zones. Romulus has only one zone: 611ace9cd14SLei YU ``` 612ace9cd14SLei YU zones: 613ace9cd14SLei YU - zone: 0 614ace9cd14SLei YU full_speed: 255 615ace9cd14SLei YU default_floor: 195 616ace9cd14SLei YU increase_delay: 5 617ace9cd14SLei YU decrease_interval: 30 618ace9cd14SLei YU ``` 619ace9cd14SLei YU It defines that the zone full speed and default floor speed for the fans, 620ace9cd14SLei YU so the fan pwm will be set to 255 if it is in full speed, and set to 195 if 621ace9cd14SLei YU fans are in default floor speed. 622ace9cd14SLei YU* `fan-config` defines which fans are controlled in which zone and which target 623ace9cd14SLei YU interface shall be used, e.g. below yaml config defines fan0 shall be 624ace9cd14SLei YU controlled in zone0 and it shall use `FanPwm` interface. 625ace9cd14SLei YU ``` 626ace9cd14SLei YU - inventory: /system/chassis/motherboard/fan0 627ace9cd14SLei YU cooling_zone: 0 628ace9cd14SLei YU sensors: 629ace9cd14SLei YU - fan0 630ace9cd14SLei YU target_interface: xyz.openbmc_project.Control.FanPwm 631ace9cd14SLei YU ... 632ace9cd14SLei YU ``` 633ace9cd14SLei YU* `events-config` defines the various events and its handlers, e.g. which fan 634ace9cd14SLei YU targets shall be set in which temperature. 635685b9ff4SGeorge Keishing This config is a bit complicated, the [example event yaml][17] provides 636ace9cd14SLei YU documents and examples. 637ace9cd14SLei YU Romulus example: 638ace9cd14SLei YU ``` 639ace9cd14SLei YU - name: set_air_cooled_speed_boundaries_based_on_ambient 640ace9cd14SLei YU groups: 641ace9cd14SLei YU - name: zone0_ambient 642ace9cd14SLei YU interface: xyz.openbmc_project.Sensor.Value 643ace9cd14SLei YU property: 644ace9cd14SLei YU name: Value 645ace9cd14SLei YU type: int64_t 646ace9cd14SLei YU matches: 647ace9cd14SLei YU - name: propertiesChanged 648ace9cd14SLei YU actions: 649ace9cd14SLei YU - name: set_floor_from_average_sensor_value 650ace9cd14SLei YU map: 651ace9cd14SLei YU value: 652ace9cd14SLei YU - 27000: 85 653ace9cd14SLei YU - 32000: 112 654ace9cd14SLei YU - 37000: 126 655ace9cd14SLei YU - 40000: 141 656ace9cd14SLei YU type: std::map<int64_t, uint64_t> 657ace9cd14SLei YU - name: set_ceiling_from_average_sensor_value 658ace9cd14SLei YU map: 659ace9cd14SLei YU value: 660ace9cd14SLei YU - 25000: 175 661ace9cd14SLei YU - 27000: 255 662ace9cd14SLei YU type: std::map<int64_t, uint64_t> 663ace9cd14SLei YU ``` 664ace9cd14SLei YU The above yaml config defines the fan floor and ceiling speed in 665ace9cd14SLei YU `zone0_ambient`'s different temperatures. E.g. 666ace9cd14SLei YU 1. When the temperature is lower than 27 degreesC, the floor speed (pwm) 667ace9cd14SLei YU shall be set to 85. 668ace9cd14SLei YU 2. When the temperature is between 27 and 32 degrees C, the floor speed 669ace9cd14SLei YU (pwm) shall be set to 112, etc. 670ace9cd14SLei YU 671ace9cd14SLei YUWith above configs, phosphor-fan will run the fan presence/monitor/control 672ace9cd14SLei YUlogic as configured specifically for the machine. 673ace9cd14SLei YU 674ace9cd14SLei YU**Note**: Romulus fans are simple. For a more complicated example, refer to 675ace9cd14SLei YU[Witherspoon fan configurations][18]. The following are the additional 676ace9cd14SLei YUfunctions of Witherspoon fan configuration: 677ace9cd14SLei YU 678ace9cd14SLei YU* It checks GPIO for fan presence. 679ace9cd14SLei YU* It checks GPIO to determine if the system is air or water cooled. 680ace9cd14SLei YU* It has more sensors and more events in fan control. 681ace9cd14SLei YU 682ace9cd14SLei YU 683ace9cd14SLei YU### GPIOs 684ace9cd14SLei YUThis section mainly focuses on the GPIOs in device tree that shall be 685ace9cd14SLei YUmonitored. 686ace9cd14SLei YUE.g.: 687ace9cd14SLei YU* A GPIO may represent a signal of host checkstop. 688ace9cd14SLei YU* A GPIO may represent a button press. 689ace9cd14SLei YU* A GPIO may represent if a device is attached or not. 690ace9cd14SLei YU 691ace9cd14SLei YUThey are categorized as `phosphor-gpio-presence` for checking presences of a 692ace9cd14SLei YUdevice, and `phosphor-gpio-monitor` for monitoring a GPIO. 693ace9cd14SLei YU 694ace9cd14SLei YU#### GPIOs in device tree 695ace9cd14SLei YUAll the GPIOs to be monitored shall be described in the device tree. 696ace9cd14SLei YUE.g. 697ace9cd14SLei YU``` 698ace9cd14SLei YU gpio-keys { 699ace9cd14SLei YU compatible = "gpio-keys"; 700ace9cd14SLei YU checkstop { 701ace9cd14SLei YU label = "checkstop"; 702ace9cd14SLei YU gpios = <&gpio ASPEED_GPIO(J, 2) GPIO_ACTIVE_LOW>; 703ace9cd14SLei YU linux,code = <ASPEED_GPIO(J, 2)>; 704ace9cd14SLei YU }; 705ace9cd14SLei YU id-button { 706ace9cd14SLei YU label = "id-button"; 707ace9cd14SLei YU gpios = <&gpio ASPEED_GPIO(Q, 7) GPIO_ACTIVE_LOW>; 708ace9cd14SLei YU linux,code = <ASPEED_GPIO(Q, 7)>; 709ace9cd14SLei YU }; 710ace9cd14SLei YU }; 711ace9cd14SLei YU``` 712ace9cd14SLei YUThe following code describes two GPIO keys, one for `checkstop` and the other 713ace9cd14SLei YUfor `id-button`, where the key code is calculated from [aspeed-gpio.h][24]: 714ace9cd14SLei YU``` 715ace9cd14SLei YU#define ASPEED_GPIO_PORT_A 0 716ace9cd14SLei YU#define ASPEED_GPIO_PORT_B 1 717ace9cd14SLei YU... 718ace9cd14SLei YU#define ASPEED_GPIO_PORT_Y 24 719ace9cd14SLei YU#define ASPEED_GPIO_PORT_Z 25 720ace9cd14SLei YU#define ASPEED_GPIO_PORT_AA 26 721ace9cd14SLei YU... 722ace9cd14SLei YU 723ace9cd14SLei YU#define ASPEED_GPIO(port, offset) \ 724ace9cd14SLei YU ((ASPEED_GPIO_PORT_##port * 8) + offset) 725ace9cd14SLei YU``` 726ace9cd14SLei YU 727ace9cd14SLei YU#### GPIO Presence 728ace9cd14SLei YUWitherspoon and Zaius have examples for gpio presence. 729ace9cd14SLei YU 730ace9cd14SLei YU* [Witherspoon][19]: 731ace9cd14SLei YU ``` 732ace9cd14SLei YU INVENTORY=/system/chassis/motherboard/powersupply0 733ace9cd14SLei YU DEVPATH=/dev/input/by-path/platform-gpio-keys-event 734ace9cd14SLei YU KEY=104 735ace9cd14SLei YU NAME=powersupply0 736ace9cd14SLei YU DRIVERS=/sys/bus/i2c/drivers/ibm-cffps,3-0069 737ace9cd14SLei YU ``` 738ace9cd14SLei YU It checks GPIO key 104 for `powersupply0`'s presence, creates the inventory 739ace9cd14SLei YU object and bind or unbind the driver. 740ace9cd14SLei YU* [Zaius][20]: 741ace9cd14SLei YU ``` 742ace9cd14SLei YU INVENTORY=/system/chassis/pcie_card_e2b 743ace9cd14SLei YU DEVPATH=/dev/input/by-path/platform-gpio-keys-event 744ace9cd14SLei YU KEY=39 745ace9cd14SLei YU NAME=pcie_card_e2b 746ace9cd14SLei YU ``` 747ace9cd14SLei YU It checks GPIO key 39 for `pcie_card_e2b`'s presence, and creates the 748ace9cd14SLei YU inventory object. 749ace9cd14SLei YU 750ace9cd14SLei YU#### GPIO monitor 751ace9cd14SLei YUTypical usage of GPIO monitor is to monitor the checkstop event from the host, 752ace9cd14SLei YUor button presses. 753ace9cd14SLei YU 754ace9cd14SLei YU* [checkstop monitor][21] is a common service for OpenPOWER machines. 755ace9cd14SLei YU ``` 756ace9cd14SLei YU DEVPATH=/dev/input/by-path/platform-gpio-keys-event 757ace9cd14SLei YU KEY=74 758ace9cd14SLei YU POLARITY=1 759ace9cd14SLei YU TARGET=obmc-host-crash@0.target 760ace9cd14SLei YU ``` 761ace9cd14SLei YU By default it monitors GPIO key 74, and if it is triggered, it tells 762ace9cd14SLei YU systemd to start `obmc-host-crash@0.target`. 763ace9cd14SLei YU For systems using a different GPIO pin for checkstop, it simply overrides 764ace9cd14SLei YU the default one by specifying its own config file in meta-machine layer. 765ace9cd14SLei YU E.g. [Zaius's checkstop config][22]. 766ace9cd14SLei YU **Note**: when the key is pressed, `phosphor-gpio-monitor` starts the target 767ace9cd14SLei YU unit and exits. 768ace9cd14SLei YU* [id-button monitor][23] is an example service on Romulus to monitor ID 769ace9cd14SLei YU button press. 770ace9cd14SLei YU ``` 771ace9cd14SLei YU DEVPATH=/dev/input/by-path/platform-gpio-keys-event 772ace9cd14SLei YU KEY=135 773ace9cd14SLei YU POLARITY=1 774ace9cd14SLei YU TARGET=id-button-pressed.service 775ace9cd14SLei YU EXTRA_ARGS=--continue 776ace9cd14SLei YU ``` 777ace9cd14SLei YU It monitors GPIO key 135 for the button press and starts 778ace9cd14SLei YU `id-button-pressed.service`, that handles the event by setting the identify 779ace9cd14SLei YU LED group's `Assert` property. 780ace9cd14SLei YU **Note**: It has an extra argument, `--continue`, that tells 781ace9cd14SLei YU `phosphor-gpio-monitor` to not exit and continue running when the key is 782ace9cd14SLei YU pressed. 783ace9cd14SLei YU 784ace9cd14SLei YU[1]: https://github.com/openbmc/linux/blob/dev-4.13/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts 785ace9cd14SLei YU[2]: https://lists.ozlabs.org/listinfo/openbmc 786ace9cd14SLei YU[3]: https://github.com/openbmc/skeleton 787ace9cd14SLei YU[4]: https://github.com/openbmc/openbmc/tree/master/meta-quanta/meta-q71l/recipes-phosphor/workbook 788ace9cd14SLei YU[5]: https://github.com/openbmc/skeleton/blob/master/configs/Romulus.py 78999585d46SGunnar Mills[6]: https://github.com/openbmc/docs/blob/master/architecture/sensor-architecture.md 790ace9cd14SLei YU[7]: https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/sensors 791ace9cd14SLei YU[8]: https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/i2c%401e78a000/i2c-bus%40440/w83773g%404c.conf 792ace9cd14SLei YU[9]: https://github.com/openbmc/linux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L208 793ace9cd14SLei YU[10]: https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/ahb/apb/pwm-tacho-controller%401e786000.conf 794ace9cd14SLei YU[11]: https://github.com/openbmc/openbmc/blob/298c4328fd20fcd7645da1565c143b1b668ef541/meta-ibm/meta-romulus/recipes-phosphor/sensors/phosphor-hwmon/obmc/hwmon/devices/platform/gpio-fsi/fsi0/slave%4000--00/00--00--00--06/sbefifo1-dev0/occ-hwmon.1.conf 795ace9cd14SLei YU[12]: https://github.com/openbmc/linux/blob/aca92be80c008bceeb6fb62fd1d450b5be5d0a4f/arch/arm/boot/dts/aspeed-bmc-opp-romulus.dts#L42 796ace9cd14SLei YU[13]: https://github.com/openbmc/phosphor-mrw-tools 797ace9cd14SLei YU[14]: https://github.com/openbmc/openbmc/blob/764b88f4056cc98082e233216704e94613499e64/meta-ibm/meta-witherspoon/conf/distro/openbmc-witherspoon.conf#L4 798ace9cd14SLei YU[15]: https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/ipmi 799ace9cd14SLei YU[16]: https://github.com/openbmc/phosphor-fan-presence 800ace9cd14SLei YU[17]: https://github.com/openbmc/phosphor-fan-presence/blob/master/control/example/events.yaml 801ace9cd14SLei YU[18]: https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-witherspoon/recipes-phosphor/fans 802ace9cd14SLei YU[19]: https://github.com/openbmc/openbmc/blob/master/meta-ibm/meta-witherspoon/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc/gpio/phosphor-power-supply-0.conf 803ace9cd14SLei YU[20]: https://github.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/gpio/phosphor-gpio-monitor/obmc/gpio/phosphor-pcie-card-e2b.conf 804ace9cd14SLei YU[21]: https://github.com/openbmc/openbmc/blob/master/meta-openpower/recipes-phosphor/host/checkstop-monitor.bb 805ace9cd14SLei YU[22]: https://github.com/openbmc/openbmc/blob/master/meta-ingrasys/meta-zaius/recipes-phosphor/host/checkstop-monitor/obmc/gpio/checkstop 806ace9cd14SLei YU[23]: https://github.com/openbmc/openbmc/tree/master/meta-ibm/meta-romulus/recipes-phosphor/gpio 807ace9cd14SLei YU[24]: https://github.com/openbmc/linux/blob/dev-4.13/include/dt-bindings/gpio/aspeed-gpio.h 808ace9cd14SLei YU[25]: https://github.com/openbmc/docs/blob/master/development/add-new-system.md 809ace9cd14SLei YU[26]: https://github.com/openbmc/openbmc/commit/e0e69beab7c268e4ad98972016c78b0d7d5769ac 810ace9cd14SLei YU[27]: https://github.com/openbmc/openbmc/commit/2a80da2262bf13aa1ddb589cf3f2b672d26b0975 811ace9cd14SLei YU[28]: https://github.com/openbmc/openbmc/blob/3cce45a96f0416b4c3d8f2b698cb830662a29227/meta-ibm/meta-romulus/recipes-phosphor/leds/romulus-led-manager-config/led.yaml 812ace9cd14SLei YU[29]: https://github.com/openbmc/phosphor-led-manager/tree/master/fault-monitor 813ace9cd14SLei YU[30]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md 814ace9cd14SLei YU[31]: https://github.com/openbmc/docs/blob/master/kernel-development.md 815ace9cd14SLei YU[32]: https://github.com/openbmc/docs/blob/master/development/dev-environment.md 816