diff options
Diffstat (limited to 'Documentation/driver-api')
61 files changed, 1702 insertions, 1120 deletions
diff --git a/Documentation/driver-api/auxiliary_bus.rst b/Documentation/driver-api/auxiliary_bus.rst index cec84908fbc0..b236de773e1d 100644 --- a/Documentation/driver-api/auxiliary_bus.rst +++ b/Documentation/driver-api/auxiliary_bus.rst @@ -24,7 +24,6 @@ Auxiliary Device Creation .. kernel-doc:: drivers/base/auxiliary.c :identifiers: auxiliary_device_init __auxiliary_device_add - auxiliary_find_device Auxiliary Device Memory Model and Lifespan ------------------------------------------ diff --git a/Documentation/driver-api/crypto/iaa/iaa-crypto.rst b/Documentation/driver-api/crypto/iaa/iaa-crypto.rst index de587cf9cbed..8e50b900d51c 100644 --- a/Documentation/driver-api/crypto/iaa/iaa-crypto.rst +++ b/Documentation/driver-api/crypto/iaa/iaa-crypto.rst @@ -179,7 +179,9 @@ has the old 'iax' device naming in place) :: # configure wq1.0 - accel-config config-wq --group-id=0 --mode=dedicated --type=kernel --name="iaa_crypto" --device_name="crypto" iax1/wq1.0 + accel-config config-wq --group-id=0 --mode=dedicated --type=kernel --priority=10 --name="iaa_crypto" --driver-name="crypto" iax1/wq1.0 + + accel-config config-engine iax1/engine1.0 --group-id=0 # enable IAA device iax1 @@ -270,7 +272,7 @@ The available attributes are: echo async_irq > /sys/bus/dsa/drivers/crypto/sync_mode Async mode without interrupts (caller must poll) can be enabled by - writing 'async' to it:: + writing 'async' to it (please see Caveat):: echo async > /sys/bus/dsa/drivers/crypto/sync_mode @@ -281,6 +283,13 @@ The available attributes are: The default mode is 'sync'. + Caveat: since the only mechanism that iaa_crypto currently implements + for async polling without interrupts is via the 'sync' mode as + described earlier, writing 'async' to + '/sys/bus/dsa/drivers/crypto/sync_mode' will internally enable the + 'sync' mode. This is to ensure correct iaa_crypto behavior until true + async polling without interrupts is enabled in iaa_crypto. + .. _iaa_default_config: IAA Default Configuration @@ -321,33 +330,30 @@ driver will generate statistics which can be accessed in debugfs at:: # ls -al /sys/kernel/debug/iaa-crypto/ total 0 - drwxr-xr-x 2 root root 0 Mar 3 09:35 . - drwx------ 47 root root 0 Mar 3 09:35 .. - -rw-r--r-- 1 root root 0 Mar 3 09:35 max_acomp_delay_ns - -rw-r--r-- 1 root root 0 Mar 3 09:35 max_adecomp_delay_ns - -rw-r--r-- 1 root root 0 Mar 3 09:35 max_comp_delay_ns - -rw-r--r-- 1 root root 0 Mar 3 09:35 max_decomp_delay_ns - -rw-r--r-- 1 root root 0 Mar 3 09:35 stats_reset - -rw-r--r-- 1 root root 0 Mar 3 09:35 total_comp_bytes_out - -rw-r--r-- 1 root root 0 Mar 3 09:35 total_comp_calls - -rw-r--r-- 1 root root 0 Mar 3 09:35 total_decomp_bytes_in - -rw-r--r-- 1 root root 0 Mar 3 09:35 total_decomp_calls - -rw-r--r-- 1 root root 0 Mar 3 09:35 wq_stats - -Most of the above statisticss are self-explanatory. The wq_stats file -shows per-wq stats, a set for each iaa device and wq in addition to -some global stats:: + drwxr-xr-x 2 root root 0 Mar 3 07:55 . + drwx------ 53 root root 0 Mar 3 07:55 .. + -rw-r--r-- 1 root root 0 Mar 3 07:55 global_stats + -rw-r--r-- 1 root root 0 Mar 3 07:55 stats_reset + -rw-r--r-- 1 root root 0 Mar 3 07:55 wq_stats - # cat wq_stats +The global_stats file shows a set of global statistics collected since +the driver has been loaded or reset:: + + # cat global_stats global stats: - total_comp_calls: 100 - total_decomp_calls: 100 - total_comp_bytes_out: 22800 - total_decomp_bytes_in: 22800 + total_comp_calls: 4300 + total_decomp_calls: 4164 + total_sw_decomp_calls: 0 + total_comp_bytes_out: 5993989 + total_decomp_bytes_in: 5993989 total_completion_einval_errors: 0 total_completion_timeout_errors: 0 - total_completion_comp_buf_overflow_errors: 0 + total_completion_comp_buf_overflow_errors: 136 + +The wq_stats file shows per-wq stats, a set for each iaa device and wq +in addition to some global stats:: + # cat wq_stats iaa device: id: 1 n_wqs: 1 @@ -379,21 +385,36 @@ some global stats:: iaa device: id: 5 n_wqs: 1 - comp_calls: 100 - comp_bytes: 22800 - decomp_calls: 100 - decomp_bytes: 22800 + comp_calls: 1360 + comp_bytes: 1999776 + decomp_calls: 0 + decomp_bytes: 0 + wqs: + name: iaa_crypto + comp_calls: 1360 + comp_bytes: 1999776 + decomp_calls: 0 + decomp_bytes: 0 + + iaa device: + id: 7 + n_wqs: 1 + comp_calls: 2940 + comp_bytes: 3994213 + decomp_calls: 4164 + decomp_bytes: 5993989 wqs: name: iaa_crypto - comp_calls: 100 - comp_bytes: 22800 - decomp_calls: 100 - decomp_bytes: 22800 + comp_calls: 2940 + comp_bytes: 3994213 + decomp_calls: 4164 + decomp_bytes: 5993989 + ... -Writing 0 to 'stats_reset' resets all the stats, including the +Writing to 'stats_reset' resets all the stats, including the per-device and per-wq stats:: - # echo 0 > stats_reset + # echo 1 > stats_reset # cat wq_stats global stats: total_comp_calls: 0 @@ -457,7 +478,6 @@ Use the following commands to enable zswap:: # echo deflate-iaa > /sys/module/zswap/parameters/compressor # echo zsmalloc > /sys/module/zswap/parameters/zpool # echo 1 > /sys/module/zswap/parameters/enabled - # echo 0 > /sys/module/zswap/parameters/same_filled_pages_enabled # echo 100 > /proc/sys/vm/swappiness # echo never > /sys/kernel/mm/transparent_hugepage/enabled # echo 1 > /proc/sys/vm/overcommit_memory @@ -536,12 +556,20 @@ The below script automatically does that:: echo "End Disable IAA" + echo "Reload iaa_crypto module" + + rmmod iaa_crypto + modprobe iaa_crypto + + echo "End Reload iaa_crypto module" + # # configure iaa wqs and devices # echo "Configure IAA" for ((i = 1; i < ${num_iaa} * 2; i += 2)); do - accel-config config-wq --group-id=0 --mode=dedicated --size=128 --priority=10 --type=kernel --name="iaa_crypto" --driver_name="crypto" iax${i}/wq${i} + accel-config config-wq --group-id=0 --mode=dedicated --wq-size=128 --priority=10 --type=kernel --name="iaa_crypto" --driver-name="crypto" iax${i}/wq${i}.0 + accel-config config-engine iax${i}/engine${i}.0 --group-id=0 done echo "End Configure IAA" @@ -552,10 +580,10 @@ The below script automatically does that:: echo "Enable IAA" for ((i = 1; i < ${num_iaa} * 2; i += 2)); do - echo enable iaa iaa${i} - accel-config enable-device iaa${i} - echo enable wq iaa${i}/wq${i}.0 - accel-config enable-wq iaa${i}/wq${i}.0 + echo enable iaa iax${i} + accel-config enable-device iax${i} + echo enable wq iax${i}/wq${i}.0 + accel-config enable-wq iax${i}/wq${i}.0 done echo "End Enable IAA" @@ -599,7 +627,6 @@ the 'fixed' compression mode:: echo deflate-iaa > /sys/module/zswap/parameters/compressor echo zsmalloc > /sys/module/zswap/parameters/zpool echo 1 > /sys/module/zswap/parameters/enabled - echo 0 > /sys/module/zswap/parameters/same_filled_pages_enabled echo 100 > /proc/sys/vm/swappiness echo never > /sys/kernel/mm/transparent_hugepage/enabled diff --git a/Documentation/driver-api/cxl/access-coordinates.rst b/Documentation/driver-api/cxl/access-coordinates.rst new file mode 100644 index 000000000000..b07950ea30c9 --- /dev/null +++ b/Documentation/driver-api/cxl/access-coordinates.rst @@ -0,0 +1,91 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +================================== +CXL Access Coordinates Computation +================================== + +Shared Upstream Link Calculation +================================ +For certain CXL region construction with endpoints behind CXL switches (SW) or +Root Ports (RP), there is the possibility of the total bandwidth for all +the endpoints behind a switch being more than the switch upstream link. +A similar situation can occur within the host, upstream of the root ports. +The CXL driver performs an additional pass after all the targets have +arrived for a region in order to recalculate the bandwidths with possible +upstream link being a limiting factor in mind. + +The algorithm assumes the configuration is a symmetric topology as that +maximizes performance. When asymmetric topology is detected, the calculation +is aborted. An asymmetric topology is detected during topology walk where the +number of RPs detected as a grandparent is not equal to the number of devices +iterated in the same iteration loop. The assumption is made that subtle +asymmetry in properties does not happen and all paths to EPs are equal. + +There can be multiple switches under an RP. There can be multiple RPs under +a CXL Host Bridge (HB). There can be multiple HBs under a CXL Fixed Memory +Window Structure (CFMWS). + +An example hierarchy: + +> CFMWS 0 +> | +> _________|_________ +> | | +> ACPI0017-0 ACPI0017-1 +> GP0/HB0/ACPI0016-0 GP1/HB1/ACPI0016-1 +> | | | | +> RP0 RP1 RP2 RP3 +> | | | | +> SW 0 SW 1 SW 2 SW 3 +> | | | | | | | | +> EP0 EP1 EP2 EP3 EP4 EP5 EP6 EP7 + +Computation for the example hierarchy: + +Min (GP0 to CPU BW, + Min(SW 0 Upstream Link to RP0 BW, + Min(SW0SSLBIS for SW0DSP0 (EP0), EP0 DSLBIS, EP0 Upstream Link) + + Min(SW0SSLBIS for SW0DSP1 (EP1), EP1 DSLBIS, EP1 Upstream link)) + + Min(SW 1 Upstream Link to RP1 BW, + Min(SW1SSLBIS for SW1DSP0 (EP2), EP2 DSLBIS, EP2 Upstream Link) + + Min(SW1SSLBIS for SW1DSP1 (EP3), EP3 DSLBIS, EP3 Upstream link))) + +Min (GP1 to CPU BW, + Min(SW 2 Upstream Link to RP2 BW, + Min(SW2SSLBIS for SW2DSP0 (EP4), EP4 DSLBIS, EP4 Upstream Link) + + Min(SW2SSLBIS for SW2DSP1 (EP5), EP5 DSLBIS, EP5 Upstream link)) + + Min(SW 3 Upstream Link to RP3 BW, + Min(SW3SSLBIS for SW3DSP0 (EP6), EP6 DSLBIS, EP6 Upstream Link) + + Min(SW3SSLBIS for SW3DSP1 (EP7), EP7 DSLBIS, EP7 Upstream link)))) + +The calculation starts at cxl_region_shared_upstream_perf_update(). A xarray +is created to collect all the endpoint bandwidths via the +cxl_endpoint_gather_bandwidth() function. The min() of bandwidth from the +endpoint CDAT and the upstream link bandwidth is calculated. If the endpoint +has a CXL switch as a parent, then min() of calculated bandwidth and the +bandwidth from the SSLBIS for the switch downstream port that is associated +with the endpoint is calculated. The final bandwidth is stored in a +'struct cxl_perf_ctx' in the xarray indexed by a device pointer. If the +endpoint is direct attached to a root port (RP), the device pointer would be an +RP device. If the endpoint is behind a switch, the device pointer would be the +upstream device of the parent switch. + +At the next stage, the code walks through one or more switches if they exist +in the topology. For endpoints directly attached to RPs, this step is skipped. +If there is another switch upstream, the code takes the min() of the current +gathered bandwidth and the upstream link bandwidth. If there's a switch +upstream, then the SSLBIS of the upstream switch. + +Once the topology walk reaches the RP, whether it's direct attached endpoints +or walking through the switch(es), cxl_rp_gather_bandwidth() is called. At +this point all the bandwidths are aggregated per each host bridge, which is +also the index for the resulting xarray. + +The next step is to take the min() of the per host bridge bandwidth and the +bandwidth from the Generic Port (GP). The bandwidths for the GP is retrieved +via ACPI tables SRAT/HMAT. The min bandwidth are aggregated under the same +ACPI0017 device to form a new xarray. + +Finally, the cxl_region_update_bandwidth() is called and the aggregated +bandwidth from all the members of the last xarray is updated for the +access coordinates residing in the cxl region (cxlr) context. diff --git a/Documentation/driver-api/cxl/index.rst b/Documentation/driver-api/cxl/index.rst index 036e49553542..965ba90e8fb7 100644 --- a/Documentation/driver-api/cxl/index.rst +++ b/Documentation/driver-api/cxl/index.rst @@ -8,5 +8,8 @@ Compute Express Link :maxdepth: 1 memory-devices + access-coordinates + + maturity-map .. only:: subproject and html diff --git a/Documentation/driver-api/cxl/maturity-map.rst b/Documentation/driver-api/cxl/maturity-map.rst new file mode 100644 index 000000000000..df8e2ac2a320 --- /dev/null +++ b/Documentation/driver-api/cxl/maturity-map.rst @@ -0,0 +1,202 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=========================================== +Compute Express Link Subsystem Maturity Map +=========================================== + +The Linux CXL subsystem tracks the dynamic `CXL specification +<https://computeexpresslink.org/cxl-specification-landing-page>`_ that +continues to respond to new use cases with new features, capability +updates and fixes. At any given point some aspects of the subsystem are +more mature than others. While the periodic pull requests summarize the +`work being incorporated each merge window +<https://lore.kernel.org/linux-cxl/?q=s%3APULL+s%3ACXL+tc%3Atorvalds+NOT+s%3ARe>`_, +those do not always convey progress relative to a starting point and a +future end goal. + +What follows is a coarse breakdown of the subsystem's major +responsibilities along with a maturity score. The expectation is that +the change-history of this document provides an overview summary of the +subsystem maturation over time. + +The maturity scores are: + +- [3] Mature: Work in this area is complete and no changes on the horizon. + Note that this score can regress from one kernel release to the next + based on new test results or end user reports. + +- [2] Stabilizing: Major functionality operational, common cases are + mature, but known corner cases are still a work in progress. + +- [1] Initial: Capability that has exited the Proof of Concept phase, but + may still have significant gaps to close and fixes to apply as real + world testing occurs. + +- [0] Known gap: Feature is on a medium to long term horizon to + implement. If the specification has a feature that does not even have + a '0' score in this document, there is a good chance that no one in + the linux-cxl@vger.kernel.org community has started to look at it. + +- X: Out of scope for kernel enabling, or kernel enabling not required + +Feature and Capabilities +======================== + +Enumeration / Provisioning +-------------------------- +All of the fundamental enumeration an object model of the subsystem is +in place, but there are several corner cases that are pending closure. + + +* [2] CXL Window Enumeration + + * [0] :ref:`Extended-linear memory-side cache <extended-linear>` + * [0] Low Memory-hole + * [0] Hetero-interleave + +* [2] Switch Enumeration + + * [0] CXL register enumeration link-up dependency + +* [2] HDM Decoder Configuration + + * [0] Decoder target and granularity constraints + +* [2] Performance enumeration + + * [3] Endpoint CDAT + * [3] Switch CDAT + * [1] CDAT to Core-mm integration + + * [1] x86 + * [0] Arm64 + * [0] All other arch. + + * [0] Shared link + +* [2] Hotplug + (see CXL Window Enumeration) + + * [0] Handle Soft Reserved conflicts + +* [0] :ref:`RCH link status <rch-link-status>` +* [0] Fabrics / G-FAM (chapter 7) +* [0] Global Access Endpoint + + +RAS +--- +In many ways CXL can be seen as a standardization of what would normally +be handled by custom EDAC drivers. The open development here is +mainly caused by the enumeration corner cases above. + +* [3] Component events (OS) +* [2] Component events (FFM) +* [1] Endpoint protocol errors (OS) +* [1] Endpoint protocol errors (FFM) +* [0] Switch protocol errors (OS) +* [1] Switch protocol errors (FFM) +* [2] DPA->HPA Address translation + + * [1] XOR Interleave translation + (see CXL Window Enumeration) + +* [1] Memory Failure coordination +* [0] Scrub control +* [2] ACPI error injection EINJ + + * [0] EINJ v2 + * [X] Compliance DOE + +* [2] Native error injection +* [3] RCH error handling +* [1] VH error handling +* [0] PPR +* [0] Sparing +* [0] Device built in test + + +Mailbox commands +---------------- + +* [3] Firmware update +* [3] Health / Alerts +* [1] :ref:`Background commands <background-commands>` +* [3] Sanitization +* [3] Security commands +* [3] RAW Command Debug Passthrough +* [0] CEL-only-validation Passthrough +* [0] Switch CCI +* [3] Timestamp +* [1] PMEM labels +* [0] PMEM GPF / Dirty Shutdown +* [0] Scan Media + +PMU +--- +* [1] Type 3 PMU +* [0] Switch USP/ DSP, Root Port + +Security +-------- + +* [X] CXL Trusted Execution Environment Security Protocol (TSP) +* [X] CXL IDE (subsumed by TSP) + +Memory-pooling +-------------- + +* [1] Hotplug of LDs (via PCI hotplug) +* [0] Dynamic Capacity Device (DCD) Support + +Multi-host sharing +------------------ + +* [0] Hardware coherent shared memory +* [0] Software managed coherency shared memory + +Multi-host memory +----------------- + +* [0] Dynamic Capacity Device Support +* [0] Sharing + +Accelerator +----------- + +* [0] Accelerator memory enumeration HDM-D (CXL 1.1/2.0 Type-2) +* [0] Accelerator memory enumeration HDM-DB (CXL 3.0 Type-2) +* [0] CXL.cache 68b (CXL 2.0) +* [0] CXL.cache 256b Cache IDs (CXL 3.0) + +User Flow Support +----------------- + +* [0] HPA->DPA Address translation (need xormaps export solution) + +Details +======= + +.. _extended-linear: + +* **Extended-linear memory-side cache**: An HMAT proposal to enumerate the presence of a + memory-side cache where the cache capacity extends the SRAT address + range capacity. `See the ECN + <https://lore.kernel.org/linux-cxl/6650e4f835a0e_195e294a8@dwillia2-mobl3.amr.corp.intel.com.notmuch/>`_ + for more details: + +.. _rch-link-status: + +* **RCH Link Status**: RCH (Restricted CXL Host) topologies, end up + hiding some standard registers like PCIe Link Status / Capabilities in + the CXL RCRB (Root Complex Register Block). + +.. _background-commands: + +* **Background commands**: The CXL background command mechanism is + awkward as the single slot is monopolized potentially indefinitely by + various commands. A `cancel on conflict + <http://lore.kernel.org/r/66035c2e8ba17_770232948b@dwillia2-xfh.jf.intel.com.notmuch>`_ + facility is needed to make sure the kernel can ensure forward progress + of priority commands. diff --git a/Documentation/driver-api/cxl/memory-devices.rst b/Documentation/driver-api/cxl/memory-devices.rst index 5149ecdc53c7..d732c42526df 100644 --- a/Documentation/driver-api/cxl/memory-devices.rst +++ b/Documentation/driver-api/cxl/memory-devices.rst @@ -328,6 +328,12 @@ CXL Memory Device .. kernel-doc:: drivers/cxl/mem.c :doc: cxl mem +.. kernel-doc:: drivers/cxl/cxlmem.h + :internal: + +.. kernel-doc:: drivers/cxl/core/memdev.c + :identifiers: + CXL Port -------- .. kernel-doc:: drivers/cxl/port.c @@ -341,6 +347,15 @@ CXL Core .. kernel-doc:: drivers/cxl/cxl.h :internal: +.. kernel-doc:: drivers/cxl/core/hdm.c + :doc: cxl core hdm + +.. kernel-doc:: drivers/cxl/core/hdm.c + :identifiers: + +.. kernel-doc:: drivers/cxl/core/cdat.c + :identifiers: + .. kernel-doc:: drivers/cxl/core/port.c :doc: cxl core diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index d55384b106bd..5c7e8194bef9 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -517,6 +517,3 @@ Public Functions Provided .. kernel-doc:: arch/x86/include/asm/io.h :internal: - -.. kernel-doc:: lib/pci_iomap.c - :export: diff --git a/Documentation/driver-api/dma-buf.rst b/Documentation/driver-api/dma-buf.rst index 0c153d79ccc4..29abf1eebf9f 100644 --- a/Documentation/driver-api/dma-buf.rst +++ b/Documentation/driver-api/dma-buf.rst @@ -77,7 +77,7 @@ consider though: the usual size discover pattern size = SEEK_END(0); SEEK_SET(0). Every other llseek operation will report -EINVAL. - If llseek on dma-buf FDs isn't support the kernel will report -ESPIPE for all + If llseek on dma-buf FDs isn't supported the kernel will report -ESPIPE for all cases. Userspace can use this to detect support for discovering the dma-buf size using llseek. diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index ecf139f73da4..d491e385d61a 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -80,6 +80,10 @@ The details of these operations are: - slave_sg: DMA a list of scatter gather buffers from/to a peripheral + - peripheral_dma_vec: DMA an array of scatter gather buffers from/to a + peripheral. Similar to slave_sg, but uses an array of dma_vec + structures instead of a scatterlist. + - dma_cyclic: Perform a cyclic DMA operation from/to a peripheral till the operation is explicitly stopped. @@ -102,6 +106,11 @@ The details of these operations are: unsigned int sg_len, enum dma_data_direction direction, unsigned long flags); + struct dma_async_tx_descriptor *dmaengine_prep_peripheral_dma_vec( + struct dma_chan *chan, const struct dma_vec *vecs, + size_t nents, enum dma_data_direction direction, + unsigned long flags); + struct dma_async_tx_descriptor *dmaengine_prep_dma_cyclic( struct dma_chan *chan, dma_addr_t buf_addr, size_t buf_len, size_t period_len, enum dma_data_direction direction); diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index ceac2a300e32..3085f8b460fa 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -433,6 +433,12 @@ supported. - residue: Provides the residue bytes of the transfer for those that support residue. +- ``device_prep_peripheral_dma_vec`` + + - Similar to ``device_prep_slave_sg``, but it takes a pointer to a + array of ``dma_vec`` structures, which (in the long run) will replace + scatterlists. + - ``device_issue_pending`` - Takes the first transaction descriptor in the pending queue, @@ -544,6 +550,10 @@ dma_cookie_t - Not really relevant any more since the introduction of ``virt-dma`` that abstracts it away. +dma_vec + +- A small structure that contains a DMA address and length. + DMA_CTRL_ACK - If clear, the descriptor cannot be reused by provider until the diff --git a/Documentation/driver-api/dpll.rst b/Documentation/driver-api/dpll.rst index ea8d16600e16..e6855cd37e85 100644 --- a/Documentation/driver-api/dpll.rst +++ b/Documentation/driver-api/dpll.rst @@ -214,6 +214,27 @@ offset values are fractional with 3-digit decimal places and shell be divided with ``DPLL_PIN_PHASE_OFFSET_DIVIDER`` to get integer part and modulo divided to get fractional part. +Embedded SYNC +============= + +Device may provide ability to use Embedded SYNC feature. It allows +to embed additional SYNC signal into the base frequency of a pin - a one +special pulse of base frequency signal every time SYNC signal pulse +happens. The user can configure the frequency of Embedded SYNC. +The Embedded SYNC capability is always related to a given base frequency +and HW capabilities. The user is provided a range of Embedded SYNC +frequencies supported, depending on current base frequency configured for +the pin. + + ========================================= ================================= + ``DPLL_A_PIN_ESYNC_FREQUENCY`` current Embedded SYNC frequency + ``DPLL_A_PIN_ESYNC_FREQUENCY_SUPPORTED`` nest available Embedded SYNC + frequency ranges + ``DPLL_A_PIN_FREQUENCY_MIN`` attr minimum value of frequency + ``DPLL_A_PIN_FREQUENCY_MAX`` attr maximum value of frequency + ``DPLL_A_PIN_ESYNC_PULSE`` pulse type of Embedded SYNC + ========================================= ================================= + Configuration commands group ============================ diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst index c5f99d834ec5..d75728eb05f8 100644 --- a/Documentation/driver-api/driver-model/devres.rst +++ b/Documentation/driver-api/driver-model/devres.rst @@ -391,10 +391,9 @@ PCI devm_pci_remap_cfgspace() : ioremap PCI configuration space devm_pci_remap_cfg_resource() : ioremap PCI configuration space resource - pcim_enable_device() : after success, all PCI ops become managed + pcim_enable_device() : after success, some PCI ops become managed pcim_iomap() : do iomap() on a single BAR pcim_iomap_regions() : do request_region() and iomap() on multiple BARs - pcim_iomap_regions_request_all() : do request_region() on all and iomap() on multiple BARs pcim_iomap_table() : array of mapped addresses indexed by BAR pcim_iounmap() : do iounmap() on a single BAR pcim_iounmap_regions() : do iounmap() and release_region() on multiple BARs @@ -405,7 +404,6 @@ PHY devm_usb_get_phy() devm_usb_get_phy_by_node() devm_usb_get_phy_by_phandle() - devm_usb_put_phy() PINCTRL devm_pinctrl_get() @@ -420,6 +418,7 @@ POWER devm_reboot_mode_unregister() PWM + devm_pwmchip_alloc() devm_pwmchip_add() devm_pwm_get() devm_fwnode_pwm_get() @@ -432,6 +431,7 @@ REGULATOR devm_regulator_bulk_put() devm_regulator_get() devm_regulator_get_enable() + devm_regulator_get_enable_read_voltage() devm_regulator_get_enable_optional() devm_regulator_get_exclusive() devm_regulator_get_optional() @@ -457,12 +457,14 @@ SERDEV SLAVE DMA ENGINE devm_acpi_dma_controller_register() - devm_acpi_dma_controller_free() SPI - devm_spi_alloc_master() - devm_spi_alloc_slave() - devm_spi_register_master() + devm_spi_alloc_host() + devm_spi_alloc_target() + devm_spi_optimize_message() + devm_spi_register_controller() + devm_spi_register_host() + devm_spi_register_target() WATCHDOG devm_watchdog_register_device() diff --git a/Documentation/driver-api/driver-model/platform.rst b/Documentation/driver-api/driver-model/platform.rst index 1fe5c6c6199c..7beb8a9648c5 100644 --- a/Documentation/driver-api/driver-model/platform.rst +++ b/Documentation/driver-api/driver-model/platform.rst @@ -41,13 +41,14 @@ and shutdown notifications using the standard conventions:: struct platform_driver { int (*probe)(struct platform_device *); - int (*remove)(struct platform_device *); + void (*remove)(struct platform_device *); void (*shutdown)(struct platform_device *); int (*suspend)(struct platform_device *, pm_message_t state); - int (*suspend_late)(struct platform_device *, pm_message_t state); - int (*resume_early)(struct platform_device *); int (*resume)(struct platform_device *); struct device_driver driver; + const struct platform_device_id *id_table; + bool prevent_deferred_probe; + bool driver_managed_dma; }; Note that probe() should in general verify that the specified device hardware diff --git a/Documentation/driver-api/eisa.rst b/Documentation/driver-api/eisa.rst index 3eac11b7eb01..b33ebe1ec9ed 100644 --- a/Documentation/driver-api/eisa.rst +++ b/Documentation/driver-api/eisa.rst @@ -196,8 +196,8 @@ eisa_bus.disable_dev virtual_root.force_probe Force the probing code to probe EISA slots even when it cannot find an EISA compliant mainboard (nothing appears on slot 0). Defaults to 0 - (don't force), and set to 1 (force probing) when either - CONFIG_ALPHA_JENSEN or CONFIG_EISA_VLB_PRIMING are set. + (don't force), and set to 1 (force probing) when + CONFIG_EISA_VLB_PRIMING is set. Random notes ============ diff --git a/Documentation/driver-api/extcon.rst b/Documentation/driver-api/extcon.rst new file mode 100644 index 000000000000..d3217b9cdcd5 --- /dev/null +++ b/Documentation/driver-api/extcon.rst @@ -0,0 +1,255 @@ +======================= +Extcon Device Subsystem +======================= + +Overview +======== + +The Extcon (External Connector) subsystem provides a unified framework for +managing external connectors in Linux systems. It allows drivers to report +the state of external connectors and provides a standardized interface for +userspace to query and monitor these states. + +Extcon is particularly useful in modern devices with multiple connectivity +options, such as smartphones, tablets, and laptops. It helps manage various +types of connectors, including: + +1. USB connectors (e.g., USB-C, micro-USB) +2. Charging ports (e.g., fast charging, wireless charging) +3. Audio jacks (e.g., 3.5mm headphone jack) +4. Video outputs (e.g., HDMI, DisplayPort) +5. Docking stations + +Real-world examples: + +1. Smartphone USB-C port: + A single USB-C port on a smartphone can serve multiple functions. Extcon + can manage the different states of this port, such as: + - USB data connection + - Charging (various types like fast charging, USB Power Delivery) + - Audio output (USB-C headphones) + - Video output (USB-C to HDMI adapter) + +2. Laptop docking station: + When a laptop is connected to a docking station, multiple connections are + made simultaneously. Extcon can handle the state changes for: + - Power delivery + - External displays + - USB hub connections + - Ethernet connectivity + +3. Wireless charging pad: + Extcon can manage the state of a wireless charging connection, allowing + the system to respond appropriately when a device is placed on or removed + from the charging pad. + +4. Smart TV HDMI ports: + In a smart TV, Extcon can manage multiple HDMI ports, detecting when + devices are connected or disconnected, and potentially identifying the + type of device (e.g., gaming console, set-top box, Blu-ray player). + +The Extcon framework simplifies the development of drivers for these complex +scenarios by providing a standardized way to report and query connector +states, handle mutually exclusive connections, and manage connector +properties. This allows for more robust and flexible handling of external +connections in modern devices. + +Key Components +============== + +extcon_dev +---------- + +The core structure representing an Extcon device:: + + struct extcon_dev { + const char *name; + const unsigned int *supported_cable; + const u32 *mutually_exclusive; + + /* Internal data */ + struct device dev; + unsigned int id; + struct raw_notifier_head nh_all; + struct raw_notifier_head *nh; + struct list_head entry; + int max_supported; + spinlock_t lock; + u32 state; + + /* Sysfs related */ + struct device_type extcon_dev_type; + struct extcon_cable *cables; + struct attribute_group attr_g_muex; + struct attribute **attrs_muex; + struct device_attribute *d_attrs_muex; + }; + +Key fields: + +- ``name``: Name of the Extcon device +- ``supported_cable``: Array of supported cable types +- ``mutually_exclusive``: Array defining mutually exclusive cable types + This field is crucial for enforcing hardware constraints. It's an array of + 32-bit unsigned integers, where each element represents a set of mutually + exclusive cable types. The array should be terminated with a 0. + + For example: + + :: + + static const u32 mutually_exclusive[] = { + BIT(0) | BIT(1), /* Cable 0 and 1 are mutually exclusive */ + BIT(2) | BIT(3) | BIT(4), /* Cables 2, 3, and 4 are mutually exclusive */ + 0 /* Terminator */ + }; + + In this example, cables 0 and 1 cannot be connected simultaneously, and + cables 2, 3, and 4 are also mutually exclusive. This is useful for + scenarios like a single port that can either be USB or HDMI, but not both + at the same time. + + The Extcon core uses this information to prevent invalid combinations of + cable states, ensuring that the reported states are always consistent + with the hardware capabilities. + +- ``state``: Current state of the device (bitmap of connected cables) + + +extcon_cable +------------ + +Represents an individual cable managed by an Extcon device:: + + struct extcon_cable { + struct extcon_dev *edev; + int cable_index; + struct attribute_group attr_g; + struct device_attribute attr_name; + struct device_attribute attr_state; + struct attribute *attrs[3]; + union extcon_property_value usb_propval[EXTCON_PROP_USB_CNT]; + union extcon_property_value chg_propval[EXTCON_PROP_CHG_CNT]; + union extcon_property_value jack_propval[EXTCON_PROP_JACK_CNT]; + union extcon_property_value disp_propval[EXTCON_PROP_DISP_CNT]; + DECLARE_BITMAP(usb_bits, EXTCON_PROP_USB_CNT); + DECLARE_BITMAP(chg_bits, EXTCON_PROP_CHG_CNT); + DECLARE_BITMAP(jack_bits, EXTCON_PROP_JACK_CNT); + DECLARE_BITMAP(disp_bits, EXTCON_PROP_DISP_CNT); + }; + +Core Functions +============== + +.. kernel-doc:: drivers/extcon/extcon.c + :identifiers: extcon_get_state + +.. kernel-doc:: drivers/extcon/extcon.c + :identifiers: extcon_set_state + +.. kernel-doc:: drivers/extcon/extcon.c + :identifiers: extcon_set_state_sync + +.. kernel-doc:: drivers/extcon/extcon.c + :identifiers: extcon_get_property + + +Sysfs Interface +=============== + +Extcon devices expose the following sysfs attributes: + +- ``name``: Name of the Extcon device +- ``state``: Current state of all supported cables +- ``cable.N/name``: Name of the Nth supported cable +- ``cable.N/state``: State of the Nth supported cable + +Usage Example +------------- + +.. code-block:: c + + #include <linux/module.h> + #include <linux/platform_device.h> + #include <linux/extcon.h> + + struct my_extcon_data { + struct extcon_dev *edev; + struct device *dev; + }; + + static const unsigned int my_extcon_cable[] = { + EXTCON_USB, + EXTCON_USB_HOST, + EXTCON_NONE, + }; + + static int my_extcon_probe(struct platform_device *pdev) + { + struct my_extcon_data *data; + int ret; + + data = devm_kzalloc(&pdev->dev, sizeof(*data), GFP_KERNEL); + if (!data) + return -ENOMEM; + + data->dev = &pdev->dev; + + /* Initialize extcon device */ + data->edev = devm_extcon_dev_allocate(data->dev, my_extcon_cable); + if (IS_ERR(data->edev)) { + dev_err(data->dev, "Failed to allocate extcon device\n"); + return PTR_ERR(data->edev); + } + + /* Register extcon device */ + ret = devm_extcon_dev_register(data->dev, data->edev); + if (ret < 0) { + dev_err(data->dev, "Failed to register extcon device\n"); + return ret; + } + + platform_set_drvdata(pdev, data); + + /* Example: Set initial state */ + extcon_set_state_sync(data->edev, EXTCON_USB, true); + + dev_info(data->dev, "My extcon driver probed successfully\n"); + return 0; + } + + static int my_extcon_remove(struct platform_device *pdev) + { + struct my_extcon_data *data = platform_get_drvdata(pdev); + + /* Example: Clear state before removal */ + extcon_set_state_sync(data->edev, EXTCON_USB, false); + + dev_info(data->dev, "My extcon driver removed\n"); + return 0; + } + + static const struct of_device_id my_extcon_of_match[] = { + { .compatible = "my,extcon-device", }, + { }, + }; + MODULE_DEVICE_TABLE(of, my_extcon_of_match); + + static struct platform_driver my_extcon_driver = { + .driver = { + .name = "my-extcon-driver", + .of_match_table = my_extcon_of_match, + }, + .probe = my_extcon_probe, + .remove = my_extcon_remove, + }; + + module_platform_driver(my_extcon_driver); + +This example demonstrates: +--------------------------- + +- Defining supported cable types (USB and USB Host in this case). +- Allocating and registering an extcon device. +- Setting an initial state for a cable (USB connected in this example). +- Clearing the state when the driver is removed. diff --git a/Documentation/driver-api/firewire.rst b/Documentation/driver-api/firewire.rst index d3cfa73cbb2b..28a32410f7d2 100644 --- a/Documentation/driver-api/firewire.rst +++ b/Documentation/driver-api/firewire.rst @@ -43,6 +43,8 @@ Firewire core transaction interfaces Firewire Isochronous I/O interfaces =================================== +.. kernel-doc:: include/linux/firewire.h + :functions: fw_iso_context_schedule_flush_completions .. kernel-doc:: drivers/firewire/core-iso.c :export: diff --git a/Documentation/driver-api/fpga/fpga-bridge.rst b/Documentation/driver-api/fpga/fpga-bridge.rst index 604208534095..833f68fb0700 100644 --- a/Documentation/driver-api/fpga/fpga-bridge.rst +++ b/Documentation/driver-api/fpga/fpga-bridge.rst @@ -6,9 +6,12 @@ API to implement a new FPGA bridge * struct fpga_bridge - The FPGA Bridge structure * struct fpga_bridge_ops - Low level Bridge driver ops -* fpga_bridge_register() - Create and register a bridge +* __fpga_bridge_register() - Create and register a bridge * fpga_bridge_unregister() - Unregister a bridge +The helper macro ``fpga_bridge_register()`` automatically sets +the module that registers the FPGA bridge as the owner. + .. kernel-doc:: include/linux/fpga/fpga-bridge.h :functions: fpga_bridge @@ -16,7 +19,7 @@ API to implement a new FPGA bridge :functions: fpga_bridge_ops .. kernel-doc:: drivers/fpga/fpga-bridge.c - :functions: fpga_bridge_register + :functions: __fpga_bridge_register .. kernel-doc:: drivers/fpga/fpga-bridge.c :functions: fpga_bridge_unregister diff --git a/Documentation/driver-api/fpga/fpga-mgr.rst b/Documentation/driver-api/fpga/fpga-mgr.rst index 49c0a9512653..8d2b79f696c1 100644 --- a/Documentation/driver-api/fpga/fpga-mgr.rst +++ b/Documentation/driver-api/fpga/fpga-mgr.rst @@ -24,7 +24,8 @@ How to support a new FPGA device -------------------------------- To add another FPGA manager, write a driver that implements a set of ops. The -probe function calls fpga_mgr_register() or fpga_mgr_register_full(), such as:: +probe function calls ``fpga_mgr_register()`` or ``fpga_mgr_register_full()``, +such as:: static const struct fpga_manager_ops socfpga_fpga_ops = { .write_init = socfpga_fpga_ops_configure_init, @@ -69,10 +70,11 @@ probe function calls fpga_mgr_register() or fpga_mgr_register_full(), such as:: } Alternatively, the probe function could call one of the resource managed -register functions, devm_fpga_mgr_register() or devm_fpga_mgr_register_full(). -When these functions are used, the parameter syntax is the same, but the call -to fpga_mgr_unregister() should be removed. In the above example, the -socfpga_fpga_remove() function would not be required. +register functions, ``devm_fpga_mgr_register()`` or +``devm_fpga_mgr_register_full()``. When these functions are used, the +parameter syntax is the same, but the call to ``fpga_mgr_unregister()`` should be +removed. In the above example, the ``socfpga_fpga_remove()`` function would not be +required. The ops will implement whatever device specific register writes are needed to do the programming sequence for this particular FPGA. These ops return 0 for @@ -125,15 +127,19 @@ API for implementing a new FPGA Manager driver * struct fpga_manager - the FPGA manager struct * struct fpga_manager_ops - Low level FPGA manager driver ops * struct fpga_manager_info - Parameter structure for fpga_mgr_register_full() -* fpga_mgr_register_full() - Create and register an FPGA manager using the +* __fpga_mgr_register_full() - Create and register an FPGA manager using the fpga_mgr_info structure to provide the full flexibility of options -* fpga_mgr_register() - Create and register an FPGA manager using standard +* __fpga_mgr_register() - Create and register an FPGA manager using standard arguments -* devm_fpga_mgr_register_full() - Resource managed version of - fpga_mgr_register_full() -* devm_fpga_mgr_register() - Resource managed version of fpga_mgr_register() +* __devm_fpga_mgr_register_full() - Resource managed version of + __fpga_mgr_register_full() +* __devm_fpga_mgr_register() - Resource managed version of __fpga_mgr_register() * fpga_mgr_unregister() - Unregister an FPGA manager +Helper macros ``fpga_mgr_register_full()``, ``fpga_mgr_register()``, +``devm_fpga_mgr_register_full()``, and ``devm_fpga_mgr_register()`` are available +to ease the registration. + .. kernel-doc:: include/linux/fpga/fpga-mgr.h :functions: fpga_mgr_states @@ -147,16 +153,16 @@ API for implementing a new FPGA Manager driver :functions: fpga_manager_info .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_register_full + :functions: __fpga_mgr_register_full .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: fpga_mgr_register + :functions: __fpga_mgr_register .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: devm_fpga_mgr_register_full + :functions: __devm_fpga_mgr_register_full .. kernel-doc:: drivers/fpga/fpga-mgr.c - :functions: devm_fpga_mgr_register + :functions: __devm_fpga_mgr_register .. kernel-doc:: drivers/fpga/fpga-mgr.c :functions: fpga_mgr_unregister diff --git a/Documentation/driver-api/fpga/fpga-region.rst b/Documentation/driver-api/fpga/fpga-region.rst index dc55d60a0b4a..2d03b5fb7657 100644 --- a/Documentation/driver-api/fpga/fpga-region.rst +++ b/Documentation/driver-api/fpga/fpga-region.rst @@ -46,13 +46,16 @@ API to add a new FPGA region ---------------------------- * struct fpga_region - The FPGA region struct -* struct fpga_region_info - Parameter structure for fpga_region_register_full() -* fpga_region_register_full() - Create and register an FPGA region using the +* struct fpga_region_info - Parameter structure for __fpga_region_register_full() +* __fpga_region_register_full() - Create and register an FPGA region using the fpga_region_info structure to provide the full flexibility of options -* fpga_region_register() - Create and register an FPGA region using standard +* __fpga_region_register() - Create and register an FPGA region using standard arguments * fpga_region_unregister() - Unregister an FPGA region +Helper macros ``fpga_region_register()`` and ``fpga_region_register_full()`` +automatically set the module that registers the FPGA region as the owner. + The FPGA region's probe function will need to get a reference to the FPGA Manager it will be using to do the programming. This usually would happen during the region's probe function. @@ -82,10 +85,10 @@ following APIs to handle building or tearing down that list. :functions: fpga_region_info .. kernel-doc:: drivers/fpga/fpga-region.c - :functions: fpga_region_register_full + :functions: __fpga_region_register_full .. kernel-doc:: drivers/fpga/fpga-region.c - :functions: fpga_region_register + :functions: __fpga_region_register .. kernel-doc:: drivers/fpga/fpga-region.c :functions: fpga_region_unregister diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst index b33aa04f213f..4fd1cbd8296e 100644 --- a/Documentation/driver-api/gpio/board.rst +++ b/Documentation/driver-api/gpio/board.rst @@ -4,12 +4,6 @@ GPIO Mappings This document explains how GPIOs can be assigned to given devices and functions. -Note that it only applies to the new descriptor-based interface. For a -description of the deprecated integer-based GPIO interface please refer to -legacy.rst (actually, there is no real mapping possible with the old -interface; you just fetch an integer from somewhere and request the -corresponding GPIO). - All platforms can enable the GPIO library, but if the platform strictly requires GPIO functionality to be present, it needs to select GPIOLIB from its Kconfig. Then, how GPIOs are mapped depends on what the platform uses to diff --git a/Documentation/driver-api/gpio/consumer.rst b/Documentation/driver-api/gpio/consumer.rst index 3e588b9d678c..bb3366047fad 100644 --- a/Documentation/driver-api/gpio/consumer.rst +++ b/Documentation/driver-api/gpio/consumer.rst @@ -2,9 +2,7 @@ GPIO Descriptor Consumer Interface ================================== -This document describes the consumer interface of the GPIO framework. Note that -it describes the new descriptor-based interface. For a description of the -deprecated integer-based GPIO interface please refer to legacy.rst. +This document describes the consumer interface of the GPIO framework. Guidelines for GPIOs consumers @@ -222,9 +220,9 @@ Use the following calls to access GPIOs from an atomic context:: int gpiod_get_value(const struct gpio_desc *desc); void gpiod_set_value(struct gpio_desc *desc, int value); -The values are boolean, zero for low, nonzero for high. When reading the value -of an output pin, the value returned should be what's seen on the pin. That -won't always match the specified output value, because of issues including +The values are boolean, zero for inactive, nonzero for active. When reading the +value of an output pin, the value returned should be what's seen on the pin. +That won't always match the specified output value, because of issues including open-drain signaling and output latencies. The get/set calls do not return errors because "invalid GPIO" should have been @@ -277,11 +275,11 @@ switch their output to a high impedance value. The consumer should not need to care. (For details read about open drain in driver.rst.) With this, all the gpiod_set_(array)_value_xxx() functions interpret the -parameter "value" as "asserted" ("1") or "de-asserted" ("0"). The physical line +parameter "value" as "active" ("1") or "inactive" ("0"). The physical line level will be driven accordingly. As an example, if the active low property for a dedicated GPIO is set, and the -gpiod_set_(array)_value_xxx() passes "asserted" ("1"), the physical line level +gpiod_set_(array)_value_xxx() passes "active" ("1"), the physical line level will be driven low. To summarize:: diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst index bf6319cc531b..ae433261e11a 100644 --- a/Documentation/driver-api/gpio/driver.rst +++ b/Documentation/driver-api/gpio/driver.rst @@ -7,7 +7,7 @@ This document serves as a guide for writers of GPIO chip drivers. Each GPIO controller driver needs to include the following header, which defines the structures used to define a GPIO driver:: - #include <linux/gpio/driver.h> + #include <linux/gpio/driver.h> Internal Representation of GPIOs @@ -69,9 +69,8 @@ driver code: The code implementing a gpio_chip should support multiple instances of the controller, preferably using the driver model. That code will configure each -gpio_chip and issue gpiochip_add(), gpiochip_add_data(), or -devm_gpiochip_add_data(). Removing a GPIO controller should be rare; use -gpiochip_remove() when it is unavoidable. +gpio_chip and issue gpiochip_add_data() or devm_gpiochip_add_data(). Removing +a GPIO controller should be rare; use gpiochip_remove() when it is unavoidable. Often a gpio_chip is part of an instance-specific structure with states not exposed by the GPIO interfaces, such as addressing, power management, and more. @@ -144,7 +143,7 @@ is not open, it will present a high-impedance (tristate) to the external rail:: in ----|| |/ ||--+ in ----| | |\ - GND GND + GND GND This configuration is normally used as a way to achieve one of two things: @@ -550,10 +549,10 @@ the interrupt separately and go with it: struct my_gpio *g; struct gpio_irq_chip *girq; - ret = devm_request_threaded_irq(dev, irq, NULL, - irq_thread_fn, IRQF_ONESHOT, "my-chip", g); + ret = devm_request_threaded_irq(dev, irq, NULL, irq_thread_fn, + IRQF_ONESHOT, "my-chip", g); if (ret < 0) - return ret; + return ret; /* Get a pointer to the gpio_irq_chip */ girq = &g->gc.irq; @@ -681,12 +680,12 @@ certain operations and keep track of usage inside of the gpiolib subsystem. Input GPIOs can be used as IRQ signals. When this happens, a driver is requested to mark the GPIO as being used as an IRQ:: - int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset) + int gpiochip_lock_as_irq(struct gpio_chip *chip, unsigned int offset) This will prevent the use of non-irq related GPIO APIs until the GPIO IRQ lock is released:: - void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) + void gpiochip_unlock_as_irq(struct gpio_chip *chip, unsigned int offset) When implementing an irqchip inside a GPIO driver, these two functions should typically be called in the .startup() and .shutdown() callbacks from the @@ -708,12 +707,12 @@ When a GPIO is used as an IRQ signal, then gpiolib also needs to know if the IRQ is enabled or disabled. In order to inform gpiolib about this, the irqchip driver should call:: - void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset) + void gpiochip_disable_irq(struct gpio_chip *chip, unsigned int offset) This allows drivers to drive the GPIO as an output while the IRQ is disabled. When the IRQ is enabled again, a driver should call:: - void gpiochip_enable_irq(struct gpio_chip *chip, unsigned int offset) + void gpiochip_enable_irq(struct gpio_chip *chip, unsigned int offset) When implementing an irqchip inside a GPIO driver, these two functions should typically be called in the .irq_disable() and .irq_enable() callbacks from the @@ -763,12 +762,12 @@ Sometimes it is useful to allow a GPIO chip driver to request its own GPIO descriptors through the gpiolib API. A GPIO driver can use the following functions to request and free descriptors:: - struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc, - u16 hwnum, - const char *label, - enum gpiod_flags flags) + struct gpio_desc *gpiochip_request_own_desc(struct gpio_desc *desc, + u16 hwnum, + const char *label, + enum gpiod_flags flags) - void gpiochip_free_own_desc(struct gpio_desc *desc) + void gpiochip_free_own_desc(struct gpio_desc *desc) Descriptors requested with gpiochip_request_own_desc() must be released with gpiochip_free_own_desc(). diff --git a/Documentation/driver-api/gpio/drivers-on-gpio.rst b/Documentation/driver-api/gpio/drivers-on-gpio.rst index af632d764ac6..95572d2a94ce 100644 --- a/Documentation/driver-api/gpio/drivers-on-gpio.rst +++ b/Documentation/driver-api/gpio/drivers-on-gpio.rst @@ -27,7 +27,12 @@ hardware descriptions such as device tree or ACPI: to the lines for a more permanent solution of this type. - gpio-beeper: drivers/input/misc/gpio-beeper.c is used to provide a beep from - an external speaker connected to a GPIO line. + an external speaker connected to a GPIO line. (If the beep is controlled by + off/on, for an actual PWM waveform, see pwm-gpio below.) + +- pwm-gpio: drivers/pwm/pwm-gpio.c is used to toggle a GPIO with a high + resolution timer producing a PWM waveform on the GPIO line, as well as + Linux high resolution timers can do. - extcon-gpio: drivers/extcon/extcon-gpio.c is used when you need to read an external connector status, such as a headset line for an audio driver or an diff --git a/Documentation/driver-api/gpio/index.rst b/Documentation/driver-api/gpio/index.rst index 1d48fe248f05..34b57cee3391 100644 --- a/Documentation/driver-api/gpio/index.rst +++ b/Documentation/driver-api/gpio/index.rst @@ -13,7 +13,6 @@ Contents: consumer board drivers-on-gpio - legacy bt8xxgpio Core diff --git a/Documentation/driver-api/gpio/intro.rst b/Documentation/driver-api/gpio/intro.rst index c9c19243b97f..5936a9c57df3 100644 --- a/Documentation/driver-api/gpio/intro.rst +++ b/Documentation/driver-api/gpio/intro.rst @@ -10,18 +10,6 @@ The documents in this directory give detailed instructions on how to access GPIOs in drivers, and how to write a driver for a device that provides GPIOs itself. -Due to the history of GPIO interfaces in the kernel, there are two different -ways to obtain and use GPIOs: - - - The descriptor-based interface is the preferred way to manipulate GPIOs, - and is described by all the files in this directory excepted legacy.rst. - - The legacy integer-based interface which is considered deprecated (but still - usable for compatibility reasons) is documented in legacy.rst. - -The remainder of this document applies to the new descriptor-based interface. -legacy.rst contains the same information applied to the legacy -integer-based interface. - What is a GPIO? =============== diff --git a/Documentation/driver-api/gpio/legacy.rst b/Documentation/driver-api/gpio/legacy.rst deleted file mode 100644 index b6505914791c..000000000000 --- a/Documentation/driver-api/gpio/legacy.rst +++ /dev/null @@ -1,695 +0,0 @@ -====================== -Legacy GPIO Interfaces -====================== - -This provides an overview of GPIO access conventions on Linux. - -These calls use the gpio_* naming prefix. No other calls should use that -prefix, or the related __gpio_* prefix. - - -What is a GPIO? -=============== -A "General Purpose Input/Output" (GPIO) is a flexible software-controlled -digital signal. They are provided from many kinds of chip, and are familiar -to Linux developers working with embedded and custom hardware. Each GPIO -represents a bit connected to a particular pin, or "ball" on Ball Grid Array -(BGA) packages. Board schematics show which external hardware connects to -which GPIOs. Drivers can be written generically, so that board setup code -passes such pin configuration data to drivers. - -System-on-Chip (SOC) processors heavily rely on GPIOs. In some cases, every -non-dedicated pin can be configured as a GPIO; and most chips have at least -several dozen of them. Programmable logic devices (like FPGAs) can easily -provide GPIOs; multifunction chips like power managers, and audio codecs -often have a few such pins to help with pin scarcity on SOCs; and there are -also "GPIO Expander" chips that connect using the I2C or SPI serial busses. -Most PC southbridges have a few dozen GPIO-capable pins (with only the BIOS -firmware knowing how they're used). - -The exact capabilities of GPIOs vary between systems. Common options: - - - Output values are writable (high=1, low=0). Some chips also have - options about how that value is driven, so that for example only one - value might be driven ... supporting "wire-OR" and similar schemes - for the other value (notably, "open drain" signaling). - - - Input values are likewise readable (1, 0). Some chips support readback - of pins configured as "output", which is very useful in such "wire-OR" - cases (to support bidirectional signaling). GPIO controllers may have - input de-glitch/debounce logic, sometimes with software controls. - - - Inputs can often be used as IRQ signals, often edge triggered but - sometimes level triggered. Such IRQs may be configurable as system - wakeup events, to wake the system from a low power state. - - - Usually a GPIO will be configurable as either input or output, as needed - by different product boards; single direction ones exist too. - - - Most GPIOs can be accessed while holding spinlocks, but those accessed - through a serial bus normally can't. Some systems support both types. - -On a given board each GPIO is used for one specific purpose like monitoring -MMC/SD card insertion/removal, detecting card writeprotect status, driving -a LED, configuring a transceiver, bitbanging a serial bus, poking a hardware -watchdog, sensing a switch, and so on. - - -GPIO conventions -================ -Note that this is called a "convention" because you don't need to do it this -way, and it's no crime if you don't. There **are** cases where portability -is not the main issue; GPIOs are often used for the kind of board-specific -glue logic that may even change between board revisions, and can't ever be -used on a board that's wired differently. Only least-common-denominator -functionality can be very portable. Other features are platform-specific, -and that can be critical for glue logic. - -Plus, this doesn't require any implementation framework, just an interface. -One platform might implement it as simple inline functions accessing chip -registers; another might implement it by delegating through abstractions -used for several very different kinds of GPIO controller. (There is some -optional code supporting such an implementation strategy, described later -in this document, but drivers acting as clients to the GPIO interface must -not care how it's implemented.) - -That said, if the convention is supported on their platform, drivers should -use it when possible. Platforms must select GPIOLIB if GPIO functionality -is strictly required. Drivers that can't work without -standard GPIO calls should have Kconfig entries which depend on GPIOLIB. The -GPIO calls are available, either as "real code" or as optimized-away stubs, -when drivers use the include file: - - #include <linux/gpio.h> - -If you stick to this convention then it'll be easier for other developers to -see what your code is doing, and help maintain it. - -Note that these operations include I/O barriers on platforms which need to -use them; drivers don't need to add them explicitly. - - -Identifying GPIOs ------------------ -GPIOs are identified by unsigned integers in the range 0..MAX_INT. That -reserves "negative" numbers for other purposes like marking signals as -"not available on this board", or indicating faults. Code that doesn't -touch the underlying hardware treats these integers as opaque cookies. - -Platforms define how they use those integers, and usually #define symbols -for the GPIO lines so that board-specific setup code directly corresponds -to the relevant schematics. In contrast, drivers should only use GPIO -numbers passed to them from that setup code, using platform_data to hold -board-specific pin configuration data (along with other board specific -data they need). That avoids portability problems. - -So for example one platform uses numbers 32-159 for GPIOs; while another -uses numbers 0..63 with one set of GPIO controllers, 64-79 with another -type of GPIO controller, and on one particular board 80-95 with an FPGA. -The numbers need not be contiguous; either of those platforms could also -use numbers 2000-2063 to identify GPIOs in a bank of I2C GPIO expanders. - -If you want to initialize a structure with an invalid GPIO number, use -some negative number (perhaps "-EINVAL"); that will never be valid. To -test if such number from such a structure could reference a GPIO, you -may use this predicate: - - int gpio_is_valid(int number); - -A number that's not valid will be rejected by calls which may request -or free GPIOs (see below). Other numbers may also be rejected; for -example, a number might be valid but temporarily unused on a given board. - -Whether a platform supports multiple GPIO controllers is a platform-specific -implementation issue, as are whether that support can leave "holes" in the space -of GPIO numbers, and whether new controllers can be added at runtime. Such issues -can affect things including whether adjacent GPIO numbers are both valid. - -Using GPIOs ------------ -The first thing a system should do with a GPIO is allocate it, using -the gpio_request() call; see later. - -One of the next things to do with a GPIO, often in board setup code when -setting up a platform_device using the GPIO, is mark its direction:: - - /* set as input or output, returning 0 or negative errno */ - int gpio_direction_input(unsigned gpio); - int gpio_direction_output(unsigned gpio, int value); - -The return value is zero for success, else a negative errno. It should -be checked, since the get/set calls don't have error returns and since -misconfiguration is possible. You should normally issue these calls from -a task context. However, for spinlock-safe GPIOs it's OK to use them -before tasking is enabled, as part of early board setup. - -For output GPIOs, the value provided becomes the initial output value. -This helps avoid signal glitching during system startup. - -For compatibility with legacy interfaces to GPIOs, setting the direction -of a GPIO implicitly requests that GPIO (see below) if it has not been -requested already. That compatibility is being removed from the optional -gpiolib framework. - -Setting the direction can fail if the GPIO number is invalid, or when -that particular GPIO can't be used in that mode. It's generally a bad -idea to rely on boot firmware to have set the direction correctly, since -it probably wasn't validated to do more than boot Linux. (Similarly, -that board setup code probably needs to multiplex that pin as a GPIO, -and configure pullups/pulldowns appropriately.) - - -Spinlock-Safe GPIO access -------------------------- -Most GPIO controllers can be accessed with memory read/write instructions. -Those don't need to sleep, and can safely be done from inside hard -(nonthreaded) IRQ handlers and similar contexts. - -Use the following calls to access such GPIOs:: - - /* GPIO INPUT: return zero or nonzero */ - int gpio_get_value(unsigned gpio); - - /* GPIO OUTPUT */ - void gpio_set_value(unsigned gpio, int value); - -The values are boolean, zero for low, nonzero for high. When reading the -value of an output pin, the value returned should be what's seen on the -pin ... that won't always match the specified output value, because of -issues including open-drain signaling and output latencies. - -The get/set calls have no error returns because "invalid GPIO" should have -been reported earlier from gpio_direction_*(). However, note that not all -platforms can read the value of output pins; those that can't should always -return zero. Also, using these calls for GPIOs that can't safely be accessed -without sleeping (see below) is an error. - -Platform-specific implementations are encouraged to optimize the two -calls to access the GPIO value in cases where the GPIO number (and for -output, value) are constant. It's normal for them to need only a couple -of instructions in such cases (reading or writing a hardware register), -and not to need spinlocks. Such optimized calls can make bitbanging -applications a lot more efficient (in both space and time) than spending -dozens of instructions on subroutine calls. - - -GPIO access that may sleep --------------------------- -Some GPIO controllers must be accessed using message based busses like I2C -or SPI. Commands to read or write those GPIO values require waiting to -get to the head of a queue to transmit a command and get its response. -This requires sleeping, which can't be done from inside IRQ handlers. -To access such GPIOs, a different set of accessors is defined:: - - /* GPIO INPUT: return zero or nonzero, might sleep */ - int gpio_get_value_cansleep(unsigned gpio); - - /* GPIO OUTPUT, might sleep */ - void gpio_set_value_cansleep(unsigned gpio, int value); - -Accessing such GPIOs requires a context which may sleep, for example -a threaded IRQ handler, and those accessors must be used instead of -spinlock-safe accessors without the cansleep() name suffix. - -Other than the fact that these accessors might sleep, and will work -on GPIOs that can't be accessed from hardIRQ handlers, these calls act -the same as the spinlock-safe calls. - -**IN ADDITION** calls to setup and configure such GPIOs must be made -from contexts which may sleep, since they may need to access the GPIO -controller chip too (These setup calls are usually made from board -setup or driver probe/teardown code, so this is an easy constraint.):: - - gpio_direction_input() - gpio_direction_output() - gpio_request() - - ## gpio_request_one() - ## gpio_request_array() - ## gpio_free_array() - - gpio_free() - - -Claiming and Releasing GPIOs ----------------------------- -To help catch system configuration errors, two calls are defined:: - - /* request GPIO, returning 0 or negative errno. - * non-null labels may be useful for diagnostics. - */ - int gpio_request(unsigned gpio, const char *label); - - /* release previously-claimed GPIO */ - void gpio_free(unsigned gpio); - -Passing invalid GPIO numbers to gpio_request() will fail, as will requesting -GPIOs that have already been claimed with that call. The return value of -gpio_request() must be checked. You should normally issue these calls from -a task context. However, for spinlock-safe GPIOs it's OK to request GPIOs -before tasking is enabled, as part of early board setup. - -These calls serve two basic purposes. One is marking the signals which -are actually in use as GPIOs, for better diagnostics; systems may have -several hundred potential GPIOs, but often only a dozen are used on any -given board. Another is to catch conflicts, identifying errors when -(a) two or more drivers wrongly think they have exclusive use of that -signal, or (b) something wrongly believes it's safe to remove drivers -needed to manage a signal that's in active use. That is, requesting a -GPIO can serve as a kind of lock. - -Some platforms may also use knowledge about what GPIOs are active for -power management, such as by powering down unused chip sectors and, more -easily, gating off unused clocks. - -For GPIOs that use pins known to the pinctrl subsystem, that subsystem should -be informed of their use; a gpiolib driver's .request() operation may call -pinctrl_gpio_request(), and a gpiolib driver's .free() operation may call -pinctrl_gpio_free(). The pinctrl subsystem allows a pinctrl_gpio_request() -to succeed concurrently with a pin or pingroup being "owned" by a device for -pin multiplexing. - -Any programming of pin multiplexing hardware that is needed to route the -GPIO signal to the appropriate pin should occur within a GPIO driver's -.direction_input() or .direction_output() operations, and occur after any -setup of an output GPIO's value. This allows a glitch-free migration from a -pin's special function to GPIO. This is sometimes required when using a GPIO -to implement a workaround on signals typically driven by a non-GPIO HW block. - -Some platforms allow some or all GPIO signals to be routed to different pins. -Similarly, other aspects of the GPIO or pin may need to be configured, such as -pullup/pulldown. Platform software should arrange that any such details are -configured prior to gpio_request() being called for those GPIOs, e.g. using -the pinctrl subsystem's mapping table, so that GPIO users need not be aware -of these details. - -Also note that it's your responsibility to have stopped using a GPIO -before you free it. - -Considering in most cases GPIOs are actually configured right after they -are claimed, three additional calls are defined:: - - /* request a single GPIO, with initial configuration specified by - * 'flags', identical to gpio_request() wrt other arguments and - * return value - */ - int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); - - /* request multiple GPIOs in a single call - */ - int gpio_request_array(struct gpio *array, size_t num); - - /* release multiple GPIOs in a single call - */ - void gpio_free_array(struct gpio *array, size_t num); - -where 'flags' is currently defined to specify the following properties: - - * GPIOF_DIR_IN - to configure direction as input - * GPIOF_DIR_OUT - to configure direction as output - - * GPIOF_INIT_LOW - as output, set initial level to LOW - * GPIOF_INIT_HIGH - as output, set initial level to HIGH - -since GPIOF_INIT_* are only valid when configured as output, so group valid -combinations as: - - * GPIOF_IN - configure as input - * GPIOF_OUT_INIT_LOW - configured as output, initial level LOW - * GPIOF_OUT_INIT_HIGH - configured as output, initial level HIGH - -Further more, to ease the claim/release of multiple GPIOs, 'struct gpio' is -introduced to encapsulate all three fields as:: - - struct gpio { - unsigned gpio; - unsigned long flags; - const char *label; - }; - -A typical example of usage:: - - static struct gpio leds_gpios[] = { - { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* default to ON */ - { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* default to OFF */ - { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* default to OFF */ - { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* default to OFF */ - { ... }, - }; - - err = gpio_request_one(31, GPIOF_IN, "Reset Button"); - if (err) - ... - - err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios)); - if (err) - ... - - gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios)); - - -GPIOs mapped to IRQs --------------------- -GPIO numbers are unsigned integers; so are IRQ numbers. These make up -two logically distinct namespaces (GPIO 0 need not use IRQ 0). You can -map between them using calls like:: - - /* map GPIO numbers to IRQ numbers */ - int gpio_to_irq(unsigned gpio); - -Those return either the corresponding number in the other namespace, or -else a negative errno code if the mapping can't be done. (For example, -some GPIOs can't be used as IRQs.) It is an unchecked error to use a GPIO -number that wasn't set up as an input using gpio_direction_input(), or -to use an IRQ number that didn't originally come from gpio_to_irq(). - -These two mapping calls are expected to cost on the order of a single -addition or subtraction. They're not allowed to sleep. - -Non-error values returned from gpio_to_irq() can be passed to request_irq() -or free_irq(). They will often be stored into IRQ resources for platform -devices, by the board-specific initialization code. Note that IRQ trigger -options are part of the IRQ interface, e.g. IRQF_TRIGGER_FALLING, as are -system wakeup capabilities. - - -Emulating Open Drain Signals ----------------------------- -Sometimes shared signals need to use "open drain" signaling, where only the -low signal level is actually driven. (That term applies to CMOS transistors; -"open collector" is used for TTL.) A pullup resistor causes the high signal -level. This is sometimes called a "wire-AND"; or more practically, from the -negative logic (low=true) perspective this is a "wire-OR". - -One common example of an open drain signal is a shared active-low IRQ line. -Also, bidirectional data bus signals sometimes use open drain signals. - -Some GPIO controllers directly support open drain outputs; many don't. When -you need open drain signaling but your hardware doesn't directly support it, -there's a common idiom you can use to emulate it with any GPIO pin that can -be used as either an input or an output: - - LOW: gpio_direction_output(gpio, 0) ... this drives the signal - and overrides the pullup. - - HIGH: gpio_direction_input(gpio) ... this turns off the output, - so the pullup (or some other device) controls the signal. - -If you are "driving" the signal high but gpio_get_value(gpio) reports a low -value (after the appropriate rise time passes), you know some other component -is driving the shared signal low. That's not necessarily an error. As one -common example, that's how I2C clocks are stretched: a slave that needs a -slower clock delays the rising edge of SCK, and the I2C master adjusts its -signaling rate accordingly. - - -GPIO controllers and the pinctrl subsystem ------------------------------------------- - -A GPIO controller on a SOC might be tightly coupled with the pinctrl -subsystem, in the sense that the pins can be used by other functions -together with an optional gpio feature. We have already covered the -case where e.g. a GPIO controller need to reserve a pin or set the -direction of a pin by calling any of:: - - pinctrl_gpio_request() - pinctrl_gpio_free() - pinctrl_gpio_direction_input() - pinctrl_gpio_direction_output() - -But how does the pin control subsystem cross-correlate the GPIO -numbers (which are a global business) to a certain pin on a certain -pin controller? - -This is done by registering "ranges" of pins, which are essentially -cross-reference tables. These are described in -Documentation/driver-api/pin-control.rst - -While the pin allocation is totally managed by the pinctrl subsystem, -gpio (under gpiolib) is still maintained by gpio drivers. It may happen -that different pin ranges in a SoC is managed by different gpio drivers. - -This makes it logical to let gpio drivers announce their pin ranges to -the pin ctrl subsystem before it will call 'pinctrl_gpio_request' in order -to request the corresponding pin to be prepared by the pinctrl subsystem -before any gpio usage. - -For this, the gpio controller can register its pin range with pinctrl -subsystem. There are two ways of doing it currently: with or without DT. - -For with DT support refer to Documentation/devicetree/bindings/gpio/gpio.txt. - -For non-DT support, user can call gpiochip_add_pin_range() with appropriate -parameters to register a range of gpio pins with a pinctrl driver. For this -exact name string of pinctrl device has to be passed as one of the -argument to this routine. - - -What do these conventions omit? -=============================== -One of the biggest things these conventions omit is pin multiplexing, since -this is highly chip-specific and nonportable. One platform might not need -explicit multiplexing; another might have just two options for use of any -given pin; another might have eight options per pin; another might be able -to route a given GPIO to any one of several pins. (Yes, those examples all -come from systems that run Linux today.) - -Related to multiplexing is configuration and enabling of the pullups or -pulldowns integrated on some platforms. Not all platforms support them, -or support them in the same way; and any given board might use external -pullups (or pulldowns) so that the on-chip ones should not be used. -(When a circuit needs 5 kOhm, on-chip 100 kOhm resistors won't do.) -Likewise drive strength (2 mA vs 20 mA) and voltage (1.8V vs 3.3V) is a -platform-specific issue, as are models like (not) having a one-to-one -correspondence between configurable pins and GPIOs. - -There are other system-specific mechanisms that are not specified here, -like the aforementioned options for input de-glitching and wire-OR output. -Hardware may support reading or writing GPIOs in gangs, but that's usually -configuration dependent: for GPIOs sharing the same bank. (GPIOs are -commonly grouped in banks of 16 or 32, with a given SOC having several such -banks.) Some systems can trigger IRQs from output GPIOs, or read values -from pins not managed as GPIOs. Code relying on such mechanisms will -necessarily be nonportable. - -Dynamic definition of GPIOs is not currently standard; for example, as -a side effect of configuring an add-on board with some GPIO expanders. - - -GPIO implementor's framework (OPTIONAL) -======================================= -As noted earlier, there is an optional implementation framework making it -easier for platforms to support different kinds of GPIO controller using -the same programming interface. This framework is called "gpiolib". - -As a debugging aid, if debugfs is available a /sys/kernel/debug/gpio file -will be found there. That will list all the controllers registered through -this framework, and the state of the GPIOs currently in use. - - -Controller Drivers: gpio_chip ------------------------------ -In this framework each GPIO controller is packaged as a "struct gpio_chip" -with information common to each controller of that type: - - - methods to establish GPIO direction - - methods used to access GPIO values - - flag saying whether calls to its methods may sleep - - optional debugfs dump method (showing extra state like pullup config) - - label for diagnostics - -There is also per-instance data, which may come from device.platform_data: -the number of its first GPIO, and how many GPIOs it exposes. - -The code implementing a gpio_chip should support multiple instances of the -controller, possibly using the driver model. That code will configure each -gpio_chip and issue gpiochip_add(). Removing a GPIO controller should be -rare; use gpiochip_remove() when it is unavoidable. - -Most often a gpio_chip is part of an instance-specific structure with state -not exposed by the GPIO interfaces, such as addressing, power management, -and more. Chips such as codecs will have complex non-GPIO state. - -Any debugfs dump method should normally ignore signals which haven't been -requested as GPIOs. They can use gpiochip_is_requested(), which returns -either NULL or the label associated with that GPIO when it was requested. - - -Platform Support ----------------- -To force-enable this framework, a platform's Kconfig will "select" GPIOLIB, -else it is up to the user to configure support for GPIO. - -If neither of these options are selected, the platform does not support -GPIOs through GPIO-lib and the code cannot be enabled by the user. - -Trivial implementations of those functions can directly use framework -code, which always dispatches through the gpio_chip:: - - #define gpio_get_value __gpio_get_value - #define gpio_set_value __gpio_set_value - -Fancier implementations could instead define those as inline functions with -logic optimizing access to specific SOC-based GPIOs. For example, if the -referenced GPIO is the constant "12", getting or setting its value could -cost as little as two or three instructions, never sleeping. When such an -optimization is not possible those calls must delegate to the framework -code, costing at least a few dozen instructions. For bitbanged I/O, such -instruction savings can be significant. - -For SOCs, platform-specific code defines and registers gpio_chip instances -for each bank of on-chip GPIOs. Those GPIOs should be numbered/labeled to -match chip vendor documentation, and directly match board schematics. They -may well start at zero and go up to a platform-specific limit. Such GPIOs -are normally integrated into platform initialization to make them always be -available, from arch_initcall() or earlier; they can often serve as IRQs. - - -Board Support -------------- -For external GPIO controllers -- such as I2C or SPI expanders, ASICs, multi -function devices, FPGAs or CPLDs -- most often board-specific code handles -registering controller devices and ensures that their drivers know what GPIO -numbers to use with gpiochip_add(). Their numbers often start right after -platform-specific GPIOs. - -For example, board setup code could create structures identifying the range -of GPIOs that chip will expose, and passes them to each GPIO expander chip -using platform_data. Then the chip driver's probe() routine could pass that -data to gpiochip_add(). - -Initialization order can be important. For example, when a device relies on -an I2C-based GPIO, its probe() routine should only be called after that GPIO -becomes available. That may mean the device should not be registered until -calls for that GPIO can work. One way to address such dependencies is for -such gpio_chip controllers to provide setup() and teardown() callbacks to -board specific code; those board specific callbacks would register devices -once all the necessary resources are available, and remove them later when -the GPIO controller device becomes unavailable. - - -Sysfs Interface for Userspace (OPTIONAL) -======================================== -Platforms which use the "gpiolib" implementors framework may choose to -configure a sysfs user interface to GPIOs. This is different from the -debugfs interface, since it provides control over GPIO direction and -value instead of just showing a gpio state summary. Plus, it could be -present on production systems without debugging support. - -Given appropriate hardware documentation for the system, userspace could -know for example that GPIO #23 controls the write protect line used to -protect boot loader segments in flash memory. System upgrade procedures -may need to temporarily remove that protection, first importing a GPIO, -then changing its output state, then updating the code before re-enabling -the write protection. In normal use, GPIO #23 would never be touched, -and the kernel would have no need to know about it. - -Again depending on appropriate hardware documentation, on some systems -userspace GPIO can be used to determine system configuration data that -standard kernels won't know about. And for some tasks, simple userspace -GPIO drivers could be all that the system really needs. - -Note that standard kernel drivers exist for common "LEDs and Buttons" -GPIO tasks: "leds-gpio" and "gpio_keys", respectively. Use those -instead of talking directly to the GPIOs; they integrate with kernel -frameworks better than your userspace code could. - - -Paths in Sysfs --------------- -There are three kinds of entry in /sys/class/gpio: - - - Control interfaces used to get userspace control over GPIOs; - - - GPIOs themselves; and - - - GPIO controllers ("gpio_chip" instances). - -That's in addition to standard files including the "device" symlink. - -The control interfaces are write-only: - - /sys/class/gpio/ - - "export" ... Userspace may ask the kernel to export control of - a GPIO to userspace by writing its number to this file. - - Example: "echo 19 > export" will create a "gpio19" node - for GPIO #19, if that's not requested by kernel code. - - "unexport" ... Reverses the effect of exporting to userspace. - - Example: "echo 19 > unexport" will remove a "gpio19" - node exported using the "export" file. - -GPIO signals have paths like /sys/class/gpio/gpio42/ (for GPIO #42) -and have the following read/write attributes: - - /sys/class/gpio/gpioN/ - - "direction" ... reads as either "in" or "out". This value may - normally be written. Writing as "out" defaults to - initializing the value as low. To ensure glitch free - operation, values "low" and "high" may be written to - configure the GPIO as an output with that initial value. - - Note that this attribute *will not exist* if the kernel - doesn't support changing the direction of a GPIO, or - it was exported by kernel code that didn't explicitly - allow userspace to reconfigure this GPIO's direction. - - "value" ... reads as either 0 (low) or 1 (high). If the GPIO - is configured as an output, this value may be written; - any nonzero value is treated as high. - - If the pin can be configured as interrupt-generating interrupt - and if it has been configured to generate interrupts (see the - description of "edge"), you can poll(2) on that file and - poll(2) will return whenever the interrupt was triggered. If - you use poll(2), set the events POLLPRI. If you use select(2), - set the file descriptor in exceptfds. After poll(2) returns, - either lseek(2) to the beginning of the sysfs file and read the - new value or close the file and re-open it to read the value. - - "edge" ... reads as either "none", "rising", "falling", or - "both". Write these strings to select the signal edge(s) - that will make poll(2) on the "value" file return. - - This file exists only if the pin can be configured as an - interrupt generating input pin. - - "active_low" ... reads as either 0 (false) or 1 (true). Write - any nonzero value to invert the value attribute both - for reading and writing. Existing and subsequent - poll(2) support configuration via the edge attribute - for "rising" and "falling" edges will follow this - setting. - -GPIO controllers have paths like /sys/class/gpio/gpiochip42/ (for the -controller implementing GPIOs starting at #42) and have the following -read-only attributes: - - /sys/class/gpio/gpiochipN/ - - "base" ... same as N, the first GPIO managed by this chip - - "label" ... provided for diagnostics (not always unique) - - "ngpio" ... how many GPIOs this manges (N to N + ngpio - 1) - -Board documentation should in most cases cover what GPIOs are used for -what purposes. However, those numbers are not always stable; GPIOs on -a daughtercard might be different depending on the base board being used, -or other cards in the stack. In such cases, you may need to use the -gpiochip nodes (possibly in conjunction with schematics) to determine -the correct GPIO number to use for a given signal. - - -API Reference -============= - -The functions listed in this section are deprecated. The GPIO descriptor based -API should be used in new code. - -.. kernel-doc:: drivers/gpio/gpiolib-legacy.c - :export: diff --git a/Documentation/driver-api/iio/buffers.rst b/Documentation/driver-api/iio/buffers.rst index e83026aebe97..63f364e862d1 100644 --- a/Documentation/driver-api/iio/buffers.rst +++ b/Documentation/driver-api/iio/buffers.rst @@ -15,8 +15,8 @@ trigger source. Multiple data channels can be read at once from IIO buffer sysfs interface ========================== An IIO buffer has an associated attributes directory under -:file:`/sys/bus/iio/iio:device{X}/buffer/*`. Here are some of the existing -attributes: +:file:`/sys/bus/iio/devices/iio:device{X}/buffer/*`. Here are some of the +existing attributes: * :file:`length`, the total number of data samples (capacity) that can be stored by the buffer. @@ -28,8 +28,8 @@ IIO buffer setup The meta information associated with a channel reading placed in a buffer is called a scan element. The important bits configuring scan elements are exposed to userspace applications via the -:file:`/sys/bus/iio/iio:device{X}/scan_elements/` directory. This directory contains -attributes of the following form: +:file:`/sys/bus/iio/devices/iio:device{X}/scan_elements/` directory. This +directory contains attributes of the following form: * :file:`enable`, used for enabling a channel. If and only if its attribute is non *zero*, then a triggered capture will contain data samples for this diff --git a/Documentation/driver-api/iio/core.rst b/Documentation/driver-api/iio/core.rst index 715cf29482a1..dfe438dc91a7 100644 --- a/Documentation/driver-api/iio/core.rst +++ b/Documentation/driver-api/iio/core.rst @@ -24,7 +24,7 @@ then we will show how a device driver makes use of an IIO device. There are two ways for a user space application to interact with an IIO driver. -1. :file:`/sys/bus/iio/iio:device{X}/`, this represents a hardware sensor +1. :file:`/sys/bus/iio/devices/iio:device{X}/`, this represents a hardware sensor and groups together the data channels of the same chip. 2. :file:`/dev/iio:device{X}`, character device node interface used for buffered data transfer and for events information retrieval. @@ -51,8 +51,8 @@ IIO device sysfs interface Attributes are sysfs files used to expose chip info and also allowing applications to set various configuration parameters. For device with -index X, attributes can be found under /sys/bus/iio/iio:deviceX/ directory. -Common attributes are: +index X, attributes can be found under /sys/bus/iio/devices/iio:deviceX/ +directory. Common attributes are: * :file:`name`, description of the physical chip. * :file:`dev`, shows the major:minor pair associated with @@ -140,16 +140,16 @@ Here is how we can make use of the channel's modifiers:: This channel's definition will generate two separate sysfs files for raw data retrieval: -* :file:`/sys/bus/iio/iio:device{X}/in_intensity_ir_raw` -* :file:`/sys/bus/iio/iio:device{X}/in_intensity_both_raw` +* :file:`/sys/bus/iio/devices/iio:device{X}/in_intensity_ir_raw` +* :file:`/sys/bus/iio/devices/iio:device{X}/in_intensity_both_raw` one file for processed data: -* :file:`/sys/bus/iio/iio:device{X}/in_illuminance_input` +* :file:`/sys/bus/iio/devices/iio:device{X}/in_illuminance_input` and one shared sysfs file for sampling frequency: -* :file:`/sys/bus/iio/iio:device{X}/sampling_frequency`. +* :file:`/sys/bus/iio/devices/iio:device{X}/sampling_frequency`. Here is how we can make use of the channel's indexing:: diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index eba851605388..16e2c4ec3c01 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -9,110 +9,143 @@ of device drivers. This document is an only somewhat organized collection of some of those interfaces — it will hopefully get better over time! The available subsections can be seen below. + +General information for driver authors +====================================== + +This section contains documentation that should, at some point or other, be +of interest to most developers working on device drivers. + .. toctree:: - :caption: Table of contents - :maxdepth: 2 + :maxdepth: 1 - driver-model/index basics + driver-model/index + device_link infrastructure ioctl - early-userspace/index pm/index - clk + +Useful support libraries +======================== + +This section contains documentation that should, at some point or other, be +of interest to most developers working on device drivers. + +.. toctree:: + :maxdepth: 1 + + early-userspace/index + connector device-io + devfreq dma-buf - device_link component - message-based - infiniband - aperture - frame-buffer - regulator - reset - iio/index - input - usb/index - firewire - pci/index + io-mapping + io_ordering + uio-howto + vfio-mediated-device + vfio + vfio-pci-device-specific-driver-acceptance + +Bus-level documentation +======================= + +.. toctree:: + :maxdepth: 1 + + auxiliary_bus cxl/index - spi - i2c - ipmb - ipmi + eisa + firewire i3c/index - interconnect - devfreq - hsi - edac - scsi - libata - target - mailbox - mtdnand - miscellaneous - mei/index - mtd/index - mmc/index - nvdimm/index - w1 + isa + men-chameleon-bus + pci/index rapidio/index - s390-drivers + slimbus + usb/index + virtio/index vme + w1 + xillybus + + +Subsystem-specific APIs +======================= + +.. toctree:: + :maxdepth: 1 + 80211/index - uio-howto + acpi/index + backlight/lp855x-driver.rst + clk + console + crypto/index + dmaengine/index + dpll + edac + extcon firmware/index - pin-control + fpga/index + frame-buffer + aperture + generic-counter gpio/index + hsi + hte/index + i2c + iio/index + infiniband + input + interconnect + ipmb + ipmi + libata + mailbox md/index media/index + mei/index + memory-devices/index + message-based misc_devices + miscellaneous + mmc/index + mtd/index + mtdnand nfc/index - dmaengine/index - slimbus - soundwire/index - thermal/index - fpga/index - acpi/index - auxiliary_bus - backlight/lp855x-driver.rst - connector - console - eisa - isa - io-mapping - io_ordering - generic-counter - memory-devices/index - men-chameleon-bus ntb + nvdimm/index nvmem parport-lowlevel + phy/index + pin-control + pldmfw/index pps ptp - phy/index pwm - pldmfw/index + pwrseq + regulator + reset rfkill + s390-drivers + scsi serial/index sm501 + soundwire/index + spi surface_aggregator/index switchtec sync_file + target + tee + thermal/index tty/index - vfio-mediated-device - vfio - vfio-pci-device-specific-driver-acceptance - virtio/index + wbrf + wmi xilinx/index - xillybus zorro - hte/index - wmi - dpll - wbrf - crypto/index - tee .. only:: subproject and html diff --git a/Documentation/driver-api/infrastructure.rst b/Documentation/driver-api/infrastructure.rst index 3d52dfdfa9fd..35e36fee4238 100644 --- a/Documentation/driver-api/infrastructure.rst +++ b/Documentation/driver-api/infrastructure.rst @@ -41,6 +41,12 @@ Device Drivers Base .. kernel-doc:: drivers/base/class.c :export: +.. kernel-doc:: include/linux/device/faux.h + :internal: + +.. kernel-doc:: drivers/base/faux.c + :export: + .. kernel-doc:: drivers/base/node.c :internal: diff --git a/Documentation/driver-api/input.rst b/Documentation/driver-api/input.rst index 4bbb26ae2a89..bd7a3578ade7 100644 --- a/Documentation/driver-api/input.rst +++ b/Documentation/driver-api/input.rst @@ -40,3 +40,10 @@ Sparse keymap support .. kernel-doc:: drivers/input/sparse-keymap.c :export: +PS/2 protocol support +--------------------- +.. kernel-doc:: include/linux/libps2.h + :internal: + +.. kernel-doc:: drivers/input/serio/libps2.c + :export: diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst index e224e47b6b09..dfa021eacd63 100644 --- a/Documentation/driver-api/ipmi.rst +++ b/Documentation/driver-api/ipmi.rst @@ -540,7 +540,7 @@ at module load time (for a module) with:: alerts_broken The addresses are normal I2C addresses. The adapter is the string -name of the adapter, as shown in /sys/class/i2c-adapter/i2c-<n>/name. +name of the adapter, as shown in /sys/bus/i2c/devices/i2c-<n>/name. It is *NOT* i2c-<n> itself. Also, the comparison is done ignoring spaces, so if the name is "This is an I2C chip" you can say adapter_name=ThisisanI2cchip. This is because it's hard to pass in diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index b4920b34cebc..c290833165e6 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -81,10 +81,10 @@ restart when the system is resumed. This requires coordination between the camera sensor and the rest of the camera pipeline. Bridge drivers are responsible for this coordination, and instruct camera sensors to stop and restart streaming by calling the appropriate subdev operations -(``.s_stream()``, ``.enable_streams()`` or ``.disable_streams()``). Camera -sensor drivers shall therefore **not** keep track of the streaming state to -stop streaming in the PM suspend handler and restart it in the resume handler. -Drivers should in general not implement the system PM handlers. +(``.enable_streams()`` or ``.disable_streams()``). Camera sensor drivers shall +therefore **not** keep track of the streaming state to stop streaming in the PM +suspend handler and restart it in the resume handler. Drivers should in general +not implement the system PM handlers. Camera sensor drivers shall **not** implement the subdev ``.s_power()`` operation, as it is deprecated. While this operation is implemented in some diff --git a/Documentation/driver-api/media/drivers/ccs/ccs.rst b/Documentation/driver-api/media/drivers/ccs/ccs.rst index 776eec72bc80..5d4451339b7f 100644 --- a/Documentation/driver-api/media/drivers/ccs/ccs.rst +++ b/Documentation/driver-api/media/drivers/ccs/ccs.rst @@ -2,59 +2,16 @@ .. include:: <isonum.txt> +.. _media-ccs-driver: + MIPI CCS camera sensor driver ============================= The MIPI CCS camera sensor driver is a generic driver for `MIPI CCS <https://www.mipi.org/specifications/camera-command-set>`_ compliant -camera sensors. It exposes three sub-devices representing the pixel array, -the binner and the scaler. - -As the capabilities of individual devices vary, the driver exposes -interfaces based on the capabilities that exist in hardware. - -Pixel Array sub-device ----------------------- - -The pixel array sub-device represents the camera sensor's pixel matrix, as well -as analogue crop functionality present in many compliant devices. The analogue -crop is configured using the ``V4L2_SEL_TGT_CROP`` on the source pad (0) of the -entity. The size of the pixel matrix can be obtained by getting the -``V4L2_SEL_TGT_NATIVE_SIZE`` target. - -Binner ------- - -The binner sub-device represents the binning functionality on the sensor. For -that purpose, selection target ``V4L2_SEL_TGT_COMPOSE`` is supported on the -sink pad (0). - -Additionally, if a device has no scaler or digital crop functionality, the -source pad (1) exposes another digital crop selection rectangle that can only -crop at the end of the lines and frames. - -Scaler ------- - -The scaler sub-device represents the digital crop and scaling functionality of -the sensor. The V4L2 selection target ``V4L2_SEL_TGT_CROP`` is used to -configure the digital crop on the sink pad (0) when digital crop is supported. -Scaling is configured using selection target ``V4L2_SEL_TGT_COMPOSE`` on the -sink pad (0) as well. - -Additionally, if the scaler sub-device exists, its source pad (1) exposes -another digital crop selection rectangle that can only crop at the end of the -lines and frames. - -Digital and analogue crop -------------------------- - -Digital crop functionality is referred to as cropping that effectively works by -dropping some data on the floor. Analogue crop, on the other hand, means that -the cropped information is never retrieved. In case of camera sensors, the -analogue data is never read from the pixel matrix that are outside the -configured selection rectangle that designates crop. The difference has an -effect in device timing and likely also in power consumption. +camera sensors. + +Also see :ref:`the CCS driver UAPI documentation <media-ccs-uapi>`. CCS static data --------------- diff --git a/Documentation/driver-api/media/drivers/index.rst b/Documentation/driver-api/media/drivers/index.rst index c4123a16b5f9..7f6f3dcd5c90 100644 --- a/Documentation/driver-api/media/drivers/index.rst +++ b/Documentation/driver-api/media/drivers/index.rst @@ -26,6 +26,7 @@ Video4Linux (V4L) drivers vimc-devel zoran ccs/ccs + ipu6 Digital TV drivers diff --git a/Documentation/driver-api/media/drivers/ipu6.rst b/Documentation/driver-api/media/drivers/ipu6.rst new file mode 100644 index 000000000000..88f6498e74db --- /dev/null +++ b/Documentation/driver-api/media/drivers/ipu6.rst @@ -0,0 +1,190 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================== +Intel IPU6 Driver +================== + +Author: Bingbu Cao <bingbu.cao@intel.com> + +Overview +========= + +Intel IPU6 is the sixth generation of Intel Image Processing Unit used in some +Intel Chipsets such as Tiger Lake, Jasper Lake, Alder Lake, Raptor Lake and +Meteor Lake. IPU6 consists of two major systems: Input System (ISYS) and +Processing System (PSYS). IPU6 are visible on the PCI bus as a single device, it +can be found by ``lspci``: + +``0000:00:05.0 Multimedia controller: Intel Corporation Device xxxx (rev xx)`` + +IPU6 has a 16 MB BAR in PCI configuration Space for MMIO registers which is +visible for driver. + +Buttress +========= + +The IPU6 is connecting to the system fabric with Buttress which is enabling host +driver to control the IPU6, it also allows IPU6 access the system memory to +store and load frame pixel streams and any other metadata. + +Buttress mainly manages several system functionalities: power management, +interrupt handling, firmware authentication and global timer sync. + +ISYS and PSYS Power flow +------------------------ + +IPU6 driver initialize the ISYS and PSYS power up or down request by setting the +Buttress frequency control register for ISYS and PSYS +(``IPU6_BUTTRESS_REG_IS_FREQ_CTL`` and ``IPU6_BUTTRESS_REG_PS_FREQ_CTL``) in +function: + +.. c:function:: int ipu6_buttress_power(...) + +Buttress forwards the request to Punit, after Punit execute the power up flow, +Buttress indicates driver that ISYS or PSYS is powered up by updating the power +status registers. + +.. Note:: ISYS power up needs take place prior to PSYS power up, ISYS power down + needs take place after PSYS power down due to hardware limitation. + +Interrupt +--------- + +IPU6 interrupt can be generated as MSI or INTA, interrupt will be triggered when +ISYS, PSYS, Buttress event or error happen, driver can get the interrupt cause +by reading the interrupt status register ``BUTTRESS_REG_ISR_STATUS``, driver +clears the irq status and then calls specific ISYS or PSYS irq handler. + +.. c:function:: irqreturn_t ipu6_buttress_isr(int irq, ...) + +Security and firmware authentication +------------------------------------- + +To address the IPU6 firmware security concerns, the IPU6 firmware needs to +undergo an authentication process before it is allowed to executed on the IPU6 +internal processors. The IPU6 driver will work with Converged Security Engine +(CSE) to complete authentication process. The CSE is responsible of +authenticating the IPU6 firmware. The authenticated firmware binary is copied +into an isolated memory region. Firmware authentication process is implemented +by CSE following an IPC handshake with the IPU6 driver. There are some Buttress +registers used by the CSE and the IPU6 driver to communicate with each other via +IPC. + +.. c:function:: int ipu6_buttress_authenticate(...) + +Global timer sync +----------------- + +The IPU6 driver initiates a Hammock Harbor synchronization flow each time it +starts camera operation. The IPU6 will synchronizes an internal counter in the +Buttress with a copy of the SoC time, this counter maintains the up-to-date time +until camera operation is stopped. The IPU6 driver can use this time counter to +calibrate the timestamp based on the timestamp in response event from firmware. + +.. c:function:: int ipu6_buttress_start_tsc_sync(...) + +DMA and MMU +============ + +The IPU6 has its own scalar processor where the firmware run at and an internal +32-bit virtual address space. The IPU6 has MMU address translation hardware to +allow that scalar processors to access the internal memory and external system +memory through IPU6 virtual address. The address translation is based on two +levels of page lookup tables stored in system memory which are maintained by the +IPU6 driver. The IPU6 driver sets the level-1 page table base address to MMU +register and allows MMU to perform page table lookups. + +The IPU6 driver exports its own DMA operations. The IPU6 driver will update the +page table entries for each DMA operation and invalidate the MMU TLB after each +unmap and free. + +Firmware file format +==================== + +The IPU6 firmware is in Code Partition Directory (CPD) file format. The CPD +firmware contains a CPD header, several CPD entries and components. The CPD +component includes 3 entries - manifest, metadata and module data. Manifest and +metadata are defined by CSE and used by CSE for authentication. Module data is +specific to IPU6 which holds the binary data of firmware called package +directory. The IPU6 driver (``ipu6-cpd.c`` in particular) parses and validates +the CPD firmware file and gets the package directory binary data of the IPU6 +firmware, copies it to specific DMA buffer and sets its base address to Buttress +``FW_SOURCE_BASE`` register. Finally the CSE will do authentication for this +firmware binary. + + +Syscom interface +================ + +The IPU6 driver communicates with firmware via the Syscom ABI. Syscom is an +inter-processor communication mechanism between the IPU scalar processors and +the CPU. There are a number of resources shared between firmware and software. +A system memory region where the message queues reside, firmware can access the +memory region via the IPU MMU. The Syscom queues are FIFO fixed depth queues +with a configurable number of tokens (messages). There are also common IPU6 MMIO +registers where the queue read and write indices reside. Software and firmware +function as producer and consumer of tokens in the queues and update the write +and read indices separately when sending or receiving each message. + +The IPU6 driver must prepare and configure the number of input and output +queues, configure the count of tokens per queue and the size of per token before +initiating and starting the communication with firmware. Firmware and software +must use same configurations. The IPU6 Buttress has a number of firmware boot +parameter registers which can be used to store the address of configuration and +initialise the Syscom state, then driver can request firmware to start and run via +setting the scalar processor control status register. + +Input System +============ + +IPU6 input system consists of MIPI D-PHY and several CSI-2 receivers. It can +capture image pixel data from camera sensors or other MIPI CSI-2 output devices. + +D-PHYs and CSI-2 ports lane mapping +----------------------------------- + +The IPU6 integrates different D-PHY IPs on different SoCs, on Tiger Lake and +Alder Lake, IPU6 integrates MCD10 D-PHY, IPU6SE on Jasper Lake integrates JSL +D-PHY and IPU6EP on Meteor Lake integrates a Synopsys DWC D-PHY. There is an +adaptional layer between D-PHY and CSI-2 receiver controller which includes port +configuration, PHY wrapper or private test interfaces for D-PHY. There are 3 +D-PHY drivers ``ipu6-isys-mcd-phy.c``, ``ipu6-isys-jsl-phy.c`` and +``ipu6-isys-dwc-phy.c`` program the above 3 D-PHYs in IPU6. + +Different IPU6 versions have different D-PHY lanes mappings, On Tiger Lake, +there are 12 data lanes and 8 clock lanes, IPU6 support maximum 8 CSI-2 ports, +see the PPI mmapping in ``ipu6-isys-mcd-phy.c`` for more information. On Jasper +Lake and Alder Lake, D-PHY has 8 data lanes and 4 clock lanes, the IPU6 supports +maximum 4 CSI-2 ports. For Meteor Lake, D-PHY has 12 data lanes and 6 clock +lanes so IPU6 support maximum 6 CSI-2 ports. + +.. Note:: Each pair of CSI-2 two ports is a single unit that can share the data + lanes. For example, for CSI-2 port 0 and 1, CSI-2 port 0 support + maximum 4 data lanes, CSI-2 port 1 support maximum 2 data lanes, CSI-2 + port 0 with 2 data lanes can work together with CSI-2 port 1 with 2 + data lanes. If trying to use CSI-2 port 0 with 4 lanes, CSI-2 port 1 + will not be available as the 4 data lanes are shared by CSI-2 port 0 + and 1. The same applies to CSI ports 2/3, 4/5 and 7/8. + +ISYS firmware ABIs +------------------ + +The IPU6 firmware implements a series of ABIs for software access. In general, +software firstly prepares the stream configuration ``struct +ipu6_fw_isys_stream_cfg_data_abi`` and sends the configuration to firmware via +sending ``STREAM_OPEN`` command. Stream configuration includes input pins and +output pins, input pin ``struct ipu6_fw_isys_input_pin_info_abi`` defines the +resolution and data type of input source, output pin ``struct +ipu6_fw_isys_output_pin_info_abi`` defines the output resolution, stride and +frame format, etc. + +Once the driver gets the interrupt from firmware that indicates stream open +successfully, the driver will send the ``STREAM_START`` and ``STREAM_CAPTURE`` +command to request firmware to start capturing image frames. ``STREAM_CAPTURE`` +command queues the buffers to firmware with ``struct +ipu6_fw_isys_frame_buff_set``, software then waits for the interrupt and +response from firmware, ``PIN_DATA_READY`` means a buffer is ready on a specific +output pin and then software can return the buffer to user. + +.. Note:: See :ref:`Examples<ipu6_isys_capture_examples>` about how to do + capture by IPU6 ISYS driver. diff --git a/Documentation/driver-api/media/mc-core.rst b/Documentation/driver-api/media/mc-core.rst index 2456950ce8ff..1d010bd7ec49 100644 --- a/Documentation/driver-api/media/mc-core.rst +++ b/Documentation/driver-api/media/mc-core.rst @@ -144,7 +144,8 @@ valid values are described at :c:func:`media_create_pad_link()` and Graph traversal ^^^^^^^^^^^^^^^ -The media framework provides APIs to iterate over entities in a graph. +The media framework provides APIs to traverse media graphs, locating connected +entities and links. To iterate over all entities belonging to a media device, drivers can use the media_device_for_each_entity macro, defined in @@ -159,31 +160,6 @@ the media_device_for_each_entity macro, defined in ... } -Drivers might also need to iterate over all entities in a graph that can be -reached only through enabled links starting at a given entity. The media -framework provides a depth-first graph traversal API for that purpose. - -.. note:: - - Graphs with cycles (whether directed or undirected) are **NOT** - supported by the graph traversal API. To prevent infinite loops, the graph - traversal code limits the maximum depth to ``MEDIA_ENTITY_ENUM_MAX_DEPTH``, - currently defined as 16. - -Drivers initiate a graph traversal by calling -:c:func:`media_graph_walk_start()` - -The graph structure, provided by the caller, is initialized to start graph -traversal at the given entity. - -Drivers can then retrieve the next entity by calling -:c:func:`media_graph_walk_next()` - -When the graph traversal is complete the function will return ``NULL``. - -Graph traversal can be interrupted at any moment. No cleanup function call -is required and the graph structure can be freed normally. - Helper functions can be used to find a link between two given pads, or a pad connected to another pad through an enabled link (:c:func:`media_entity_find_link()`, :c:func:`media_pad_remote_pad_first()`, @@ -276,6 +252,45 @@ Subsystems should facilitate link validation by providing subsystem specific helper functions to provide easy access for commonly needed information, and in the end provide a way to use driver-specific callbacks. +Pipeline traversal +^^^^^^^^^^^^^^^^^^ + +Once a pipeline has been constructed with :c:func:`media_pipeline_start()`, +drivers can iterate over entities or pads in the pipeline with the +:c:macro:´media_pipeline_for_each_entity` and +:c:macro:´media_pipeline_for_each_pad` macros. Iterating over pads is +straightforward: + +.. code-block:: c + + media_pipeline_pad_iter iter; + struct media_pad *pad; + + media_pipeline_for_each_pad(pipe, &iter, pad) { + /* 'pad' will point to each pad in turn */ + ... + } + +To iterate over entities, the iterator needs to be initialized and cleaned up +as an additional steps: + +.. code-block:: c + + media_pipeline_entity_iter iter; + struct media_entity *entity; + int ret; + + ret = media_pipeline_entity_iter_init(pipe, &iter); + if (ret) + ...; + + media_pipeline_for_each_entity(pipe, &iter, entity) { + /* 'entity' will point to each entity in turn */ + ... + } + + media_pipeline_entity_iter_cleanup(&iter); + Media Controller Device Allocator API ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst index 29d66a47b56e..c71003f74b1c 100644 --- a/Documentation/driver-api/media/tx-rx.rst +++ b/Documentation/driver-api/media/tx-rx.rst @@ -49,11 +49,14 @@ Link frequency The :ref:`V4L2_CID_LINK_FREQ <v4l2-cid-link-freq>` control is used to tell the receiver the frequency of the bus (i.e. it is not the same as the symbol rate). -``.s_stream()`` callback -^^^^^^^^^^^^^^^^^^^^^^^^ +``.enable_streams()`` and ``.disable_streams()`` callbacks +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The struct struct v4l2_subdev_video_ops->s_stream() callback is used by the -receiver driver to control the transmitter driver's streaming state. +The struct v4l2_subdev_pad_ops->enable_streams() and struct +v4l2_subdev_pad_ops->disable_streams() callbacks are used by the receiver driver +to control the transmitter driver's streaming state. These callbacks may not be +called directly, but by using ``v4l2_subdev_enable_streams()`` and +``v4l2_subdev_disable_streams()``. CSI-2 transmitter drivers @@ -76,14 +79,15 @@ where * - link_freq - The value of the ``V4L2_CID_LINK_FREQ`` integer64 menu item. * - nr_of_lanes - - Number of data lanes used on the CSI-2 link. This can - be obtained from the OF endpoint configuration. + - Number of data lanes used on the CSI-2 link. * - 2 - Data is transferred on both rising and falling edge of the signal. * - bits_per_sample - Number of bits per sample. * - k - - 16 for D-PHY and 7 for C-PHY + - 16 for D-PHY and 7 for C-PHY. + +Information on whether D-PHY or C-PHY is used, and the value of ``nr_of_lanes``, can be obtained from the OF endpoint configuration. .. note:: @@ -127,7 +131,7 @@ Stopping the transmitter ^^^^^^^^^^^^^^^^^^^^^^^^ A transmitter stops sending the stream of images as a result of -calling the ``.s_stream()`` callback. Some transmitters may stop the +calling the ``.disable_streams()`` callback. Some transmitters may stop the stream at a frame boundary whereas others stop immediately, effectively leaving the current frame unfinished. The receiver driver should not make assumptions either way, but function properly in both diff --git a/Documentation/driver-api/media/v4l2-core.rst b/Documentation/driver-api/media/v4l2-core.rst index 58cba831ade5..ad987c34ad2a 100644 --- a/Documentation/driver-api/media/v4l2-core.rst +++ b/Documentation/driver-api/media/v4l2-core.rst @@ -26,3 +26,4 @@ Video4Linux devices v4l2-tuner v4l2-common v4l2-tveeprom + v4l2-jpeg diff --git a/Documentation/driver-api/media/v4l2-jpeg.rst b/Documentation/driver-api/media/v4l2-jpeg.rst new file mode 100644 index 000000000000..af3bc52f865b --- /dev/null +++ b/Documentation/driver-api/media/v4l2-jpeg.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0 + +V4L2 JPEG header related functions and data structures +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. kernel-doc:: include/media/v4l2-jpeg.h + :internal: + +.. kernel-doc:: drivers/media/v4l2-core/v4l2-jpeg.c + :export: diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index 1db2ba27c54c..13aec460e802 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -229,7 +229,7 @@ Asynchronous sub-device notifier for sub-devices ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A driver that registers an asynchronous sub-device may also register an -asynchronous notifier. This is called an asynchronous sub-device notifier andthe +asynchronous notifier. This is called an asynchronous sub-device notifier and the process is similar to that of a bridge driver apart from that the notifier is initialised using :c:func:`v4l2_async_subdev_nf_init` instead. A sub-device notifier may complete only after the V4L2 device becomes available, i.e. there's diff --git a/Documentation/driver-api/mmc/index.rst b/Documentation/driver-api/mmc/index.rst index 7339736ac774..8188863e5959 100644 --- a/Documentation/driver-api/mmc/index.rst +++ b/Documentation/driver-api/mmc/index.rst @@ -10,4 +10,5 @@ MMC/SD/SDIO card support mmc-dev-attrs mmc-dev-parts mmc-async-req + mmc-test mmc-tools diff --git a/Documentation/driver-api/mmc/mmc-test.rst b/Documentation/driver-api/mmc/mmc-test.rst new file mode 100644 index 000000000000..1fe33eb43742 --- /dev/null +++ b/Documentation/driver-api/mmc/mmc-test.rst @@ -0,0 +1,299 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================== +MMC Test Framework +======================== + +Overview +======== + +The `mmc_test` framework is designed to test the performance and reliability of host controller drivers and all devices handled by the MMC subsystem. This includes not only MMC devices but also SD cards and other devices supported by the subsystem. + +The framework provides a variety of tests to evaluate different aspects of the host controller and device interactions, such as read and write performance, data integrity, and error handling. These tests help ensure that the host controller drivers and devices operate correctly under various conditions. + +The `mmc_test` framework is particularly useful for: + +- Verifying the functionality and performance of MMC and SD host controller drivers. +- Ensuring compatibility and reliability of MMC and SD devices. +- Identifying and diagnosing issues in the MMC subsystem. + +The results of the tests are logged in the kernel log, providing detailed information about the test outcomes and any encountered issues. + +Note: whatever is on your card will be overwritten by these tests. + +Initialization +============== + +To use the ``mmc_test`` framework, follow these steps: + +1. **Enable the MMC Test Framework**: + + Ensure that the ``CONFIG_MMC_TEST`` kernel configuration option is enabled. This can be done by configuring the kernel: + + .. code-block:: none + + make menuconfig + + Navigate to: + + Device Drivers ---> + <*> MMC/SD/SDIO card support ---> + [*] MMC host test driver + + Alternatively, you can enable it directly in the kernel configuration file: + + .. code-block:: none + + echo "CONFIG_MMC_TEST=y" >> .config + + Rebuild and install the kernel if necessary. + +2. **Load the MMC Test Module**: + + If the ``mmc_test`` framework is built as a module, you need to load it using ``modprobe``: + + .. code-block:: none + + modprobe mmc_test + +Binding the MMC Card for Testing +================================ + +To enable MMC testing, you need to unbind the MMC card from the ``mmcblk`` driver and bind it to the ``mmc_test`` driver. This allows the ``mmc_test`` framework to take control of the MMC card for testing purposes. + +1. Identify the MMC card: + + .. code-block:: sh + + ls /sys/bus/mmc/devices/ + + This will list the MMC devices, such as ``mmc0:0001``. + +2. Unbind the MMC card from the ``mmcblk`` driver: + + .. code-block:: sh + + echo 'mmc0:0001' > /sys/bus/mmc/drivers/mmcblk/unbind + +3. Bind the MMC card to the ``mmc_test`` driver: + + .. code-block:: sh + + echo 'mmc0:0001' > /sys/bus/mmc/drivers/mmc_test/bind + +After binding, you should see a line in the kernel log indicating that the card has been claimed for testing: + +.. code-block:: none + + mmc_test mmc0:0001: Card claimed for testing. + + +Usage - Debugfs Entries +======================= + +Once the ``mmc_test`` framework is enabled, you can interact with the following debugfs entries located in ``/sys/kernel/debug/mmc0/mmc0:0001``: + +1. **test**: + + This file is used to run specific tests. Write the test number to this file to execute a test. + + .. code-block:: sh + + echo <test_number> > /sys/kernel/debug/mmc0/mmc0:0001/test + + The test result is indicated in the kernel log info. You can view the kernel log using the `dmesg` command or by checking the log file in `/var/log/`. + + .. code-block:: sh + + dmesg | grep mmc0 + + Example: + + To run test number 4 (Basic read with data verification): + + .. code-block:: sh + + echo 4 > /sys/kernel/debug/mmc0/mmc0:0001/test + + Check the kernel log for the result: + + .. code-block:: sh + + dmesg | grep mmc0 + +2. **testlist**: + + This file lists all available tests. You can read this file to see the list of tests and their corresponding numbers. + + .. code-block:: sh + + cat /sys/kernel/debug/mmc0/mmc0:0001/testlist + + The available tests are listed in the table below: + ++------+--------------------------------+---------------------------------------------+ +| Test | Test Name | Test Description | ++======+================================+=============================================+ +| 0 | Run all tests | Runs all available tests | ++------+--------------------------------+---------------------------------------------+ +| 1 | Basic write | Performs a basic write operation of a | +| | | single 512-Byte block to the MMC card | +| | | without data verification. | ++------+--------------------------------+---------------------------------------------+ +| 2 | Basic read | Same for read | ++------+--------------------------------+---------------------------------------------+ +| 3 | Basic write | Performs a basic write operation of a | +| | (with data verification) | single 512-Byte block to the MMC card | +| | | with data verification by reading back | +| | | the written data and comparing it. | ++------+--------------------------------+---------------------------------------------+ +| 4 | Basic read | Same for read | +| | (with data verification) | | ++------+--------------------------------+---------------------------------------------+ +| 5 | Multi-block write | Performs a multi-block write operation of | +| | | 8 blocks (each 512 bytes) to the MMC card. | ++------+--------------------------------+---------------------------------------------+ +| 6 | Multi-block read | Same for read | ++------+--------------------------------+---------------------------------------------+ +| 7 | Power of two block writes | Performs write operations with block sizes | +| | | that are powers of two, starting from 1 | +| | | byte up to 256 bytes, to the MMC card. | ++------+--------------------------------+---------------------------------------------+ +| 8 | Power of two block reads | Same for read | ++------+--------------------------------+---------------------------------------------+ +| 9 | Weird sized block writes | Performs write operations with varying | +| | | block sizes starting from 3 bytes and | +| | | increasing by 7 bytes each iteration, up | +| | | to 511 bytes, to the MMC card. | ++------+--------------------------------+---------------------------------------------+ +| 10 | Weird sized block reads | same for read | ++------+--------------------------------+---------------------------------------------+ +| 11 | Badly aligned write | Performs write operations with buffers | +| | | starting at different alignments (0 to 7 | +| | | bytes offset) to test how the MMC card | +| | | handles unaligned data transfers. | ++------+--------------------------------+---------------------------------------------+ +| 12 | Badly aligned read | same for read | ++------+--------------------------------+---------------------------------------------+ +| 13 | Badly aligned multi-block write| same for multi-write | ++------+--------------------------------+---------------------------------------------+ +| 14 | Badly aligned multi-block read | same for multi-read | ++------+--------------------------------+---------------------------------------------+ +| 15 | Proper xfer_size at write | intentionally create a broken transfer by | +| | (Start failure) | modifying the MMC request in a way that it | +| | | will not perform as expected, e.g. use | +| | | MMC_WRITE_BLOCK for a multi-block transfer | ++------+--------------------------------+---------------------------------------------+ +| 16 | Proper xfer_size at read | same for read | +| | (Start failure) | | ++------+--------------------------------+---------------------------------------------+ +| 17 | Proper xfer_size at write | same for 2 blocks | +| | (Midway failure) | | ++------+--------------------------------+---------------------------------------------+ +| 18 | Proper xfer_size at read | same for read | +| | (Midway failure) | | ++------+--------------------------------+---------------------------------------------+ +| 19 | Highmem write | use a high memory page | ++------+--------------------------------+---------------------------------------------+ +| 20 | Highmem read | same for read | ++------+--------------------------------+---------------------------------------------+ +| 21 | Multi-block highmem write | same for multi-write | ++------+--------------------------------+---------------------------------------------+ +| 22 | Multi-block highmem read | same for mult-read | ++------+--------------------------------+---------------------------------------------+ +| 23 | Best-case read performance | Performs 512K sequential read (non sg) | ++------+--------------------------------+---------------------------------------------+ +| 24 | Best-case write performance | same for write | ++------+--------------------------------+---------------------------------------------+ +| 25 | Best-case read performance | Same using sg | +| | (Into scattered pages) | | ++------+--------------------------------+---------------------------------------------+ +| 26 | Best-case write performance | same for write | +| | (From scattered pages) | | ++------+--------------------------------+---------------------------------------------+ +| 27 | Single read performance | By transfer size | ++------+--------------------------------+---------------------------------------------+ +| 28 | Single write performance | By transfer size | ++------+--------------------------------+---------------------------------------------+ +| 29 | Single trim performance | By transfer size | ++------+--------------------------------+---------------------------------------------+ +| 30 | Consecutive read performance | By transfer size | ++------+--------------------------------+---------------------------------------------+ +| 31 | Consecutive write performance | By transfer size | ++------+--------------------------------+---------------------------------------------+ +| 32 | Consecutive trim performance | By transfer size | ++------+--------------------------------+---------------------------------------------+ +| 33 | Random read performance | By transfer size | ++------+--------------------------------+---------------------------------------------+ +| 34 | Random write performance | By transfer size | ++------+--------------------------------+---------------------------------------------+ +| 35 | Large sequential read | Into scattered pages | ++------+--------------------------------+---------------------------------------------+ +| 36 | Large sequential write | From scattered pages | ++------+--------------------------------+---------------------------------------------+ +| 37 | Write performance | With blocking req 4k to 4MB | ++------+--------------------------------+---------------------------------------------+ +| 38 | Write performance | With non-blocking req 4k to 4MB | ++------+--------------------------------+---------------------------------------------+ +| 39 | Read performance | With blocking req 4k to 4MB | ++------+--------------------------------+---------------------------------------------+ +| 40 | Read performance | With non-blocking req 4k to 4MB | ++------+--------------------------------+---------------------------------------------+ +| 41 | Write performance | Blocking req 1 to 512 sg elems | ++------+--------------------------------+---------------------------------------------+ +| 42 | Write performance | Non-blocking req 1 to 512 sg elems | ++------+--------------------------------+---------------------------------------------+ +| 43 | Read performance | Blocking req 1 to 512 sg elems | ++------+--------------------------------+---------------------------------------------+ +| 44 | Read performance | Non-blocking req 1 to 512 sg elems | ++------+--------------------------------+---------------------------------------------+ +| 45 | Reset test | | ++------+--------------------------------+---------------------------------------------+ +| 46 | Commands during read | No Set Block Count (CMD23) | ++------+--------------------------------+---------------------------------------------+ +| 47 | Commands during write | No Set Block Count (CMD23) | ++------+--------------------------------+---------------------------------------------+ +| 48 | Commands during read | Use Set Block Count (CMD23) | ++------+--------------------------------+---------------------------------------------+ +| 49 | Commands during write | Use Set Block Count (CMD23) | ++------+--------------------------------+---------------------------------------------+ +| 50 | Commands during non-blocking | Read - use Set Block Count (CMD23) | ++------+--------------------------------+---------------------------------------------+ +| 51 | Commands during non-blocking | Write - use Set Block Count (CMD23) | ++------+--------------------------------+---------------------------------------------+ + +Test Results +============ + +The results of the tests are logged in the kernel log. Each test logs the start, end, and result of the test. The possible results are: + +- **OK**: The test completed successfully. +- **FAILED**: The test failed. +- **UNSUPPORTED (by host)**: The test is unsupported by the host. +- **UNSUPPORTED (by card)**: The test is unsupported by the card. +- **ERROR**: An error occurred during the test. + +Example Kernel Log Output +========================= + +When running a test, you will see log entries similar to the following in the kernel log: + +.. code-block:: none + + [ 1234.567890] mmc0: Starting tests of card mmc0:0001... + [ 1234.567891] mmc0: Test case 4. Basic read (with data verification)... + [ 1234.567892] mmc0: Result: OK + [ 1234.567893] mmc0: Tests completed. + +In this example, test case 4 (Basic read with data verification) was executed, and the result was OK. + + +Contributing +============ + +Contributions to the `mmc_test` framework are welcome. Please follow the standard Linux kernel contribution guidelines and submit patches to the appropriate maintainers. + +Contact +======= + +For more information or to report issues, please contact the MMC subsystem maintainers. diff --git a/Documentation/driver-api/mtd/nand_ecc.rst b/Documentation/driver-api/mtd/nand_ecc.rst index 74347c14a70b..a0d681f26a2e 100644 --- a/Documentation/driver-api/mtd/nand_ecc.rst +++ b/Documentation/driver-api/mtd/nand_ecc.rst @@ -462,7 +462,7 @@ statements is reduced. This is also reflected in the assembly code. Analysis 3 ========== -Very weird. Guess it has to do with caching or instruction parallellism +Very weird. Guess it has to do with caching or instruction parallelism or so. I also tried on an eeePC (Celeron, clocked at 900 Mhz). Interesting observation was that this one is only 30% slower (according to time) executing the code as my 3Ghz D920 processor. diff --git a/Documentation/driver-api/pci/pci.rst b/Documentation/driver-api/pci/pci.rst index 4843cfad4f60..59d86e827198 100644 --- a/Documentation/driver-api/pci/pci.rst +++ b/Documentation/driver-api/pci/pci.rst @@ -4,6 +4,12 @@ PCI Support Library .. kernel-doc:: drivers/pci/pci.c :export: +.. kernel-doc:: drivers/pci/iomap.c + :export: + +.. kernel-doc:: drivers/pci/devres.c + :export: + .. kernel-doc:: drivers/pci/pci-driver.c :export: @@ -40,6 +46,9 @@ PCI Support Library .. kernel-doc:: drivers/pci/pci-sysfs.c :internal: +.. kernel-doc:: drivers/pci/tph.c + :export: + PCI Hotplug Support Library --------------------------- diff --git a/Documentation/driver-api/pin-control.rst b/Documentation/driver-api/pin-control.rst index 4639912dc9cc..27ea1236307e 100644 --- a/Documentation/driver-api/pin-control.rst +++ b/Documentation/driver-api/pin-control.rst @@ -1002,7 +1002,7 @@ it even more compact which assumes you want to use pinctrl-foo and position .. code-block:: c static struct pinctrl_map mapping[] __initdata = { - PIN_MAP_MUX_GROUP("foo-i2c.o", PINCTRL_STATE_DEFAULT, + PIN_MAP_MUX_GROUP("foo-i2c.0", PINCTRL_STATE_DEFAULT, "pinctrl-foo", NULL, "i2c0"), }; diff --git a/Documentation/driver-api/pps.rst b/Documentation/driver-api/pps.rst index 78dded03e5d8..71ad04c82d6c 100644 --- a/Documentation/driver-api/pps.rst +++ b/Documentation/driver-api/pps.rst @@ -202,6 +202,46 @@ Sometimes one needs to be able not only to catch PPS signals but to produce them also. For example, running a distributed simulation, which requires computers' clock to be synchronized very tightly. +To do so the class pps-gen has been added. PPS generators can be +registered in the kernel by defining a struct pps_gen_source_info as +follows:: + + static struct pps_gen_source_info pps_gen_dummy_info = { + .name = "dummy", + .use_system_clock = true, + .get_time = pps_gen_dummy_get_time, + .enable = pps_gen_dummy_enable, + }; + +Where the use_system_clock states if the generator uses the system +clock to generate its pulses, or they are from a peripheral device +clock. Method get_time() is used to query the time stored into the +generator clock, while the method enable() is used to enable or +disable the PPS pulse generation. + +Then calling the function pps_gen_register_source() in your +initialization routine as follows creates a new generator in the +system:: + + pps_gen = pps_gen_register_source(&pps_gen_dummy_info); + +Generators SYSFS support +------------------------ + +If the SYSFS filesystem is enabled in the kernel it provides a new class:: + + $ ls /sys/class/pps-gen/ + pps-gen0/ pps-gen1/ pps-gen2/ + +Every directory is the ID of a PPS generator defined in the system and +inside of it you find several files:: + + $ ls -F /sys/class/pps-gen/pps-gen0/ + dev enable name power/ subsystem@ system time uevent + +To enable the PPS signal generation you can use the command below:: + + $ echo 1 > /sys/class/pps-gen/pps-gen0/enable Parallel port generator ------------------------ diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst index 3c28ccc4b611..b41b1c56477f 100644 --- a/Documentation/driver-api/pwm.rst +++ b/Documentation/driver-api/pwm.rst @@ -143,11 +143,12 @@ to implement the pwm_*() functions itself. This means that it's impossible to have multiple PWM drivers in the system. For this reason it's mandatory for new drivers to use the generic PWM framework. -A new PWM controller/chip can be added using pwmchip_add() and removed -again with pwmchip_remove(). pwmchip_add() takes a filled in struct -pwm_chip as argument which provides a description of the PWM chip, the -number of PWM devices provided by the chip and the chip-specific -implementation of the supported PWM operations to the framework. +A new PWM controller/chip can be allocated using pwmchip_alloc(), then +registered using pwmchip_add() and removed again with pwmchip_remove(). To undo +pwmchip_alloc() use pwmchip_put(). pwmchip_add() takes a filled in struct +pwm_chip as argument which provides a description of the PWM chip, the number +of PWM devices provided by the chip and the chip-specific implementation of the +supported PWM operations to the framework. When implementing polarity support in a PWM driver, make sure to respect the signal conventions in the PWM framework. By definition, normal polarity diff --git a/Documentation/driver-api/pwrseq.rst b/Documentation/driver-api/pwrseq.rst new file mode 100644 index 000000000000..ad18b2326b68 --- /dev/null +++ b/Documentation/driver-api/pwrseq.rst @@ -0,0 +1,95 @@ +.. SPDX-License-Identifier: GPL-2.0-only +.. Copyright 2024 Linaro Ltd. + +==================== +Power Sequencing API +==================== + +:Author: Bartosz Golaszewski + +Introduction +============ + +This framework is designed to abstract complex power-up sequences that are +shared between multiple logical devices in the Linux kernel. + +The intention is to allow consumers to obtain a power sequencing handle +exposed by the power sequence provider and delegate the actual requesting and +control of the underlying resources as well as to allow the provider to +mitigate any potential conflicts between multiple users behind the scenes. + +Glossary +-------- + +The power sequencing API uses a number of terms specific to the subsystem: + +Unit + + A unit is a discrete chunk of a power sequence. For instance one unit may + enable a set of regulators, another may enable a specific GPIO. Units can + define dependencies in the form of other units that must be enabled before + it itself can be. + +Target + + A target is a set of units (composed of the "final" unit and its + dependencies) that a consumer selects by its name when requesting a handle + to the power sequencer. Via the dependency system, multiple targets may + share the same parts of a power sequence but ignore parts that are + irrelevant. + +Descriptor + + A handle passed by the pwrseq core to every consumer that serves as the + entry point to the provider layer. It ensures coherence between different + users and keeps reference counting consistent. + +Consumer interface +================== + +The consumer API is aimed to be as simple as possible. The driver interested in +getting a descriptor from the power sequencer should call pwrseq_get() and +specify the name of the target it wants to reach in the sequence after calling +pwrseq_power_up(). The descriptor can be released by calling pwrseq_put() and +the consumer can request the powering down of its target with +pwrseq_power_off(). Note that there is no guarantee that pwrseq_power_off() +will have any effect as there may be multiple users of the underlying resources +who may keep them active. + +Provider interface +================== + +The provider API is admittedly not nearly as straightforward as the one for +consumers but it makes up for it in flexibility. + +Each provider can logically split the power-up sequence into discrete chunks +(units) and define their dependencies. They can then expose named targets that +consumers may use as the final point in the sequence that they wish to reach. + +To that end the providers fill out a set of configuration structures and +register with the pwrseq subsystem by calling pwrseq_device_register(). + +Dynamic consumer matching +------------------------- + +The main difference between pwrseq and other Linux kernel providers is the +mechanism for dynamic matching of consumers and providers. Every power sequence +provider driver must implement the `match()` callback and pass it to the pwrseq +core when registering with the subsystems. + +When a client requests a sequencer handle, the core will call this callback for +every registered provider and let it flexibly figure out whether the proposed +client device is indeed its consumer. For example: if the provider binds to the +device-tree node representing a power management unit of a chipset and the +consumer driver controls one of its modules, the provider driver may parse the +relevant regulator supply properties in device tree and see if they lead from +the PMU to the consumer. + +API reference +============= + +.. kernel-doc:: include/linux/pwrseq/provider.h + :internal: + +.. kernel-doc:: drivers/power/sequencing/core.c + :export: diff --git a/Documentation/driver-api/scsi.rst b/Documentation/driver-api/scsi.rst index 64b231d125e0..bf2be96cc2d6 100644 --- a/Documentation/driver-api/scsi.rst +++ b/Documentation/driver-api/scsi.rst @@ -20,7 +20,7 @@ Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen out of use, the SCSI command set is more widely used than ever to communicate with devices over a number of different busses. -The `SCSI protocol <http://www.t10.org/scsi-3.htm>`__ is a big-endian +The `SCSI protocol <https://www.t10.org/scsi-3.htm>`__ is a big-endian peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16 bytes long, often followed by an associated data payload. @@ -28,8 +28,7 @@ SCSI commands can be transported over just about any kind of bus, and are the default protocol for storage devices attached to USB, SATA, SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are also commonly exchanged over Infiniband, -`I2O <http://i2o.shadowconnect.com/faq.php>`__, TCP/IP -(`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel +TCP/IP (`iSCSI <https://en.wikipedia.org/wiki/ISCSI>`__), even `Parallel ports <http://cyberelk.net/tim/parport/parscsi.html>`__. Design of the Linux SCSI subsystem @@ -127,7 +126,7 @@ Manage scsi_dev_info_list, which tracks blacklisted and whitelisted devices. .. kernel-doc:: drivers/scsi/scsi_devinfo.c - :internal: + :export: drivers/scsi/scsi_ioctl.c ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -163,16 +162,15 @@ statistics and to pass information directly to the lowlevel driver. I.E. plumbing to manage /proc/scsi/\* .. kernel-doc:: drivers/scsi/scsi_proc.c - :internal: drivers/scsi/scsi_netlink.c ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Infrastructure to provide async events from transports to userspace via netlink, using a single NETLINK_SCSITRANSPORT protocol for all -transports. See `the original patch -submission <http://marc.info/?l=linux-scsi&m=115507374832500&w=2>`__ for -more details. +transports. See `the original patch submission +<https://lore.kernel.org/linux-scsi/1155070439.6275.5.camel@localhost.localdomain/>`__ +for more details. .. kernel-doc:: drivers/scsi/scsi_netlink.c :internal: @@ -194,7 +192,7 @@ else, sequentially scan LUNs up until some maximum is reached, or a LUN is seen that cannot have a device attached to it. .. kernel-doc:: drivers/scsi/scsi_scan.c - :internal: + :export: drivers/scsi/scsi_sysctl.c ~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -259,7 +257,7 @@ attributes for Serial Attached SCSI, a variant of SATA aimed at large high-end systems. The SAS transport class contains common code to deal with SAS HBAs, an -aproximated representation of SAS topologies in the driver model, and +approximated representation of SAS topologies in the driver model, and various sysfs attributes to expose these topologies and management interfaces to userspace. @@ -328,11 +326,11 @@ the ordinary is seen. To be more realistic, the simulated devices have the transport attributes of SAS disks. -For documentation see http://sg.danny.cz/sg/sdebug26.html +For documentation see http://sg.danny.cz/sg/scsi_debug.html todo ~~~~ Parallel (fast/wide/ultra) SCSI, USB, SATA, SAS, Fibre Channel, -FireWire, ATAPI devices, Infiniband, I2O, Parallel ports, +FireWire, ATAPI devices, Infiniband, Parallel ports, netlink... diff --git a/Documentation/driver-api/soundwire/stream.rst b/Documentation/driver-api/soundwire/stream.rst index b432a2de45d3..2a794484f62c 100644 --- a/Documentation/driver-api/soundwire/stream.rst +++ b/Documentation/driver-api/soundwire/stream.rst @@ -324,12 +324,12 @@ framework, this stream state is linked to .hw_params() operation. int sdw_stream_add_master(struct sdw_bus * bus, struct sdw_stream_config * stream_config, - struct sdw_ports_config * ports_config, + const struct sdw_ports_config * ports_config, struct sdw_stream_runtime * stream); int sdw_stream_add_slave(struct sdw_slave * slave, struct sdw_stream_config * stream_config, - struct sdw_ports_config * ports_config, + const struct sdw_ports_config * ports_config, struct sdw_stream_runtime * stream); diff --git a/Documentation/driver-api/thermal/sysfs-api.rst b/Documentation/driver-api/thermal/sysfs-api.rst index 6c1175c6afba..c803b89b7248 100644 --- a/Documentation/driver-api/thermal/sysfs-api.rst +++ b/Documentation/driver-api/thermal/sysfs-api.rst @@ -4,8 +4,6 @@ Generic Thermal Sysfs driver How To Written by Sujith Thomas <sujith.thomas@intel.com>, Zhang Rui <rui.zhang@intel.com> -Updated: 2 January 2008 - Copyright (c) 2008 Intel Corporation @@ -38,61 +36,57 @@ temperature) and throttle appropriate devices. :: - struct thermal_zone_device - *thermal_zone_device_register(char *type, - int trips, int mask, void *devdata, - struct thermal_zone_device_ops *ops, - const struct thermal_zone_params *tzp, - int passive_delay, int polling_delay)) + struct thermal_zone_device * + thermal_zone_device_register_with_trips(const char *type, + const struct thermal_trip *trips, + int num_trips, void *devdata, + const struct thermal_zone_device_ops *ops, + const struct thermal_zone_params *tzp, + unsigned int passive_delay, + unsigned int polling_delay) - This interface function adds a new thermal zone device (sensor) to + This interface function adds a new thermal zone device (sensor) to the /sys/class/thermal folder as `thermal_zone[0-*]`. It tries to bind all the - thermal cooling devices registered at the same time. + thermal cooling devices registered to it at the same time. type: the thermal zone type. trips: - the total number of trip points this thermal zone supports. - mask: - Bit string: If 'n'th bit is set, then trip point 'n' is writable. + the table of trip points for this thermal zone. devdata: device private data ops: thermal zone device call-backs. - .bind: - bind the thermal zone device with a thermal cooling device. - .unbind: - unbind the thermal zone device with a thermal cooling device. + .should_bind: + check whether or not a given cooling device should be bound to + a given trip point in this thermal zone. .get_temp: get the current temperature of the thermal zone. .set_trips: - set the trip points window. Whenever the current temperature - is updated, the trip points immediately below and above the - current temperature are found. - .get_mode: - get the current mode (enabled/disabled) of the thermal zone. - - - "enabled" means the kernel thermal management is - enabled. - - "disabled" will prevent kernel thermal driver action - upon trip points so that user applications can take - charge of thermal management. - .set_mode: - set the mode (enabled/disabled) of the thermal zone. - .get_trip_type: - get the type of certain trip point. - .get_trip_temp: - get the temperature above which the certain trip point - will be fired. + set the trip points window. Whenever the current temperature + is updated, the trip points immediately below and above the + current temperature are found. + .change_mode: + change the mode (enabled/disabled) of the thermal zone. + .set_trip_temp: + set the temperature of a given trip point. + .get_crit_temp: + get the critical temperature for this thermal zone. .set_emul_temp: - set the emulation temperature which helps in debugging - different threshold temperature points. + set the emulation temperature which helps in debugging + different threshold temperature points. + .get_trend: + get the trend of most recent zone temperature changes. + .hot: + hot trip point crossing handler. + .critical: + critical trip point crossing handler. tzp: thermal zone platform parameters. passive_delay: - number of milliseconds to wait between polls when - performing passive cooling. + number of milliseconds to wait between polls when performing passive + cooling. polling_delay: number of milliseconds to wait between polls when checking whether trip points have been crossed (0 for interrupt driven systems). @@ -251,56 +245,6 @@ temperature) and throttle appropriate devices. It deletes the corresponding entry from /sys/class/thermal folder and unbinds itself from all the thermal zone devices using it. -1.3 interface for binding a thermal zone device with a thermal cooling device ------------------------------------------------------------------------------ - - :: - - int thermal_zone_bind_cooling_device(struct thermal_zone_device *tz, - int trip, struct thermal_cooling_device *cdev, - unsigned long upper, unsigned long lower, unsigned int weight); - - This interface function binds a thermal cooling device to a particular trip - point of a thermal zone device. - - This function is usually called in the thermal zone device .bind callback. - - tz: - the thermal zone device - cdev: - thermal cooling device - trip: - indicates which trip point in this thermal zone the cooling device - is associated with. - upper: - the Maximum cooling state for this trip point. - THERMAL_NO_LIMIT means no upper limit, - and the cooling device can be in max_state. - lower: - the Minimum cooling state can be used for this trip point. - THERMAL_NO_LIMIT means no lower limit, - and the cooling device can be in cooling state 0. - weight: - the influence of this cooling device in this thermal - zone. See 1.4.1 below for more information. - - :: - - int thermal_zone_unbind_cooling_device(struct thermal_zone_device *tz, - int trip, struct thermal_cooling_device *cdev); - - This interface function unbinds a thermal cooling device from a particular - trip point of a thermal zone device. This function is usually called in - the thermal zone device .unbind callback. - - tz: - the thermal zone device - cdev: - thermal cooling device - trip: - indicates which trip point in this thermal zone the cooling device - is associated with. - 1.4 Thermal Zone Parameters --------------------------- @@ -371,8 +315,6 @@ Thermal cooling device sys I/F, created once it's registered:: Then next two dynamic attributes are created/removed in pairs. They represent the relationship between a thermal zone and its associated cooling device. -They are created/removed for each successful execution of -thermal_zone_bind_cooling_device/thermal_zone_unbind_cooling_device. :: @@ -464,14 +406,7 @@ are supposed to implement the callback. If they don't, the thermal framework calculated the trend by comparing the previous and the current temperature values. -4.2. get_thermal_instance -------------------------- - -This function returns the thermal_instance corresponding to a given -{thermal_zone, cooling_device, trip_point} combination. Returns NULL -if such an instance does not exist. - -4.3. thermal_cdev_update +4.2. thermal_cdev_update ------------------------ This function serves as an arbitrator to set the state of a cooling diff --git a/Documentation/driver-api/tty/console.rst b/Documentation/driver-api/tty/console.rst new file mode 100644 index 000000000000..4348e36cd33b --- /dev/null +++ b/Documentation/driver-api/tty/console.rst @@ -0,0 +1,45 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======= +Console +======= + +.. contents:: :local: + +Struct Console +============== + +.. kernel-doc:: include/linux/console.h + :identifiers: console cons_flags + +Internals +--------- + +.. kernel-doc:: include/linux/console.h + :identifiers: nbcon_state nbcon_prio nbcon_context nbcon_write_context + +Struct Consw +============ + +.. kernel-doc:: include/linux/console.h + :identifiers: consw + +Console functions +================= + +.. kernel-doc:: include/linux/console.h + :identifiers: console_srcu_read_flags console_srcu_write_flags + console_is_registered for_each_console_srcu for_each_console + +.. kernel-doc:: drivers/tty/vt/selection.c + :export: +.. kernel-doc:: drivers/tty/vt/vt.c + :export: + +Internals +--------- + +.. kernel-doc:: drivers/tty/vt/selection.c + :internal: +.. kernel-doc:: drivers/tty/vt/vt.c + :internal: diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst index b490da11f257..c1ffe3d1ec46 100644 --- a/Documentation/driver-api/tty/index.rst +++ b/Documentation/driver-api/tty/index.rst @@ -38,6 +38,7 @@ In-detail description of the named TTY structures is in separate documents: tty_buffer tty_ioctl tty_internals + console Writing TTY Driver ================== diff --git a/Documentation/driver-api/usb/callbacks.rst b/Documentation/driver-api/usb/callbacks.rst index 2b80cf54bcc3..927da49b8f00 100644 --- a/Documentation/driver-api/usb/callbacks.rst +++ b/Documentation/driver-api/usb/callbacks.rst @@ -99,8 +99,10 @@ The disconnect() callback This callback is a signal to break any connection with an interface. You are not allowed any IO to a device after returning from this callback. You also may not do any other operation that may interfere -with another driver bound the interface, eg. a power management -operation. +with another driver bound to the interface, eg. a power management +operation. Outstanding operations on the device must be completed or +aborted before this callback may return. + If you are called due to a physical disconnection, all your URBs will be killed by usbcore. Note that in this case disconnect will be called some time after the physical disconnection. Thus your driver must be prepared diff --git a/Documentation/driver-api/usb/usb.rst b/Documentation/driver-api/usb/usb.rst index fb41768696ec..89f9c37bb979 100644 --- a/Documentation/driver-api/usb/usb.rst +++ b/Documentation/driver-api/usb/usb.rst @@ -422,7 +422,7 @@ USBDEVFS_CONNECTINFO USBDEVFS_GET_SPEED Returns the speed of the device. The speed is returned as a - nummerical value in accordance with enum usb_device_speed + numerical value in accordance with enum usb_device_speed File modification time is not updated by this request. diff --git a/Documentation/driver-api/usb/writing_musb_glue_layer.rst b/Documentation/driver-api/usb/writing_musb_glue_layer.rst index 10416cc11cd5..e755c8551bba 100644 --- a/Documentation/driver-api/usb/writing_musb_glue_layer.rst +++ b/Documentation/driver-api/usb/writing_musb_glue_layer.rst @@ -717,4 +717,4 @@ https://www.maximintegrated.com/app-notes/index.mvp/id/1822 :ref:`Writing USB Device Drivers <writing-usb-driver>` Texas Instruments USB Configuration Wiki Page: -http://processors.wiki.ti.com/index.php/Usbgeneralpage +https://web.archive.org/web/20201215135015/http://processors.wiki.ti.com/index.php/Usbgeneralpage diff --git a/Documentation/driver-api/vfio.rst b/Documentation/driver-api/vfio.rst index 633d11c7fa71..2a21a42c9386 100644 --- a/Documentation/driver-api/vfio.rst +++ b/Documentation/driver-api/vfio.rst @@ -364,7 +364,7 @@ IOMMUFD IOAS/HWPT to enable userspace DMA:: MAP_PRIVATE | MAP_ANONYMOUS, 0, 0); map.iova = 0; /* 1MB starting at 0x0 from device view */ map.length = 1024 * 1024; - map.ioas_id = alloc_data.out_ioas_id;; + map.ioas_id = alloc_data.out_ioas_id; ioctl(iommufd, IOMMU_IOAS_MAP, &map); diff --git a/Documentation/driver-api/virtio/writing_virtio_drivers.rst b/Documentation/driver-api/virtio/writing_virtio_drivers.rst index e14c58796d25..e5de6f5d061a 100644 --- a/Documentation/driver-api/virtio/writing_virtio_drivers.rst +++ b/Documentation/driver-api/virtio/writing_virtio_drivers.rst @@ -97,7 +97,6 @@ like this:: static struct virtio_driver virtio_dummy_driver = { .driver.name = KBUILD_MODNAME, - .driver.owner = THIS_MODULE, .id_table = id_table, .probe = virtio_dummy_probe, .remove = virtio_dummy_remove, diff --git a/Documentation/driver-api/wbrf.rst b/Documentation/driver-api/wbrf.rst index f48bfa029813..6b18833e2e69 100644 --- a/Documentation/driver-api/wbrf.rst +++ b/Documentation/driver-api/wbrf.rst @@ -68,7 +68,7 @@ The expected flow for the consumers: can be enabled for the device. 2. Call `amd_wbrf_register_notifier` to register for notification of frequency band change(add or remove) from other producers. -3. Call the `amd_wbrf_retrieve_freq_band` initally to retrieve +3. Call the `amd_wbrf_retrieve_freq_band` initially to retrieve current active frequency bands considering some producers may broadcast such information before the consumer is up. 4. On receiving a notification for frequency band change, run diff --git a/Documentation/driver-api/wmi.rst b/Documentation/driver-api/wmi.rst index 6ca58c8249e5..4e8dbdb1fc67 100644 --- a/Documentation/driver-api/wmi.rst +++ b/Documentation/driver-api/wmi.rst @@ -7,12 +7,11 @@ WMI Driver API The WMI driver core supports a more modern bus-based interface for interacting with WMI devices, and an older GUID-based interface. The latter interface is considered to be deprecated, so new WMI drivers should generally avoid it since -it has some issues with multiple WMI devices and events sharing the same GUIDs -and/or notification IDs. The modern bus-based interface instead maps each -WMI device to a :c:type:`struct wmi_device <wmi_device>`, so it supports -WMI devices sharing GUIDs and/or notification IDs. Drivers can then register -a :c:type:`struct wmi_driver <wmi_driver>`, which will be bound to compatible -WMI devices by the driver core. +it has some issues with multiple WMI devices sharing the same GUID. +The modern bus-based interface instead maps each WMI device to a +:c:type:`struct wmi_device <wmi_device>`, so it supports WMI devices sharing the +same GUID. Drivers can then register a :c:type:`struct wmi_driver <wmi_driver>` +which will be bound to compatible WMI devices by the driver core. .. kernel-doc:: include/linux/wmi.h :internal: |