LEDS: Add README file

Change-Id: Id159738eee3828483ba58b51068e09aad1b64822
Signed-off-by: Vishwanatha Subbanna <vishwa@linux.vnet.ibm.com>

1 files changed, 127 insertions, 0 deletions

diff --git a/xyz/openbmc_project/Led/README.md b/xyz/openbmc_project/Led/README.md
new file mode 100644
index 0000000..bb6aff5
--- /dev/null
+++ b/xyz/openbmc_project/Led/README.md
@@ -0,0 +1,127 @@
+# Managing LED groups and physical LEDs through BMC
+
+## Overview
+
+LEDs that are present in the system can be managed by:
+`BMC / Hardware controller / Operating system`. This document describes how
+to control the LEDs that are managed by BMC.
+
+## Understanding LED groups
+
+While it is entirely possible to act directly on a physical LED, it makes
+hard when more than one LED is to be acted on for a particular usecase.
+
+For example: Certain systems may have a requirement to **Blink** one particular
+LED upon reaching some state. However, some other systems may have a requirement
+to **Blink** set of LEDs in different frequencies. Few more systems may have a
+requirement to act on set of LEDs with different actions. Meaning, some LEDs
+to be solid [ON] while some LEDs to be Blinking etc.
+
+As described above, it is more of a system specific policy on what set
+of LEDs to be acted on in different usecases. Taking all that complexity into
+the code makes it impossible to extend across implementations and hence the need
+of a manager that works on the set of LEDs and policies and that is the Group.
+
+To make concept of Group more evident, here is another example:
+Consider a requirement of blinking system Enclosure LED indicating
+an internal problem:
+
+If the DIMM has some issues then the system admin needs a way of identifying
+that system before acting on it. In one case, the LED group may consist of
+DIMM LED + Enclosure Fault LED. However, if the DIMM is attached to a Raiser
+card, then the LED group may consist of DIMM LED + Raise card LED + Enclosure
+Fault LED. Defining this path will make it easier to locate the box and the
+exact part that needs servicing.
+
+Definition of LED groups could be static or generated from MRW and must be in
+YAML format. A group definition looks like this:
+```
+bmc_booted:
+    led_1:
+      Action: On
+      Frequency: 1000
+    led_2:
+      Action: Blink
+      Frequency: 1000
+      DutyOn: 50
+
+enclosure_identify:
+    id_front:
+      Action: Blink
+      Frequency: 1000
+      DutyOn: 50
+    id_rear:
+      Action: Blink
+      Frequency: 1000
+      DutyOn: 50
+```
+This says that the group `bmc_booted` consists of 2 physical LEDs in it.
+When this group is acted on, led_1 will turn solid [ON], while led_2
+would be blinking at 50% duty cycle.
+
+## Dbus interfaces for LED groups.
+
+Refer: [specification](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/Group.interface.yaml)
+
+There is only one property called **asserted** defined on groups and when set to
+boolean **true**, the actions listed for the LEDs in that group will get into
+effect as described above.
+When the property is set to **false**, the actions are un-done.
+
+* Henceforth, the term **asserted** would mean writing boolean **true**
+  onto `assert` property of the group. Term **de-assert** would mean
+  writing **false** to `assert` property.
+
+## Group Dbus information
+
+**Path: "/xyz/openbmc_project/led/groups/<name>"**
+**Interface: "xyz.openbmc_Project.Led.Group"**
+
+Using the yaml definition above, a user can just set the `asserted` property to
+boolean `true` on '/xyz/openbmc_project/led/groups/enclosure_identify' and that
+would result in blinking the front and rear Identify LEDs of the enclosure.
+
+## Mandatory groups
+
+It is mandatory that all implementations provide definitions of atleast 2 groups
+namely; **bmc_booted** and **power_on**. Those would be asserted post reaching
+BMCReady and PowerOn respecively. It is fine to have no LEDs in those groups but
+the group as such is deemed required.
+
+Example: The Group yaml may just be;
+```
+bmc_booted:
+power_on:
+```
+## Understanding Physical LEDs
+
+It is always **recommended** that external users use **only** the LED groups.
+Describing the Physical LED here just for documenting it and strictly NOT to
+be used outside of the firmware code.
+
+## Dbus interfaces for physical LEDs.
+
+Refer: [specification](https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Led/Physical.interface.yaml)
+
+## Dbus information
+
+**Path: "/xyz/openbmc_project/led/physical/<name>"**
+**Interface: "xyz.openbmc_Project.Led.Physical"**
+
+Using **/xyz/openbmc_project/led/groups/enclosure_identify** as example;
+setting the `asserted` property to `true` would result in these actions in
+*id_front* and *id_rear* physical LEDs.
+
+1) Property *DutyOn* is set to `50` in;
+  `/xyz/openbmc/project/led/physical/id_front` and
+  `/xyz/openbmc/project/led/physical/id_rear`
+
+2) Property *State* is set to `xyz.openbmc_project.Led.Physical.Action.On` in
+   `/xyz/openbmc/project/led/physical/id_front` and
+   `/xyz/openbmc/project/led/physical/id_rear`
+
+Which means, if some test wants to verify if the action on Group really resulted
+in acting on physical LED, those are the properties to be read from physical
+service.
+
+#                                         END of Document