diff options
Diffstat (limited to 'Documentation/driver-api')
| -rw-r--r-- | Documentation/driver-api/dcdbas.rst | 99 | ||||
| -rw-r--r-- | Documentation/driver-api/device-io.rst | 9 | ||||
| -rw-r--r-- | Documentation/driver-api/index.rst | 8 | ||||
| -rw-r--r-- | Documentation/driver-api/isapnp.rst | 15 | ||||
| -rw-r--r-- | Documentation/driver-api/media/camera-sensor.rst | 7 | ||||
| -rwxr-xr-x | Documentation/driver-api/media/drivers/ccs/mk-ccs-regs | 104 | ||||
| -rw-r--r-- | Documentation/driver-api/media/index.rst | 7 | ||||
| -rw-r--r-- | Documentation/driver-api/media/tx-rx.rst | 25 | ||||
| -rw-r--r-- | Documentation/driver-api/media/v4l2-subdev.rst | 11 | ||||
| -rw-r--r-- | Documentation/driver-api/mei/index.rst | 7 | ||||
| -rw-r--r-- | Documentation/driver-api/nvmem.rst | 8 | ||||
| -rw-r--r-- | Documentation/driver-api/pci/index.rst | 5 | ||||
| -rw-r--r-- | Documentation/driver-api/pci/p2pdma.rst | 16 | ||||
| -rw-r--r-- | Documentation/driver-api/pwm.rst | 17 | ||||
| -rw-r--r-- | Documentation/driver-api/tee.rst | 66 |
15 files changed, 200 insertions, 204 deletions
diff --git a/Documentation/driver-api/dcdbas.rst b/Documentation/driver-api/dcdbas.rst deleted file mode 100644 index 309cc57a7c1c..000000000000 --- a/Documentation/driver-api/dcdbas.rst +++ /dev/null @@ -1,99 +0,0 @@ -=================================== -Dell Systems Management Base Driver -=================================== - -Overview -======== - -The Dell Systems Management Base Driver provides a sysfs interface for -systems management software such as Dell OpenManage to perform system -management interrupts and host control actions (system power cycle or -power off after OS shutdown) on certain Dell systems. - -Dell OpenManage requires this driver on the following Dell PowerEdge systems: -300, 1300, 1400, 400SC, 500SC, 1500SC, 1550, 600SC, 1600SC, 650, 1655MC, -700, and 750. Other Dell software such as the open source libsmbios project -is expected to make use of this driver, and it may include the use of this -driver on other Dell systems. - -The Dell libsmbios project aims towards providing access to as much BIOS -information as possible. See http://linux.dell.com/libsmbios/main/ for -more information about the libsmbios project. - - -System Management Interrupt -=========================== - -On some Dell systems, systems management software must access certain -management information via a system management interrupt (SMI). The SMI data -buffer must reside in 32-bit address space, and the physical address of the -buffer is required for the SMI. The driver maintains the memory required for -the SMI and provides a way for the application to generate the SMI. -The driver creates the following sysfs entries for systems management -software to perform these system management interrupts:: - - /sys/devices/platform/dcdbas/smi_data - /sys/devices/platform/dcdbas/smi_data_buf_phys_addr - /sys/devices/platform/dcdbas/smi_data_buf_size - /sys/devices/platform/dcdbas/smi_request - -Systems management software must perform the following steps to execute -a SMI using this driver: - -1) Lock smi_data. -2) Write system management command to smi_data. -3) Write "1" to smi_request to generate a calling interface SMI or - "2" to generate a raw SMI. -4) Read system management command response from smi_data. -5) Unlock smi_data. - - -Host Control Action -=================== - -Dell OpenManage supports a host control feature that allows the administrator -to perform a power cycle or power off of the system after the OS has finished -shutting down. On some Dell systems, this host control feature requires that -a driver perform a SMI after the OS has finished shutting down. - -The driver creates the following sysfs entries for systems management software -to schedule the driver to perform a power cycle or power off host control -action after the system has finished shutting down: - -/sys/devices/platform/dcdbas/host_control_action -/sys/devices/platform/dcdbas/host_control_smi_type -/sys/devices/platform/dcdbas/host_control_on_shutdown - -Dell OpenManage performs the following steps to execute a power cycle or -power off host control action using this driver: - -1) Write host control action to be performed to host_control_action. -2) Write type of SMI that driver needs to perform to host_control_smi_type. -3) Write "1" to host_control_on_shutdown to enable host control action. -4) Initiate OS shutdown. - (Driver will perform host control SMI when it is notified that the OS - has finished shutting down.) - - -Host Control SMI Type -===================== - -The following table shows the value to write to host_control_smi_type to -perform a power cycle or power off host control action: - -=================== ===================== -PowerEdge System Host Control SMI Type -=================== ===================== - 300 HC_SMITYPE_TYPE1 - 1300 HC_SMITYPE_TYPE1 - 1400 HC_SMITYPE_TYPE2 - 500SC HC_SMITYPE_TYPE2 - 1500SC HC_SMITYPE_TYPE2 - 1550 HC_SMITYPE_TYPE2 - 600SC HC_SMITYPE_TYPE2 - 1600SC HC_SMITYPE_TYPE2 - 650 HC_SMITYPE_TYPE2 - 1655MC HC_SMITYPE_TYPE2 - 700 HC_SMITYPE_TYPE3 - 750 HC_SMITYPE_TYPE3 -=================== ===================== diff --git a/Documentation/driver-api/device-io.rst b/Documentation/driver-api/device-io.rst index 2c7abd234f4e..d55384b106bd 100644 --- a/Documentation/driver-api/device-io.rst +++ b/Documentation/driver-api/device-io.rst @@ -408,11 +408,12 @@ functions for details on the CPU side of things. ioremap_uc() ------------ -ioremap_uc() behaves like ioremap() except that on the x86 architecture without -'PAT' mode, it marks memory as uncached even when the MTRR has designated -it as cacheable, see Documentation/arch/x86/pat.rst. +ioremap_uc() is only meaningful on old x86-32 systems with the PAT extension, +and on ia64 with its slightly unconventional ioremap() behavior, everywhere +elss ioremap_uc() defaults to return NULL. -Portable drivers should avoid the use of ioremap_uc(). + +Portable drivers should avoid the use of ioremap_uc(), use ioremap() instead. ioremap_cache() --------------- diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst index 3cc0e1a517c0..eba851605388 100644 --- a/Documentation/driver-api/index.rst +++ b/Documentation/driver-api/index.rst @@ -9,11 +9,8 @@ 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. -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 driver-model/index @@ -81,10 +78,8 @@ available subsections can be seen below. backlight/lp855x-driver.rst connector console - dcdbas eisa isa - isapnp io-mapping io_ordering generic-counter @@ -117,6 +112,7 @@ available subsections can be seen below. dpll wbrf crypto/index + tee .. only:: subproject and html diff --git a/Documentation/driver-api/isapnp.rst b/Documentation/driver-api/isapnp.rst deleted file mode 100644 index 8d0840ac847b..000000000000 --- a/Documentation/driver-api/isapnp.rst +++ /dev/null @@ -1,15 +0,0 @@ -========================================================== -ISA Plug & Play support by Jaroslav Kysela <perex@suse.cz> -========================================================== - -Interface /proc/isapnp -====================== - -The interface has been removed. See pnp.txt for more details. - -Interface /proc/bus/isapnp -========================== - -This directory allows access to ISA PnP cards and logical devices. -The regular files contain the contents of ISA PnP registers for -a logical device. diff --git a/Documentation/driver-api/media/camera-sensor.rst b/Documentation/driver-api/media/camera-sensor.rst index 6456145f96ed..b4920b34cebc 100644 --- a/Documentation/driver-api/media/camera-sensor.rst +++ b/Documentation/driver-api/media/camera-sensor.rst @@ -9,8 +9,8 @@ This document covers the in-kernel APIs only. For the best practices on userspace API implementation in camera sensor drivers, please see :ref:`media_using_camera_sensor_drivers`. -CSI-2 and parallel (BT.601 and BT.656) busses ---------------------------------------------- +CSI-2, parallel and BT.656 buses +-------------------------------- Please see :ref:`transmitter-receiver`. @@ -60,7 +60,8 @@ management over the pipeline. Camera sensor drivers are responsible for controlling the power state of the device they otherwise control as well. They shall use runtime PM to manage power states. Runtime PM shall be enabled at probe time and disabled at remove -time. Drivers should enable runtime PM autosuspend. +time. Drivers should enable runtime PM autosuspend. Also see +:ref:`async sub-device registration <media-registering-async-subdevs>`. The runtime PM handlers shall handle clocks, regulators, GPIOs, and other system resources required to power the sensor up and down. For drivers that diff --git a/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs b/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs index 2a4edc7e051a..3d3152b45821 100755 --- a/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs +++ b/Documentation/driver-api/media/drivers/ccs/mk-ccs-regs @@ -82,14 +82,6 @@ for my $fh ($H, $LH) { print $fh "/* $license */\n$copyright$note\n"; } -sub bit_def($) { - my $bit = shift @_; - - return "BIT($bit)" if defined $kernel; - return "(1U << $bit)" if $bit =~ /^[a-zA-Z0-9_]+$/; - return "(1U << ($bit))"; -} - print $H <<EOF #ifndef __${uc_header}__ #define __${uc_header}__ @@ -97,23 +89,63 @@ print $H <<EOF EOF ; -print $H "#include <linux/bits.h>\n\n" if defined $kernel; - print $H <<EOF -#define CCS_FL_BASE 16 +#include <linux/bits.h> + +#include <media/v4l2-cci.h> + EOF - ; + if defined $kernel; + +print $H "#define CCS_FL_BASE " . + (defined $kernel ? "CCI_REG_PRIVATE_SHIFT" : 16) . "\n"; + +my $flag = -1; +my $all_flags; + +sub bit_def($) { + my $bit = shift @_; + + if (defined $kernel) { + return "BIT$bit" if $bit =~ /^\(.*\)$/; + return "BIT($bit)"; + } + return "(1U << $bit)"; +} + +sub flag_str($$) { + my ($flag, $check) = @_; -print $H "#define CCS_FL_16BIT " . bit_def("CCS_FL_BASE") . "\n"; -print $H "#define CCS_FL_32BIT " . bit_def("CCS_FL_BASE + 1") . "\n"; -print $H "#define CCS_FL_FLOAT_IREAL " . bit_def("CCS_FL_BASE + 2") . "\n"; -print $H "#define CCS_FL_IREAL " . bit_def("CCS_FL_BASE + 3") . "\n"; + $$flag++; + + my $flag_str = !$$flag ? "CCS_FL_BASE" : "(CCS_FL_BASE + $$flag)"; + + $flag_str = bit_def($flag_str); + + $$check .= " | " if defined $$check; + + $$check .= $flag_str; + + return $flag_str; +} + +if (! defined $kernel) { + print $H "#define CCS_FL_16BIT " . flag_str(\$flag, \$all_flags) . "\n"; + print $H "#define CCS_FL_32BIT " . flag_str(\$flag, \$all_flags) . "\n"; +} + +print $H "#define CCS_FL_FLOAT_IREAL " . flag_str(\$flag, \$all_flags) . "\n"; +print $H "#define CCS_FL_IREAL " . flag_str(\$flag, \$all_flags) . "\n"; +print $H "#define CCS_BUILD_BUG \\ + BUILD_BUG_ON(~CCI_REG_PRIVATE_MASK & ($all_flags))\n" + if defined $kernel; print $H <<EOF + #define CCS_R_ADDR(r) ((r) & 0xffff) EOF - ; + if ! defined $kernel; print $A <<EOF #include <stdint.h> @@ -189,12 +221,12 @@ sub tabconv($) { return (join "\n", @l) . "\n"; } -sub elem_size(@) { +sub elem_bits(@) { my @flags = @_; - return 2 if grep /^16$/, @flags; - return 4 if grep /^32$/, @flags; - return 1; + return 16 if grep /^16$/, @flags; + return 32 if grep /^32$/, @flags; + return 8; } sub arr_size($) { @@ -296,9 +328,13 @@ while (<$R>) { next if $#{$this{args}} + 1 != scalar keys %{$this{argparams}}; - my $reg_formula = "($this{addr}"; + my $reg_formula = "$this{addr}"; my $lim_formula; + chop $reg_formula; + + $reg_formula = "(" . $reg_formula if $this{flagstring} ne ""; + foreach my $arg (@{$this{args}}) { my $d = $h->{$arg}->{discontig}; my $times = $h->{$arg}->{elsize} != 1 ? @@ -315,11 +351,13 @@ while (<$R>) { $lim_formula .= (defined $lim_formula ? " + " : "") . "($arg)$times"; } - $reg_formula .= ")\n"; + $reg_formula .= ")"; $lim_formula =~ s/^\(([a-z0-9]+)\)$/$1/i; print $H tabconv sprintf("#define %-62s %s", "CCS_R_" . (uc $this{name}) . - $this{arglist}, $reg_formula); + $this{arglist}, $reg_formula . + (($this{flagstring} eq "") ? "" : + " | " . $this{flagstring} . ")") . "\n"); print $H tabconv $hdr_data; undef $hdr_data; @@ -369,16 +407,23 @@ while (<$R>) { $name =~ s/[,\.-]/_/g; my $flagstring = ""; - my $size = elem_size(@flags); - $flagstring .= "| CCS_FL_16BIT " if $size eq "2"; - $flagstring .= "| CCS_FL_32BIT " if $size eq "4"; + my $bits = elem_bits(@flags); + if (! defined $kernel) { + $flagstring .= "| CCS_FL_16BIT " if $bits == 16; + $flagstring .= "| CCS_FL_32BIT " if $bits == 32; + } $flagstring .= "| CCS_FL_FLOAT_IREAL " if grep /^float_ireal$/, @flags; $flagstring .= "| CCS_FL_IREAL " if grep /^ireal$/, @flags; $flagstring =~ s/^\| //; $flagstring =~ s/ $//; $flagstring = "($flagstring)" if $flagstring =~ /\|/; my $base_addr = $addr; - $addr = "($addr | $flagstring)" if $flagstring ne ""; + $addr = "CCI_REG$bits($addr)" if defined $kernel; + + if ($flagstring ne "" && !@$args) { + $addr = "($addr | $flagstring)"; + $flagstring = ""; + } my $arglist = @$args ? "(" . (join ", ", @$args) . ")" : ""; $hdr_data .= sprintf "#define %-62s %s\n", "CCS_R_" . (uc $name), $addr @@ -388,11 +433,12 @@ while (<$R>) { %this = ( name => $name, addr => $addr, + flagstring => $flagstring, base_addr => $base_addr, argparams => {}, args => $args, arglist => $arglist, - elsize => $size, + elsize => $bits / 8, ); if (!@$args) { diff --git a/Documentation/driver-api/media/index.rst b/Documentation/driver-api/media/index.rst index 08e206567408..d5593182a3f9 100644 --- a/Documentation/driver-api/media/index.rst +++ b/Documentation/driver-api/media/index.rst @@ -20,13 +20,8 @@ Documentation/userspace-api/media/index.rst - for the userspace APIs used on media devices. -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 5 :numbered: diff --git a/Documentation/driver-api/media/tx-rx.rst b/Documentation/driver-api/media/tx-rx.rst index e1e9258dd862..29d66a47b56e 100644 --- a/Documentation/driver-api/media/tx-rx.rst +++ b/Documentation/driver-api/media/tx-rx.rst @@ -6,8 +6,8 @@ Pixel data transmitter and receiver drivers =========================================== V4L2 supports various devices that transmit and receive pixel data. Examples of -these devices include a camera sensor, a TV tuner and a parallel or a CSI-2 -receiver in an SoC. +these devices include a camera sensor, a TV tuner and a parallel, a BT.656 or a +CSI-2 receiver in an SoC. Bus types --------- @@ -22,12 +22,13 @@ the host SoC. It is defined by the `MIPI alliance`_. .. _`MIPI alliance`: https://www.mipi.org/ -Parallel -^^^^^^^^ +Parallel and BT.656 +^^^^^^^^^^^^^^^^^^^ -`BT.601`_ and `BT.656`_ are the most common parallel busses. +The parallel and `BT.656`_ buses transport one bit of data on each clock cycle +per data line. The parallel bus uses synchronisation and other additional +signals whereas BT.656 embeds synchronisation. -.. _`BT.601`: https://en.wikipedia.org/wiki/Rec._601 .. _`BT.656`: https://en.wikipedia.org/wiki/ITU-R_BT.656 Transmitter drivers @@ -90,8 +91,8 @@ where pixel rate on the camera sensor's pixel array which is indicated by the :ref:`V4L2_CID_PIXEL_RATE <v4l2-cid-pixel-rate>` control. -LP-11 and LP-111 modes -^^^^^^^^^^^^^^^^^^^^^^ +LP-11 and LP-111 states +^^^^^^^^^^^^^^^^^^^^^^^ As part of transitioning to high speed mode, a CSI-2 transmitter typically briefly sets the bus to LP-11 or LP-111 state, depending on the PHY. This period @@ -105,7 +106,7 @@ in software, especially when there is no interrupt telling something is happening. One way to address this is to configure the transmitter side explicitly to LP-11 -or LP-111 mode, which requires support from the transmitter hardware. This is +or LP-111 state, which requires support from the transmitter hardware. This is not universally available. Many devices return to this state once streaming is stopped while the state after power-on is LP-00 or LP-000. @@ -116,11 +117,11 @@ transitioning to streaming state, but not yet start streaming. Similarly, the to call ``.post_streamoff()`` for each successful call of ``.pre_streamon()``. In the context of CSI-2, the ``.pre_streamon()`` callback is used to transition -the transmitter to the LP-11 or LP-111 mode. This also requires powering on the +the transmitter to the LP-11 or LP-111 state. This also requires powering on the device, so this should be only done when it is needed. -Receiver drivers that do not need explicit LP-11 or LP-111 mode setup are waived -from calling the two callbacks. +Receiver drivers that do not need explicit LP-11 or LP-111 state setup are +waived from calling the two callbacks. Stopping the transmitter ^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/Documentation/driver-api/media/v4l2-subdev.rst b/Documentation/driver-api/media/v4l2-subdev.rst index e56b50b3f203..1db2ba27c54c 100644 --- a/Documentation/driver-api/media/v4l2-subdev.rst +++ b/Documentation/driver-api/media/v4l2-subdev.rst @@ -181,6 +181,8 @@ You can unregister a sub-device using: Afterwards the subdev module can be unloaded and :c:type:`sd <v4l2_subdev>`->dev == ``NULL``. +.. _media-registering-async-subdevs: + Registering asynchronous sub-devices ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -195,6 +197,11 @@ performed using the :c:func:`v4l2_async_unregister_subdev` call. Subdevices registered this way are stored in a global list of subdevices, ready to be picked up by bridge drivers. +Drivers must complete all initialization of the sub-device before +registering it using :c:func:`v4l2_async_register_subdev`, including +enabling runtime PM. This is because the sub-device becomes accessible +as soon as it gets registered. + Asynchronous sub-device notifiers ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -562,8 +569,8 @@ device configuration. This is often implemented as e.g. an array of struct v4l2_mbus_framefmt, one entry for each pad, and similarly for crop and compose rectangles. -In addition to the active configuration, each subdev file handle has an array of -struct v4l2_subdev_pad_config, managed by the V4L2 core, which contains the try +In addition to the active configuration, each subdev file handle has a struct +v4l2_subdev_state, managed by the V4L2 core, which contains the try configuration. To simplify the subdev drivers the V4L2 subdev API now optionally supports a diff --git a/Documentation/driver-api/mei/index.rst b/Documentation/driver-api/mei/index.rst index 3a22b522ee78..eae6f18f18cf 100644 --- a/Documentation/driver-api/mei/index.rst +++ b/Documentation/driver-api/mei/index.rst @@ -9,13 +9,8 @@ Intel(R) Management Engine Interface (Intel(R) MEI) **Copyright** |copy| 2019 Intel Corporation -.. only:: html - - .. class:: toc-title - - Table of Contents - .. toctree:: + :caption: Table of Contents :maxdepth: 3 mei diff --git a/Documentation/driver-api/nvmem.rst b/Documentation/driver-api/nvmem.rst index de221e91c8e3..5d9500d21ecc 100644 --- a/Documentation/driver-api/nvmem.rst +++ b/Documentation/driver-api/nvmem.rst @@ -41,7 +41,7 @@ A NVMEM provider can register with NVMEM core by supplying relevant nvmem configuration to nvmem_register(), on success core would return a valid nvmem_device pointer. -nvmem_unregister(nvmem) is used to unregister a previously registered provider. +nvmem_unregister() is used to unregister a previously registered provider. For example, a simple nvram case:: @@ -200,3 +200,9 @@ and let you add cells dynamically. Another use case for layouts is the post processing of cells. With layouts, it is possible to associate a custom post processing hook to a cell. It even possible to add this hook to cells not created by the layout itself. + +9. Internal kernel API +====================== + +.. kernel-doc:: drivers/nvmem/core.c + :export: diff --git a/Documentation/driver-api/pci/index.rst b/Documentation/driver-api/pci/index.rst index c6cf1fef61ce..a38e475cdbe3 100644 --- a/Documentation/driver-api/pci/index.rst +++ b/Documentation/driver-api/pci/index.rst @@ -4,11 +4,8 @@ The Linux PCI driver implementer's API guide ============================================ -.. class:: toc-title - - Table of contents - .. toctree:: + :caption: Table of contents :maxdepth: 2 pci diff --git a/Documentation/driver-api/pci/p2pdma.rst b/Documentation/driver-api/pci/p2pdma.rst index 44deb52beeb4..d0b241628cf1 100644 --- a/Documentation/driver-api/pci/p2pdma.rst +++ b/Documentation/driver-api/pci/p2pdma.rst @@ -83,19 +83,9 @@ this to include other types of resources like doorbells. Client Drivers -------------- -A client driver typically only has to conditionally change its DMA map -routine to use the mapping function :c:func:`pci_p2pdma_map_sg()` instead -of the usual :c:func:`dma_map_sg()` function. Memory mapped in this -way does not need to be unmapped. - -The client may also, optionally, make use of -:c:func:`is_pci_p2pdma_page()` to determine when to use the P2P mapping -functions and when to use the regular mapping functions. In some -situations, it may be more appropriate to use a flag to indicate a -given request is P2P memory and map appropriately. It is important to -ensure that struct pages that back P2P memory stay out of code that -does not have support for them as other code may treat the pages as -regular memory which may not be appropriate. +A client driver only has to use the mapping API :c:func:`dma_map_sg()` +and :c:func:`dma_unmap_sg()` functions as usual, and the implementation +will do the right thing for the P2P capable memory. Orchestrator Drivers diff --git a/Documentation/driver-api/pwm.rst b/Documentation/driver-api/pwm.rst index bb264490a87a..3c28ccc4b611 100644 --- a/Documentation/driver-api/pwm.rst +++ b/Documentation/driver-api/pwm.rst @@ -41,11 +41,20 @@ the getter, devm_pwm_get() and devm_fwnode_pwm_get(), also exist. After being requested, a PWM has to be configured using:: - int pwm_apply_state(struct pwm_device *pwm, struct pwm_state *state); + int pwm_apply_might_sleep(struct pwm_device *pwm, struct pwm_state *state); This API controls both the PWM period/duty_cycle config and the enable/disable state. +PWM devices can be used from atomic context, if the PWM does not sleep. You +can check if this the case with:: + + bool pwm_might_sleep(struct pwm_device *pwm); + +If false, the PWM can also be configured from atomic context with:: + + int pwm_apply_atomic(struct pwm_device *pwm, struct pwm_state *state); + As a consumer, don't rely on the output's state for a disabled PWM. If it's easily possible, drivers are supposed to emit the inactive state, but some drivers cannot. If you rely on getting the inactive state, use .duty_cycle=0, @@ -57,13 +66,13 @@ If supported by the driver, the signal can be optimized, for example to improve EMI by phase shifting the individual channels of a chip. The pwm_config(), pwm_enable() and pwm_disable() functions are just wrappers -around pwm_apply_state() and should not be used if the user wants to change +around pwm_apply_might_sleep() and should not be used if the user wants to change several parameter at once. For example, if you see pwm_config() and pwm_{enable,disable}() calls in the same function, this probably means you -should switch to pwm_apply_state(). +should switch to pwm_apply_might_sleep(). The PWM user API also allows one to query the PWM state that was passed to the -last invocation of pwm_apply_state() using pwm_get_state(). Note this is +last invocation of pwm_apply_might_sleep() using pwm_get_state(). Note this is different to what the driver has actually implemented if the request cannot be satisfied exactly with the hardware in use. There is currently no way for consumers to get the actually implemented settings. diff --git a/Documentation/driver-api/tee.rst b/Documentation/driver-api/tee.rst new file mode 100644 index 000000000000..5eaeb8103988 --- /dev/null +++ b/Documentation/driver-api/tee.rst @@ -0,0 +1,66 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=============================================== +TEE (Trusted Execution Environment) driver API +=============================================== + +Kernel provides a TEE bus infrastructure where a Trusted Application is +represented as a device identified via Universally Unique Identifier (UUID) and +client drivers register a table of supported device UUIDs. + +TEE bus infrastructure registers following APIs: + +match(): + iterates over the client driver UUID table to find a corresponding + match for device UUID. If a match is found, then this particular device is + probed via corresponding probe API registered by the client driver. This + process happens whenever a device or a client driver is registered with TEE + bus. + +uevent(): + notifies user-space (udev) whenever a new device is registered on + TEE bus for auto-loading of modularized client drivers. + +TEE bus device enumeration is specific to underlying TEE implementation, so it +is left open for TEE drivers to provide corresponding implementation. + +Then TEE client driver can talk to a matched Trusted Application using APIs +listed in include/linux/tee_drv.h. + +TEE client driver example +------------------------- + +Suppose a TEE client driver needs to communicate with a Trusted Application +having UUID: ``ac6a4085-0e82-4c33-bf98-8eb8e118b6c2``, so driver registration +snippet would look like:: + + static const struct tee_client_device_id client_id_table[] = { + {UUID_INIT(0xac6a4085, 0x0e82, 0x4c33, + 0xbf, 0x98, 0x8e, 0xb8, 0xe1, 0x18, 0xb6, 0xc2)}, + {} + }; + + MODULE_DEVICE_TABLE(tee, client_id_table); + + static struct tee_client_driver client_driver = { + .id_table = client_id_table, + .driver = { + .name = DRIVER_NAME, + .bus = &tee_bus_type, + .probe = client_probe, + .remove = client_remove, + }, + }; + + static int __init client_init(void) + { + return driver_register(&client_driver.driver); + } + + static void __exit client_exit(void) + { + driver_unregister(&client_driver.driver); + } + + module_init(client_init); + module_exit(client_exit); |