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