summaryrefslogtreecommitdiffstats
path: root/Documentation/driver-api
diff options
context:
space:
mode:
authorMaarten Lankhorst <maarten.lankhorst@linux.intel.com>2020-06-29 12:15:51 +0200
committerMaarten Lankhorst <maarten.lankhorst@linux.intel.com>2020-06-29 12:16:26 +0200
commit60e9eabf41fa916d2ef68c5bf929197975917578 (patch)
tree39ce456390ed34d2624aed1260203f43fff94d38 /Documentation/driver-api
parent84e543bc9d1dc550132ba25b72df28d40cc44333 (diff)
parent0a19b068acc47d05212f03e494381926dc0381e2 (diff)
Backmerge remote-tracking branch 'drm/drm-next' into drm-misc-next
Some conflicts with ttm_bo->offset removal, but drm-misc-next needs updating to v5.8. Signed-off-by: Maarten Lankhorst <maarten.lankhorst@linux.intel.com>
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r--Documentation/driver-api/acpi/linuxized-acpica.rst6
-rw-r--r--Documentation/driver-api/driver-model/device.rst4
-rw-r--r--Documentation/driver-api/driver-model/devres.rst14
-rw-r--r--Documentation/driver-api/driver-model/driver.rst32
-rw-r--r--Documentation/driver-api/driver-model/overview.rst2
-rw-r--r--Documentation/driver-api/gpio/board.rst15
-rw-r--r--Documentation/driver-api/iio/triggers.rst2
-rw-r--r--Documentation/driver-api/index.rst2
-rw-r--r--Documentation/driver-api/infiniband.rst3
-rw-r--r--Documentation/driver-api/ipmi.rst746
-rw-r--r--Documentation/driver-api/media/cec-core.rst474
-rw-r--r--Documentation/driver-api/media/csi2.rst91
-rw-r--r--Documentation/driver-api/media/drivers/bttv-devel.rst116
-rw-r--r--Documentation/driver-api/media/drivers/contributors.rst131
-rw-r--r--Documentation/driver-api/media/drivers/cpia2_devel.rst56
-rw-r--r--Documentation/driver-api/media/drivers/cx2341x-devel.rst3685
-rw-r--r--Documentation/driver-api/media/drivers/cx88-devel.rst113
-rw-r--r--Documentation/driver-api/media/drivers/davinci-vpbe-devel.rst39
-rw-r--r--Documentation/driver-api/media/drivers/dvb-usb.rst357
-rw-r--r--Documentation/driver-api/media/drivers/fimc-devel.rst33
-rw-r--r--Documentation/driver-api/media/drivers/frontends.rst32
-rw-r--r--Documentation/driver-api/media/drivers/index.rst38
-rw-r--r--Documentation/driver-api/media/drivers/pvrusb2.rst202
-rw-r--r--Documentation/driver-api/media/drivers/pxa_camera.rst194
-rw-r--r--Documentation/driver-api/media/drivers/radiotrack.rst168
-rw-r--r--Documentation/driver-api/media/drivers/saa7134-devel.rst67
-rw-r--r--Documentation/driver-api/media/drivers/sh_mobile_ceu_camera.rst142
-rw-r--r--Documentation/driver-api/media/drivers/tuners.rst133
-rw-r--r--Documentation/driver-api/media/drivers/vimc-devel.rst15
-rw-r--r--Documentation/driver-api/media/dtv-ca.rst6
-rw-r--r--Documentation/driver-api/media/dtv-common.rst62
-rw-r--r--Documentation/driver-api/media/dtv-core.rst39
-rw-r--r--Documentation/driver-api/media/dtv-demux.rst84
-rw-r--r--Documentation/driver-api/media/dtv-frontend.rst445
-rw-r--r--Documentation/driver-api/media/dtv-net.rst6
-rw-r--r--Documentation/driver-api/media/index.rst54
-rw-r--r--Documentation/driver-api/media/mc-core.rst309
-rw-r--r--Documentation/driver-api/media/rc-core.rst88
-rw-r--r--Documentation/driver-api/media/v4l2-async.rst5
-rw-r--r--Documentation/driver-api/media/v4l2-clocks.rst31
-rw-r--r--Documentation/driver-api/media/v4l2-common.rst8
-rw-r--r--Documentation/driver-api/media/v4l2-controls.rst823
-rw-r--r--Documentation/driver-api/media/v4l2-core.rst29
-rw-r--r--Documentation/driver-api/media/v4l2-dev.rst375
-rw-r--r--Documentation/driver-api/media/v4l2-device.rst146
-rw-r--r--Documentation/driver-api/media/v4l2-dv-timings.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-event.rst181
-rw-r--r--Documentation/driver-api/media/v4l2-fh.rst141
-rw-r--r--Documentation/driver-api/media/v4l2-flash-led-class.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-fwnode.rst5
-rw-r--r--Documentation/driver-api/media/v4l2-intro.rst76
-rw-r--r--Documentation/driver-api/media/v4l2-mc.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-mediabus.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-mem2mem.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-rect.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-subdev.rst492
-rw-r--r--Documentation/driver-api/media/v4l2-tuner.rst8
-rw-r--r--Documentation/driver-api/media/v4l2-tveeprom.rst6
-rw-r--r--Documentation/driver-api/media/v4l2-videobuf.rst403
-rw-r--r--Documentation/driver-api/media/v4l2-videobuf2.rst12
-rw-r--r--Documentation/driver-api/mtdnand.rst6
-rw-r--r--Documentation/driver-api/nvdimm/nvdimm.rst4
-rw-r--r--Documentation/driver-api/pm/cpuidle.rst5
-rw-r--r--Documentation/driver-api/pm/devices.rst199
-rw-r--r--Documentation/driver-api/soundwire/stream.rst89
-rw-r--r--Documentation/driver-api/soundwire/summary.rst7
-rw-r--r--Documentation/driver-api/thermal/cpu-idle-cooling.rst3
-rw-r--r--Documentation/driver-api/thermal/index.rst1
-rw-r--r--Documentation/driver-api/usb/bulk-streams.rst4
-rw-r--r--Documentation/driver-api/usb/writing_musb_glue_layer.rst6
70 files changed, 10987 insertions, 119 deletions
diff --git a/Documentation/driver-api/acpi/linuxized-acpica.rst b/Documentation/driver-api/acpi/linuxized-acpica.rst
index 0ca8f1538519..6bee03383225 100644
--- a/Documentation/driver-api/acpi/linuxized-acpica.rst
+++ b/Documentation/driver-api/acpi/linuxized-acpica.rst
@@ -175,9 +175,9 @@ illustrated in the following figure::
B. acpica / master - "master" branch of the git repository at
<https://github.com/acpica/acpica.git>.
C. linux-pm / linux-next - "linux-next" branch of the git repository at
- <http://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
+ <https://git.kernel.org/pub/scm/linux/kernel/git/rafael/linux-pm.git>.
D. linux / master - "master" branch of the git repository at
- <http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.
+ <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git>.
Before the linuxized ACPICA patches are sent to the Linux ACPI community
for review, there is a quality assurance build test process to reduce
@@ -274,6 +274,6 @@ before they become available from the ACPICA release process.
a diff file indicating the state of the current divergences::
# git clone https://github.com/acpica/acpica
- # git clone http://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
+ # git clone https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
# cd acpica
# generate/linux/divergences.sh -s ../linux
diff --git a/Documentation/driver-api/driver-model/device.rst b/Documentation/driver-api/driver-model/device.rst
index 2b868d49d349..b9b022371e85 100644
--- a/Documentation/driver-api/driver-model/device.rst
+++ b/Documentation/driver-api/driver-model/device.rst
@@ -50,10 +50,10 @@ Attributes
Attributes of devices can be exported by a device driver through sysfs.
-Please see Documentation/filesystems/sysfs.txt for more information
+Please see Documentation/filesystems/sysfs.rst for more information
on how sysfs works.
-As explained in Documentation/kobject.txt, device attributes must be
+As explained in Documentation/core-api/kobject.rst, device attributes must be
created before the KOBJ_ADD uevent is generated. The only way to realize
that is by defining an attribute group.
diff --git a/Documentation/driver-api/driver-model/devres.rst b/Documentation/driver-api/driver-model/devres.rst
index 46c13780994c..e0b58c392e4f 100644
--- a/Documentation/driver-api/driver-model/devres.rst
+++ b/Documentation/driver-api/driver-model/devres.rst
@@ -284,21 +284,13 @@ I2C
IIO
devm_iio_device_alloc()
- devm_iio_device_free()
devm_iio_device_register()
- devm_iio_device_unregister()
devm_iio_kfifo_allocate()
- devm_iio_kfifo_free()
devm_iio_triggered_buffer_setup()
- devm_iio_triggered_buffer_cleanup()
devm_iio_trigger_alloc()
- devm_iio_trigger_free()
devm_iio_trigger_register()
- devm_iio_trigger_unregister()
devm_iio_channel_get()
- devm_iio_channel_release()
devm_iio_channel_get_all()
- devm_iio_channel_release_all()
INPUT
devm_input_allocate_device()
@@ -322,6 +314,7 @@ IOMAP
devm_platform_ioremap_resource() : calls devm_ioremap_resource() for platform device
devm_platform_ioremap_resource_wc()
devm_platform_ioremap_resource_byname()
+ devm_platform_get_and_ioremap_resource()
devm_iounmap()
pcim_iomap()
pcim_iomap_regions() : do request_region() and iomap() on multiple BARs
@@ -372,6 +365,11 @@ MUX
devm_mux_chip_register()
devm_mux_control_get()
+NET
+ devm_alloc_etherdev()
+ devm_alloc_etherdev_mqs()
+ devm_register_netdev()
+
PER-CPU MEM
devm_alloc_percpu()
devm_free_percpu()
diff --git a/Documentation/driver-api/driver-model/driver.rst b/Documentation/driver-api/driver-model/driver.rst
index 63887b813005..7d5040f6a3d8 100644
--- a/Documentation/driver-api/driver-model/driver.rst
+++ b/Documentation/driver-api/driver-model/driver.rst
@@ -4,7 +4,6 @@ Device Drivers
See the kerneldoc for the struct device_driver.
-
Allocation
~~~~~~~~~~
@@ -167,9 +166,26 @@ the driver to that device.
A driver's probe() may return a negative errno value to indicate that
the driver did not bind to this device, in which case it should have
-released all resources it allocated::
+released all resources it allocated.
+
+Optionally, probe() may return -EPROBE_DEFER if the driver depends on
+resources that are not yet available (e.g., supplied by a driver that
+hasn't initialized yet). The driver core will put the device onto the
+deferred probe list and will try to call it again later. If a driver
+must defer, it should return -EPROBE_DEFER as early as possible to
+reduce the amount of time spent on setup work that will need to be
+unwound and reexecuted at a later time.
+
+.. warning::
+ -EPROBE_DEFER must not be returned if probe() has already created
+ child devices, even if those child devices are removed again
+ in a cleanup path. If -EPROBE_DEFER is returned after a child
+ device has been registered, it may result in an infinite loop of
+ .probe() calls to the same driver.
+
+::
- void (*sync_state)(struct device *dev);
+ void (*sync_state) (struct device *dev);
sync_state is called only once for a device. It's called when all the consumer
devices of the device have successfully probed. The list of consumers of the
@@ -212,6 +228,8 @@ 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
@@ -224,11 +242,15 @@ not. It should free any resources allocated specifically for the
device; i.e. anything in the device's driver_data field.
If the device is still present, it should quiesce the device and place
-it into a supported low-power state::
+it into a supported low-power state.
+
+::
int (*suspend) (struct device *dev, pm_message_t state);
-suspend is called to put the device in a low power state::
+suspend is called to put the device in a low power state.
+
+::
int (*resume) (struct device *dev);
diff --git a/Documentation/driver-api/driver-model/overview.rst b/Documentation/driver-api/driver-model/overview.rst
index d4d1e9b40e0c..e98d0ab4a9b6 100644
--- a/Documentation/driver-api/driver-model/overview.rst
+++ b/Documentation/driver-api/driver-model/overview.rst
@@ -121,4 +121,4 @@ device-specific data or tunable interfaces.
More information about the sysfs directory layout can be found in
the other documents in this directory and in the file
-Documentation/filesystems/sysfs.txt.
+Documentation/filesystems/sysfs.rst.
diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst
index ce91518bf9f4..191fa867826a 100644
--- a/Documentation/driver-api/gpio/board.rst
+++ b/Documentation/driver-api/gpio/board.rst
@@ -113,13 +113,15 @@ files that desire to do so need to include the following header::
GPIOs are mapped by the means of tables of lookups, containing instances of the
gpiod_lookup structure. Two macros are defined to help declaring such mappings::
- GPIO_LOOKUP(chip_label, chip_hwnum, con_id, flags)
- GPIO_LOOKUP_IDX(chip_label, chip_hwnum, con_id, idx, flags)
+ GPIO_LOOKUP(key, chip_hwnum, con_id, flags)
+ GPIO_LOOKUP_IDX(key, chip_hwnum, con_id, idx, flags)
where
- - chip_label is the label of the gpiod_chip instance providing the GPIO
- - chip_hwnum is the hardware number of the GPIO within the chip
+ - key is either the label of the gpiod_chip instance providing the GPIO, or
+ the GPIO line name
+ - chip_hwnum is the hardware number of the GPIO within the chip, or U16_MAX
+ to indicate that key is a GPIO line name
- con_id is the name of the GPIO function from the device point of view. It
can be NULL, in which case it will match any function.
- idx is the index of the GPIO within the function.
@@ -135,7 +137,10 @@ where
In the future, these flags might be extended to support more properties.
-Note that GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
+Note that:
+ 1. GPIO line names are not guaranteed to be globally unique, so the first
+ match found will be used.
+ 2. GPIO_LOOKUP() is just a shortcut to GPIO_LOOKUP_IDX() where idx = 0.
A lookup table can then be defined as follows, with an empty entry defining its
end. The 'dev_id' field of the table is the identifier of the device that will
diff --git a/Documentation/driver-api/iio/triggers.rst b/Documentation/driver-api/iio/triggers.rst
index 5c2156de6284..dfd7ba3eabde 100644
--- a/Documentation/driver-api/iio/triggers.rst
+++ b/Documentation/driver-api/iio/triggers.rst
@@ -4,9 +4,7 @@ Triggers
* struct :c:type:`iio_trigger` — industrial I/O trigger device
* :c:func:`devm_iio_trigger_alloc` — Resource-managed iio_trigger_alloc
-* :c:func:`devm_iio_trigger_free` — Resource-managed iio_trigger_free
* :c:func:`devm_iio_trigger_register` — Resource-managed iio_trigger_register
-* :c:func:`devm_iio_trigger_unregister` — Resource-managed
iio_trigger_unregister
* :c:func:`iio_trigger_validate_own_device` — Check if a trigger and IIO
device belong to the same device
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d4e78cb3ef4d..6567187e7687 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -39,6 +39,7 @@ available subsections can be seen below.
spi
i2c
ipmb
+ ipmi
i3c/index
interconnect
devfreq
@@ -63,6 +64,7 @@ available subsections can be seen below.
pinctl
gpio/index
md/index
+ media/index
misc_devices
nfc/index
dmaengine/index
diff --git a/Documentation/driver-api/infiniband.rst b/Documentation/driver-api/infiniband.rst
index 1a3116f32ff0..30e142ccbee9 100644
--- a/Documentation/driver-api/infiniband.rst
+++ b/Documentation/driver-api/infiniband.rst
@@ -37,9 +37,6 @@ InfiniBand core interfaces
.. kernel-doc:: drivers/infiniband/core/ud_header.c
:export:
-.. kernel-doc:: drivers/infiniband/core/fmr_pool.c
- :export:
-
.. kernel-doc:: drivers/infiniband/core/umem.c
:export:
diff --git a/Documentation/driver-api/ipmi.rst b/Documentation/driver-api/ipmi.rst
new file mode 100644
index 000000000000..5ef1047e2e66
--- /dev/null
+++ b/Documentation/driver-api/ipmi.rst
@@ -0,0 +1,746 @@
+=====================
+The Linux IPMI Driver
+=====================
+
+:Author: Corey Minyard <minyard@mvista.com> / <minyard@acm.org>
+
+The Intelligent Platform Management Interface, or IPMI, is a
+standard for controlling intelligent devices that monitor a system.
+It provides for dynamic discovery of sensors in the system and the
+ability to monitor the sensors and be informed when the sensor's
+values change or go outside certain boundaries. It also has a
+standardized database for field-replaceable units (FRUs) and a watchdog
+timer.
+
+To use this, you need an interface to an IPMI controller in your
+system (called a Baseboard Management Controller, or BMC) and
+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
+subject and I can't cover it all here!
+
+Configuration
+-------------
+
+The Linux IPMI driver is modular, which means you have to pick several
+things to have it work right depending on your hardware. Most of
+these are available in the 'Character Devices' menu then the IPMI
+menu.
+
+No matter what, you must pick 'IPMI top-level message handler' to use
+IPMI. What you do beyond that depends on your needs and hardware.
+
+The message handler does not provide any user-level interfaces.
+Kernel code (like the watchdog) can still use it. If you need access
+from userland, you need to select 'Device interface for IPMI' if you
+want access through a device driver.
+
+The driver interface depends on your hardware. If your system
+properly provides the SMBIOS info for IPMI, the driver will detect it
+and just work. If you have a board with a standard interface (These
+will generally be either "KCS", "SMIC", or "BT", consult your hardware
+manual), choose the 'IPMI SI handler' option. A driver also exists
+for direct I2C access to the IPMI management controller. Some boards
+support this, but it is unknown if it will work on every board. For
+this, choose 'IPMI SMBus handler', but be ready to try to do some
+figuring to see if it will work on your system if the SMBIOS/APCI
+information is wrong or not present. It is fairly safe to have both
+these enabled and let the drivers auto-detect what is present.
+
+You should generally enable ACPI on your system, as systems with IPMI
+can have ACPI tables describing them.
+
+If you have a standard interface and the board manufacturer has done
+their job correctly, the IPMI controller should be automatically
+detected (via ACPI or SMBIOS tables) and should just work. Sadly,
+many boards do not have this information. The driver attempts
+standard defaults, but they may not work. If you fall into this
+situation, you need to read the section below named 'The SI Driver' or
+"The SMBus Driver" on how to hand-configure your system.
+
+IPMI defines a standard watchdog timer. You can enable this with the
+'IPMI Watchdog Timer' config option. If you compile the driver into
+the kernel, then via a kernel command-line option you can have the
+watchdog timer start as soon as it initializes. It also have a lot
+of other options, see the 'Watchdog' section below for more details.
+Note that you can also have the watchdog continue to run if it is
+closed (by default it is disabled on close). Go into the 'Watchdog
+Cards' menu, enable 'Watchdog Timer Support', and enable the option
+'Disable watchdog shutdown on close'.
+
+IPMI systems can often be powered off using IPMI commands. Select
+'IPMI Poweroff' to do this. The driver will auto-detect if the system
+can be powered off by IPMI. It is safe to enable this even if your
+system doesn't support this option. This works on ATCA systems, the
+Radisys CPI1 card, and any IPMI system that supports standard chassis
+management commands.
+
+If you want the driver to put an event into the event log on a panic,
+enable the 'Generate a panic event to all BMCs on a panic' option. If
+you want the whole panic string put into the event log using OEM
+events, enable the 'Generate OEM events containing the panic string'
+option. You can also enable these dynamically by setting the module
+parameter named "panic_op" in the ipmi_msghandler module to "event"
+or "string". Setting that parameter to "none" disables this function.
+
+Basic Design
+------------
+
+The Linux IPMI driver is designed to be very modular and flexible, you
+only need to take the pieces you need and you can use it in many
+different ways. Because of that, it's broken into many chunks of
+code. These chunks (by module name) are:
+
+ipmi_msghandler - This is the central piece of software for the IPMI
+system. It handles all messages, message timing, and responses. The
+IPMI users tie into this, and the IPMI physical interfaces (called
+System Management Interfaces, or SMIs) also tie in here. This
+provides the kernelland interface for IPMI, but does not provide an
+interface for use by application processes.
+
+ipmi_devintf - This provides a userland IOCTL interface for the IPMI
+driver, each open file for this device ties in to the message handler
+as an IPMI user.
+
+ipmi_si - A driver for various system interfaces. This supports KCS,
+SMIC, and BT interfaces. Unless you have an SMBus interface or your
+own custom interface, you probably need to use this.
+
+ipmi_ssif - A driver for accessing BMCs on the SMBus. It uses the
+I2C kernel driver's SMBus interfaces to send and receive IPMI messages
+over the SMBus.
+
+ipmi_powernv - A driver for access BMCs on POWERNV systems.
+
+ipmi_watchdog - IPMI requires systems to have a very capable watchdog
+timer. This driver implements the standard Linux watchdog timer
+interface on top of the IPMI message handler.
+
+ipmi_poweroff - Some systems support the ability to be turned off via
+IPMI commands.
+
+bt-bmc - This is not part of the main driver, but instead a driver for
+accessing a BMC-side interface of a BT interface. It is used on BMCs
+running Linux to provide an interface to the host.
+
+These are all individually selectable via configuration options.
+
+Much documentation for the interface is in the include files. The
+IPMI include files are:
+
+linux/ipmi.h - Contains the user interface and IOCTL interface for IPMI.
+
+linux/ipmi_smi.h - Contains the interf