diff options
Diffstat (limited to 'Documentation/driver-api')
63 files changed, 1624 insertions, 466 deletions
diff --git a/Documentation/driver-api/80211/index.rst b/Documentation/driver-api/80211/index.rst index af210859d3e1..62305e9c3113 100644 --- a/Documentation/driver-api/80211/index.rst +++ b/Documentation/driver-api/80211/index.rst @@ -8,10 +8,3 @@ Linux 802.11 Driver Developer's Guide cfg80211 mac80211 mac80211-advanced - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/driver-api/acpi/acpi-drivers.rst b/Documentation/driver-api/acpi/acpi-drivers.rst new file mode 100644 index 000000000000..376b6d8a678c --- /dev/null +++ b/Documentation/driver-api/acpi/acpi-drivers.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +========================================= +Why using ACPI drivers is not a good idea +========================================= + +:Copyright: |copy| 2026, Intel Corporation + +:Author: Rafael J. Wysocki <rafael.j.wysocki@intel.com> + +Even though binding drivers directly to struct acpi_device objects, also +referred to as "ACPI device nodes", allows basic functionality to be provided +at least in some cases, there are problems with it, related to general +consistency, sysfs layout, power management operation ordering, and code +cleanliness. + +First of all, ACPI device nodes represent firmware entities rather than +hardware and in many cases they provide auxiliary information on devices +enumerated independently (like PCI devices or CPUs). It is therefore generally +questionable to assign resources to them because the entities represented by +them do not decode addresses in the memory or I/O address spaces and do not +generate interrupts or similar (all of that is done by hardware). + +Second, as a general rule, a struct acpi_device can only be a parent of another +struct acpi_device. If that is not the case, the location of the child device +in the device hierarchy is at least confusing and it may not be straightforward +to identify the piece of hardware providing functionality represented by it. +However, binding a driver directly to an ACPI device node may cause that to +happen if the given driver registers input devices or wakeup sources under it, +for example. + +Next, using system suspend and resume callbacks directly on ACPI device nodes +is also questionable because it may cause ordering problems to appear. Namely, +ACPI device nodes are registered before enumerating hardware corresponding to +them and they land on the PM list in front of the majority of other device +objects. Consequently, the execution ordering of their PM callbacks may be +different from what is generally expected. Also, in general, dependencies +returned by _DEP objects do not affect ACPI device nodes themselves, but the +"physical" devices associated with them, which potentially is one more source +of inconsistency related to treating ACPI device nodes as "real" device +representation. + +All of the above means that binding drivers to ACPI device nodes should +generally be avoided and so struct acpi_driver objects should not be used. + +Moreover, a device ID is necessary to bind a driver directly to an ACPI device +node, but device IDs are not generally associated with all of them. Some of +them contain alternative information allowing the corresponding pieces of +hardware to be identified, for example represented by an _ADR object return +value, and device IDs are not used in those cases. In consequence, confusingly +enough, binding an ACPI driver to an ACPI device node may even be impossible. + +When that happens, the piece of hardware corresponding to the given ACPI device +node is represented by another device object, like a struct pci_dev, and the +ACPI device node is the "ACPI companion" of that device, accessible through its +fwnode pointer used by the ACPI_COMPANION() macro. The ACPI companion holds +additional information on the device configuration and possibly some "recipes" +on device manipulation in the form of AML (ACPI Machine Language) bytecode +provided by the platform firmware. Thus the role of the ACPI device node is +similar to the role of a struct device_node on a system where Device Tree is +used for platform description. + +For consistency, this approach has been extended to the cases in which ACPI +device IDs are used. Namely, in those cases, an additional device object is +created to represent the piece of hardware corresponding to a given ACPI device +node. By default, it is a platform device, but it may also be a PNP device, a +CPU device, or another type of device, depending on what the given piece of +hardware actually is. There are even cases in which multiple devices are +"backed" or "accompanied" by one ACPI device node (e.g. ACPI device nodes +corresponding to GPUs that may provide firmware interfaces for backlight +brightness control in addition to GPU configuration information). + +This means that it really should never be necessary to bind a driver directly to +an ACPI device node because there is a "proper" device object representing the +corresponding piece of hardware that can be bound to by a "proper" driver using +the given ACPI device node as the device's ACPI companion. Thus, in principle, +there is no reason to use ACPI drivers and if they all were replaced with other +driver types (for example, platform drivers), some code could be dropped and +some complexity would go away. diff --git a/Documentation/driver-api/acpi/index.rst b/Documentation/driver-api/acpi/index.rst index ace0008e54c2..2b10d83f9994 100644 --- a/Documentation/driver-api/acpi/index.rst +++ b/Documentation/driver-api/acpi/index.rst @@ -7,3 +7,4 @@ ACPI Support linuxized-acpica scan_handlers + acpi-drivers diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst index 5e9f7aee71a7..8b6a5888cb11 100644 --- a/Documentation/driver-api/basics.rst +++ b/Documentation/driver-api/basics.rst @@ -114,10 +114,25 @@ Kernel objects manipulation Kernel utility functions ------------------------ -.. kernel-doc:: include/linux/kernel.h +.. kernel-doc:: include/linux/array_size.h + :internal: + +.. kernel-doc:: include/linux/container_of.h + :internal: + +.. kernel-doc:: include/linux/kstrtox.h :internal: :no-identifiers: kstrtol kstrtoul +.. kernel-doc:: include/linux/stddef.h + :internal: + +.. kernel-doc:: include/linux/util_macros.h + :internal: + +.. kernel-doc:: include/linux/wordpart.h + :internal: + .. kernel-doc:: kernel/printk/printk.c :export: :no-identifiers: printk diff --git a/Documentation/driver-api/clk.rst b/Documentation/driver-api/clk.rst index 93bab5336dfd..c6aca8186a78 100644 --- a/Documentation/driver-api/clk.rst +++ b/Documentation/driver-api/clk.rst @@ -77,9 +77,6 @@ the operations defined in clk-provider.h:: void (*disable_unused)(struct clk_hw *hw); unsigned long (*recalc_rate)(struct clk_hw *hw, unsigned long parent_rate); - long (*round_rate)(struct clk_hw *hw, - unsigned long rate, - unsigned long *parent_rate); int (*determine_rate)(struct clk_hw *hw, struct clk_rate_request *req); int (*set_parent)(struct clk_hw *hw, u8 index); @@ -220,9 +217,7 @@ optional or must be evaluated on a case-by-case basis. +----------------+------+-------------+---------------+-------------+------+ |.recalc_rate | | y | | | | +----------------+------+-------------+---------------+-------------+------+ - |.round_rate | | y [1]_ | | | | - +----------------+------+-------------+---------------+-------------+------+ - |.determine_rate | | y [1]_ | | | | + |.determine_rate | | y | | | | +----------------+------+-------------+---------------+-------------+------+ |.set_rate | | y | | | | +----------------+------+-------------+---------------+-------------+------+ @@ -238,8 +233,6 @@ optional or must be evaluated on a case-by-case basis. |.init | | | | | | +----------------+------+-------------+---------------+-------------+------+ -.. [1] either one of round_rate or determine_rate is required. - Finally, register your clock at run-time with a hardware-specific registration function. This function simply populates struct clk_foo's data and then passes the common struct clk parameters to the framework diff --git a/Documentation/driver-api/coco/index.rst b/Documentation/driver-api/coco/index.rst index af9f08ca0cfd..783c8b033547 100644 --- a/Documentation/driver-api/coco/index.rst +++ b/Documentation/driver-api/coco/index.rst @@ -8,5 +8,3 @@ Confidential Computing :maxdepth: 1 measurement-registers - -.. only:: subproject and html diff --git a/Documentation/driver-api/crypto/iaa/index.rst b/Documentation/driver-api/crypto/iaa/index.rst index aa6837e27264..463f7da569c5 100644 --- a/Documentation/driver-api/crypto/iaa/index.rst +++ b/Documentation/driver-api/crypto/iaa/index.rst @@ -11,10 +11,3 @@ API. :maxdepth: 1 iaa-crypto - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/driver-api/crypto/index.rst b/Documentation/driver-api/crypto/index.rst index fb9709b98bea..bba669014cb2 100644 --- a/Documentation/driver-api/crypto/index.rst +++ b/Documentation/driver-api/crypto/index.rst @@ -11,10 +11,3 @@ configuration. :maxdepth: 1 iaa/index - -.. only:: subproject and html - - Indices - ======= - - * :ref:`genindex` diff --git a/Documentation/driver-api/cxl/conventions.rst b/Documentation/driver-api/cxl/conventions.rst index e37336d7b116..0d2e07279ad9 100644 --- a/Documentation/driver-api/cxl/conventions.rst +++ b/Documentation/driver-api/cxl/conventions.rst @@ -1,9 +1,7 @@ .. SPDX-License-Identifier: GPL-2.0 -.. include:: <isonum.txt> -======================================= Compute Express Link: Linux Conventions -======================================= +####################################### There exists shipping platforms that bend or break CXL specification expectations. Record the details and the rationale for those deviations. @@ -11,172 +9,10 @@ Borrow the ACPI Code First template format to capture the assumptions and tradeoffs such that multiple platform implementations can follow the same convention. -<(template) Title> -================== +.. toctree:: + :maxdepth: 1 + :caption: Contents -Document --------- -CXL Revision <rev>, Version <ver> - -License -------- -SPDX-License Identifier: CC-BY-4.0 - -Creator/Contributors --------------------- - -Summary of the Change ---------------------- - -<Detail the conflict with the specification and where available the -assumptions and tradeoffs taken by the hardware platform.> - - -Benefits of the Change ----------------------- - -<Detail what happens if platforms and Linux do not adopt this -convention.> - -References ----------- - -Detailed Description of the Change ----------------------------------- - -<Propose spec language that corrects the conflict.> - - -Resolve conflict between CFMWS, Platform Memory Holes, and Endpoint Decoders -============================================================================ - -Document --------- - -CXL Revision 3.2, Version 1.0 - -License -------- - -SPDX-License Identifier: CC-BY-4.0 - -Creator/Contributors --------------------- - -- Fabio M. De Francesco, Intel -- Dan J. Williams, Intel -- Mahesh Natu, Intel - -Summary of the Change ---------------------- - -According to the current Compute Express Link (CXL) Specifications (Revision -3.2, Version 1.0), the CXL Fixed Memory Window Structure (CFMWS) describes zero -or more Host Physical Address (HPA) windows associated with each CXL Host -Bridge. Each window represents a contiguous HPA range that may be interleaved -across one or more targets, including CXL Host Bridges. Each window has a set -of restrictions that govern its usage. It is the Operating System-directed -configuration and Power Management (OSPM) responsibility to utilize each window -for the specified use. - -Table 9-22 of the current CXL Specifications states that the Window Size field -contains the total number of consecutive bytes of HPA this window describes. -This value must be a multiple of the Number of Interleave Ways (NIW) * 256 MB. - -Platform Firmware (BIOS) might reserve physical addresses below 4 GB where a -memory gap such as the Low Memory Hole for PCIe MMIO may exist. In such cases, -the CFMWS Range Size may not adhere to the NIW * 256 MB rule. - -The HPA represents the actual physical memory address space that the CXL devices -can decode and respond to, while the System Physical Address (SPA), a related -but distinct concept, represents the system-visible address space that users can -direct transaction to and so it excludes reserved regions. - -BIOS publishes CFMWS to communicate the active SPA ranges that, on platforms -with LMH's, map to a strict subset of the HPA. The SPA range trims out the hole, -resulting in lost capacity in the Endpoints with no SPA to map to that part of -the HPA range that intersects the hole. - -E.g, an x86 platform with two CFMWS and an LMH starting at 2 GB: - - +--------+------------+-------------------+------------------+-------------------+------+ - | Window | CFMWS Base | CFMWS Size | HDM Decoder Base | HDM Decoder Size | Ways | - +========+============+===================+==================+===================+======+ - | 0 | 0 GB | 2 GB | 0 GB | 3 GB | 12 | - +--------+------------+-------------------+------------------+-------------------+------+ - | 1 | 4 GB | NIW*256MB Aligned | 4 GB | NIW*256MB Aligned | 12 | - +--------+------------+-------------------+------------------+-------------------+------+ - -HDM decoder base and HDM decoder size represent all the 12 Endpoint Decoders of -a 12 ways region and all the intermediate Switch Decoders. They are configured -by the BIOS according to the NIW * 256MB rule, resulting in a HPA range size of -3GB. Instead, the CFMWS Base and CFMWS Size are used to configure the Root -Decoder HPA range that results smaller (2GB) than that of the Switch and -Endpoint Decoders in the hierarchy (3GB). - -This creates 2 issues which lead to a failure to construct a region: - -1) A mismatch in region size between root and any HDM decoder. The root decoders - will always be smaller due to the trim. - -2) The trim causes the root decoder to violate the (NIW * 256MB) rule. - -This change allows a region with a base address of 0GB to bypass these checks to -allow for region creation with the trimmed root decoder address range. - -This change does not allow for any other arbitrary region to violate these -checks - it is intended exclusively to enable x86 platforms which map CXL memory -under 4GB. - -Despite the HDM decoders covering the PCIE hole HPA region, it is expected that -the platform will never route address accesses to the CXL complex because the -root decoder only covers the trimmed region (which excludes this). This is -outside the ability of Linux to enforce. - -On the example platform, only the first 2GB will be potentially usable, but -Linux, aiming to adhere to the current specifications, fails to construct -Regions and attach Endpoint and intermediate Switch Decoders to them. - -There are several points of failure that due to the expectation that the Root -Decoder HPA size, that is equal to the CFMWS from which it is configured, has -to be greater or equal to the matching Switch and Endpoint HDM Decoders. - -In order to succeed with construction and attachment, Linux must construct a -Region with Root Decoder HPA range size, and then attach to that all the -intermediate Switch Decoders and Endpoint Decoders that belong to the hierarchy -regardless of their range sizes. - -Benefits of the Change ----------------------- - -Without the change, the OSPM wouldn't match intermediate Switch and Endpoint -Decoders with Root Decoders configured with CFMWS HPA sizes that don't align -with the NIW * 256MB constraint, and so it leads to lost memdev capacity. - -This change allows the OSPM to construct Regions and attach intermediate Switch -and Endpoint Decoders to them, so that the addressable part of the memory -devices total capacity is made available to the users. - -References ----------- - -Compute Express Link Specification Revision 3.2, Version 1.0 -<https://www.computeexpresslink.org/> - -Detailed Description of the Change ----------------------------------- - -The description of the Window Size field in table 9-22 needs to account for -platforms with Low Memory Holes, where SPA ranges might be subsets of the -endpoints HPA. Therefore, it has to be changed to the following: - -"The total number of consecutive bytes of HPA this window represents. This value -shall be a multiple of NIW * 256 MB. - -On platforms that reserve physical addresses below 4 GB, such as the Low Memory -Hole for PCIe MMIO on x86, an instance of CFMWS whose Base HPA range is 0 might -have a size that doesn't align with the NIW * 256 MB constraint. - -Note that the matching intermediate Switch Decoders and the Endpoint Decoders -HPA range sizes must still align to the above-mentioned rule, but the memory -capacity that exceeds the CFMWS window size won't be accessible.". + conventions/cxl-lmh.rst + conventions/cxl-atl.rst + conventions/template.rst diff --git a/Documentation/driver-api/cxl/conventions/cxl-atl.rst b/Documentation/driver-api/cxl/conventions/cxl-atl.rst new file mode 100644 index 000000000000..3a36a84743d0 --- /dev/null +++ b/Documentation/driver-api/cxl/conventions/cxl-atl.rst @@ -0,0 +1,304 @@ +.. SPDX-License-Identifier: GPL-2.0 + +ACPI PRM CXL Address Translation +================================ + +Document +-------- + +CXL Revision 3.2, Version 1.0 + +License +------- + +SPDX-License Identifier: CC-BY-4.0 + +Creator/Contributors +-------------------- + +- Robert Richter, AMD et al. + +Summary of the Change +--------------------- + +The CXL Fixed Memory Window Structures (CFMWS) describe zero or more Host +Physical Address (HPA) windows associated with one or more CXL Host Bridges. +Each HPA range of a CXL Host Bridge is represented by a CFMWS entry. An HPA +range may include addresses currently assigned to CXL.mem devices, or an OS may +assign ranges from an address window to a device. + +Host-managed Device Memory is Device-attached memory that is mapped to system +coherent address space and accessible to the Host using standard write-back +semantics. The managed address range is configured in the CXL HDM Decoder +registers of the device. An HDM Decoder in a device is responsible for +converting HPA into DPA by stripping off specific address bits. + +CXL devices and CXL bridges use the same HPA space. It is common across all +components that belong to the same host domain. The view of the address region +must be consistent on the CXL.mem path between the Host and the Device. + +This is described in the *CXL 3.2 specification* (Table 1-1, 3.3.1, +8.2.4.20, 9.13.1, 9.18.1.3). [#cxl-spec-3.2]_ + +Depending on the interconnect architecture of the platform, components attached +to a host may not share the same host physical address space. Those platforms +need addr |