diff options
Diffstat (limited to 'Documentation/firmware-guide/acpi')
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/leds.rst | 111 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/enumeration.rst | 4 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/extcon-intel-int3496.rst | 33 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/index.rst | 2 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/method-tracing.rst | 2 |
5 files changed, 149 insertions, 3 deletions
diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst new file mode 100644 index 000000000000..946efe2b2936 --- /dev/null +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -0,0 +1,111 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +======================================== +Describing and referring to LEDs in ACPI +======================================== + +Individual LEDs are described by hierarchical data extension [6] nodes under the +device node, the LED driver chip. The "reg" property in the LED specific nodes +tells the numerical ID of each individual LED output to which the LEDs are +connected. [3] The hierarchical data nodes are named "led@X", where X is the +number of the LED output. + +Referring to LEDs in Device tree is documented in [4], in "flash-leds" property +documentation. In short, LEDs are directly referred to by using phandles. + +While Device tree allows referring to any node in the tree[1], in ACPI +references are limited to device nodes only [2]. For this reason using the same +mechanism on ACPI is not possible. A mechanism to refer to non-device ACPI nodes +is documented in [7]. + +ACPI allows (as does DT) using integer arguments after the reference. A +combination of the LED driver device reference and an integer argument, +referring to the "reg" property of the relevant LED, is used to identify +individual LEDs. The value of the "reg" property is a contract between the +firmware and software, it uniquely identifies the LED driver outputs. + +Under the LED driver device, The first hierarchical data extension package list +entry shall contain the string "led@" followed by the number of the LED, +followed by the referred object name. That object shall be named "LED" followed +by the number of the LED. + +Example +======= + +An ASL example of a camera sensor device and a LED driver device for two LEDs is +show below. Objects not relevant for LEDs or the references to them have been +omitted. :: + + Device (LED) + { + Name (_DSD, Package () { + ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), + Package () { + Package () { "led@0", LED0 }, + Package () { "led@1", LED1 }, + } + }) + Name (LED0, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 0 }, + Package () { "flash-max-microamp", 1000000 }, + Package () { "flash-timeout-us", 200000 }, + Package () { "led-max-microamp", 100000 }, + Package () { "label", "white:flash" }, + } + }) + Name (LED1, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "reg", 1 }, + Package () { "led-max-microamp", 10000 }, + Package () { "label", "red:indicator" }, + } + }) + } + + Device (SEN) + { + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { + "flash-leds", + Package () { ^LED, "led@0", ^LED, "led@1" }, + } + } + }) + } + +where +:: + + LED LED driver device + LED0 First LED + LED1 Second LED + SEN Camera sensor device (or another device the LED is related to) + +References +========== + +[1] Device tree. <URL:http://www.devicetree.org>, referenced 2019-02-21. + +[2] Advanced Configuration and Power Interface Specification. + <URL:https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf>, + referenced 2019-02-21. + +[3] Documentation/devicetree/bindings/leds/common.txt + +[4] Documentation/devicetree/bindings/media/video-interfaces.txt + +[5] Device Properties UUID For _DSD. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, + referenced 2019-02-21. + +[6] Hierarchical Data Extension UUID For _DSD. + <URL:http://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, + referenced 2019-02-21. + +[7] Documentation/firmware-guide/acpi/dsd/data-node-references.rst diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 850be9696931..0a72b6321f5f 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -316,7 +316,7 @@ specifies the path to the controller. In order to use these GPIOs in Linux we need to translate them to the corresponding Linux GPIO descriptors. There is a standard GPIO API for that and is documented in -Documentation/gpio/. +Documentation/admin-guide/gpio/. In the above example we can get the corresponding two GPIO descriptors with a code like this:: @@ -339,7 +339,7 @@ a code like this:: There are also devm_* versions of these functions which release the descriptors once the device is released. -See Documentation/acpi/gpio-properties.txt for more information about the +See Documentation/firmware-guide/acpi/gpio-properties.rst for more information about the _DSD binding related to GPIOs. MFD devices diff --git a/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst new file mode 100644 index 000000000000..5137ca834b54 --- /dev/null +++ b/Documentation/firmware-guide/acpi/extcon-intel-int3496.rst @@ -0,0 +1,33 @@ +===================================================== +Intel INT3496 ACPI device extcon driver documentation +===================================================== + +The Intel INT3496 ACPI device extcon driver is a driver for ACPI +devices with an acpi-id of INT3496, such as found for example on +Intel Baytrail and Cherrytrail tablets. + +This ACPI device describes how the OS can read the id-pin of the devices' +USB-otg port, as well as how it optionally can enable Vbus output on the +otg port and how it can optionally control the muxing of the data pins +between an USB host and an USB peripheral controller. + +The ACPI devices exposes this functionality by returning an array with up +to 3 gpio descriptors from its ACPI _CRS (Current Resource Settings) call: + +======= ===================================================================== +Index 0 The input gpio for the id-pin, this is always present and valid +Index 1 The output gpio for enabling Vbus output from the device to the otg + port, write 1 to enable the Vbus output (this gpio descriptor may + be absent or invalid) +Index 2 The output gpio for muxing of the data pins between the USB host and + the USB peripheral controller, write 1 to mux to the peripheral + controller +======= ===================================================================== + +There is a mapping between indices and GPIO connection IDs as follows + + ======= ======= + id index 0 + vbus index 1 + mux index 2 + ======= ======= diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index ae609eec4679..ad3b5afdae77 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -10,6 +10,7 @@ ACPI Support namespace dsd/graph dsd/data-node-references + dsd/leds enumeration osi method-customizing @@ -24,3 +25,4 @@ ACPI Support acpi-lid lpit video_extension + extcon-intel-int3496 diff --git a/Documentation/firmware-guide/acpi/method-tracing.rst b/Documentation/firmware-guide/acpi/method-tracing.rst index d0b077b73f5f..0aa7e2c5d32a 100644 --- a/Documentation/firmware-guide/acpi/method-tracing.rst +++ b/Documentation/firmware-guide/acpi/method-tracing.rst @@ -68,7 +68,7 @@ c. Filter out the debug layer/level matched logs when the specified Where: 0xXXXXXXXX/0xYYYYYYYY - Refer to Documentation/acpi/debug.txt for possible debug layer/level + Refer to Documentation/firmware-guide/acpi/debug.rst for possible debug layer/level masking values. \PPPP.AAAA.TTTT.HHHH Full path of a control method that can be found in the ACPI namespace. |