1# Physical LED Design Support 2 3Author: Velumani T (Velu), [velumanit@hcl](mailto:velumanit@hcl.com) Jayashree D 4(Jayashree), [jayashree-d@hcl](mailto:jayashree-d@hcl.com) 5 6Other contributors: None 7 8Created: July 10, 2022 9 10## Problem Description 11 12The existing phosphor-led-sysfs design exposes one service per LED configuration 13in device tree. Hence, multiple services will be created for multiple GPIO pins 14configured for LEDs. 15 16There are cases where multiple LEDs were configured in the device tree for each 17host and needs to be paired as a group of LEDs for the specified host in the 18multi host platform. 19 20For example, Power LED and System Identification LED combines into a single 21bicolor blue-yellow LED per host. A total of 4 × LEDs will be placed along the 22front edge of the board in a grid. The grid will be 2 × rows of 2 × LEDs to 23match the layout of the card slots. 24 25Depending on the status of each host, blue or yellow LED needs to be Blink, OFF 26or ON and other LEDs needs to be in OFF state. Therefore, bi-color LED needs to 27be paired as a group and exposed in the userspace. 28 29Based on the current design in phosphor-led-sysfs application, pairing groups 30will be difficult, since it exposes one service per LED. To abstract this method 31and also to create LEDs under a single service, a new application is proposed. 32 33## Background and References 34 35The below diagram represents the overview for current physical LED design. 36 37``` 38 39 KERNEL META-PHOSPHOR PHOSPHOR-LED-SYSFS SERVICE 40 41 +------------+ Event 1 +----------+ LED 1 +-----------------------------+ 42 | |----------->| |-------->| | 43 | LED 1 | Event 2 | | LED 2 | Service 1 : | 44 | |----------->| UDEV |-------->| xyz.openbmc_project. | 45 | LED 2 | ..... | Events | .... | Led.Controller.LED1 | 46 | | ..... | | .... | Service 2 : | 47 | LED 3 | Event N | | LED N | xyz.openbmc_project. | 48 | |----------->| |-------->| Led.Controller.LED2 | 49 | LED 4 | +----------+ | ....... | 50 | | | ....... | 51 | ....... | | Service N : | 52 | ....... | | xyz.openbmc_project. | 53 | ....... | | Led.Controller.LEDN | 54 | | +-----------------------------+ 55 | LED N | | 56 | | | 57 +------------+ V 58 +----------------------------------+ 59 | | 60 | Service 1 : | 61 | /xyz/openbmc_project/<led1> | 62 | | 63 | Service 2 : | 64 | /xyz/openbmc_project/<led2> | 65 | ....... | 66 | ....... | 67 | | 68 | Service N : | 69 | /xyz/openbmc_project/<ledN> | 70 | | 71 +----------------------------------+ 72 73 PHOSPHSOR-LED-SYSFS DAEMON 74 75``` 76 77The existing design uses sysfs entry as udev events for particular LED and 78triggers the necessary action to generate the dbus object path and interface for 79that specified service. It exposes one service per LED. 80 81**Example** 82 83``` 84 busctl tree xyz.openbmc_project.LED.Controller.led1 85 `-/xyz 86 `-/xyz/openbmc_project 87 `-/xyz/openbmc_project/led 88 `-/xyz/openbmc_project/led/physical 89 `-/xyz/openbmc_project/led/physical/led1 90 91 busctl tree xyz.openbmc_project.LED.Controller.led2 92 `-/xyz 93 `-/xyz/openbmc_project 94 `-/xyz/openbmc_project/led 95 `-/xyz/openbmc_project/led/physical 96 `-/xyz/openbmc_project/led/physical/led2 97 98``` 99 100## Requirements 101 102- To support the systemd service to trigger script. 103 104- Add DBUS API method for phosphor-led-sysfs daemon. 105 106## Proposed Design 107 108The below diagram represents the overview for proposed physical LED design. 109 110``` 111 112 KERNEL PHOSPHOR-LED-SYSFS DAEMON 113 114 +------------+ Event 1 +--------+ +---------+ +--------------+ 115 | |----------> | | | | | | 116 | LED 1 | Event 2 | UDEV | | SYSFS | | EXECUTABLE | 117 | |----------> | Events |----->| SERVICE |----->| (DBUS Method | 118 | LED 2 | ..... | | | | | call) | 119 | | Event N | | | | | | 120 | LED 3 |----------> +--------+ +---------+ +--------------+ 121 | | | 122 | | V 123 | LED 4 | +------------------------------------------------------+ 124 | | | +-----------+ +---------------------------------+ | 125 | ....... | | | | | Service : | | 126 | ....... | | | SYSTEMD | | | | 127 | ....... | | | SERVICE | | /xyz/openbmc_project/led/<led1>| | 128 | | | | ( LED. |-->| /xyz/openbmc_project/led/<led2>| | 129 | LED N | | |Controller)| | ..... | | 130 | | | | | | ..... | | 131 | | | | | | /xyz/openbmc_project/led/<ledN>| | 132 +------------+ | +-----------+ +---------------------------------+ | 133 +------------------------------------------------------+ 134 135``` 136 137This document proposes a new design for physical LED implementation. 138 139- Physical Leds are defined in the device tree under "leds" section and 140 corresponding GPIO pins are configured. 141 142``` 143 leds { 144 compatible = "gpio-leds"; 145 146 ledName { 147 label = "devicename:color:function"; 148 gpios = <&gpio ASPEED_GPIO(M, 0) GPIO_ACTIVE_HIGH>; 149 }; 150 }; 151``` 152 153- Dbus API method will be created in the phosphor-led-sysfs repository under 154 **_xyz.openbmc_project.Led.Sysfs.Internal_** interface name to add or remove 155 the LED, which will be coming from each udev LED event. 156 157``` 158 NAME TYPE SIGNATURE RESULT/VALUE FLAGS 159 160 xyz.openbmc_project.Led.Sysfs.Internal interface - - - 161 .AddLED method s - - 162 .RemoveLED method s - - 163 164``` 165 166- udev event will be triggered for each LED and service will be invoked to run 167 the executable for each LED event. 168 169- Executable will call Dbus API method in the phosphor-led-sysfs repository to 170 pass LED name as argument from udev, after the primary service started. 171 172- Phosphor-led-sysfs will have a single systemd service (primary service) 173 **_(xyz.openbmc_project.LED.Controller.service)_** running by default at 174 system startup. 175 176- Once Dbus API method call invoked, phosphor-led-sysfs daemon will retrieve the 177 LED name as parameter and map the name with /sys/class/leds path in the 178 hardware. Next, the dbus pbject path and interface will be created under 179 single systemd service (xyz.openbmc_project.LED.Controller). 180 181- The schema will be implemented in the phosphor-led-sysfs daemon. A group of 182 LEDs is paired for each host and the schema handles color control for that 183 group to activate one LED which must be Blink/ON/OFF state and set the 184 remaining LEDs in the group as OFF state. 185 186**_Example_** 187 188``` 189 190 SERVICE xyz.openbmc_project.LED.Controller 191 192 INTERFACE xyz.openbmc_project.LED.Physical 193 194 OBJECT PATH 195 196 busctl tree xyz.openbmc_project.LED.Controller 197 `-/xyz 198 `-/xyz/openbmc_project 199 `-/xyz/openbmc_project/led 200 `-/xyz/openbmc_project/led/physical 201 `-/xyz/openbmc_project/led/physical/led1 202 `-/xyz/openbmc_project/led/physical/led2 203 ............ 204 ............ 205 `-/xyz/openbmc_project/led/physical/ledN 206``` 207 208## Alternatives Considered 209 210**Approach 1** 211 212When the udev event is initialized for the LED, it will save those LED names in 213a file utilizing the script. Phosphor-led-sysfs will monitor the file using 214inotify to handle the changes. By reading the file, all the LEDs name will be 215retrieved and dbus path will be created for all the LEDs under single systemd 216service. 217 218inotify will monitor the file continuously and it needs to communicate between 219udev events and phosphor-led-sysfs application. Since, udev events can be 220generated before systemd service, inotify does not need to monitor the file 221afterwards and also it is not a well used mechanism to communicate. 222 223Executable for Dbus method is a better way to communicate with the application 224after the system startup and populate the dbus path for LEDs under single 225service. 226 227## Impacts 228 229These changes will have API impact since the dbus objects will exposes multiple 230LEDs path in single service. The systemd service will have single name 231**_xyz.openbmc_project.LED.Controller_** instead of multiple services. 232 233## Testing 234 235The proposed design is tested in a multiple hosts platform. 236 237**_Manual Test_** - The physical LEDs status will be tested using busctl 238commands in the hardware. 239 240**_Robot Test_** - The physical LEDs will be tested under robotframework using 241REST API in the system LEDs suite. 242 243**_Unit Test_** - The proposed code can be covered by the unit tests which are 244already present. 245