Commit c1aac62f authored by Linus Torvalds's avatar Linus Torvalds

Merge tag 'docs-4.11' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "A slightly quieter cycle for documentation this time around.

  Three more DocBook template files have been converted to RST; only 21
  to go. There are various build improvements and the usual array of
  documentation improvements and fixes"

* tag 'docs-4.11' of git://git.lwn.net/linux: (44 commits)
  docs / driver-api: Fix structure references in device_link.rst
  PM / docs: Fix structure references in device.rst
  Add a target to check broken external links in the Documentation
  Documentation: Fix linux-api list typo
  Documentation: DocBook/Makefile comment typo
  Improve sparse documentation
  Documentation: make Makefile.sphinx no-ops quieter
  Documentation: DMA-ISA-LPC.txt
  Documentation: input: fix path to input code definitions
  docs: Remove the copyright year from conf.py
  docs: Fix a warning in the Korean HOWTO.rst translation
  PM / sleep / docs: Convert PM notifiers document to reST
  PM / core / docs: Convert sleep states API document to reST
  PM / core: Update kerneldoc comments in pm.h
  doc-rst: Fix recursive make invocation from macros
  doc-rst: Delete output of failed dot-SVG conversion
  doc-rst: Break shell command sequences on failure
  Documentation/sphinx: make targets independent of Sphinx work for HAVE_SPHINX=0
  doc-rst: fixed cleandoc target when used with O=dir
  Documentation/sphinx: prevent generation of .pyc files in the source tree
  ...
parents fd7e9a88 bd856262
......@@ -42,7 +42,7 @@ requirements you pass the flag GFP_DMA to kmalloc.
Unfortunately the memory available for ISA DMA is scarce so unless you
allocate the memory during boot-up it's a good idea to also pass
__GFP_REPEAT and __GFP_NOWARN to make the allocater try a bit harder.
__GFP_REPEAT and __GFP_NOWARN to make the allocator try a bit harder.
(This scarcity also means that you should allocate the buffer as
early as possible and not release it until the driver is unloaded.)
......
......@@ -13,7 +13,7 @@ DOCBOOKS := z8530book.xml \
gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \
genericirq.xml s390-drivers.xml scsi.xml \
sh.xml regulator.xml w1.xml \
writing_musb_glue_layer.xml iio.xml
writing_musb_glue_layer.xml
ifeq ($(DOCBOOKS),)
......@@ -71,6 +71,7 @@ installmandocs: mandocs
# no-op for the DocBook toolchain
epubdocs:
latexdocs:
linkcheckdocs:
###
#External programs used
......@@ -272,6 +273,6 @@ cleandocs:
$(Q)rm -rf $(call objectify, $(clean-dirs))
# Declare the contents of the .PHONY variable as phony. We keep that
# information in a variable se we can use it in if_changed and friends.
# information in a variable so we can use it in if_changed and friends.
.PHONY: $(PHONY)
This diff is collapsed.
This diff is collapsed.
This diff is collapsed.
......@@ -43,7 +43,7 @@ ALLSPHINXOPTS = $(KERNELDOC_CONF) $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# commands; the 'cmd' from scripts/Kbuild.include is not *loopable*
loop_cmd = $(echo-cmd) $(cmd_$(1))
loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
# $2 sphinx builder e.g. "html"
# $3 name of the build subfolder / e.g. "media", used as:
......@@ -54,7 +54,8 @@ loop_cmd = $(echo-cmd) $(cmd_$(1))
# e.g. "media" for the linux-tv book-set at ./Documentation/media
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2;\
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media $2 && \
PYTHONDONTWRITEBYTECODE=1 \
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(srctree)/$(src)/$5/$(SPHINX_CONF)) \
$(SPHINXBUILD) \
-b $2 \
......@@ -63,13 +64,16 @@ quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
-D version=$(KERNELVERSION) -D release=$(KERNELRELEASE) \
$(ALLSPHINXOPTS) \
$(abspath $(srctree)/$(src)/$5) \
$(abspath $(BUILDDIR)/$3/$4);
$(abspath $(BUILDDIR)/$3/$4)
htmldocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
linkcheckdocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,linkcheck,$(var),,$(var)))
latexdocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,latex,$(var),latex,$(var)))
ifeq ($(HAVE_PDFLATEX),0)
......@@ -80,27 +84,34 @@ pdfdocs:
else # HAVE_PDFLATEX
pdfdocs: latexdocs
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex;)
$(foreach var,$(SPHINXDIRS), $(MAKE) PDFLATEX=$(PDFLATEX) LATEXOPTS="$(LATEXOPTS)" -C $(BUILDDIR)/$(var)/latex || exit;)
endif # HAVE_PDFLATEX
epubdocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,epub,$(var),epub,$(var)))
xmldocs:
@$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,xml,$(var),xml,$(var)))
endif # HAVE_SPHINX
# The following targets are independent of HAVE_SPHINX, and the rules should
# work or silently pass without Sphinx.
# no-ops for the Sphinx toolchain
sgmldocs:
@:
psdocs:
@:
mandocs:
@:
installmandocs:
@:
cleandocs:
$(Q)rm -rf $(BUILDDIR)
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) -C Documentation/media clean
endif # HAVE_SPHINX
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/media clean
dochelp:
@echo ' Linux kernel internal documentation in different formats (Sphinx):'
......@@ -109,6 +120,7 @@ dochelp:
@echo ' pdfdocs - PDF'
@echo ' epubdocs - EPUB'
@echo ' xmldocs - XML'
@echo ' linkcheckdocs - check for broken external links (will connect to external hosts)'
@echo ' cleandocs - clean all generated files'
@echo
@echo ' make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
......
......@@ -17,7 +17,7 @@ What is Linux?
loading, shared copy-on-write executables, proper memory management,
and multistack networking including IPv4 and IPv6.
It is distributed under the GNU General Public License - see the
It is distributed under the GNU General Public License v2 - see the
accompanying COPYING file for more details.
On what hardware does it run?
......@@ -236,7 +236,7 @@ Configuring the kernel
- Having unnecessary drivers will make the kernel bigger, and can
under some circumstances lead to problems: probing for a
nonexistent controller card may confuse your other controllers
nonexistent controller card may confuse your other controllers.
- A kernel with math-emulation compiled in will still use the
coprocessor if one is present: the math emulation will just
......
......@@ -93,9 +93,9 @@ Command Language Reference
At the lexical level, a command comprises a sequence of words separated
by spaces or tabs. So these are all equivalent::
nullarbor:~ # echo -c 'file svcsock.c line 1603 +p' >
nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' >
<debugfs>/dynamic_debug/control
nullarbor:~ # echo -c ' file svcsock.c line 1603 +p ' >
nullarbor:~ # echo -n ' file svcsock.c line 1603 +p ' >
<debugfs>/dynamic_debug/control
nullarbor:~ # echo -n 'file svcsock.c line 1603 +p' >
<debugfs>/dynamic_debug/control
......
......@@ -90,7 +90,7 @@ and thus removes any access restriction implied by it.
4. IOC_PR_PREEMPT
This ioctl command releases the existing reservation referred to by
old_key and replaces it with a a new reservation of type for the
old_key and replaces it with a new reservation of type for the
reservation key new_key.
......
......@@ -615,7 +615,7 @@ to allocate a page of memory for that task.
If a cpuset has its 'cpuset.cpus' modified, then each task in that cpuset
will have its allowed CPU placement changed immediately. Similarly,
if a task's pid is written to another cpusets 'cpuset.tasks' file, then its
if a task's pid is written to another cpuset's 'tasks' file, then its
allowed CPU placement is changed immediately. If such a task had been
bound to some subset of its cpuset using the sched_setaffinity() call,
the task will be allowed to run on any CPU allowed in its new cpuset,
......
......@@ -58,7 +58,7 @@ master_doc = 'index'
# General information about the project.
project = 'The Linux Kernel'
copyright = '2016, The kernel development community'
copyright = 'The kernel development community'
author = 'The kernel development community'
# The version info for the project you're documenting, acts as replacement for
......
This diff is collapsed.
......@@ -13,6 +13,7 @@ Core utilities
assoc_array
atomic_ops
cpu_hotplug
local_ops
workqueue
......
......@@ -82,7 +82,9 @@ UltraSPARC-III
-------
Several "PowerBook" and "iBook2" notebooks are supported.
The following POWER processors are supported in powernv mode:
POWER8
POWER9
1.5 SuperH
----------
......
This diff is collapsed.
......@@ -103,3 +103,9 @@ have already built it.
The optional make variable CF can be used to pass arguments to sparse. The
build system passes -Wbitwise to sparse automatically.
Checking RCU annotations
~~~~~~~~~~~~~~~~~~~~~~~~
RCU annotations are not checked by default. To enable RCU annotation
checks, include -DCONFIG_SPARSE_RCU_POINTER in your CF flags.
......@@ -116,9 +116,11 @@ crc32table.h*
cscope.*
defkeymap.c
devlist.h*
devicetable-offsets.h
dnotify_test
docproc
dslm
dtc
elf2ecoff
elfconfig.h*
evergreen_reg_safe.h
......@@ -153,8 +155,8 @@ keywords.c
ksym.c*
ksym.h*
kxgettext
lex.c
lex.*.c
*lex.c
*lex.*.c
linux
logo_*.c
logo_*_clut224.c
......@@ -215,6 +217,7 @@ series
setup
setup.bin
setup.elf
sortextable
sImage
sm_tbl*
split-include
......
.. Copyright 2001 Matthew Wilcox
..
.. This documentation is free software; you can redistribute
.. it and/or modify it under the terms of the GNU General Public
.. License as published by the Free Software Foundation; either
.. version 2 of the License, or (at your option) any later
.. version.
===============================
Bus-Independent Device Accesses
===============================
:Author: Matthew Wilcox
:Author: Alan Cox
Introduction
============
Linux provides an API which abstracts performing IO across all busses
and devices, allowing device drivers to be written independently of bus
type.
Memory Mapped IO
================
Getting Access to the Device
----------------------------
The most widely supported form of IO is memory mapped IO. That is, a
part of the CPU's address space is interpreted not as accesses to
memory, but as accesses to a device. Some architectures define devices
to be at a fixed address, but most have some method of discovering
devices. The PCI bus walk is a good example of such a scheme. This
document does not cover how to receive such an address, but assumes you
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
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
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()`.
Accessing the device
--------------------
The part of the interface most used by drivers is reading and writing
memory-mapped registers on the device. Linux provides interfaces to read
and write 8-bit, 16-bit, 32-bit and 64-bit quantities. Due to a
historical accident, these are named byte, word, long and quad accesses.
Both read and write accesses are supported; there is no prefetch support
at this time.
The functions are named readb(), readw(), readl(), readq(),
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
provided. Do not use memset or memcpy on IO addresses; they are not
guaranteed to copy data in order.
The read and write functions are defined to be ordered. That is the
compiler is not permitted to reorder the I/O sequence. When the ordering
can be compiler optimised, you can use __readb() and friends to
indicate the relaxed ordering. Use this with care.
While the basic functions are defined to be synchronous with respect to
each other and ordered with respect to each other the busses the devices
sit on may themselves have asynchronicity. In particular many authors
are burned by the fact that PCI bus writes are posted asynchronously. A
driver author must issue a read from the same device to ensure that
writes have occurred in the specific cases the author cares. This kind
of property cannot be hidden from driver writers in the API. In some
cases, the read used to flush the device may be expected to fail (if the
card is resetting, for example). In that case, the read should be done
from config space, which is guaranteed to soft-fail if the card doesn't
respond.
The following is an example of flushing a write to a device when the
driver would like to ensure the write's effects are visible prior to
continuing execution::
static inline void
qla1280_disable_intrs(struct scsi_qla_host *ha)
{
struct device_reg *reg;
reg = ha->iobase;
/* disable risc and host interrupts */
WRT_REG_WORD(&reg->ictrl, 0);
/*
* The following read will ensure that the above write
* has been received by the device before we return from this
* function.
*/
RD_REG_WORD(&reg->ictrl);
ha->flags.ints_enabled = 0;
}
In addition to write posting, on some large multiprocessing systems
(e.g. SGI Challenge, Origin and Altix machines) posted writes won't be
strongly ordered coming from different CPUs. Thus it's important to
properly protect parts of your driver that do memory-mapped writes with
locks and use the :c:func:`mmiowb()` to make sure they arrive in the
order intended. Issuing a regular readX() will also ensure write ordering,
but should only be used when the
driver has to be sure that the write has actually arrived at the device
(not that it's simply ordered with respect to other writes), since a
full readX() is a relatively expensive operation.
Generally, one should use :c:func:`mmiowb()` prior to releasing a spinlock
that protects regions using :c:func:`writeb()` or similar functions that
aren't surrounded by readb() calls, which will ensure ordering
and flushing. The following pseudocode illustrates what might occur if
write ordering isn't guaranteed via :c:func:`mmiowb()` or one of the
readX() functions::
CPU A: spin_lock_irqsave(&dev_lock, flags)
CPU A: ...
CPU A: writel(newval, ring_ptr);
CPU A: spin_unlock_irqrestore(&dev_lock, flags)
...
CPU B: spin_lock_irqsave(&dev_lock, flags)
CPU B: writel(newval2, ring_ptr);
CPU B: ...
CPU B: spin_unlock_irqrestore(&dev_lock, flags)
In the case above, newval2 could be written to ring_ptr before newval.
Fixing it is easy though::
CPU A: spin_lock_irqsave(&dev_lock, flags)
CPU A: ...
CPU A: writel(newval, ring_ptr);
CPU A: mmiowb(); /* ensure no other writes beat us to the device */
CPU A: spin_unlock_irqrestore(&dev_lock, flags)
...
CPU B: spin_lock_irqsave(&dev_lock, flags)
CPU B: writel(newval2, ring_ptr);
CPU B: ...
CPU B: mmiowb();
CPU B: spin_unlock_irqrestore(&dev_lock, flags)
See tg3.c for a real world example of how to use :c:func:`mmiowb()`
PCI ordering rules also guarantee that PIO read responses arrive after any
outstanding DMA writes from that bus, since for some devices the result of
a readb() call may signal to the driver that a DMA transaction is
complete. In many cases, however, the driver may want to indicate that the
next readb() call has no relation to any previous DMA writes
performed by the device. The driver can use readb_relaxed() for
these cases, although only some platforms will honor the relaxed
semantics. Using the relaxed read functions will provide significant
performance benefits on platforms that support it. The qla2xxx driver
provides examples of how to use readX_relaxed(). In many cases, a majority
of the driver's readX() calls can safely be converted to readX_relaxed()
calls, since only a few will indicate or depend on DMA completion.
Port Space Accesses
===================
Port Space Explained
--------------------
Another form of IO commonly supported is Port Space. This is a range of
addresses separate to the normal memory address space. Access to these
addresses is generally not as fast as accesses to the memory mapped
addresses, and it also has a potentially smaller address space.
Unlike memory mapped IO, no preparation is required to access port
space.
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()`.
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
port.
Public Functions Provided
=========================
.. kernel-doc:: arch/x86/include/asm/io.h
:internal:
.. kernel-doc:: lib/pci_iomap.c
:export:
.. |struct dev_pm_domain| replace:: :c:type:`struct dev_pm_domain <dev_pm_domain>`
.. |struct generic_pm_domain| replace:: :c:type:`struct generic_pm_domain <generic_pm_domain>`
============
Device links
============
......@@ -120,12 +123,11 @@ Examples
is the same as if the MMU was the parent of the master device.
The fact that both devices share the same power domain would normally
suggest usage of a :c:type:`struct dev_pm_domain` or :c:type:`struct
generic_pm_domain`, however these are not independent devices that
happen to share a power switch, but rather the MMU device serves the
busmaster device and is useless without it. A device link creates a
synthetic hierarchical relationship between the devices and is thus
more apt.
suggest usage of a |struct dev_pm_domain| or |struct generic_pm_domain|,
however these are not independent devices that happen to share a power
switch, but rather the MMU device serves the busmaster device and is
useless without it. A device link creates a synthetic hierarchical
relationship between the devices and is thus more apt.
* A Thunderbolt host controller comprises a number of PCIe hotplug ports
and an NHI device to manage the PCIe switch. On resume from system sleep,
......@@ -157,7 +159,7 @@ Examples
Alternatives
============
* A :c:type:`struct dev_pm_domain` can be used to override the bus,
* A |struct dev_pm_domain| can be used to override the bus,
class or device type callbacks. It is intended for devices sharing
a single on/off switch, however it does not guarantee a specific
suspend/resume ordering, this needs to be implemented separately.
......@@ -166,7 +168,7 @@ Alternatives
suspended. Furthermore it cannot be used to enforce a specific shutdown
ordering or a driver presence dependency.
* A :c:type:`struct generic_pm_domain` is a lot more heavyweight than a
* A |struct generic_pm_domain| is a lot more heavyweight than a
device link and does not allow for shutdown ordering or driver presence
dependencies. It also cannot be used on ACPI systems.
......
=======
Buffers
=======
* struct :c:type:`iio_buffer` — general buffer structure
* :c:func:`iio_validate_scan_mask_onehot` — Validates that exactly one channel
is selected
* :c:func:`iio_buffer_get` — Grab a reference to the buffer
* :c:func:`iio_buffer_put` — Release the reference to the buffer
The Industrial I/O core offers a way for continuous data capture based on a
trigger source. Multiple data channels can be read at once from
:file:`/dev/iio:device{X}` character device node, thus reducing the CPU load.
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:`length`, the total number of data samples (capacity) that can be
stored by the buffer.
* :file:`enable`, activate buffer capture.
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 file 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
channel.
* :file:`type`, description of the scan element data storage within the buffer
and hence the form in which it is read from user space.
Format is [be|le]:[s|u]bits/storagebitsXrepeat[>>shift] .
* *be* or *le*, specifies big or little endian.
* *s* or *u*, specifies if signed (2's complement) or unsigned.
* *bits*, is the number of valid data bits.
* *storagebits*, is the number of bits (after padding) that it occupies in the
buffer.
* *shift*, if specified, is the shift that needs to be applied prior to
masking out unused bits.
* *repeat*, specifies the number of bits/storagebits repetitions. When the
repeat element is 0 or 1, then the repeat value is omitted.
For example, a driver for a 3-axis accelerometer with 12 bit resolution where
data is stored in two 8-bits registers as follows::
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
|D3 |D2 |D1 |D0 | X | X | X | X | (LOW byte, address 0x06)
+---+---+---+---+---+---+---+---+
7 6 5 4 3 2 1 0
+---+---+---+---+---+---+---+---+
|D11|D10|D9 |D8 |D7 |D6 |D5 |D4 | (HIGH byte, address 0x07)
+---+---+---+---+---+---+---+---+
will have the following scan element type for each axis::
$ cat /sys/bus/iio/devices/iio:device0/scan_elements/in_accel_y_type
le:s12/16>>4
A user space application will interpret data samples read from the buffer as
two byte little endian signed data, that needs a 4 bits right shift before
masking out the 12 valid bits of data.
For implementing buffer support a driver should initialize the following
fields in iio_chan_spec definition::
struct iio_chan_spec {
/* other members */
int scan_index
struct {
char sign;
u8 realbits;
u8 storagebits;
u8 shift;
u8 repeat;
enum iio_endian endianness;
} scan_type;
};
The driver implementing the accelerometer described above will have the
following channel definition::
struct struct iio_chan_spec accel_channels[] = {
{
.type = IIO_ACCEL,
.modified = 1,
.channel2 = IIO_MOD_X,
/* other stuff here */
.scan_index = 0,
.scan_type = {
.sign = 's',
.realbits = 12,
.storagebits = 16,
.shift = 4,
.endianness = IIO_LE,
},
}
/* similar for Y (with channel2 = IIO_MOD_Y, scan_index = 1)
* and Z (with channel2 = IIO_MOD_Z, scan_index = 2) axis
*/
}
Here **scan_index** defines the order in which the enabled channels are placed
inside the buffer. Channels with a lower **scan_index** will be placed before
channels with a higher index. Each channel needs to have a unique
**scan_index**.
Setting **scan_index** to -1 can be used to indicate that the specific channel
does not support buffered capture. In this case no entries will be created for
the channel in the scan_elements directory.
More details
============
.. kernel-doc:: include/linux/iio/buffer.h
.. kernel-doc:: drivers/iio/industrialio-buffer.c
:export:
=============
Core elements
=============
The Industrial I/O core offers a unified framework for writing drivers for
many different types of embedded sensors. a standard interface to user space
applications manipulating sensors. The implementation can be found under
:file:`drivers/iio/industrialio-*`
Industrial I/O Devices
----------------------
* struct :c:type:`iio_dev` - industrial I/O device
* :c:func:`iio_device_alloc()` - alocate an :c:type:`iio_dev` from a driver
* :c:func:`iio_device_free()` - free an :c:type:`iio_dev` from a driver
* :c:func:`iio_device_register()` - register a device with the IIO subsystem
* :c:func:`iio_device_unregister()` - unregister a device from the IIO
subsystem
An IIO device usually corresponds to a single hardware sensor and it
provides all the information needed by a driver handling a device.
Let's first have a look at the functionality embedded in an IIO device
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
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.
A typical IIO driver will register itself as an :doc:`I2C <../i2c>` or
:doc:`SPI <../spi>` driver and will create two routines, probe and remove.
At probe:
1. Call :c:func:`iio_device_alloc()`, which allocates memory for an IIO device.
2. Initialize IIO device fields with driver specific information (e.g.
device name, device channels).
3. Call :c:func:`iio_device_register()`, this registers the device with the
IIO core. After this call the device is ready to accept requests from user
space applications.
At remove, we free the resources allocated in probe in reverse order:
1. :c:func:`iio_device_unregister()`, unregister the device from the IIO core.
2. :c:func:`iio_device_free()`, free the memory allocated for the IIO device.
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:
* :file:`name`, description of the physical chip.
* :file:`dev`, shows the major:minor pair associated with
:file:`/dev/iio:deviceX` node.
* :file:`sampling_frequency_available`, available discrete set of sampling
frequency values for device.
* Available standard attributes for IIO devices are described in the
:file:`Documentation/ABI/testing/sysfs-bus-iio` file in the Linux kernel
sources.
IIO device channels
===================
struct :c:type:`iio_chan_spec` - specification of a single channel
An IIO device channel is a representation of a data channel. An IIO device can
have one or multiple channels. For example:
* a thermometer sensor has one channel representing the temperature measurement.
* a light sensor with two channels indicating the measurements in the visible
and infrared spectrum.
* an accelerometer can have up to 3 channels representing acceleration on X, Y
and Z axes.
An IIO channel is described by the struct :c:type:`iio_chan_spec`.
A thermometer driver for the temperature sensor in the example above would
have to describe its channel as follows::
static const struct iio_chan_spec temp_channel[] = {
{
.type = IIO_TEMP,
.info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
},
};
Channel sysfs attributes exposed to userspace are specified in the form of
bitmasks. Depending on their shared info, attributes can be set in one of the
following masks:
* **info_mask_separate**, attributes will be specific to
this channel
* **info_mask_shared_by_type**, attributes are shared by all channels of the
same type
* **info_mask_shared_by_dir**, attributes are shared by all channels of the same
direction
* **info_mask_shared_by_all**, attributes are shared by all channels
When there are multiple data channels per channel type we have two ways to
distinguish between them:
* set **.modified** field of :c:type:`iio_chan_spec` to 1. Modifiers are
specified using **.channel2** field of the same :c:type:`iio_chan_spec`
structure and are used to indicate a physically unique characteristic of the
channel such as its direction or spectral response. For example, a light
sensor can have two channels, one for infrared light and one for both
infrared and visible light.
* set **.indexed** field of :c:type:`iio_chan_spec` to 1. In this case the
channel is simply another instance with an index specified by the **.channel**
field.
Here is how we can make use of the channel's modifiers::
static const struct iio_chan_spec light_channels[] = {
{
.type = IIO_INTENSITY,
.modified = 1,
.channel2 = IIO_MOD_LIGHT_IR,
.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
.info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
},
{
.type = IIO_INTENSITY,
.modified = 1,
.channel2 = IIO_MOD_LIGHT_BOTH,
.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
.info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
},
{
.type = IIO_LIGHT,
.info_mask_separate = BIT(IIO_CHAN_INFO_PROCESSED),
.info_mask_shared = BIT(IIO_CHAN_INFO_SAMP_FREQ),
},
}
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`
one file for processed data:
* :file:`/sys/bus/iio/iio:device{X}/in_illuminance_input`
and one shared sysfs file for sampling frequency:
* :file:`/sys/bus/iio/iio:device{X}/sampling_frequency`.
Here is how we can make use of the channel's indexing::
static const struct iio_chan_spec light_channels[] = {
{
.type = IIO_VOLTAGE,
.indexed = 1,
.channel = 0,
.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
},
{
.type = IIO_VOLTAGE,
.indexed = 1,
.channel = 1,
.info_mask_separate = BIT(IIO_CHAN_INFO_RAW),
},
}
This will generate two separate attributes files for raw data retrieval:
* :file:`/sys/bus/iio/devices/iio:device{X}/in_voltage0_raw`, representing
voltage measurement for channel 0.
* :file:`/sys/bus/iio/devices/iio:device{X}/in_voltage1_raw`, representing
voltage measurement for channel 1.
More details
============
.. kernel-doc:: include/linux/iio/iio.h
.. kernel-doc:: drivers/iio/industrialio-core.c
:export:
.. include:: <isonum.txt>
Industrial I/O
==============
**Copyright** |copy| 2015 Intel Corporation
Contents:
.. toctree::
:maxdepth: 2
intro
core
buffers
triggers
triggered-buffers
.. include:: <isonum.txt>
============
Introduction
============
The main purpose of the Industrial I/O subsystem (IIO) is to provide support
for devices that in some sense perform either
analog-to-digital conversion (ADC) or digital-to-analog conversion (DAC)
or both. The aim is to fill the gap between the somewhat similar hwmon and
:doc:`input <../input>` subsystems. Hwmon is directed at low sample rate
sensors used to monitor and control the system itself, like fan speed control
or temperature measurement. :doc:`Input <../input>` is, as its name suggests,
focused on human interaction input devices (keyboard, mouse, touchscreen).
In some cases there is considerable overlap between these and IIO.
Devices that fall into this category include:
* analog to digital converters (ADCs)
* accelerometers
* capacitance to digital converters (CDCs)
* digital to analog converters (DACs)
* gyroscopes
* inertial measurement units (IMUs)
* color and light sensors
* magnetometers
* pressure sensors
* proximity sensors
* temperature sensors
Usually these sensors are connected via :doc:`SPI <../spi>` or
:doc:`I2C <../i2c>`. A common use case of the sensors devices is to have
combined functionality (e.g. light plus proximity sensor).
=================
Triggered Buffers
=================
Now that we know what buffers and triggers are let's see how they work together.
IIO triggered buffer setup
==========================
* :c:func:`iio_triggered_buffer_setup` — Setup triggered buffer and pollfunc
* :c:func:`iio_triggered_buffer_cleanup` — Free resources allocated by
:c:func:`iio_triggered_buffer_setup`
* struct :c:type:`iio_buffer_setup_ops` — buffer setup related callbacks
A typical triggered buffer setup looks like this::
const struct iio_buffer_setup_ops sensor_buffer_setup_ops = {
.preenable = sensor_buffer_preenable,
.postenable = sensor_buffer_postenable,
.postdisable = sensor_buffer_postdisable,
.predisable = sensor_buffer_predisable,
};
irqreturn_t sensor_iio_pollfunc(int irq, void *p)
{
pf->timestamp = iio_get_time_ns((struct indio_dev *)p);
return IRQ_WAKE_THREAD;
}
irqreturn_t sensor_trigger_handler(int irq, void *p)
{
u16 buf[8];
int i = 0;
/* read data for each active channel */
for_each_set_bit(bit, active_scan_mask, masklength)
buf[i++] = sensor_get_data(bit)
iio_push_to_buffers_with_timestamp(indio_dev, buf, timestamp);
iio_trigger_notify_done(trigger);
return IRQ_HANDLED;
}
/* setup triggered buffer, usually in probe function */
iio_triggered_buffer_setup(indio_dev, sensor_iio_polfunc,
sensor_trigger_handler,
sensor_buffer_setup_ops);
The important things to notice here are:
* :c:type:`iio_buffer_setup_ops`, the buffer setup functions to be called at
predefined points in the buffer configuration sequence (e.g. before enable,
after disable). If not specified, the IIO core uses the default
iio_triggered_buffer_setup_ops.
* **sensor_iio_pollfunc**, the function that will be used as top half of poll
function. It should do as little processing as possible, because it runs in
interrupt context. The most common operation is recording of the current
timestamp and for this reason one can use the IIO core defined
:c:func:`iio_pollfunc_store_time` function.
* **sensor_trigger_handler**, the function that will be used as bottom half of
the poll function. This runs in the context of a kernel thread and all the
processing takes place here. It usually reads data from the device and
stores it in the internal buffer together with the timestamp recorded in the
top half.
More details
============
.. kernel-doc:: drivers/iio/buffer/industrialio-triggered-buffer.c
========
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
In many situations it is useful for a driver to be able to capture data based
on some external event (trigger) as opposed to periodically polling for data.
An IIO trigger can be provided by a device driver that also has an IIO device
based on hardware generated events (e.g. data ready or threshold exceeded) or
provided by a separate driver from an independent interrupt source (e.g. GPIO
line connected to some external system, timer interrupt or user space writing
a specific file in sysfs). A trigger may initiate data capture for a number of
sensors and also it may be completely unrelated to the sensor itself.
IIO trigger sysfs interface
===========================
There are two locations in sysfs related to triggers:
* :file:`/sys/bus/iio/devices/trigger{Y}/*`, this file is created once an
IIO trigger is registered with the IIO core and corresponds to trigger
with index Y.
Because triggers can be very different depending on type there are few
standard attributes that we can describe here:
* :file:`name`, trigger name that can be later used for association with a
device.
* :file:`sampling_frequency`, some timer based triggers use this attribute to
specify the frequency for trigger calls.
* :file:`/sys/bus/iio/devices/iio:device{X}/trigger/*`, this directory is
created once the device supports a triggered buffer. We can associate a
trigger with our device by writing the trigger's name in the
:file:`current_trigger` file.
IIO trigger setup
=================
Let's see a simple example of how to setup a trigger to be used by a driver::
struct iio_trigger_ops trigger_ops = {
.set_trigger_state = sample_trigger_state,
.validate_device = sample_validate_device,
}
struct iio_trigger *trig;
/* first, allocate memory for our trigger */
trig = iio_trigger_alloc(dev, "trig-%s-%d", name, idx);
/* setup trigger operations field */
trig->ops = &trigger_ops;
/* now register the trigger with the IIO core */
iio_trigger_register(trig);
IIO trigger ops
===============
* struct :c:type:`iio_trigger_ops` — operations structure for an iio_trigger.
Notice that a trigger has a set of operations attached:
* :file:`set_trigger_state`, switch the trigger on/off on demand.
* :file:`validate_device`, function to validate the device when the current
trigger gets changed.
More details
============
.. kernel-doc:: include/linux/iio/trigger.h
.. kernel-doc:: drivers/iio/industrialio-trigger.c
:export:
......@@ -16,11 +16,15 @@ available subsections can be seen below.
basics
infrastructure
pm/index
device-io
dma-buf
device_link
message-based
sound
frame-buffer
regulator
iio/index
input
usb
spi
......
# -*- coding: utf-8; mode: python -*-
project = "Device Power Management"
tags.add("subproject")
latex_documents = [
('index', 'pm.tex', project,
'The kernel development community', 'manual'),
]
=======================
Device Power Management
=======================
.. toctree::
devices
notifiers
types
.. only:: subproject and html
Indices
=======
* :ref:`genindex`
=============================
Suspend/Hibernation Notifiers
=============================
::
Copyright (c) 2016 Intel Corp., Rafael J. Wysocki <rafael.j.wysocki@intel.com>
There are some operations that subsystems or drivers may want to carry out
before hibernation/suspend or after restore/resume, but they require the system
to be fully functional, so the drivers' and subsystems' ``->suspend()`` and
``->resume()`` or even ``->prepare()`` and ``->complete()`` callbacks are not
suitable for this purpose.
For example, device drivers may want to upload firmware to their devices after
resume/restore, but they cannot do it by calling :c:func:`request_firmware()`
from their ``->resume()`` or ``->complete()`` callback routines (user land
processes are frozen at these points). The solution may be to load the firmware
into memory before processes are frozen and upload it from there in the
``->resume()`` routine. A suspend/hibernation notifier may be used for that.
Subsystems or drivers having such needs can register suspend notifiers that
will be called upon the following events by the PM core:
``PM_HIBERNATION_PREPARE``
The system is going to hibernate, tasks will be frozen immediately. This
is different from ``PM_SUSPEND_PREPARE`` below, because in this case
additional work is done between the notifiers and the invocation of PM
callbacks for the "freeze" transition.
``PM_POST_HIBERNATION``
The system memory state has been restored from a hibernation image or an
error occurred during hibernation. Device restore callbacks have been
executed and tasks have been thawed.
``PM_RESTORE_PREPARE``
The system is going to restore a hibernation image. If all goes well,
the restored image kernel will issue a ``PM_POST_HIBERNATION``
notification.
``PM_POST_RESTORE``
An error occurred during restore from hibernation. Device restore
callbacks have been executed and tasks have been thawed.
``PM_SUSPEND_PREPARE``
The system is preparing for suspend.
``PM_POST_SUSPEND``
The system has just resumed or an error occurred during suspend. Device
resume callbacks have been executed and tasks have been thawed.
It is generally assumed that whatever the notifiers do for
``PM_HIBERNATION_PREPARE``, should be undone for ``PM_POST_HIBERNATION``.
Analogously, operations carried out for ``PM_SUSPEND_PREPARE`` should be
reversed for ``PM_POST_SUSPEND``.
Moreover, if one of the notifiers fails for the ``PM_HIBERNATION_PREPARE`` or
``PM_SUSPEND_PREPARE`` event, the notifiers that have already succeeded for that
event will be called for ``PM_POST_HIBERNATION`` or ``PM_POST_SUSPEND``,
respectively.
The hibernation and suspend notifiers are called with :c:data:`pm_mutex` held.
They are defined in the usual way, but their last argument is meaningless (it is
always NULL).
To register and/or unregister a suspend notifier use
:c:func:`register_pm_notifier()` and :c:func:`unregister_pm_notifier()`,
respectively (both defined in :file:`include/linux/suspend.h`). If you don't
need to unregister the notifier, you can also use the :c:func:`pm_notifier()`
macro defined in :file:`include/linux/suspend.h`.
==================================
Device Power Management Data Types
==================================
.. kernel-doc:: include/linux/pm.h
.. Copyright 2007-2008 Wolfson Microelectronics
.. This documentation is free software; you can redistribute
.. it and/or modify it under the terms of the GNU General Public
.. License version 2 as published by the Free Software Foundation.
=================================
Voltage and current regulator API
=================================
:Author: Liam Girdwood
:Author: Mark Brown
Introduction
============
This framework is designed to provide a standard kernel interface to
control voltage and current regulators.
The intention is to allow systems to dynamically control regulator power
output in order to save power and prolong battery life. This applies to
both voltage regulators (where voltage output is controllable) and
current sinks (where current limit is controllable).
Note that additional (and currently more complete) documentation is
available in the Linux kernel source under
``Documentation/power/regulator``.
Glossary
--------
The regulator API uses a number of terms which may not be familiar:
Regulator
Electronic device that supplies power to other devices. Most regulators
can enable and disable their output and some can also control their
output voltage or current.
Consumer
Electronic device which consumes power provided by a regulator. These
may either be static, requiring only a fixed supply, or dynamic,
requiring active management of the regulator at runtime.
Power Domain
The electronic circuit supplied by a given regulator, including the
regulator and all consumer devices. The configuration of the regulator
is shared between all the components in the circuit.
Power Management Integrated Circuit (PMIC)
An IC which contains numerous regulators and often also other
subsystems. In an embedded system the primary PMIC is often equivalent
to a combination of the PSU and southbridge in a desktop system.
Consumer driver interface
=========================
This offers a similar API to the kernel clock framework. Consumer
drivers use `get <#API-regulator-get>`__ and
`put <#API-regulator-put>`__ operations to acquire and release
regulators. Functions are provided to `enable <#API-regulator-enable>`__
and `disable <#API-regulator-disable>`__ the regulator and to get and
set the runtime parameters of the regulator.
When requesting regulators consumers use symbolic names for their
supplies, such as "Vcc", which are mapped into actual regulator devices
by the machine interface.
A stub version of this API is provided when the regulator framework is
not in use in order to minimise the need to use ifdefs.
Enabling and disabling
----------------------
The regulator API provides reference counted enabling and disabling of
regulators. Consumer devices use the :c:func:`regulator_enable()` and
:c:func:`regulator_disable()` functions to enable and disable
regulators. Calls to the two functions must be balanced.
Note that since multiple consumers may be using a regulator and machine
constraints may not allow the regulator to be disabled there is no
guarantee that calling :c:func:`regulator_disable()` will actually
cause the supply provided by the regulator to be disabled. Consumer
drivers should assume that the regulator may be enabled at all times.
Configuration
-------------
Some consumer devices may need to be able to dynamically configure their
supplies. For example, MMC drivers may need to select the correct
operating voltage for their cards. This may be done while the regulator
is enabled or disabled.
The :c:func:`regulator_set_voltage()` and
:c:func:`regulator_set_current_limit()` functions provide the primary
interface for this. Both take ranges of voltages and currents, supporting
drivers that do not require a specific value (eg, CPU frequency scaling
normally permits the CPU to use a wider range of supply voltages at lower
frequencies but does not require that the supply voltage be lowered). Where
an exact value is required both minimum and maximum values should be
identical.
Callbacks
---------
Callbacks may also be registered for events such as regulation failures.
Regulator driver interface
==========================
Drivers for regulator chips register the regulators with the regulator
core, providing operations structures to the core. A notifier interface
allows error conditions to be reported to the core.
Registration should be triggered by explicit setup done by the platform,
supplying a struct :c:type:`regulator_init_data` for the regulator
containing constraint and supply information.
Machine interface
=================
This interface provides a way to define how regulators are connected to
consumers on a given system and what the valid operating parameters are
for the system.
Supplies
--------
Regulator supplies are specified using struct
:c:type:`regulator_consumer_supply`. This is done at driver registration
time as part of the machine constraints.
Constraints
-----------
As well as defining the connections the machine interface also provides
constraints defining the operations that clients are allowed to perform
and the parameters that may be set. This is required since generally
regulator devices will offer more flexibility than it is safe to use on
a given system, for example supporting higher supply voltages than the
consumers are rated for.
This is done at driver registration time` by providing a
struct :c:type:`regulation_constraints`.
The constraints may also specify an initial configuration for the
regulator in the constraints, which is particularly useful for use with
static consumers.
API reference
=============
Due to limitations of the kernel documentation framework and the
existing layout of the source code the entire regulator API is
documented here.
.. kernel-doc:: include/linux/regulator/consumer.h
:internal:
.. kernel-doc:: include/linux/regulator/machine.h
:internal:
.. kernel-doc:: include/linux/regulator/driver.h
:internal:
.. kernel-doc:: drivers/regulator/core.c
:export:
......@@ -117,10 +117,10 @@ support, which is achieved via the R0 and R1 config register bits, where:
R0..R1
------
0 0 => 9 bits, 0.5 degrees Celcius
1 0 => 10 bits, 0.25 degrees Celcius
0 1 => 11 bits, 0.125 degrees Celcius
1 1 => 12 bits, 0.0625 degrees Celcius
0 0 => 9 bits, 0.5 degrees Celsius
1 0 => 10 bits, 0.25 degrees Celsius
0 1 => 11 bits, 0.125 degrees Celsius
1 1 => 12 bits, 0.0625 degrees Celsius
Note:
At initial device power-on, the default resolution is set to 12-bits.
......
......@@ -68,6 +68,14 @@ Korean translations
translations/ko_KR/index
Chinese translations
--------------------
.. toctree::
:maxdepth: 1
translations/zh_CN/index
Indices and tables
==================
......
......@@ -279,10 +279,10 @@ struct input_event {
'time' is the timestamp, it returns the time at which the event happened.
Type is for example EV_REL for relative moment, EV_KEY for a keypress or
release. More types are defined in include/linux/input.h.
release. More types are defined in include/uapi/linux/input-event-codes.h.
'code' is event code, for example REL_X or KEY_BACKSPACE, again a complete
list is in include/linux/input.h.
list is in include/uapi/linux/input-event-codes.h.
'value' is the value the event carries. Either a relative change for
EV_REL, absolute new value for EV_ABS (joysticks ...), or 0 for EV_KEY for
......
......@@ -24,7 +24,7 @@ Prerequisites
-------------
First the prerequisites. Without these you have already failed, because you
will need to add a a 32-bit compat layer:
will need to add a 32-bit compat layer:
* Only use fixed sized integers. To avoid conflicts with typedefs in userspace
the kernel has special types like __u32, __s64. Use them.
......
......@@ -358,7 +358,7 @@ The current Livepatch implementation has several limitations:
Each function has to handle TOC and save LR before it could call
the ftrace handler. This operation has to be reverted on return.
Fortunately, the generic ftrace code has the same problem and all
this is is handled on the ftrace level.
this is handled on the ftrace level.
+ Kretprobes using the ftrace framework conflict with the patched
......
......@@ -36,7 +36,7 @@ quiet_cmd_genpdf = GENPDF $2
cmd_genpdf = convert $2 $3
quiet_cmd_gendot = DOT $2
cmd_gendot = dot -Tsvg $2 > $3
cmd_gendot = dot -Tsvg $2 > $3 || { rm -f $3; exit 1; }
%.pdf: %.svg
@$(call cmd,genpdf,$<,$@)
......@@ -103,6 +103,7 @@ html: all
epub: all
xml: all
latex: $(IMGPDF) all
linkcheck:
clean:
-rm -f $(DOTTGT) $(IMGTGT) ${TARGETS} 2>/dev/null
......
......@@ -272,7 +272,7 @@ on the socket thus waking up the application thread. When the application
sees the error (which may just be a disconnect) it should unattach the
socket from KCM and then close it. It is assumed that once an error is
posted on the TCP socket the data stream is unrecoverable (i.e. an error
may have occurred in in the middle of receiving a messssge).
may have occurred in the middle of receiving a messssge).
TCP connection monitoring
-------------------------
......
......@@ -14,8 +14,6 @@ freezing-of-tasks.txt
- How processes and controlled during suspend
interface.txt
- Power management user interface in /sys/power
notifiers.txt
- Registering suspend notifiers in device drivers
opp.txt
- Operating Performance Point library
pci.txt
......
......@@ -197,7 +197,8 @@ tasks, since it generally exists anyway.
A driver must have all firmwares it may need in RAM before suspend() is called.
If keeping them is not practical, for example due to their size, they must be
requested early enough using the suspend notifier API described in notifiers.txt.
requested early enough using the suspend notifier API described in
Documentation/driver-api/pm/notifiers.rst.
VI. Are there any precautions to be taken to prevent freezing failures?
......
Suspend notifiers
(C) 2007-2011 Rafael J. Wysocki <rjw@sisk.pl>, GPL
There are some operations that subsystems or drivers may want to carry out
before hibernation/suspend or after restore/resume, but they require the system
to be fully functional, so the drivers' and subsystems' .suspend() and .resume()
or even .prepare() and .complete() callbacks are not suitable for this purpose.
For example, device drivers may want to upload firmware to their devices after
resume/restore, but they cannot do it by calling request_firmware() from their
.resume() or .complete() routines (user land processes are frozen at these
points). The solution may be to load the firmware into memory before processes
are frozen and upload it from there in the .resume() routine.
A suspend/hibernation notifier may be used for this purpose.
The subsystems or drivers having such needs can register suspend notifiers that
will be called upon the following events by the PM core:
PM_HIBERNATION_PREPARE The system is going to hibernate, tasks will be frozen
immediately. This is different from PM_SUSPEND_PREPARE
below because here we do additional work between notifiers
and drivers freezing.
PM_POST_HIBERNATION The system memory state has been restored from a
hibernation image or an error occurred during
hibernation. Device drivers' restore callbacks have
been executed and tasks have been thawed.
PM_RESTORE_PREPARE The system is going to restore a hibernation image.
If all goes well, the restored kernel will issue a
PM_POST_HIBERNATION notification.
PM_POST_RESTORE An error occurred during restore from hibernation.
Device drivers' restore callbacks have been executed
and tasks have been thawed.
PM_SUSPEND_PREPARE The system is preparing for suspend.
PM_POST_SUSPEND The system has just resumed or an error occurred during
suspend. Device drivers' resume callbacks have been
executed and tasks have been thawed.
It is generally assumed that whatever the notifiers do for
PM_HIBERNATION_PREPARE, should be undone for PM_POST_HIBERNATION. Analogously,
operations performed for PM_SUSPEND_PREPARE should be reversed for
PM_POST_SUSPEND. Additionally, all of the notifiers are called for
PM_POST_HIBERNATION if one of them fails for PM_HIBERNATION_PREPARE, and
all of the notifiers are called for PM_POST_SUSPEND if one of them fails for
PM_SUSPEND_PREPARE.
The hibernation and suspend notifiers are called with pm_mutex held. They are
defined in the usual way, but their last argument is meaningless (it is always
NULL). To register and/or unregister a suspend notifier use the functions
register_pm_notifier() and unregister_pm_notifier(), respectively, defined in
include/linux/suspend.h . If you don't need to unregister the notifier, you can
also use the pm_notifier() macro defined in include/linux/suspend.h .
......@@ -713,7 +713,7 @@ In addition to that the prepare() callback may carry out some operations
preparing the device to be suspended, although it should not allocate memory
(if additional memory is required to suspend the device, it has to be
preallocated earlier, for example in a suspend/hibernate notifier as described
in Documentation/power/notifiers.txt).
in Documentation/driver-api/pm/notifiers.rst).
3.1.2. suspend()
......
......@@ -63,7 +63,7 @@ for instance) is a PPS source too, and if not they should provide the
possibility to open another device as PPS source.
In LinuxPPS the PPS sources are simply char devices usually mapped
into files /dev/pps0, /dev/pps1, etc..
into files /dev/pps0, /dev/pps1, etc.
PPS with USB to serial devices
......@@ -71,9 +71,12 @@ PPS with USB to serial devices
It is possible to grab the PPS from an USB to serial device. However,
you should take into account the latencies and jitter introduced by
the USB stack. Users has reported clock instability around +-1ms when
synchronized with PPS through USB. This isn't suited for time server
synchronization.
the USB stack. Users have reported clock instability around +-1ms when
synchronized with PPS through USB. With USB 2.0, jitter may decrease
down to the order of 125 microseconds.
This may be suitable for time server synchronization with NTP because
of its undersampling and algorithms.
If your device doesn't report PPS, you can check that the feature is
supported by its driver. Most of the time, you only need to add a call
......@@ -166,7 +169,8 @@ Testing the PPS support
In order to test the PPS support even without specific hardware you can use
the ktimer driver (see the client subsection in the PPS configuration menu)
and the userland tools provided in the Documentation/pps/ directory.
and the userland tools available in your distribution's pps-tools package,
http://linuxpps.org , or https://github.com/ago/pps-tools .
Once you have enabled the compilation of ktimer just modprobe it (if
not statically compiled):
......@@ -183,8 +187,8 @@ and the run ppstest as follow:
source 0 - assert 1186592700.388931295, sequence: 365 - clear 0.000000000, sequence: 0
source 0 - assert 1186592701.389032765, sequence: 366 - clear 0.000000000, sequence: 0
Please, note that to compile userland programs you need the file timepps.h
(see Documentation/pps/).
Please, note that to compile userland programs you need the file timepps.h .
This is available in the pps-tools repository mentioned above.
Generators
......
......@@ -42,7 +42,7 @@ thresholds can be configured thanks to the following HWMON attributes:
* Critical: temp1_crit and temp1_crit_hyst;
* Shutdown: temp1_emergency and temp1_emergency_hyst.
NOTE: Remember that the values are stored as milli degrees Celcius. Don't forget
NOTE: Remember that the values are stored as milli degrees Celsius. Don't forget
to multiply!
Fan management
......
......@@ -111,7 +111,7 @@ Linux カーネルソースツリーは幅広い範囲のドキュメントを
カーネルの変更が、カーネルがユーザ空間に公開しているインターフェイスの
変更を引き起こす場合、その変更を説明するマニュアルページのパッチや情報
をマニュアルページのメンテナ mtk.manpages@gmail.com に送り、CC を
linux-api@ver.kernel.org に送ることを勧めます。
linux-api@vger.kernel.org に送ることを勧めます。
以下はカーネルソースツリーに含まれている読んでおくべきファイルの一覧で
す-
......
.. raw:: latex
\renewcommand\thesection*
\renewcommand\thesubsection*
Chinese translations
====================
.. toctree::
:maxdepth: 1
coding-style
......@@ -543,7 +543,7 @@ relevant attribute files are usb2_hardware_lpm and usb3_hardware_lpm.
When a USB 3.0 lpm-capable device is plugged in to a
xHCI host which supports link PM, it will check if U1
and U2 exit latencies have been set in the BOS
descriptor; if the check is is passed and the host
descriptor; if the check is passed and the host
supports USB3 hardware LPM, USB3 hardware LPM will be
enabled for the device and these files will be created.
The files hold a string value (enable or disable)
......
......@@ -296,7 +296,7 @@ thp_split_page is incremented every time a huge page is split into base
reason is that a huge page is old and is being reclaimed.
This action implies splitting all PMD the page mapped with.
thp_split_page_failed is is incremented if kernel fails to split huge
thp_split_page_failed is incremented if kernel fails to split huge
page. This can happen if the page was pinned by somebody.
thp_deferred_split_page is incremented when a huge page is put onto split
......
......@@ -1446,7 +1446,7 @@ $(help-board-dirs): help-%:
# Documentation targets
# ---------------------------------------------------------------------------
DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs
DOC_TARGETS := xmldocs sgmldocs psdocs latexdocs pdfdocs htmldocs mandocs installmandocs epubdocs cleandocs linkcheckdocs
PHONY += $(DOC_TARGETS)
$(DOC_TARGETS): scripts_basic FORCE
$(Q)$(MAKE) $(build)=scripts build_docproc build_check-lc_ctype
......
......@@ -64,24 +64,7 @@ typedef struct pm_message {
} pm_message_t;
/**
* struct dev_pm_ops - device PM callbacks
*
* Several device power state transitions are externally visible, affecting
* the state of pending I/O queues and (for drivers that touch hardware)
* interrupts, wakeups, DMA, and other hardware state. There may also be
* internal transitions to various low-power modes which are transparent
* to the rest of the driver stack (such as a driver that's ON gating off
* clocks which are not in active use).
*
* The externally visible transitions are handled with the help of callbacks
* included in this structure in such a way that two levels of callbacks are
* involved. First, the PM core executes callbacks provided by PM domains,
* device types, classes and bus types. They are the subsystem-level callbacks
* supposed to execute callbacks provided by device drivers, although they may
* choose not to do that. If the driver callbacks are executed, they have to
* collaborate with the subsystem-level callbacks to achieve the goals
* appropriate for the given system transition, given transition phase and the
* subsystem the device belongs to.
* struct dev_pm_ops - device PM callbacks.
*
* @prepare: The principal role of this callback is to prevent new children of
* the device from being registered after it has returned (the driver's
......@@ -240,34 +223,6 @@ typedef struct pm_message {
* driver's interrupt handler, which is guaranteed not to run while
* @restore_noirq() is being executed. Analogous to @resume_noirq().
*
* All of the above callbacks, except for @complete(), return error codes.
* However, the error codes returned by the resume operations, @resume(),
* @thaw(), @restore(), @resume_noirq(), @thaw_noirq(), and @restore_noirq(), do
* not cause the PM core to abort the resume transition during which they are
* returned. The error codes returned in those cases are only printed by the PM
* core to the system logs for debugging purposes. Still, it is recommended
* that drivers only return error codes from their resume methods in case of an
* unrecoverable failure (i.e. when the device being handled refuses to resume
* and becomes unusable) to allow us to modify the PM core in the future, so
* that it can avoid attempting to handle devices that failed to resume and
* their children.
*
* It is allowed to unregister devices while the above callbacks are being
* executed. However, a callback routine must NOT try to unregister the device
* it was called for, although it may unregister children of that device (for
* example, if it detects that a child was unplugged while the system was
* asleep).
*
* Refer to Documentation/power/admin-guide/devices.rst for more information about the role
* of the above callbacks in the system suspend process.
*
* There also are callbacks related to runtime power management of devices.
* Again, these callbacks are executed by the PM core only for subsystems
* (PM domains, device types, classes and bus types) and the subsystem-level
* callbacks are supposed to invoke the driver callbacks. Moreover, the exact
* actions to be performed by a device driver's callbacks generally depend on
* the platform and subsystem the device belongs to.
*
* @runtime_suspend: Prepare the device for a condition in which it won't be
* able to communicate with the CPU(s) and RAM due to power management.
* This need not mean that the device should be put into a low-power state.
......@@ -287,11 +242,51 @@ typedef struct pm_message {
* Check these conditions, and return 0 if it's appropriate to let the PM
* core queue a suspend request for the device.
*
* Refer to Documentation/power/runtime_pm.txt for more information about the
* role of the above callbacks in device runtime power management.
* Several device power state transitions are externally visible, affecting
* the state of pending I/O queues and (for drivers that touch hardware)
* interrupts, wakeups, DMA, and other hardware state. There may also be
* internal transitions to various low-power modes which are transparent
* to the rest of the driver stack (such as a driver that's ON gating off
* clocks which are not in active use).
*
* The externally visible transitions are handled with the help of callbacks
* included in this structure in such a way that, typically, two levels of
* callbacks are involved. First, the PM core executes callbacks provided by PM
* domains, device types, classes and bus types. They are the subsystem-level
* callbacks expected to execute callbacks provided by device drivers, although
* they may choose not to do that. If the driver callbacks are executed, they
* have to collaborate with the subsystem-level callbacks to achieve the goals
* appropriate for the given system transition, given transition phase and the
* subsystem the device belongs to.
*
* All of the above callbacks, except for @complete(), return error codes.
* However, the error codes returned by @resume(), @thaw(), @restore(),
* @resume_noirq(), @thaw_noirq(), and @restore_noirq(), do not cause the PM
* core to abort the resume transition during which they are returned. The
* error codes returned in those cases are only printed to the system logs for
* debugging purposes. Still, it is recommended that drivers only return error
* codes from their resume methods in case of an unrecoverable failure (i.e.
* when the device being handled refuses to resume and becomes unusable) to
* allow the PM core to be modified in the future, so that it can avoid
* attempting to handle devices that failed to resume and their children.
*
* It is allowed to unregister devices while the above callbacks are being
* executed. However, a callback routine MUST NOT try to unregister the device
* it was called for, although it may unregister children of that device (for
* example, if it detects that a child was unplugged while the system was
* asleep).
*
* There also are callbacks related to runtime power management of devices.
* Again, as a rule these callbacks are executed by the PM core for subsystems
* (PM domains, device types, classes and bus types) and the subsystem-level
* callbacks are expected to invoke the driver callbacks. Moreover, the exact
* actions to be performed by a device driver's callbacks generally depend on
* the platform and subsystem the device belongs to.
*
* Refer to Documentation/power/runtime_pm.txt for more information about the
* role of the @runtime_suspend(), @runtime_resume() and @runtime_idle()
* callbacks in device runtime power management.
*/
struct dev_pm_ops {
int (*prepare)(struct device *dev);
void (*complete)(struct device *dev);
......@@ -391,7 +386,7 @@ const struct dev_pm_ops name = { \
SET_RUNTIME_PM_OPS(suspend_fn, resume_fn, idle_fn) \
}
/**
/*
* PM_EVENT_ messages
*
* The following PM_EVENT_ messages are defined for the internal use of the PM
......@@ -487,7 +482,7 @@ const struct dev_pm_ops name = { \
#define PMSG_IS_AUTO(msg) (((msg).event & PM_EVENT_AUTO) != 0)
/**
/*
* Device run-time power management status.
*
* These status labels are used internally by the PM core to indicate the
......@@ -517,7 +512,7 @@ enum rpm_status {
RPM_SUSPENDING,
};
/**
/*
* Device run-time power management request types.
*
* RPM_REQ_NONE Do nothing.
......@@ -616,15 +611,18 @@ extern void update_pm_runtime_accounting(struct device *dev);
extern int dev_pm_get_subsys_data(struct device *dev);
extern void dev_pm_put_subsys_data(struct device *dev);
/*
* Power domains provide callbacks that are executed during system suspend,
* hibernation, system resume and during runtime PM transitions along with
* subsystem-level and driver-level callbacks.
/**
* struct dev_pm_domain - power management domain representation.
*
* @ops: Power management operations associated with this domain.
* @detach: Called when removing a device from the domain.
* @activate: Called before executing probe routines for bus types and drivers.
* @sync: Called after successful driver probe.
* @dismiss: Called after unsuccessful driver probe and after driver removal.
*
* Power domains provide callbacks that are executed during system suspend,
* hibernation, system resume and during runtime PM transitions instead of
* subsystem-level and driver-level callbacks.
*/
struct dev_pm_domain {
struct dev_pm_ops ops;
......
This diff is collapsed.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment