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