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