diff options
Diffstat (limited to 'Documentation/driver-api')
20 files changed, 177 insertions, 46 deletions
diff --git a/Documentation/driver-api/connector.rst b/Documentation/driver-api/connector.rst index c100c7482289..23d068191fb1 100644 --- a/Documentation/driver-api/connector.rst +++ b/Documentation/driver-api/connector.rst @@ -26,7 +26,7 @@ netlink based networking for inter-process communication in a significantly easier way:: int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *)); - void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); + void cn_netlink_send_mult(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask); void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask); struct cb_id @@ -48,7 +48,8 @@ be dereferenced to `struct cn_msg *`:: __u32 seq; __u32 ack; - __u32 len; /* Length of the following data */ + __u16 len; /* Length of the following data */ + __u16 flags; __u8 data[0]; }; diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 0e389378f71d..764963876d08 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -36,14 +36,14 @@ are starting with one. Physical addresses are of type unsigned long. This address should not be used directly. Instead, to get an address suitable for passing to the accessor functions described below, you -should call :c:func:`ioremap()`. An address suitable for accessing +should call ioremap(). An address suitable for accessing the device will be returned to you. After you've finished using the device (say, in your module's exit -routine), call :c:func:`iounmap()` in order to return the address +routine), call iounmap() in order to return the address space to the kernel. Most architectures allocate new address space each -time you call :c:func:`ioremap()`, and they can run out unless you -call :c:func:`iounmap()`. +time you call ioremap(), and they can run out unless you +call iounmap(). Accessing the device -------------------- @@ -60,8 +60,8 @@ readb_relaxed(), readw_relaxed(), readl_relaxed(), readq_relaxed(), writeb(), writew(), writel() and writeq(). Some devices (such as framebuffers) would like to use larger transfers than -8 bytes at a time. For these devices, the :c:func:`memcpy_toio()`, -:c:func:`memcpy_fromio()` and :c:func:`memset_io()` functions are +8 bytes at a time. For these devices, the memcpy_toio(), +memcpy_fromio() and memset_io() functions are provided. Do not use memset or memcpy on IO addresses; they are not guaranteed to copy data in order. @@ -135,15 +135,15 @@ Accessing Port Space Accesses to this space are provided through a set of functions which allow 8-bit, 16-bit and 32-bit accesses; also known as byte, word and -long. These functions are :c:func:`inb()`, :c:func:`inw()`, -:c:func:`inl()`, :c:func:`outb()`, :c:func:`outw()` and -:c:func:`outl()`. +long. These functions are inb(), inw(), +inl(), outb(), outw() and +outl(). Some variants are provided for these functions. Some devices require that accesses to their ports are slowed down. This functionality is provided by appending a ``_p`` to the end of the function. -There are also equivalents to memcpy. The :c:func:`ins()` and -:c:func:`outs()` functions copy bytes, words or longs to the given +There are also equivalents to memcpy. The ins() and +outs() functions copy bytes, words or longs to the given port. Public Functions Provided diff --git a/Documentation/driver-api/dmaengine/client.rst b/Documentation/driver-api/dmaengine/client.rst index 2104830a99ae..b0f32cfc38c2 100644 --- a/Documentation/driver-api/dmaengine/client.rst +++ b/Documentation/driver-api/dmaengine/client.rst @@ -5,7 +5,7 @@ DMA Engine API Guide Vinod Koul <vinod dot koul at intel.com> .. note:: For DMA Engine usage in async_tx please see: - ``Documentation/crypto/async-tx-api.txt`` + ``Documentation/crypto/async-tx-api.rst`` Below is a guide to device driver writers on how to use the Slave-DMA API of the diff --git a/Documentation/driver-api/dmaengine/provider.rst b/Documentation/driver-api/dmaengine/provider.rst index 56e5833e8a07..954422c2b704 100644 --- a/Documentation/driver-api/dmaengine/provider.rst +++ b/Documentation/driver-api/dmaengine/provider.rst @@ -95,7 +95,7 @@ accommodates that API in some cases, and made some design choices to ensure that it stayed compatible. For more information on the Async TX API, please look the relevant -documentation file in Documentation/crypto/async-tx-api.txt. +documentation file in Documentation/crypto/async-tx-api.rst. DMAEngine APIs ============== diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst index 7d5040f6a3d8..06f818b1d622 100644 --- a/Documentation/driver-api/driver-model/driver.rst +++ b/Documentation/driver-api/driver-model/driver.rst @@ -228,8 +228,6 @@ over management of devices from the bootloader, the usage of sync_state() is not restricted to that. Use it whenever it makes sense to take an action after all the consumers of a device have probed:: -:: - int (*remove) (struct device *dev); remove is called to unbind a driver from a device. This may be diff --git a/Documentation/driver-api/early-userspace/early_userspace_support.rst b/Documentation/driver-api/early-userspace/early_userspace_support.rst index 3deefb34046b..8a58c61932ff 100644 --- a/Documentation/driver-api/early-userspace/early_userspace_support.rst +++ b/Documentation/driver-api/early-userspace/early_userspace_support.rst @@ -92,7 +92,7 @@ You can obtain somewhat infrequent snapshots of klibc from https://www.kernel.org/pub/linux/libs/klibc/ For active users, you are better off using the klibc git -repository, at http://git.kernel.org/?p=libs/klibc/klibc.git +repository, at https://git.kernel.org/?p=libs/klibc/klibc.git The standalone klibc distribution currently provides three components, in addition to the klibc library: @@ -122,7 +122,7 @@ and a number of other utilities, so you can replace kinit and build custom initramfs images that meet your needs exactly. For questions and help, you can sign up for the early userspace -mailing list at http://www.zytor.com/mailman/listinfo/klibc +mailing list at https://www.zytor.com/mailman/listinfo/klibc How does it work? ================= diff --git a/Documentation/driver-api/i3c/protocol.rst b/Documentation/driver-api/i3c/protocol.rst index dae3b6d32c6b..02653defa011 100644 --- a/Documentation/driver-api/i3c/protocol.rst +++ b/Documentation/driver-api/i3c/protocol.rst @@ -14,7 +14,7 @@ collisions are prevented, ...) please have a look at the I3C specification. This document is just a brief introduction to the I3C protocol and the concepts it brings to the table. If you need more information, please refer to the MIPI I3C specification (can be downloaded here -http://resources.mipi.org/mipi-i3c-v1-download). +https://resources.mipi.org/mipi-i3c-v1-download). Introduction ============ diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 6567187e7687..3eb0085d5e42 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -48,6 +48,7 @@ available subsections can be seen below. scsi libata target + mailbox mtdnand miscellaneous mei/index diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst index 5ef1047e2e66..292f587fccdd 100644 --- a/Documentation/driver-api/ipmi.rst +++ b/Documentation/driver-api/ipmi.rst @@ -18,7 +18,7 @@ management software that can use the IPMI system. This document describes how to use the IPMI driver for Linux. If you are not familiar with IPMI itself, see the web site at -http://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big +https://www.intel.com/design/servers/ipmi/index.htm. IPMI is a big subject and I can't cover it all here! Configuration diff --git a/Documentation/driver-api/mailbox.rst b/Documentation/driver-api/mailbox.rst new file mode 100644 index 000000000000..0ed95009cc30 --- /dev/null +++ b/Documentation/driver-api/mailbox.rst @@ -0,0 +1,129 @@ +============================ +The Common Mailbox Framework +============================ + +:Author: Jassi Brar <jaswinder.singh@linaro.org> + +This document aims to help developers write client and controller +drivers for the API. But before we start, let us note that the +client (especially) and controller drivers are likely going to be +very platform specific because the remote firmware is likely to be +proprietary and implement non-standard protocol. So even if two +platforms employ, say, PL320 controller, the client drivers can't +be shared across them. Even the PL320 driver might need to accommodate +some platform specific quirks. So the API is meant mainly to avoid +similar copies of code written for each platform. Having said that, +nothing prevents the remote f/w to also be Linux based and use the +same api there. However none of that helps us locally because we only +ever deal at client's protocol level. + +Some of the choices made during implementation are the result of this +peculiarity of this "common" framework. + + + +Controller Driver (See include/linux/mailbox_controller.h) +========================================================== + + +Allocate mbox_controller and the array of mbox_chan. +Populate mbox_chan_ops, except peek_data() all are mandatory. +The controller driver might know a message has been consumed +by the remote by getting an IRQ or polling some hardware flag +or it can never know (the client knows by way of the protocol). +The method in order of preference is IRQ -> Poll -> None, which +the controller driver should set via 'txdone_irq' or 'txdone_poll' +or neither. + + +Client Driver (See include/linux/mailbox_client.h) +================================================== + + +The client might want to operate in blocking mode (synchronously +send a message through before returning) or non-blocking/async mode (submit +a message and a callback function to the API and return immediately). + +:: + + struct demo_client { + struct mbox_client cl; + struct mbox_chan *mbox; + struct completion c; + bool async; + /* ... */ + }; + + /* + * This is the handler for data received from remote. The behaviour is purely + * dependent upon the protocol. This is just an example. + */ + static void message_from_remote(struct mbox_client *cl, void *mssg) + { + struct demo_client *dc = container_of(cl, struct demo_client, cl); + if (dc->async) { + if (is_an_ack(mssg)) { + /* An ACK to our last sample sent */ + return; /* Or do something else here */ + } else { /* A new message from remote */ + queue_req(mssg); + } + } else { + /* Remote f/w sends only ACK packets on this channel */ + return; + } + } + + static void sample_sent(struct mbox_client *cl, void *mssg, int r) + { + struct demo_client *dc = container_of(cl, struct demo_client, cl); + complete(&dc->c); + } + + static void client_demo(struct platform_device *pdev) + { + struct demo_client *dc_sync, *dc_async; + /* The controller already knows async_pkt and sync_pkt */ + struct async_pkt ap; + struct sync_pkt sp; + + dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL); + dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL); + + /* Populate non-blocking mode client */ + dc_async->cl.dev = &pdev->dev; + dc_async->cl.rx_callback = message_from_remote; + dc_async->cl.tx_done = sample_sent; + dc_async->cl.tx_block = false; + dc_async->cl.tx_tout = 0; /* doesn't matter here */ + dc_async->cl.knows_txdone = false; /* depending upon protocol */ + dc_async->async = true; + init_completion(&dc_async->c); + + /* Populate blocking mode client */ + dc_sync->cl.dev = &pdev->dev; + dc_sync->cl.rx_callback = message_from_remote; + dc_sync->cl.tx_done = NULL; /* operate in blocking mode */ + dc_sync->cl.tx_block = true; + dc_sync->cl.tx_tout = 500; /* by half a second */ + dc_sync->cl.knows_txdone = false; /* depending upon protocol */ + dc_sync->async = false; + + /* ASync mailbox is listed second in 'mboxes' property */ + dc_async->mbox = mbox_request_channel(&dc_async->cl, 1); + /* Populate data packet */ + /* ap.xxx = 123; etc */ + /* Send async message to remote */ + mbox_send_message(dc_async->mbox, &ap); + + /* Sync mailbox is listed first in 'mboxes' property */ + dc_sync->mbox = mbox_request_channel(&dc_sync->cl, 0); + /* Populate data packet */ + /* sp.abc = 123; etc */ + /* Send message to remote in blocking mode */ + mbox_send_message(dc_sync->mbox, &sp); + /* At this point 'sp' has been sent */ + + /* Now wait for async chan to be done */ + wait_for_completion(&dc_async->c); + } diff --git a/Documentation/driver-api/memory-devices/ti-gpmc.rst b/Documentation/driver-api/memory-devices/ti-gpmc.rst index 33efcb81f080..b1bb86871ad7 100644 --- a/Documentation/driver-api/memory-devices/ti-gpmc.rst +++ b/Documentation/driver-api/memory-devices/ti-gpmc.rst @@ -14,7 +14,7 @@ memory devices like * Pseudo-SRAM devices GPMC is found on Texas Instruments SoC's (OMAP based) -IP details: http://www.ti.com/lit/pdf/spruh73 section 7.1 +IP details: https://www.ti.com/lit/pdf/spruh73 section 7.1 GPMC generic timing calculation: diff --git a/Documentation/driver-api/mmc/mmc-tools.rst b/Documentation/driver-api/mmc/mmc-tools.rst index 54406093768b..a231e9644351 100644 --- a/Documentation/driver-api/mmc/mmc-tools.rst +++ b/Documentation/driver-api/mmc/mmc-tools.rst @@ -5,7 +5,7 @@ MMC tools introduction There is one MMC test tools called mmc-utils, which is maintained by Chris Ball, you can find it at the below public git repository: - http://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ + https://git.kernel.org/cgit/linux/kernel/git/cjb/mmc-utils.git/ Functions ========= diff --git a/Documentation/driver-api/ntb.rst b/Documentation/driver-api/ntb.rst index 87d1372da879..11577c2105c5 100644 --- a/Documentation/driver-api/ntb.rst +++ b/Documentation/driver-api/ntb.rst @@ -9,7 +9,7 @@ registers and memory translation windows, as well as non common features like scratchpad and message registers. Scratchpad registers are read-and-writable registers that are accessible from either side of the device, so that peers can exchange a small amount of information at a fixed address. Message registers can -be utilized for the same purpose. Additionally they are provided with with +be utilized for the same purpose. Additionally they are provided with special status bits to make sure the information isn't rewritten by another peer. Doorbell registers provide a way for peers to send interrupt events. Memory windows allow translated read and write access to the peer memory. diff --git a/Documentation/driver-api/nvdimm/nvdimm.rst b/Documentation/driver-api/nvdimm/nvdimm.rst index 79c0fd39f2af..ef6d59e0978e 100644 --- a/Documentation/driver-api/nvdimm/nvdimm.rst +++ b/Documentation/driver-api/nvdimm/nvdimm.rst @@ -73,7 +73,7 @@ DAX: process address space. DSM: - Device Specific Method: ACPI method to to control specific + Device Specific Method: ACPI method to control specific device - in this case the firmware. DCR: @@ -113,13 +113,13 @@ Supporting Documents -------------------- ACPI 6: - http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf + https://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf NVDIMM Namespace: - http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf + https://pmem.io/documents/NVDIMM_Namespace_Spec.pdf DSM Interface Example: - http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf + https://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf Driver Writer's Guide: - http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf + https://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf Git Trees --------- @@ -778,7 +778,7 @@ Why the Term "namespace"? 2. The term originated to describe the sub-devices that can be created within a NVME controller (see the nvme specification: - http://www.nvmexpress.org/specifications/), and NFIT namespaces are + https://www.nvmexpress.org/specifications/), and NFIT namespaces are meant to parallel the capabilities and configurability of NVME-namespaces. @@ -786,7 +786,7 @@ Why the Term "namespace"? LIBNVDIMM/LIBNDCTL: Block Translation Table "btt" ------------------------------------------------- -A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked +A BTT (design document: https://pmem.io/2014/09/23/btt.html) is a stacked block device driver that fronts either the whole block device or a partition of a block device emitted by either a PMEM or BLK NAMESPACE. diff --git a/Documentation/driver-api/nvdimm/security.rst b/Documentation/driver-api/nvdimm/security.rst index ad9dea099b34..7aab71524116 100644 --- a/Documentation/driver-api/nvdimm/security.rst +++ b/Documentation/driver-api/nvdimm/security.rst @@ -138,6 +138,6 @@ another encrypted-key. This command is only available when the master security is enabled, indicated by the extended security status. -[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf +[1]: https://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf diff --git a/Documentation/driver-api/rapidio/rapidio.rst b/Documentation/driver-api/rapidio/rapidio.rst index fb8942d3ba85..74c552ad3eb8 100644 --- a/Documentation/driver-api/rapidio/rapidio.rst +++ b/Documentation/driver-api/rapidio/rapidio.rst @@ -356,7 +356,7 @@ NOTE: http://www.rapidio.org/education/technology_comparisons/ [3] RapidIO support for Linux. - http://lwn.net/Articles/139118/ + https://lwn.net/Articles/139118/ [4] Matt Porter. RapidIO for Linux. Ottawa Linux Symposium, 2005 - http://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf + https://www.kernel.org/doc/ols/2005/ols2005v2-pages-43-56.pdf diff --git a/Documentation/driver-api/thermal/cpu-idle-cooling.rst b/Documentation/driver-api/thermal/cpu-idle-cooling.rst index b9f34ceb2a38..c2a7ca676853 100644 --- a/Documentation/driver-api/thermal/cpu-idle-cooling.rst +++ b/Documentation/driver-api/thermal/cpu-idle-cooling.rst @@ -1,3 +1,5 @@ +.. SPDX-License-Identifier: GPL-2.0 + ================ CPU Idle Cooling ================ @@ -48,7 +50,7 @@ idle state target residency, we lead to dropping the static and the dynamic leakage for this period (modulo the energy needed to enter this state). So the sustainable power with idle cycles has a linear relation with the OPP’s sustainable power and can be computed with a -coefficient similar to: +coefficient similar to:: Power(IdleCycle) = Coef x Power(OPP) @@ -139,7 +141,7 @@ Power considerations -------------------- When we reach the thermal trip point, we have to sustain a specified -power for a specific temperature but at this time we consume: +power for a specific temperature but at this time we consume:: Power = Capacitance x Voltage^2 x Frequency x Utilisation @@ -148,7 +150,7 @@ wrong in the system setup). The ‘Capacitance’ and ‘Utilisation’ are a fixed value, ‘Voltage’ and the ‘Frequency’ are fixed artificially because we don’t want to change the OPP. We can group the ‘Capacitance’ and the ‘Utilisation’ into a single term which is the -‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have: +‘Dynamic Power Coefficient (Cdyn)’ Simplifying the above, we have:: Pdyn = Cdyn x Voltage^2 x Frequency @@ -157,7 +159,7 @@ in order to target the sustainable power defined in the device tree. So with the idle injection mechanism, we want an average power (Ptarget) resulting in an amount of time running at full power on a specific OPP and idle another amount of time. That could be put in a -equation: +equation:: P(opp)target = ((Trunning x (P(opp)running) + (Tidle x P(opp)idle)) / (Trunning + Tidle) @@ -168,7 +170,7 @@ equation: At this point if we know the running period for the CPU, that gives us the idle injection we need. Alternatively if we have the idle -injection duration, we can compute the running duration with: +injection duration, we can compute the running duration with:: Trunning = Tidle / ((P(opp)running / P(opp)target) - 1) @@ -191,7 +193,7 @@ However, in this demonstration we ignore three aspects: target residency, otherwise we end up consuming more energy and potentially invert the mitigation effect -So the final equation is: +So the final equation is:: Trunning = (Tidle - Twakeup ) x (((P(opp)dyn + P(opp)static ) - P(opp)target) / P(opp)target ) diff --git a/Documentation/driver-api/thermal/nouveau_thermal.rst b/Documentation/driver-api/thermal/nouveau_thermal.rst index 37255fd6735d..79ece266cf6d 100644 --- a/Documentation/driver-api/thermal/nouveau_thermal.rst +++ b/Documentation/driver-api/thermal/nouveau_thermal.rst @@ -93,4 +93,4 @@ Thermal management on Nouveau is new and may not work on all cards. If you have inquiries, please ping mupuf on IRC (#nouveau, freenode). Bug reports should be filled on Freedesktop's bug tracker. Please follow -http://nouveau.freedesktop.org/wiki/Bugs +https://nouveau.freedesktop.org/wiki/Bugs diff --git a/Documentation/driver-api/usb/dma.rst b/Documentation/driver-api/usb/dma.rst index 59d5aee89e37..2b3dbd3265b4 100644 --- a/Documentation/driver-api/usb/dma.rst +++ b/Documentation/driver-api/usb/dma.rst @@ -10,7 +10,7 @@ API overview The big picture is that USB drivers can continue to ignore most DMA issues, though they still must provide DMA-ready buffers (see -``Documentation/DMA-API-HOWTO.txt``). That's how they've worked through +:doc:`/core-api/dma-api-howto`). That's how they've worked through the 2.4 (and earlier) kernels, or they can now be DMA-aware. DMA-aware usb drivers: @@ -60,7 +60,7 @@ and effects like cache-trashing can impose subtle penalties. force a consistent memory access ordering by using memory barriers. It's not using a streaming DMA mapping, so it's good for small transfers on systems where the I/O would otherwise thrash an IOMMU mapping. (See - ``Documentation/DMA-API-HOWTO.txt`` for definitions of "coherent" and + :doc:`/core-api/dma-api-howto` for definitions of "coherent" and "streaming" DMA mappings.) Asking for 1/Nth of a page (as well as asking for N pages) is reasonably @@ -91,7 +91,7 @@ Working with existing buffers Existing buffers aren't usable for DMA without first being mapped into the DMA address space of the device. However, most buffers passed to your driver can safely be used with such DMA mapping. (See the first section -of Documentation/DMA-API-HOWTO.txt, titled "What memory is DMA-able?") +of :doc:`/core-api/dma-api-howto`, titled "What memory is DMA-able?") - When you're using scatterlists, you can map everything at once. On some systems, this kicks in an IOMMU and turns the scatterlists into single diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 0b3d9ff221bb..2176297e5765 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst @@ -318,6 +318,6 @@ linux-usb Mailing List Archives: https://lore.kernel.org/linux-usb/ Programming Guide for Linux USB Device Drivers: -http://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf +https://lmu.web.psi.ch/docu/manuals/software_manuals/linux_sl/usb_linux_programming_guide.pdf -USB Home Page: http://www.usb.org +USB Home Page: https://www.usb.org |