diff options
Diffstat (limited to 'Documentation/firmware-guide')
| -rw-r--r-- | Documentation/firmware-guide/acpi/DSD-properties-rules.rst | 11 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/apei/einj.rst | 21 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/chromeos-acpi-device.rst | 363 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/data-node-references.rst | 28 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/graph.rst | 40 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/leds.rst | 40 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/dsd/phy.rst | 28 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/enumeration.rst | 188 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/gpio-properties.rst | 26 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/index.rst | 1 | ||||
| -rw-r--r-- | Documentation/firmware-guide/acpi/osi.rst | 25 |
11 files changed, 596 insertions, 175 deletions
diff --git a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst index 8b2d8d0864c2..70442bc2521e 100644 --- a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst +++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst @@ -21,7 +21,9 @@ specific type) associated with it. In the ACPI _DSD context it is an element of the sub-package following the generic Device Properties UUID in the _DSD return package as specified in the -Device Properties UUID definition document [1]_. +section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section +"Device Properties UUID" in _DSD (Device Specific Data) Implementation Guide +document [1]_. It also may be regarded as the definition of a key and the associated data type that can be returned by _DSD in the Device Properties UUID sub-package for a @@ -36,7 +38,9 @@ Property subsets are nested collections of properties. Each of them is associated with an additional key (name) allowing the subset to be referred to as a whole (and to be treated as a separate entity). The canonical representation of property subsets is via the mechanism specified in the -Hierarchical Properties Extension UUID definition document [2]_. +section titled "Well-Known _DSD UUIDs and Data Structure Formats" sub-section +"Hierarchical Data Extension UUID" in _DSD (Device Specific Data) +Implementation Guide document [1]_. Property sets may be hierarchical. That is, a property set may contain multiple property subsets that each may contain property subsets of its @@ -96,5 +100,4 @@ contents. References ========== -.. [1] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf -.. [2] https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf +.. [1] https://github.com/UEFI/DSD-Guide diff --git a/Documentation/firmware-guide/acpi/apei/einj.rst b/Documentation/firmware-guide/acpi/apei/einj.rst index c042176e1707..d6b61d22f525 100644 --- a/Documentation/firmware-guide/acpi/apei/einj.rst +++ b/Documentation/firmware-guide/acpi/apei/einj.rst @@ -168,7 +168,7 @@ An error injection example:: 0x00000008 Memory Correctable 0x00000010 Memory Uncorrectable non-fatal # echo 0x12345000 > param1 # Set memory address for injection - # echo $((-1 << 12)) > param2 # Mask 0xfffffffffffff000 - anywhere in this page + # echo 0xfffffffffffff000 > param2 # Mask - anywhere in this page # echo 0x8 > error_type # Choose correctable memory error # echo 1 > error_inject # Inject now @@ -181,5 +181,24 @@ You should see something like this in dmesg:: [22715.834759] EDAC sbridge MC3: PROCESSOR 0:306e7 TIME 1422553404 SOCKET 0 APIC 0 [22716.616173] EDAC MC3: 1 CE memory read error on CPU_SrcID#0_Channel#0_DIMM#0 (channel:0 slot:0 page:0x12345 offset:0x0 grain:32 syndrome:0x0 - area:DRAM err_code:0001:0090 socket:0 channel_mask:1 rank:0) +Special notes for injection into SGX enclaves: + +There may be a separate BIOS setup option to enable SGX injection. + +The injection process consists of setting some special memory controller +trigger that will inject the error on the next write to the target +address. But the h/w prevents any software outside of an SGX enclave +from accessing enclave pages (even BIOS SMM mode). + +The following sequence can be used: + 1) Determine physical address of enclave page + 2) Use "notrigger=1" mode to inject (this will setup + the injection address, but will not actually inject) + 3) Enter the enclave + 4) Store data to the virtual address matching physical address from step 1 + 5) Execute CLFLUSH for that virtual address + 6) Spin delay for 250ms + 7) Read from the virtual address. This will trigger the error + For more information about EINJ, please refer to ACPI specification version 4.0, section 17.5 and ACPI 5.0, section 18.6. diff --git a/Documentation/firmware-guide/acpi/chromeos-acpi-device.rst b/Documentation/firmware-guide/acpi/chromeos-acpi-device.rst new file mode 100644 index 000000000000..f37fc90ce340 --- /dev/null +++ b/Documentation/firmware-guide/acpi/chromeos-acpi-device.rst @@ -0,0 +1,363 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================== +Chrome OS ACPI Device +===================== + +Hardware functionality specific to Chrome OS is exposed through a Chrome OS ACPI device. +The plug and play ID of a Chrome OS ACPI device is GGL0001. GGL is a valid PNP ID of Google. +PNP ID can be used with the ACPI devices according to the guidelines. The following ACPI +objects are supported: + +.. flat-table:: Supported ACPI Objects + :widths: 1 2 + :header-rows: 1 + + * - Object + - Description + + * - CHSW + - Chrome OS switch positions + + * - HWID + - Chrome OS hardware ID + + * - FWID + - Chrome OS firmware version + + * - FRID + - Chrome OS read-only firmware version + + * - BINF + - Chrome OS boot information + + * - GPIO + - Chrome OS GPIO assignments + + * - VBNV + - Chrome OS NVRAM locations + + * - VDTA + - Chrome OS verified boot data + + * - FMAP + - Chrome OS flashmap base address + + * - MLST + - Chrome OS method list + +CHSW (Chrome OS switch positions) +================================= +This control method returns the switch positions for Chrome OS specific hardware switches. + +Arguments: +---------- +None + +Result code: +------------ +An integer containing the switch positions as bitfields: + +.. flat-table:: + :widths: 1 2 + + * - 0x00000002 + - Recovery button was pressed when x86 firmware booted. + + * - 0x00000004 + - Recovery button was pressed when EC firmware booted. (required if EC EEPROM is + rewritable; otherwise optional) + + * - 0x00000020 + - Developer switch was enabled when x86 firmware booted. + + * - 0x00000200 + - Firmware write protection was disabled when x86 firmware booted. (required if + firmware write protection is controlled through x86 BIOS; otherwise optional) + +All other bits are reserved and should be set to 0. + +HWID (Chrome OS hardware ID) +============================ +This control method returns the hardware ID for the Chromebook. + +Arguments: +---------- +None + +Result code: +------------ +A null-terminated ASCII string containing the hardware ID from the Model-Specific Data area of +EEPROM. + +Note that the hardware ID can be up to 256 characters long, including the terminating null. + +FWID (Chrome OS firmware version) +================================= +This control method returns the firmware version for the rewritable portion of the main +processor firmware. + +Arguments: +---------- +None + +Result code: +------------ +A null-terminated ASCII string containing the complete firmware version for the rewritable +portion of the main processor firmware. + +FRID (Chrome OS read-only firmware version) +=========================================== +This control method returns the firmware version for the read-only portion of the main +processor firmware. + +Arguments: +---------- +None + +Result code: +------------ +A null-terminated ASCII string containing the complete firmware version for the read-only +(bootstrap + recovery ) portion of the main processor firmware. + +BINF (Chrome OS boot information) +================================= +This control method returns information about the current boot. + +Arguments: +---------- +None + +Result code: +------------ + +.. code-block:: + + Package { + Reserved1 + Reserved2 + Active EC Firmware + Active Main Firmware Type + Reserved5 + } + +.. flat-table:: + :widths: 1 1 2 + :header-rows: 1 + + * - Field + - Format + - Description + + * - Reserved1 + - DWORD + - Set to 256 (0x100). This indicates this field is no longer used. + + * - Reserved2 + - DWORD + - Set to 256 (0x100). This indicates this field is no longer used. + + * - Active EC firmware + - DWORD + - The EC firmware which was used during boot. + + - 0 - Read-only (recovery) firmware + - 1 - Rewritable firmware. + + Set to 0 if EC firmware is always read-only. + + * - Active Main Firmware Type + - DWORD + - The main firmware type which was used during boot. + + - 0 - Recovery + - 1 - Normal + - 2 - Developer + - 3 - netboot (factory installation only) + + Other values are reserved. + + * - Reserved5 + - DWORD + - Set to 256 (0x100). This indicates this field is no longer used. + +GPIO (Chrome OS GPIO assignments) +================================= +This control method returns information about Chrome OS specific GPIO assignments for +Chrome OS hardware, so the kernel can directly control that hardware. + +Arguments: +---------- +None + +Result code: +------------ +.. code-block:: + + Package { + Package { + // First GPIO assignment + Signal Type //DWORD + Attributes //DWORD + Controller Offset //DWORD + Controller Name //ASCIIZ + }, + ... + Package { + // Last GPIO assignment + Signal Type //DWORD + Attributes //DWORD + Controller Offset //DWORD + Controller Name //ASCIIZ + } + } + +Where ASCIIZ means a null-terminated ASCII string. + +.. flat-table:: + :widths: 1 1 2 + :header-rows: 1 + + * - Field + - Format + - Description + + * - Signal Type + - DWORD + - Type of GPIO signal + + - 0x00000001 - Recovery button + - 0x00000002 - Developer mode switch + - 0x00000003 - Firmware write protection switch + - 0x00000100 - Debug header GPIO 0 + - ... + - 0x000001FF - Debug header GPIO 255 + + Other values are reserved. + + * - Attributes + - DWORD + - Signal attributes as bitfields: + + - 0x00000001 - Signal is active-high (for button, a GPIO value + of 1 means the button is pressed; for switches, a GPIO value + of 1 means the switch is enabled). If this bit is 0, the signal + is active low. Set to 0 for debug header GPIOs. + + * - Controller Offset + - DWORD + - GPIO number on the specified controller. + + * - Controller Name + - ASCIIZ + - Name of the controller for the GPIO. + Currently supported names: + "NM10" - Intel NM10 chip + +VBNV (Chrome OS NVRAM locations) +================================ +This control method returns information about the NVRAM (CMOS) locations used to +communicate with the BIOS. + +Arguments: +---------- +None + +Result code: +------------ +.. code-block:: + + Package { + NV Storage Block Offset //DWORD + NV Storage Block Size //DWORD + } + +.. flat-table:: + :widths: 1 1 2 + :header-rows: 1 + + * - Field + - Format + - Description + + * - NV Storage Block Offset + - DWORD + - Offset in CMOS bank 0 of the verified boot non-volatile storage block, counting from + the first writable CMOS byte (that is, offset=0 is the byte following the 14 bytes of + clock data). + + * - NV Storage Block Size + - DWORD + - Size in bytes of the verified boot non-volatile storage block. + +FMAP (Chrome OS flashmap address) +================================= +This control method returns the physical memory address of the start of the main processor +firmware flashmap. + +Arguments: +---------- +None + +NoneResult code: +---------------- +A DWORD containing the physical memory address of the start of the main processor firmware +flashmap. + +VDTA (Chrome OS verified boot data) +=================================== +This control method returns the verified boot data block shared between the firmware +verification step and the kernel verification step. + +Arguments: +---------- +None + +Result code: +------------ +A buffer containing the verified boot data block. + +MECK (Management Engine Checksum) +================================= +This control method returns the SHA-1 or SHA-256 hash that is read out of the Management +Engine extended registers during boot. The hash is exported via ACPI so the OS can verify that +the ME firmware has not changed. If Management Engine is not present, or if the firmware was +unable to read the extended registers, this buffer can be zero. + +Arguments: +---------- +None + +Result code: +------------ +A buffer containing the ME hash. + +MLST (Chrome OS method list) +============================ +This control method returns a list of the other control methods supported by the Chrome OS +hardware device. + +Arguments: +---------- +None + +Result code: +------------ +A package containing a list of null-terminated ASCII strings, one for each control method +supported by the Chrome OS hardware device, not including the MLST method itself. +For this version of the specification, the result is: + +.. code-block:: + + Package { + "CHSW", + "FWID", + "HWID", + "FRID", + "BINF", + "GPIO", + "VBNV", + "FMAP", + "VDTA", + "MECK" + } diff --git a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst index b7ad47df49de..8d8b53e96bcf 100644 --- a/Documentation/firmware-guide/acpi/dsd/data-node-references.rst +++ b/Documentation/firmware-guide/acpi/dsd/data-node-references.rst @@ -5,7 +5,7 @@ Referencing hierarchical data nodes =================================== -:Copyright: |copy| 2018 Intel Corporation +:Copyright: |copy| 2018, 2021 Intel Corporation :Author: Sakari Ailus <sakari.ailus@linux.intel.com> ACPI in general allows referring to device objects in the tree only. @@ -13,9 +13,9 @@ Hierarchical data extension nodes may not be referred to directly, hence this document defines a scheme to implement such references. A reference consist of the device object name followed by one or more -hierarchical data extension [1] keys. Specifically, the hierarchical data -extension node which is referred to by the key shall lie directly under the -parent object i.e. either the device object or another hierarchical data +hierarchical data extension [dsd-guide] keys. Specifically, the hierarchical +data extension node which is referred to by the key shall lie directly under +the parent object i.e. either the device object or another hierarchical data extension node. The keys in the hierarchical data nodes shall consist of the name of the node, @@ -33,7 +33,7 @@ extension key. Example ======= -In the ASL snippet below, the "reference" _DSD property [2] contains a +In the ASL snippet below, the "reference" _DSD property contains a device object reference to DEV0 and under that device object, a hierarchical data extension key "node@1" referring to the NOD1 object and lastly, a hierarchical data extension key "anothernode" referring to @@ -52,12 +52,14 @@ the ANOD object which is also the final target node of the reference. Name (NOD0, Package() { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { + Package () { "reg", 0 }, Package () { "random-property", 3 }, } }) Name (NOD1, Package() { ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { + Package () { "reg", 1 }, Package () { "anothernode", "ANOD" }, } }) @@ -74,7 +76,11 @@ the ANOD object which is also the final target node of the reference. Name (_DSD, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () { "reference", ^DEV0, "node@1", "anothernode" }, + Package () { + "reference", Package () { + ^DEV0, "node@1", "anothernode" + } + }, } }) } @@ -85,10 +91,6 @@ Documentation/firmware-guide/acpi/dsd/graph.rst. References ========== -[1] Hierarchical Data Extension UUID For _DSD. -<https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf>, -referenced 2018-07-17. - -[2] Device Properties UUID For _DSD. -<https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf>, -referenced 2016-10-04. +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. diff --git a/Documentation/firmware-guide/acpi/dsd/graph.rst b/Documentation/firmware-guide/acpi/dsd/graph.rst index 0ced07cb1be3..b9dbfc73ed25 100644 --- a/Documentation/firmware-guide/acpi/dsd/graph.rst +++ b/Documentation/firmware-guide/acpi/dsd/graph.rst @@ -7,11 +7,11 @@ Graphs _DSD ==== -_DSD (Device Specific Data) [7] is a predefined ACPI device +_DSD (Device Specific Data) [dsd-guide] is a predefined ACPI device configuration object that can be used to convey information on hardware features which are not specifically covered by the ACPI -specification [1][6]. There are two _DSD extensions that are relevant -for graphs: property [4] and hierarchical data extensions [5]. The +specification [acpi]. There are two _DSD extensions that are relevant +for graphs: property [dsd-guide] and hierarchical data extensions. The property extension provides generic key-value pairs whereas the hierarchical data extension supports nodes with references to other nodes, forming a tree. The nodes in the tree may contain properties as @@ -36,8 +36,9 @@ Ports and endpoints =================== The port and endpoint concepts are very similar to those in Devicetree -[3]. A port represents an interface in a device, and an endpoint -represents a connection to that interface. +[devicetree, graph-bindings]. A port represents an interface in a device, and +an endpoint represents a connection to that interface. Also see [data-node-ref] +for generic data node references. All port nodes are located under the device's "_DSD" node in the hierarchical data extension tree. The data extension related to each port node must begin @@ -153,25 +154,20 @@ the "ISP" device and vice versa. References ========== -[1] _DSD (Device Specific Data) Implementation Guide. - https://www.uefi.org/sites/default/files/resources/_DSD-implementation-guide-toplevel-1_1.htm, - referenced 2016-10-03. +[acpi] Advanced Configuration and Power Interface Specification. + https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30. -[2] Devicetree. https://www.devicetree.org, referenced 2016-10-03. +[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst -[3] Documentation/devicetree/bindings/graph.txt +[devicetree] Devicetree. https://www.devicetree.org, referenced 2016-10-03. -[4] Device Properties UUID For _DSD. - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, - referenced 2016-10-04. +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. -[5] Hierarchical Data Extension UUID For _DSD. - https://www.uefi.org/sites/default/files/resources/_DSD-hierarchical-data-extension-UUID-v1.1.pdf, - referenced 2016-10-04. - -[6] Advanced Configuration and Power Interface Specification. - https://www.uefi.org/sites/default/files/resources/ACPI_6_1.pdf, - referenced 2016-10-04. - -[7] _DSD Device Properties Usage Rules. +[dsd-rules] _DSD Device Properties Usage Rules. Documentation/firmware-guide/acpi/DSD-properties-rules.rst + +[graph-bindings] Common bindings for device graphs (Devicetree). + https://github.com/devicetree-org/dt-schema/blob/main/schemas/graph.yaml, + referenced 2021-11-30. diff --git a/Documentation/firmware-guide/acpi/dsd/leds.rst b/Documentation/firmware-guide/acpi/dsd/leds.rst index b99fff8e06f2..93db592c93c7 100644 --- a/Documentation/firmware-guide/acpi/dsd/leds.rst +++ b/Documentation/firmware-guide/acpi/dsd/leds.rst @@ -5,19 +5,20 @@ Describing and referring to LEDs in ACPI ======================================== -Individual LEDs are described by hierarchical data extension [6] nodes under the +Individual LEDs are described by hierarchical data extension [5] 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 +connected. [leds] 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. +Referring to LEDs in Device tree is documented in [video-interfaces], 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]. +While Device tree allows referring to any node in the tree [devicetree], in +ACPI references are limited to device nodes only [acpi]. For this reason using +the same mechanism on ACPI is not possible. A mechanism to refer to non-device +ACPI nodes is documented in [data-node-ref]. ACPI allows (as does DT) using integer arguments after the reference. A combination of the LED driver device reference and an integer argument, @@ -90,22 +91,17 @@ where References ========== -[1] Device tree. https://www.devicetree.org, referenced 2019-02-21. +[acpi] Advanced Configuration and Power Interface Specification. + https://uefi.org/specifications/ACPI/6.4/, referenced 2021-11-30. -[2] Advanced Configuration and Power Interface Specification. - https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf, - referenced 2019-02-21. +[data-node-ref] Documentation/firmware-guide/acpi/dsd/data-node-references.rst -[3] Documentation/devicetree/bindings/leds/common.txt +[devicetree] Devicetree. https://www.devicetree.org, referenced 2019-02-21. -[4] Documentation/devicetree/bindings/media/video-interfaces.txt +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. -[5] Device Properties UUID For _DSD. - https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf, - referenced 2019-02-21. +[leds] Documentation/devicetree/bindings/leds/common.yaml -[6] Hierarchical Data Extension UUID For _DSD. - https://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 +[video-interfaces] Documentation/devicetree/bindings/media/video-interfaces.yaml diff --git a/Documentation/firmware-guide/acpi/dsd/phy.rst b/Documentation/firmware-guide/acpi/dsd/phy.rst index 680ad179e5f9..673ac374f92a 100644 --- a/Documentation/firmware-guide/acpi/dsd/phy.rst +++ b/Documentation/firmware-guide/acpi/dsd/phy.rst @@ -4,17 +4,17 @@ MDIO bus and PHYs in ACPI ========================= -The PHYs on an MDIO bus [1] are probed and registered using +The PHYs on an MDIO bus [phy] are probed and registered using fwnode_mdiobus_register_phy(). Later, for connecting these PHYs to their respective MACs, the PHYs registered on the MDIO bus have to be referenced. This document introduces two _DSD properties that are to be used -for connecting PHYs on the MDIO bus [3] to the MAC layer. +for connecting PHYs on the MDIO bus [dsd-properties-rules] to the MAC layer. These properties are defined in accordance with the "Device -Properties UUID For _DSD" [2] document and the +Properties UUID For _DSD" [dsd-guide] document and the daffd814-6eba-4d8c-8a91-bc9bbf4aa301 UUID must be used in the Device Data Descriptors containing them. @@ -48,22 +48,22 @@ as device object references (e.g. \_SB.MDI0.PHY1). phy-mode -------- The "phy-mode" _DSD property is used to describe the connection to -the PHY. The valid values for "phy-mode" are defined in [4]. +the PHY. The valid values for "phy-mode" are defined in [ethernet-controller]. managed ------- Optional property, which specifies the PHY management type. -The valid values for "managed" are defined in [4]. +The valid values for "managed" are defined in [ethernet-controller]. fixed-link ---------- The "fixed-link" is described by a data-only subnode of the MAC port, which is linked in the _DSD package via hierarchical data extension (UUID dbb8e3e6-5886-4ba6-8795-1319f52a966b -in accordance with [5] "_DSD Implementation Guide" document). +in accordance with [dsd-guide] "_DSD Implementation Guide" document). The subnode should comprise a required property ("speed") and possibly the optional ones - complete list of parameters and -their values are specified in [4]. +their values are specified in [ethernet-controller]. The following ASL example illustrates the usage of these properties. @@ -188,12 +188,14 @@ MAC node example with a "fixed-link" subnode. References ========== -[1] Documentation/networking/phy.rst +[phy] Documentation/networking/phy.rst -[2] https://www.uefi.org/sites/default/files/resources/_DSD-device-properties-UUID.pdf +[dsd-properties-rules] + Documentation/firmware-guide/acpi/DSD-properties-rules.rst -[3] Documentation/firmware-guide/acpi/DSD-properties-rules.rst +[ethernet-controller] + Documentation/devicetree/bindings/net/ethernet-controller.yaml -[4] Documentation/devicetree/bindings/net/ethernet-controller.yaml - -[5] https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.pdf +[dsd-guide] DSD Guide. + https://github.com/UEFI/DSD-Guide/blob/main/dsd-guide.adoc, referenced + 2021-11-30. diff --git a/Documentation/firmware-guide/acpi/enumeration.rst b/Documentation/firmware-guide/acpi/enumeration.rst index 74b830b2fd59..b9dc0c603f36 100644 --- a/Documentation/firmware-guide/acpi/enumeration.rst +++ b/Documentation/firmware-guide/acpi/enumeration.rst @@ -19,16 +19,17 @@ possible we decided to do following: platform devices. - Devices behind real busses where there is a connector resource - are represented as struct spi_device or struct i2c_device - (standard UARTs are not busses so there is no struct uart_device). + are represented as struct spi_device or struct i2c_device. Note + that standard UARTs are not busses so there is no struct uart_device, + although some of them may be represented by struct serdev_device. As both ACPI and Device Tree represent a tree of devices (and their resources) this implementation follows the Device Tree way as much as possible. -The ACPI implementation enumerates devices behind busses (platform, SPI and -I2C), creates the physical devices and binds them to their ACPI handle in -the ACPI namespace. +The ACPI implementation enumerates devices behind busses (platform, SPI, +I2C, and in some cases UART), creates the physical devices and binds them +to their ACPI handle in the ACPI namespace. This means that when ACPI_HANDLE(dev) returns non-NULL the device was enumerated from ACPI namespace. This handle can be used to extract other @@ -46,18 +47,16 @@ some minor changes. Adding ACPI support for an existing driver should be pretty straightforward. Here is the simplest example:: - #ifdef CONFIG_ACPI static const struct acpi_device_id mydrv_acpi_match[] = { /* ACPI IDs here */ { } }; MODULE_DEVICE_TABLE(acpi, mydrv_acpi_match); - #endif static struct platform_driver my_driver = { ... .driver = { - .acpi_match_table = ACPI_PTR(mydrv_acpi_match), + .acpi_match_table = mydrv_acpi_match, }, }; @@ -143,6 +142,44 @@ In robust cases the client unfortunately needs to call acpi_dma_request_slave_chan_by_index() directly and therefore choose the specific FixedDMA resource by its index. +Named Interrupts +================ + +Drivers enumerated via ACPI can have names to interrupts in the ACPI table +which can be used to get the IRQ number in the driver. + +The interrupt name can be listed in _DSD as 'interrupt-names'. The names +should be listed as an array of strings which will map to the Interrupt() +resource in the ACPI table corresponding to its index. + +The table below shows an example of its usage:: + + Device (DEV0) { + ... + Name (_CRS, ResourceTemplate() { + ... + Interrupt (ResourceConsumer, Level, ActiveHigh, Exclusive) { + 0x20, + 0x24 + } + }) + + Name (_DSD, Package () { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { + Package () { "interrupt-names", Package () { "default", "alert" } }, + } + ... + }) + } + +The interrupt name 'default' will correspond to 0x20 in Interrupt() +resource and 'alert' to 0x24. Note that only the Interrupt() resource +is mapped and not GpioInt() or similar. + +The driver can call the function - fwnode_irq_get_byname() with the fwnode +and interrupt name as arguments to get the corresponding IRQ number. + SPI serial bus support ====================== @@ -155,7 +192,7 @@ Here is what the ACPI namespace for a SPI slave might look like:: Device (EEP0) { Name (_ADR, 1) - Name (_CID, Package() { + Name (_CID, Package () { "ATML0025", "AT25", }) @@ -168,63 +205,55 @@ Here is what the ACPI namespace for a SPI slave might look like:: } ... -The SPI device drivers only need to add ACPI IDs in a similar way than with +The SPI device drivers only need to add ACPI IDs in a similar way to the platform device drivers. Below is an example where we add ACPI support to at25 SPI eeprom driver (this is meant for the above ACPI snippet):: - #ifdef CONFIG_ACPI static const struct acpi_device_id at25_acpi_match[] = { { "AT25", 0 }, - { }, + { } }; MODULE_DEVICE_TABLE(acpi, at25_acpi_match); - #endif static struct spi_driver at25_driver = { .driver = { ... - .acpi_match_table = ACPI_PTR(at25_acpi_match), + .acpi_match_table = at25_acpi_match, }, }; Note that this driver actually needs more information like page size of the -eeprom etc. but at the time writing this there is no standard way of -passing those. One idea is to return this in _DSM method like:: +eeprom, etc. This information can be passed via _DSD method like:: Device (EEP0) { ... - Method (_DSM, 4, NotSerialized) + Name (_DSD, Package () { - Store (Package (6) + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () { - "byte-len", 1024, - "addr-mode", 2, - "page-size, 32 - }, Local0) - - // Check UUIDs etc. - - Return (Local0) - } - -Then the at25 SPI driver can get this configuration by calling _DSM on its -ACPI handle like:: - - struct acpi_buffer output = { ACPI_ALLOCATE_BUFFER, NULL }; - struct acpi_object_list input; - acpi_status status; + Package () { "size", 1024 }, + Package () { "pagesize", 32 }, + Package () { "address-width", 16 }, + } + }) + } - /* Fill in the input buffer */ +Then the at25 SPI driver can get this configuration by calling device property +APIs during ->probe() phase like:: - status = acpi_evaluate_object(ACPI_HANDLE(&spi->dev), "_DSM", - &input, &output); - if (ACPI_FAILURE(status)) - /* Handle the error */ + err = device_property_read_u32(dev, "size", &size); + if (err) + ...error handling... - /* Extract the data here */ + err = device_property_read_u32(dev, "pagesize", &page_size); + if (err) + ...error handling... - kfree(output.pointer); + err = device_property_read_u32(dev, "address-width", &addr_width); + if (err) + ...error handling... I2C serial bus support ====================== @@ -237,26 +266,24 @@ registered. Below is an example of how to add ACPI support to the existing mpu3050 input driver:: - #ifdef CONFIG_ACPI static const struct acpi_device_id mpu3050_acpi_match[] = { { "MPU3050", 0 }, - { }, + { } }; MODULE_DEVICE_TABLE(acpi, mpu3050_acpi_match); - #endif static struct i2c_driver mpu3050_i2c_driver = { .driver = { .name = "mpu3050", - .owner = THIS_MODULE, .pm = &mpu3050_pm, .of_match_table = mpu3050_of_match, - .acpi_match_table = ACPI_PTR(mpu3050_acpi_match), + .acpi_match_table = mpu3050_acpi_match, }, .probe = mpu3050_probe, .remove = mpu3050_remove, .id_table = mpu3050_ids, }; + module_i2c_driver(mpu3050_i2c_driver); Reference to PWM device ======================= @@ -282,9 +309,9 @@ introduced, i.e.:: } } } - }) ... + } In the above example the PWM-based LED driver references to the PWM channel 0 of \_SB.PCI0.PWM device with initial period setting equal to 600 ms (note that @@ -306,26 +333,13 @@ For example:: { Name (SBUF, ResourceTemplate() { - ... // Used to power on/off the device - GpioIo (Exclusive, PullDefault, 0x0000, 0x0000, - IoRestrictionOutputOnly, "\\_SB.PCI0.GPI0", - 0x00, ResourceConsumer,,) - { - // Pin List - 0x0055 - } + GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionOutputOnly, + "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 85 } // Interrupt for the device - GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, - 0x0000, "\\_SB.PCI0.GPI0", 0x00, ResourceConsumer,,) - { - // Pin list - 0x0058 - } - - ... - + GpioInt (Edge, ActiveHigh, ExclusiveAndWake, PullNone, 0, + "\\_SB.PCI0.GPI0", 0, ResourceConsumer) { 88 } } Return (SBUF) @@ -337,17 +351,18 @@ For example:: ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () {"power-gpios", Package() {^DEV, 0, 0, 0 }}, - Package () {"irq-gpios", Package() {^DEV, 1, 0, 0 }}, + Package () { "power-gpios", Package () { ^DEV, 0, 0, 0 } }, + Package () { "irq-gpios", Package () { ^DEV, 1, 0, 0 } }, } }) ... + } These GPIO numbers are controller relative and path "\\_SB.PCI0.GPI0" 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 +There is a standard GPIO API for that and it is documented in Documentation/admin-guide/gpio/. In the above example we can get the corresponding two GPIO descriptors with @@ -374,6 +389,31 @@ descriptors once the device is released. See Documentation/firmware-guide/acpi/gpio-properties.rst for more information about the _DSD binding related to GPIOs. +RS-485 support +============== + +ACPI _DSD (Device Specific Data) can be used to describe RS-485 capability +of UART. + +For example:: + + Device (DEV) + { + ... + + // ACPI 5.1 _DSD used for RS-485 capabilities + Name (_DSD, Package () + { + ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), + Package () + { + Package () {"rs485-rts-active-low", Zero}, + Package () {"rs485-rx-active-high", Zero}, + Package () {"rs485-rx-during-tx", Zero}, + } + }) + ... + MFD devices =========== @@ -460,10 +500,10 @@ namespace link:: Device (TMP0) { Name (_HID, "PRP0001") - Name (_DSD, Package() { + Name (_DSD, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package (2) { "compatible", "ti,tmp75" }, + Package () { "compatible", "ti,tmp75" }, } }) Method (_CRS, 0, Serialized) @@ -498,8 +538,8 @@ information. PCI hierarchy representation ============================ -Sometimes could be useful to enumerate a PCI device, knowing its position on the -PCI bus. +Sometimes it could be useful to enumerate a PCI device, knowing its position on +the PCI bus. For example, some systems use PCI devices soldered directly on the mother board, in a fixed position (ethernet, Wi-Fi, serial ports, etc.). In this conditions it @@ -510,7 +550,7 @@ To identify a PCI device, a complete hierarchical description is required, from the chipset root port to the final device, through all the intermediate bridges/switches of the board. -For example, let us assume to have a system with a PCIe serial port, an +For example, let's assume we have a system with a PCIe serial port, an Exar XR17V3521, soldered on the main board. This UART chip also includes 16 GPIOs and we want to add the property ``gpio-line-names`` [1] to these pins. In this case, the ``lspci`` output for this component is:: @@ -553,8 +593,8 @@ of the chipset bridge (also called "root port") with address:: Bus: 0 - Device: 14 - Function: 1 -To find this information is necessary disassemble the BIOS ACPI tables, in -particular the DSDT (see also [2]):: +To find this information, it is necessary to disassemble the BIOS ACPI tables, +in particular the DSDT (see also [2]):: mkdir ~/tables/ cd ~/tables/ diff --git a/Documentation/firmware-guide/acpi/gpio-properties.rst b/Documentation/firmware-guide/acpi/gpio-properties.rst index df4b711053ee..eaec732cc77c 100644 --- a/Documentation/firmware-guide/acpi/gpio-properties.rst +++ b/Documentation/firmware-guide/acpi/gpio-properties.rst @@ -21,18 +21,18 @@ index, like the ASL example below shows:: Name (_CRS, ResourceTemplate () { GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, - "\\_SB.GPO0", 0, ResourceConsumer) {15} + "\\_SB.GPO0", 0, ResourceConsumer) { 15 } GpioIo (Exclusive, PullUp, 0, 0, IoRestrictionOutputOnly, - "\\_SB.GPO0", 0, ResourceConsumer) {27, 31} + "\\_SB.GPO0", 0, ResourceConsumer) { 27, 31 } }) Name (_DSD, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () - { - Package () {"reset-gpios", Package() {^BTH, 1, 1, 0 }}, - Package () {"shutdown-gpios", Package() {^BTH, 0, 0, 0 }}, + { + Package () { "reset-gpios", Package () { ^BTH, 1, 1, 0 } }, + Package () { "shutdown-gpios", Package () { ^BTH, 0, 0, 0 } }, } }) } @@ -123,17 +123,17 @@ Example:: // _DSD Hierarchical Properties Extension UUID ToUUID("dbb8e3e6-5886-4ba6-8795-1319f52a966b"), Package () { - Package () {"hog-gpio8", "G8PU"} + Package () { "hog-gpio8", "G8PU" } } }) Name (G8PU, Package () { ToUUID("daffd814-6eba-4d8c-8a91-bc9bbf4aa301"), Package () { - Package () {"gpio-hog", 1}, - Package () {"gpios", Package () {8, 0}}, - Package () {"output-high", 1}, - Package () {"line-name", "gpio8-pullup"}, + Package () { "gpio-hog", 1 }, + Package () { "gpios", Package () { 8, 0 } }, + Package () { "output-high", 1 }, + Package () { "line-name", "gpio8-pullup" }, } }) @@ -266,15 +266,17 @@ have a device like below:: Name (_CRS, ResourceTemplate () { GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, - "\\_SB.GPO0", 0, ResourceConsumer) {15} + "\\_SB.GPO0", 0, ResourceConsumer) { 15 } GpioIo (Exclusive, PullNone, 0, 0, IoRestrictionNone, - "\\_SB.GPO0", 0, ResourceConsumer) {27} + "\\_SB.GPO0", 0, ResourceConsumer) { 27 } }) } The driver might expect to get the right GPIO when it does:: desc = gpiod_get(dev, "reset", GPIOD_OUT_LOW); + if (IS_ERR(desc)) + ...error handling... but since there is no way to know the mapping between "reset" and the GpioIo() in _CRS desc will hold ERR_PTR(-ENOENT). diff --git a/Documentation/firmware-guide/acpi/index.rst b/Documentation/firmware-guide/acpi/index.rst index b053b0c3d696..b6a42f4ffe03 100644 --- a/Documentation/firmware-guide/acpi/index.rst +++ b/Documentation/firmware-guide/acpi/index.rst @@ -29,3 +29,4 @@ ACPI Support non-d0-probe extcon-intel-int3496 intel-pmc-mux + chromeos-acpi-device diff --git a/Documentation/firmware-guide/acpi/osi.rst b/Documentation/firmware-guide/acpi/osi.rst index 05869c0045d7..784850adfcb6 100644 --- a/Documentation/firmware-guide/acpi/osi.rst +++ b/Documentation/firmware-guide/acpi/osi.rst @@ -41,26 +41,23 @@ But it is likely that they will all eventually be added. What should an OEM do if they want to support Linux and Windows using the same BIOS image? Often they need to do something different for Linux to deal with how Linux is different from Windows. -Here the BIOS should ask exactly what it wants to know: +In this case, the OEM should create custom ASL to be executed by the +Linux kernel and changes to Linux kernel drivers to execute this custom +ASL. The easiest way to accomplish this is to introduce a device specific +method (_DSM) that is called from the Linux kernel. + +In the past the kernel used to support something like: _OSI("Linux-OEM-my_interface_name") where 'OEM' is needed if this is an OEM-specific hook, and 'my_interface_name' describes the hook, which could be a quirk, a bug, or a bug-fix. -In addition, the OEM should send a patch to upstream Linux -via the linux-acpi@vger.kernel.org mailing list. When that patch -is checked into Linux, the OS will answer "YES" when the BIOS -on the OEM's system uses _OSI to ask if the interface is supported -by the OS. Linux distributors can back-port that patch for Linux -pre-installs, and it will be included by all distributions that -re-base to upstream. If the distribution can not update the kernel binary, -they can also add an acpi_osi=Linux-OEM-my_interface_name -cmdline parameter to the boot loader, as needed. - -If the string refers to a feature where the upstream kernel -eventually grows support, a patch should be sent to remove -the string when that support is added to the kernel. +However this was discovered to be abused by other BIOS vendors to change +completely unrelated code on completely unrelated systems. This prompted +an evaluation of all of it's uses. This uncovered that they aren't needed +for any of the original reasons. As such, the kernel will not respond to +any custom Linux-* strings by default. That was easy. Read on, to find out how to do it wrong. |