summaryrefslogtreecommitdiff
path: root/Documentation/driver-api
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2020-12-15 03:55:54 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2020-12-15 03:55:54 +0300
commitff6135959a9150ad45cb92ca38da270903a74343 (patch)
tree31d7f607078641a425851fc58bed311e3c84f175 /Documentation/driver-api
parentf9b4240b074730f41c1ef8e0d695d10fb5bb1e27 (diff)
parent47e44ed01434e51e2e42b188482d837c01e5d16e (diff)
downloadlinux-ff6135959a9150ad45cb92ca38da270903a74343.tar.xz
Merge tag 'docs-5.11' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "A much quieter cycle for documentation (happily), with, one hopes, the bulk of the churn behind us. Significant stuff in this pull includes: - A set of new Chinese translations - Italian translation updates - A mechanism from Mauro to automatically format Documentation/features for the built docs - Automatic cross references without explicit :ref: markup - A new reset-controller document - An extensive new document on reporting problems from Thorsten That last patch also adds the CC-BY-4.0 license to LICENSES/dual; there was some discussion on this, but we seem to have consensus and an ack from Greg for that addition" * tag 'docs-5.11' of git://git.lwn.net/linux: (50 commits) docs: fix broken cross reference in translations/zh_CN docs: Note that sphinx 1.7 will be required soon docs: update requirements to install six module docs: reporting-issues: move 'outdated, need help' note to proper place docs: Update documentation to reflect what TAINT_CPU_OUT_OF_SPEC means docs: add a reset controller chapter to the driver API docs docs: make reporting-bugs.rst obsolete docs: Add a new text describing how to report bugs LICENSES: Add the CC-BY-4.0 license Documentation: fix multiple typos found in the admin-guide subdirectory Documentation: fix typos found in admin-guide subdirectory kernel-doc: Fix example in Nested structs/unions docs: clean up sysctl/kernel: titles, version docs: trace: fix event state structure name docs: nios2: add missing ReST file scripts: get_feat.pl: reduce table width for all features output scripts: get_feat.pl: change the group by order scripts: get_feat.pl: make complete table more coincise scripts: kernel-doc: fix parsing function-like typedefs Documentation: fix typos found in process, dev-tools, and doc-guide subdirectories ...
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r--Documentation/driver-api/index.rst1
-rw-r--r--Documentation/driver-api/mtd/intel-spi.rst4
-rw-r--r--Documentation/driver-api/mtd/spi-nor.rst6
-rw-r--r--Documentation/driver-api/reset.rst221
4 files changed, 228 insertions, 4 deletions
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index f357f3eb400c..08c32952fce3 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -29,6 +29,7 @@ available subsections can be seen below.
infiniband
frame-buffer
regulator
+ reset
iio/index
input
usb/index
diff --git a/Documentation/driver-api/mtd/intel-spi.rst b/Documentation/driver-api/mtd/intel-spi.rst
index 0e6d9cd5388d..0465f6879262 100644
--- a/Documentation/driver-api/mtd/intel-spi.rst
+++ b/Documentation/driver-api/mtd/intel-spi.rst
@@ -52,7 +52,7 @@ Linux.
16384+0 records out
8388608 bytes (8.4 MB) copied, 10.0269 s, 837 kB/s
- 6) Verify the backup:
+ 6) Verify the backup::
# sha1sum /dev/mtd0ro bios.bak
fdbb011920572ca6c991377c4b418a0502668b73 /dev/mtd0ro
@@ -66,7 +66,7 @@ Linux.
# flash_erase /dev/mtd0 0 0
Erasing 4 Kibyte @ 7ff000 -- 100 % complete
- 8) Once completed without errors you can write the new BIOS image:
+ 8) Once completed without errors you can write the new BIOS image::
# dd if=MNW2MAX1.X64.0092.R01.1605221712.bin of=/dev/mtd0
diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
index 1f0437676762..4a3adca417fd 100644
--- a/Documentation/driver-api/mtd/spi-nor.rst
+++ b/Documentation/driver-api/mtd/spi-nor.rst
@@ -34,7 +34,8 @@ Before this framework, the layer is like::
------------------------
SPI NOR chip
- After this framework, the layer is like:
+After this framework, the layer is like::
+
MTD
------------------------
SPI NOR framework
@@ -45,7 +46,8 @@ Before this framework, the layer is like::
------------------------
SPI NOR chip
- With the SPI NOR controller driver (Freescale QuadSPI), it looks like:
+With the SPI NOR controller driver (Freescale QuadSPI), it looks like::
+
MTD
------------------------
SPI NOR framework
diff --git a/Documentation/driver-api/reset.rst b/Documentation/driver-api/reset.rst
new file mode 100644
index 000000000000..84e03d7039cc
--- /dev/null
+++ b/Documentation/driver-api/reset.rst
@@ -0,0 +1,221 @@
+.. SPDX-License-Identifier: GPL-2.0-only
+
+====================
+Reset controller API
+====================
+
+Introduction
+============
+
+Reset controllers are central units that control the reset signals to multiple
+peripherals.
+The reset controller API is split into two parts:
+the `consumer driver interface <#consumer-driver-interface>`__ (`API reference
+<#reset-consumer-api>`__), which allows peripheral drivers to request control
+over their reset input signals, and the `reset controller driver interface
+<#reset-controller-driver-interface>`__ (`API reference
+<#reset-controller-driver-api>`__), which is used by drivers for reset
+controller devices to register their reset controls to provide them to the
+consumers.
+
+While some reset controller hardware units also implement system restart
+functionality, restart handlers are out of scope for the reset controller API.
+
+Glossary
+--------
+
+The reset controller API uses these terms with a specific meaning:
+
+Reset line
+
+ Physical reset line carrying a reset signal from a reset controller
+ hardware unit to a peripheral module.
+
+Reset control
+
+ Control method that determines the state of one or multiple reset lines.
+ Most commonly this is a single bit in reset controller register space that
+ either allows direct control over the physical state of the reset line, or
+ is self-clearing and can be used to trigger a predetermined pulse on the
+ reset line.
+ In more complicated reset controls, a single trigger action can launch a
+ carefully timed sequence of pulses on multiple reset lines.
+
+Reset controller
+
+ A hardware module that provides a number of reset controls to control a
+ number of reset lines.
+
+Reset consumer
+
+ Peripheral module or external IC that is put into reset by the signal on a
+ reset line.
+
+Consumer driver interface
+=========================
+
+This interface provides an API that is similar to the kernel clock framework.
+Consumer drivers use get and put operations to acquire and release reset
+controls.
+Functions are provided to assert and deassert the controlled reset lines,
+trigger reset pulses, or to query reset line status.
+
+When requesting reset controls, consumers can use symbolic names for their
+reset inputs, which are mapped to an actual reset control on an existing reset
+controller device by the core.
+
+A stub version of this API is provided when the reset controller framework is
+not in use in order to minimize the need to use ifdefs.
+
+Shared and exclusive resets
+---------------------------
+
+The reset controller API provides either reference counted deassertion and
+assertion or direct, exclusive control.
+The distinction between shared and exclusive reset controls is made at the time
+the reset control is requested, either via devm_reset_control_get_shared() or
+via devm_reset_control_get_exclusive().
+This choice determines the behavior of the API calls made with the reset
+control.
+
+Shared resets behave similarly to clocks in the kernel clock framework.
+They provide reference counted deassertion, where only the first deassert,
+which increments the deassertion reference count to one, and the last assert
+which decrements the deassertion reference count back to zero, have a physical
+effect on the reset line.
+
+Exclusive resets on the other hand guarantee direct control.
+That is, an assert causes the reset line to be asserted immediately, and a
+deassert causes the reset line to be deasserted immediately.
+
+Assertion and deassertion
+-------------------------
+
+Consumer drivers use the reset_control_assert() and reset_control_deassert()
+functions to assert and deassert reset lines.
+For shared reset controls, calls to the two functions must be balanced.
+
+Note that since multiple consumers may be using a shared reset control, there
+is no guarantee that calling reset_control_assert() on a shared reset control
+will actually cause the reset line to be asserted.
+Consumer drivers using shared reset controls should assume that the reset line
+may be kept deasserted at all times.
+The API only guarantees that the reset line can not be asserted as long as any
+consumer has requested it to be deasserted.
+
+Triggering
+----------
+
+Consumer drivers use reset_control_reset() to trigger a reset pulse on a
+self-deasserting reset control.
+In general, these resets can not be shared between multiple consumers, since
+requesting a pulse from any consumer driver will reset all connected
+peripherals.
+
+The reset controller API allows requesting self-deasserting reset controls as
+shared, but for those only the first trigger request causes an actual pulse to
+be issued on the reset line.
+All further calls to this function have no effect until all consumers have
+called reset_control_rearm().
+For shared reset controls, calls to the two functions must be balanced.
+This allows devices that only require an initial reset at any point before the
+driver is probed or resumed to share a pulsed reset line.
+
+Querying
+--------
+
+Only some reset controllers support querying the current status of a reset
+line, via reset_control_status().
+If supported, this function returns a positive non-zero value if the given
+reset line is asserted.
+The reset_control_status() function does not accept a
+`reset control array <#reset-control-arrays>`__ handle as its input parameter.
+
+Optional resets
+---------------
+
+Often peripherals require a reset line on some platforms but not on others.
+For this, reset controls can be requested as optional using
+devm_reset_control_get_optional_exclusive() or
+devm_reset_control_get_optional_shared().
+These functions return a NULL pointer instead of an error when the requested
+reset control is not specified in the device tree.
+Passing a NULL pointer to the reset_control functions causes them to return
+quietly without an error.
+
+Reset control arrays
+--------------------
+
+Some drivers need to assert a bunch of reset lines in no particular order.
+devm_reset_control_array_get() returns an opaque reset control handle that can
+be used to assert, deassert, or trigger all specified reset controls at once.
+The reset control API does not guarantee the order in which the individual
+controls therein are handled.
+
+Reset controller driver interface
+=================================
+
+Drivers for reset controller modules provide the functionality necessary to
+assert or deassert reset signals, to trigger a reset pulse on a reset line, or
+to query its current state.
+All functions are optional.
+
+Initialization
+--------------
+
+Drivers fill a struct :c:type:`reset_controller_dev` and register it with
+reset_controller_register() in their probe function.
+The actual functionality is implemented in callback functions via a struct
+:c:type:`reset_control_ops`.
+
+API reference
+=============
+
+The reset controller API is documented here in two parts:
+the `reset consumer API <#reset-consumer-api>`__ and the `reset controller
+driver API <#reset-controller-driver-api>`__.
+
+Reset consumer API
+------------------
+
+Reset consumers can control a reset line using an opaque reset control handle,
+which can be obtained from devm_reset_control_get_exclusive() or
+devm_reset_control_get_shared().
+Given the reset control, consumers can call reset_control_assert() and
+reset_control_deassert(), trigger a reset pulse using reset_control_reset(), or
+query the reset line status using reset_control_status().
+
+.. kernel-doc:: include/linux/reset.h
+ :internal:
+
+.. kernel-doc:: drivers/reset/core.c
+ :functions: reset_control_reset
+ reset_control_assert
+ reset_control_deassert
+ reset_control_status
+ reset_control_acquire
+ reset_control_release
+ reset_control_rearm
+ reset_control_put
+ of_reset_control_get_count
+ of_reset_control_array_get
+ devm_reset_control_array_get
+ reset_control_get_count
+
+Reset controller driver API
+---------------------------
+
+Reset controller drivers are supposed to implement the necessary functions in
+a static constant structure :c:type:`reset_control_ops`, allocate and fill out
+a struct :c:type:`reset_controller_dev`, and register it using
+devm_reset_controller_register().
+
+.. kernel-doc:: include/linux/reset-controller.h
+ :internal:
+
+.. kernel-doc:: drivers/reset/core.c
+ :functions: of_reset_simple_xlate
+ reset_controller_register
+ reset_controller_unregister
+ devm_reset_controller_register
+ reset_controller_add_lookup