UbiquitousOS
/
OpenCloudOS-Kernel
mirror of https://gitee.com/OpenCloudOS/OpenCloudOS-Kernel.git
11
0
Fork 0
Code Issues Projects Releases Wiki Activity

Merge branch 'next' (accumulated 3.16 merge window patches) into master 

Now that 3.15 is released, this merges the 'next' branch into 'master',
bringing us to the normal situation where my 'master' branch is the
merge window.

* accumulated work in next: (6809 commits)
  ufs: sb mutex merge + mutex_destroy
  powerpc: update comments for generic idle conversion
  cris: update comments for generic idle conversion
  idle: remove cpu_idle() forward declarations
  nbd: zero from and len fields in NBD_CMD_DISCONNECT.
  mm: convert some level-less printks to pr_*
  MAINTAINERS: adi-buildroot-devel is moderated
  MAINTAINERS: add linux-api for review of API/ABI changes
  mm/kmemleak-test.c: use pr_fmt for logging
  fs/dlm/debug_fs.c: replace seq_printf by seq_puts
  fs/dlm/lockspace.c: convert simple_str to kstr
  fs/dlm/config.c: convert simple_str to kstr
  mm: mark remap_file_pages() syscall as deprecated
  mm: memcontrol: remove unnecessary memcg argument from soft limit functions
  mm: memcontrol: clean up memcg zoneinfo lookup
  mm/memblock.c: call kmemleak directly from memblock_(alloc|free)
  mm/mempool.c: update the kmemleak stack trace for mempool allocations
  lib/radix-tree.c: update the kmemleak stack trace for radix tree allocations
  mm: introduce kmemleak_update_trace()
  mm/kmemleak.c: use %u to print ->checksum
  ...
This commit is contained in:
Linus Torvalds 2014-06-08 11:31:16 -07:00
parent 1860e37987 1a5700bc2d
commit 3f17ea6dea
5560 changed files with 309083 additions and 158345 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
Documentation/ABI/testing/configfs-usb-gadget
View File

@ -62,6 +62,40 @@ KernelVersion: 3.11
Description:
This group contains functions available to this USB gadget.
What: /config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n>
Date: May 2014
KernelVersion: 3.16
Description:
This group contains "Feature Descriptors" specific for one
gadget's USB interface or one interface group described
by an IAD.
The attributes:
compatible_id - 8-byte string for "Compatible ID"
sub_compatible_id - 8-byte string for "Sub Compatible ID"
What: /config/usb-gadget/gadget/functions/<func>.<inst>/interface.<n>/<property>
Date: May 2014
KernelVersion: 3.16
Description:
This group contains "Extended Property Descriptors" specific for one
gadget's USB interface or one interface group described
by an IAD.
The attributes:
type - value 1..7 for interpreting the data
1: unicode string
2: unicode string with environment variable
3: binary
4: little-endian 32-bit
5: big-endian 32-bit
6: unicode string with a symbolic link
7: multiple unicode strings
data - blob of data to be interpreted depending on
type
What: /config/usb-gadget/gadget/strings
Date: Jun 2013
KernelVersion: 3.11
@ -79,3 +113,14 @@ Description:
product - gadget's product description
manufacturer - gadget's manufacturer description
What: /config/usb-gadget/gadget/os_desc
Date: May 2014
KernelVersion: 3.16
Description:
This group contains "OS String" extension handling attributes.
use - flag turning "OS Desctiptors" support on/off
b_vendor_code - one-byte value used for custom per-device and
per-interface requests
qw_sign - an identifier to be reported as "OS String"
proper

46
Documentation/ABI/testing/sysfs-bus-iio
View File

@ -114,14 +114,17 @@ What: /sys/bus/iio/devices/iio:deviceX/in_temp_raw
What: /sys/bus/iio/devices/iio:deviceX/in_tempX_raw
What: /sys/bus/iio/devices/iio:deviceX/in_temp_x_raw
What: /sys/bus/iio/devices/iio:deviceX/in_temp_y_raw
What: /sys/bus/iio/devices/iio:deviceX/in_temp_z_raw
What: /sys/bus/iio/devices/iio:deviceX/in_temp_ambient_raw
What: /sys/bus/iio/devices/iio:deviceX/in_temp_object_raw
KernelVersion: 2.6.35
Contact: linux-iio@vger.kernel.org
Description:
Raw (unscaled no bias removal etc.) temperature measurement.
If an axis is specified it generally means that the temperature
sensor is associated with one part of a compound device (e.g.
a gyroscope axis). Units after application of scale and offset
a gyroscope axis). The ambient and object modifiers distinguish
between ambient (reference) and distant temperature for contact-
less measurements. Units after application of scale and offset
are milli degrees Celsius.
What: /sys/bus/iio/devices/iio:deviceX/in_tempX_input
@ -210,6 +213,14 @@ Contact: linux-iio@vger.kernel.org
Description:
Scaled humidity measurement in milli percent.
What: /sys/bus/iio/devices/iio:deviceX/in_X_mean_raw
KernelVersion: 3.5
Contact: linux-iio@vger.kernel.org
Description:
Averaged raw measurement from channel X. The number of values
used for averaging is device specific. The converting rules for
normal raw values also applies to the averaged raw values.
What: /sys/bus/iio/devices/iio:deviceX/in_accel_offset
What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_offset
What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_offset
@ -784,6 +795,7 @@ What: /sys/.../iio:deviceX/scan_elements/in_incli_x_en
What: /sys/.../iio:deviceX/scan_elements/in_incli_y_en
What: /sys/.../iio:deviceX/scan_elements/in_pressureY_en
What: /sys/.../iio:deviceX/scan_elements/in_pressure_en
What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_en
KernelVersion: 2.6.37
Contact: linux-iio@vger.kernel.org
Description:
@ -799,6 +811,7 @@ What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_type
What: /sys/.../iio:deviceX/scan_elements/in_timestamp_type
What: /sys/.../iio:deviceX/scan_elements/in_pressureY_type
What: /sys/.../iio:deviceX/scan_elements/in_pressure_type
What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_type
KernelVersion: 2.6.37
Contact: linux-iio@vger.kernel.org
Description:
@ -845,6 +858,7 @@ What: /sys/.../iio:deviceX/scan_elements/in_incli_y_index
What: /sys/.../iio:deviceX/scan_elements/in_timestamp_index
What: /sys/.../iio:deviceX/scan_elements/in_pressureY_index
What: /sys/.../iio:deviceX/scan_elements/in_pressure_index
What: /sys/.../iio:deviceX/scan_elements/in_rot_quaternion_index
KernelVersion: 2.6.37
Contact: linux-iio@vger.kernel.org
Description:
@ -881,6 +895,25 @@ Description:
on-chip EEPROM. After power-up or chip reset the device will
automatically load the saved configuration.
What: /sys/.../iio:deviceX/in_illuminanceY_input
What: /sys/.../iio:deviceX/in_illuminanceY_raw
What: /sys/.../iio:deviceX/in_illuminanceY_mean_raw
KernelVersion: 3.4
Contact: linux-iio@vger.kernel.org
Description:
Illuminance measurement, units after application of scale
and offset are lux.
What: /sys/.../iio:deviceX/in_intensityY_raw
What: /sys/.../iio:deviceX/in_intensityY_ir_raw
What: /sys/.../iio:deviceX/in_intensityY_both_raw
KernelVersion: 3.4
Contact: linux-iio@vger.kernel.org
Description:
Unit-less light intensity. Modifiers both and ir indicate
that measurements contains visible and infrared light
components or just infrared light, respectively.
What: /sys/.../iio:deviceX/in_intensity_red_integration_time
What: /sys/.../iio:deviceX/in_intensity_green_integration_time
What: /sys/.../iio:deviceX/in_intensity_blue_integration_time
@ -891,3 +924,12 @@ Contact: linux-iio@vger.kernel.org
Description:
This attribute is used to get/set the integration time in
seconds.
What: /sys/bus/iio/devices/iio:deviceX/in_rot_quaternion_raw
KernelVersion: 3.15
Contact: linux-iio@vger.kernel.org
Description:
Raw value of quaternion components using a format
x y z w. Here x, y, and z component represents the axis about
which a rotation will occur and w component represents the
amount of rotation.

16
Documentation/ABI/testing/sysfs-bus-iio-proximity-as3935 Normal file
View File

@ -0,0 +1,16 @@
What /sys/bus/iio/devices/iio:deviceX/in_proximity_raw
Date: March 2014
KernelVersion: 3.15
Contact: Matt Ranostay <mranostay@gmail.com>
Description:
Get the current distance in meters of storm (1km steps)
1000-40000 = distance in meters
What /sys/bus/iio/devices/iio:deviceX/sensor_sensitivity
Date: March 2014
KernelVersion: 3.15
Contact: Matt Ranostay <mranostay@gmail.com>
Description:
Show or set the gain boost of the amp, from 0-31 range.
18 = indoors (default)
14 = outdoors

21
Documentation/ABI/testing/sysfs-bus-pci
View File

@ -250,3 +250,24 @@ Description:
valid. For example, writing a 2 to this file when sriov_numvfs
is not 0 and not 2 already will return an error. Writing a 10
when the value of sriov_totalvfs is 8 will return an error.
What: /sys/bus/pci/devices/.../driver_override
Date: April 2014
Contact: Alex Williamson <alex.williamson@redhat.com>
Description:
This file allows the driver for a device to be specified which
will override standard static and dynamic ID matching. When
specified, only a driver with a name matching the value written
to driver_override will have an opportunity to bind to the
device. The override is specified by writing a string to the
driver_override file (echo pci-stub > driver_override) and
may be cleared with an empty string (echo > driver_override).
This returns the device to standard matching rules binding.
Writing to driver_override does not automatically unbind the
device from its current driver or make any attempt to
automatically load the specified driver. If no driver with a
matching name is currently loaded in the kernel, the device
will not bind to any driver. This also allows devices to
opt-out of driver binding using a driver_override name such as
"none". Only a single driver may be specified in the override,
there is no support for parsing delimiters.

4
Documentation/ABI/testing/sysfs-devices-system-cpu
View File

@ -128,7 +128,7 @@ Description: Discover cpuidle policy and mechanism
What: /sys/devices/system/cpu/cpu#/cpufreq/*
Date: pre-git history
Contact: cpufreq@vger.kernel.org
Contact: linux-pm@vger.kernel.org
Description: Discover and change clock speed of CPUs
Clock scaling allows you to change the clock speed of the
@ -146,7 +146,7 @@ Description: Discover and change clock speed of CPUs
What: /sys/devices/system/cpu/cpu#/cpufreq/freqdomain_cpus
Date: June 2013
Contact: cpufreq@vger.kernel.org
Contact: linux-pm@vger.kernel.org
Description: Discover CPUs in the same CPU frequency coordination domain
freqdomain_cpus is the list of CPUs (online+offline) that share

23
Documentation/ABI/testing/sysfs-driver-hid-thingm
View File

@ -1,23 +0,0 @@
What: /sys/class/leds/blink1::<serial>/rgb
Date: January 2013
Contact: Vivien Didelot <vivien.didelot@savoirfairelinux.com>
Description: The ThingM blink1 is an USB RGB LED. The color notation is
3-byte hexadecimal. Read this attribute to get the last set
color. Write the 24-bit hexadecimal color to change the current
LED color. The default color is full white (0xFFFFFF).
For instance, set the color to green with: echo 00FF00 > rgb
What: /sys/class/leds/blink1::<serial>/fade
Date: January 2013
Contact: Vivien Didelot <vivien.didelot@savoirfairelinux.com>
Description: This attribute allows to set a fade time in milliseconds for
the next color change. Read the attribute to know the current
fade time. The default value is set to 0 (no fade time). For
instance, set a fade time of 2 seconds with: echo 2000 > fade
What: /sys/class/leds/blink1::<serial>/play
Date: January 2013
Contact: Vivien Didelot <vivien.didelot@savoirfairelinux.com>
Description: This attribute is used to play/pause the light patterns. Write 1
to start playing, 0 to stop. Reading this attribute returns the
current playing status.

8
Documentation/ABI/testing/sysfs-platform-brcmstb-gisb-arb Normal file
View File

@ -0,0 +1,8 @@
What: /sys/devices/../../gisb_arb_timeout
Date: May 2014
KernelVersion: 3.17
Contact: Florian Fainelli <f.fainelli@gmail.com>
Description:
Returns the currently configured raw timeout value of the
Broadcom Set Top Box internal GISB bus arbiter. Minimum value
is 1, and maximum value is 0xffffffff.

56
Documentation/ABI/testing/sysfs-platform-chipidea-usb-otg Normal file
View File

@ -0,0 +1,56 @@
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_req
Date: Feb 2014
Contact: Li Jun <b47624@freescale.com>
Description:
Can be set and read.
Set a_bus_req(A-device bus request) input to be 1 if
the application running on the A-device wants to use the bus,
and to be 0 when the application no longer wants to use
the bus(or wants to work as peripheral). a_bus_req can also
be set to 1 by kernel in response to remote wakeup signaling
from the B-device, the A-device should decide to resume the bus.
Valid values are "1" and "0".
Reading: returns 1 if the application running on the A-device
is using the bus as host role, otherwise 0.
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_bus_drop
Date: Feb 2014
Contact: Li Jun <b47624@freescale.com>
Description:
Can be set and read
The a_bus_drop(A-device bus drop) input is 1 when the
application running on the A-device wants to power down
the bus, and is 0 otherwise, When a_bus_drop is 1, then
the a_bus_req shall be 0.
Valid values are "1" and "0".
Reading: returns 1 if the bus is off(vbus is turned off) by
A-device, otherwise 0.
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/b_bus_req
Date: Feb 2014
Contact: Li Jun <b47624@freescale.com>
Description:
Can be set and read.
The b_bus_req(B-device bus request) input is 1 during the time
that the application running on the B-device wants to use the
bus as host, and is 0 when the application no longer wants to
work as host and decides to switch back to be peripheral.
Valid values are "1" and "0".
Reading: returns if the application running on the B device
is using the bus as host role, otherwise 0.
What: /sys/bus/platform/devices/ci_hdrc.0/inputs/a_clr_err
Date: Feb 2014
Contact: Li Jun <b47624@freescale.com>
Description:
Only can be set.
The a_clr_err(A-device Vbus error clear) input is used to clear
vbus error, then A-device will power down the bus.
Valid value is "1"

29
Documentation/ABI/testing/sysfs-power
View File

@ -7,19 +7,30 @@ Description:
subsystem.
What: /sys/power/state
Date: August 2006
Date: May 2014
Contact: Rafael J. Wysocki <rjw@rjwysocki.net>
Description:
The /sys/power/state file controls the system power state.
Reading from this file returns what states are supported,
which is hard-coded to 'freeze' (Low-Power Idle), 'standby'
(Power-On Suspend), 'mem' (Suspend-to-RAM), and 'disk'
(Suspend-to-Disk).
The /sys/power/state file controls system sleep states.
Reading from this file returns the available sleep state
labels, which may be "mem", "standby", "freeze" and "disk"
(hibernation). The meanings of the first three labels depend on
the relative_sleep_states command line argument as follows:
1) relative_sleep_states = 1
"mem", "standby", "freeze" represent non-hibernation sleep
states from the deepest ("mem", always present) to the
shallowest ("freeze"). "standby" and "freeze" may or may
not be present depending on the capabilities of the
platform. "freeze" can only be present if "standby" is
present.
2) relative_sleep_states = 0 (default)
"mem" - "suspend-to-RAM", present if supported.
"standby" - "power-on suspend", present if supported.
"freeze" - "suspend-to-idle", always present.
Writing to this file one of these strings causes the system to
transition into that state. Please see the file
Documentation/power/states.txt for a description of each of
these states.
transition into the corresponding state, if available. See
Documentation/power/states.txt for a description of what
"suspend-to-RAM", "power-on suspend" and "suspend-to-idle" mean.
What: /sys/power/disk
Date: September 2006

5
Documentation/Changes
View File

@ -73,6 +73,11 @@ Perl
You will need perl 5 and the following modules: Getopt::Long, Getopt::Std,
File::Basename, and File::Find to build the kernel.
BC
--
You will need bc to build kernels 3.10 and higher
System utilities
================

22
Documentation/CodingStyle
View File

@ -660,15 +660,23 @@ There are a number of driver model diagnostic macros in <linux/device.h>
which you should use to make sure messages are matched to the right device
and driver, and are tagged with the right level: dev_err(), dev_warn(),
dev_info(), and so forth. For messages that aren't associated with a
particular device, <linux/printk.h> defines pr_debug() and pr_info().
particular device, <linux/printk.h> defines pr_notice(), pr_info(),
pr_warn(), pr_err(), etc.
Coming up with good debugging messages can be quite a challenge; and once
you have them, they can be a huge help for remote troubleshooting. Such
messages should be compiled out when the DEBUG symbol is not defined (that
is, by default they are not included). When you use dev_dbg() or pr_debug(),
that's automatic. Many subsystems have Kconfig options to turn on -DDEBUG.
A related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to the
ones already enabled by DEBUG.
you have them, they can be a huge help for remote troubleshooting. However
debug message printing is handled differently than printing other non-debug
messages. While the other pr_XXX() functions print unconditionally,
pr_debug() does not; it is compiled out by default, unless either DEBUG is
defined or CONFIG_DYNAMIC_DEBUG is set. That is true for dev_dbg() also,
and a related convention uses VERBOSE_DEBUG to add dev_vdbg() messages to
the ones already enabled by DEBUG.
Many subsystems have Kconfig debug options to turn on -DDEBUG in the
corresponding Makefile; in other cases specific files #define DEBUG. And
when a debug message should be unconditionally printed, such as if it is
already inside a debug-related #ifdef secton, printk(KERN_DEBUG ...) can be
used.
Chapter 14: Allocating memory

210
Documentation/DMA-API-HOWTO.txt
View File

@ -9,16 +9,76 @@ This is a guide to device driver writers on how to use the DMA API
with example pseudo-code. For a concise description of the API, see
DMA-API.txt.
Most of the 64bit platforms have special hardware that translates bus
addresses (DMA addresses) into physical addresses. This is similar to
how page tables and/or a TLB translates virtual addresses to physical
addresses on a CPU. This is needed so that e.g. PCI devices can
access with a Single Address Cycle (32bit DMA address) any page in the
64bit physical address space. Previously in Linux those 64bit
platforms had to set artificial limits on the maximum RAM size in the
system, so that the virt_to_bus() static scheme works (the DMA address
translation tables were simply filled on bootup to map each bus
address to the physical page __pa(bus_to_virt())).
CPU and DMA addresses
There are several kinds of addresses involved in the DMA API, and it's
important to understand the differences.
The kernel normally uses virtual addresses. Any address returned by
kmalloc(), vmalloc(), and similar interfaces is a virtual address and can
be stored in a "void *".
The virtual memory system (TLB, page tables, etc.) translates virtual
addresses to CPU physical addresses, which are stored as "phys_addr_t" or
"resource_size_t". The kernel manages device resources like registers as
physical addresses. These are the addresses in /proc/iomem. The physical
address is not directly useful to a driver; it must use ioremap() to map
the space and produce a virtual address.
I/O devices use a third kind of address: a "bus address" or "DMA address".
If a device has registers at an MMIO address, or if it performs DMA to read
or write system memory, the addresses used by the device are bus addresses.
In some systems, bus addresses are identical to CPU physical addresses, but
in general they are not. IOMMUs and host bridges can produce arbitrary
mappings between physical and bus addresses.
Here's a picture and some examples:
CPU CPU Bus
Virtual Physical Address
Address Address Space
Space Space
+-------+ +------+ +------+
| | |MMIO | Offset | |
| | Virtual |Space | applied | |
C +-------+ --------> B +------+ ----------> +------+ A
| | mapping | | by host | |
+-----+ | | | | bridge | | +--------+
| | | | +------+ | | | |
| CPU | | | | RAM | | | | Device |
| | | | | | | | | |
+-----+ +-------+ +------+ +------+ +--------+
| | Virtual |Buffer| Mapping | |
X +-------+ --------> Y +------+ <---------- +------+ Z
| | mapping | RAM | by IOMMU
| | | |
| | | |
+-------+ +------+
During the enumeration process, the kernel learns about I/O devices and
their MMIO space and the host bridges that connect them to the system. For
example, if a PCI device has a BAR, the kernel reads the bus address (A)
from the BAR and converts it to a CPU physical address (B). The address B
is stored in a struct resource and usually exposed via /proc/iomem. When a
driver claims a device, it typically uses ioremap() to map physical address
B at a virtual address (C). It can then use, e.g., ioread32(C), to access
the device registers at bus address A.
If the device supports DMA, the driver sets up a buffer using kmalloc() or
a similar interface, which returns a virtual address (X). The virtual
memory system maps X to a physical address (Y) in system RAM. The driver
can use virtual address X to access the buffer, but the device itself
cannot because DMA doesn't go through the CPU virtual memory system.
In some simple systems, the device can do DMA directly to physical address
Y. But in many others, there is IOMMU hardware that translates bus
addresses to physical addresses, e.g., it translates Z to Y. This is part
of the reason for the DMA API: the driver can give a virtual address X to
an interface like dma_map_single(), which sets up any required IOMMU
mapping and returns the bus address Z. The driver then tells the device to
do DMA to Z, and the IOMMU maps it to the buffer at address Y in system
RAM.
So that Linux can use the dynamic DMA mapping, it needs some help from the
drivers, namely it has to take into account that DMA addresses should be
@ -29,17 +89,17 @@ The following API will work of course even on platforms where no such
hardware exists.
Note that the DMA API works with any bus independent of the underlying
microprocessor architecture. You should use the DMA API rather than
the bus specific DMA API (e.g. pci_dma_*).
microprocessor architecture. You should use the DMA API rather than the
bus-specific DMA API, i.e., use the dma_map_*() interfaces rather than the
pci_map_*() interfaces.
First of all, you should make sure
#include <linux/dma-mapping.h>
is in your driver. This file will obtain for you the definition of the
dma_addr_t (which can hold any valid DMA address for the platform)
type which should be used everywhere you hold a DMA (bus) address
returned from the DMA mapping functions.
is in your driver, which provides the definition of dma_addr_t. This type
can hold any valid DMA or bus address for the platform and should be used
everywhere you hold a DMA address returned from the DMA mapping functions.
What memory is DMA'able?
@ -123,9 +183,9 @@ Here, dev is a pointer to the device struct of your device, and mask
is a bit mask describing which bits of an address your device
supports. It returns zero if your card can perform DMA properly on
the machine given the address mask you provided. In general, the
device struct of your device is embedded in the bus specific device
struct of your device. For example, a pointer to the device struct of
your PCI device is pdev->dev (pdev is a pointer to the PCI device
device struct of your device is embedded in the bus-specific device
struct of your device. For example, &pdev->dev is a pointer to the
device struct of a PCI device (pdev is a pointer to the PCI device
struct of your device).
If it returns non-zero, your device cannot perform DMA properly on
@ -147,8 +207,7 @@ exactly why.
The standard 32-bit addressing device would do something like this:
if (dma_set_mask_and_coherent(dev, DMA_BIT_MASK(32))) {
printk(KERN_WARNING
"mydev: No suitable DMA available.\n");
dev_warn(dev, "mydev: No suitable DMA available\n");
goto ignore_this_device;
}
@ -170,8 +229,7 @@ all 64-bits when accessing streaming DMA:
} else if (!dma_set_mask(dev, DMA_BIT_MASK(32))) {
using_dac = 0;
} else {
printk(KERN_WARNING
"mydev: No suitable DMA available.\n");
dev_warn(dev, "mydev: No suitable DMA available\n");
goto ignore_this_device;
}
@ -187,22 +245,20 @@ the case would look like this:
using_dac = 0;
consistent_using_dac = 0;
} else {
printk(KERN_WARNING
"mydev: No suitable DMA available.\n");
dev_warn(dev, "mydev: No suitable DMA available\n");
goto ignore_this_device;
}
The coherent coherent mask will always be able to set the same or a
smaller mask as the streaming mask. However for the rare case that a
device driver only uses consistent allocations, one would have to
check the return value from dma_set_coherent_mask().
The coherent mask will always be able to set the same or a smaller mask as
the streaming mask. However for the rare case that a device driver only
uses consistent allocations, one would have to check the return value from
dma_set_coherent_mask().
Finally, if your device can only drive the low 24-bits of
address you might do something like:
if (dma_set_mask(dev, DMA_BIT_MASK(24))) {
printk(KERN_WARNING
"mydev: 24-bit DMA addressing not available.\n");
dev_warn(dev, "mydev: 24-bit DMA addressing not available\n");
goto ignore_this_device;
}
@ -232,14 +288,14 @@ Here is pseudo-code showing how this might be done:
card->playback_enabled = 1;
} else {
card->playback_enabled = 0;
printk(KERN_WARNING "%s: Playback disabled due to DMA limitations.\n",
dev_warn(dev, "%s: Playback disabled due to DMA limitations\n",
card->name);
}
if (!dma_set_mask(dev, RECORD_ADDRESS_BITS)) {
card->record_enabled = 1;
} else {
card->record_enabled = 0;
printk(KERN_WARNING "%s: Record disabled due to DMA limitations.\n",
dev_warn(dev, "%s: Record disabled due to DMA limitations\n",
card->name);
}
@ -331,7 +387,7 @@ context with the GFP_ATOMIC flag.
Size is the length of the region you want to allocate, in bytes.
This routine will allocate RAM for that region, so it acts similarly to
__get_free_pages (but takes size instead of a page order). If your
__get_free_pages() (but takes size instead of a page order). If your
driver needs regions sized smaller than a page, you may prefer using
the dma_pool interface, described below.
@ -343,11 +399,11 @@ the consistent DMA mask has been explicitly changed via
dma_set_coherent_mask(). This is true of the dma_pool interface as
well.
dma_alloc_coherent returns two values: the virtual address which you
dma_alloc_coherent() returns two values: the virtual address which you
can use to access it from the CPU and dma_handle which you pass to the
card.
The cpu return address and the DMA bus master address are both
The CPU virtual address and the DMA bus address are both
guaranteed to be aligned to the smallest PAGE_SIZE order which
is greater than or equal to the requested size. This invariant
exists (for example) to guarantee that if you allocate a chunk
@ -359,13 +415,13 @@ To unmap and free such a DMA region, you call:
dma_free_coherent(dev, size, cpu_addr, dma_handle);
where dev, size are the same as in the above call and cpu_addr and
dma_handle are the values dma_alloc_coherent returned to you.
dma_handle are the values dma_alloc_coherent() returned to you.
This function may not be called in interrupt context.
If your driver needs lots of smaller memory regions, you can write
custom code to subdivide pages returned by dma_alloc_coherent,
custom code to subdivide pages returned by dma_alloc_coherent(),
or you can use the dma_pool API to do that. A dma_pool is like
a kmem_cache, but it uses dma_alloc_coherent not __get_free_pages.
a kmem_cache, but it uses dma_alloc_coherent(), not __get_free_pages().
Also, it understands common hardware constraints for alignment,
like queue heads needing to be aligned on N byte boundaries.
@ -373,37 +429,37 @@ Create a dma_pool like this:
struct dma_pool *pool;
pool = dma_pool_create(name, dev, size, align, alloc);
pool = dma_pool_create(name, dev, size, align, boundary);
The "name" is for diagnostics (like a kmem_cache name); dev and size
are as above. The device's hardware alignment requirement for this
type of data is "align" (which is expressed in bytes, and must be a
power of two). If your device has no boundary crossing restrictions,
pass 0 for alloc; passing 4096 says memory allocated from this pool
pass 0 for boundary; passing 4096 says memory allocated from this pool
must not cross 4KByte boundaries (but at that time it may be better to
go for dma_alloc_coherent directly instead).
use dma_alloc_coherent() directly instead).
Allocate memory from a dma pool like this:
Allocate memory from a DMA pool like this:
cpu_addr = dma_pool_alloc(pool, flags, &dma_handle);
flags are SLAB_KERNEL if blocking is permitted (not in_interrupt nor
holding SMP locks), SLAB_ATOMIC otherwise. Like dma_alloc_coherent,
flags are GFP_KERNEL if blocking is permitted (not in_interrupt nor
holding SMP locks), GFP_ATOMIC otherwise. Like dma_alloc_coherent(),
this returns two values, cpu_addr and dma_handle.
Free memory that was allocated from a dma_pool like this:
dma_pool_free(pool, cpu_addr, dma_handle);
where pool is what you passed to dma_pool_alloc, and cpu_addr and
dma_handle are the values dma_pool_alloc returned. This function
where pool is what you passed to dma_pool_alloc(), and cpu_addr and
dma_handle are the values dma_pool_alloc() returned. This function
may be called in interrupt context.
Destroy a dma_pool by calling:
dma_pool_destroy(pool);
Make sure you've called dma_pool_free for all memory allocated
Make sure you've called dma_pool_free() for all memory allocated
from a pool before you destroy the pool. This function may not
be called in interrupt context.
@ -418,7 +474,7 @@ one of the following values:
DMA_FROM_DEVICE
DMA_NONE
One should provide the exact DMA direction if you know it.
You should provide the exact DMA direction if you know it.
DMA_TO_DEVICE means "from main memory to the device"
DMA_FROM_DEVICE means "from the device to main memory"
@ -489,14 +545,14 @@ and to unmap it:
dma_unmap_single(dev, dma_handle, size, direction);
You should call dma_mapping_error() as dma_map_single() could fail and return
error. Not all dma implementations support dma_mapping_error() interface.
error. Not all DMA implementations support the dma_mapping_error() interface.
However, it is a good practice to call dma_mapping_error() interface, which
will invoke the generic mapping error check interface. Doing so will ensure
that the mapping code will work correctly on all dma implementations without
that the mapping code will work correctly on all DMA implementations without
any dependency on the specifics of the underlying implementation. Using the
returned address without checking for errors could result in failures ranging
from panics to silent data corruption. A couple of examples of incorrect ways
to check for errors that make assumptions about the underlying dma
to check for errors that make assumptions about the underlying DMA
implementation are as follows and these are applicable to dma_map_page() as
well.
@ -516,13 +572,13 @@ Incorrect example 2:
goto map_error;
}
You should call dma_unmap_single when the DMA activity is finished, e.g.
You should call dma_unmap_single() when the DMA activity is finished, e.g.,
from the interrupt which told you that the DMA transfer is done.
Using cpu pointers like this for single mappings has a disadvantage,
Using CPU pointers like this for single mappings has a disadvantage:
you cannot reference HIGHMEM memory in this way. Thus, there is a
map/unmap interface pair akin to dma_{map,unmap}_single. These
interfaces deal with page/offset pairs instead of cpu pointers.
map/unmap interface pair akin to dma_{map,unmap}_single(). These
interfaces deal with page/offset pairs instead of CPU pointers.
Specifically:
struct device *dev = &my_dev->dev;
@ -550,7 +606,7 @@ Here, "offset" means byte offset within the given page.
You should call dma_mapping_error() as dma_map_page() could fail and return
error as outlined under the dma_map_single() discussion.
You should call dma_unmap_page when the DMA activity is finished, e.g.
You should call dma_unmap_page() when the DMA activity is finished, e.g.,
from the interrupt which told you that the DMA transfer is done.
With scatterlists, you map a region gathered from several regions by:
@ -588,18 +644,16 @@ PLEASE NOTE: The 'nents' argument to the dma_unmap_sg call must be
it should _NOT_ be the 'count' value _returned_ from the
dma_map_sg call.
Every dma_map_{single,sg} call should have its dma_unmap_{single,sg}
counterpart, because the bus address space is a shared resource (although
in some ports the mapping is per each BUS so less devices contend for the
same bus address space) and you could render the machine unusable by eating
all bus addresses.
Every dma_map_{single,sg}() call should have its dma_unmap_{single,sg}()
counterpart, because the bus address space is a shared resource and
you could render the machine unusable by consuming all bus addresses.
If you need to use the same streaming DMA region multiple times and touch
the data in between the DMA transfers, the buffer needs to be synced
properly in order for the cpu and device to see the most uptodate and
properly in order for the CPU and device to see the most up-to-date and
correct copy of the DMA buffer.
So, firstly, just map it with dma_map_{single,sg}, and after each DMA
So, firstly, just map it with dma_map_{single,sg}(), and after each DMA
transfer call either:
dma_sync_single_for_cpu(dev, dma_handle, size, direction);
@ -611,7 +665,7 @@ or:
as appropriate.
Then, if you wish to let the device get at the DMA area again,
finish accessing the data with the cpu, and then before actually
finish accessing the data with the CPU, and then before actually
giving the buffer to the hardware call either:
dma_sync_single_for_device(dev, dma_handle, size, direction);
@ -623,9 +677,9 @@ or:
as appropriate.
After the last DMA transfer call one of the DMA unmap routines
dma_unmap_{single,sg}. If you don't touch the data from the first dma_map_*
call till dma_unmap_*, then you don't have to call the dma_sync_*
routines at all.
dma_unmap_{single,sg}(). If you don't touch the data from the first
dma_map_*() call till dma_unmap_*(), then you don't have to call the
dma_sync_*() routines at all.
Here is pseudo code which shows a situation in which you would need
to use the dma_sync_*() interfaces.
@ -690,12 +744,12 @@ to use the dma_sync_*() interfaces.
}
}
Drivers converted fully to this interface should not use virt_to_bus any
longer, nor should they use bus_to_virt. Some drivers have to be changed a
little bit, because there is no longer an equivalent to bus_to_virt in the
Drivers converted fully to this interface should not use virt_to_bus() any
longer, nor should they use bus_to_virt(). Some drivers have to be changed a
little bit, because there is no longer an equivalent to bus_to_virt() in the
dynamic DMA mapping scheme - you have to always store the DMA addresses
returned by the dma_alloc_coherent, dma_pool_alloc, and dma_map_single
calls (dma_map_sg stores them in the scatterlist itself if the platform
returned by the dma_alloc_coherent(), dma_pool_alloc(), and dma_map_single()
calls (dma_map_sg() stores them in the scatterlist itself if the platform
supports dynamic DMA mapping in hardware) in your driver structures and/or
in the card registers.
@ -709,9 +763,9 @@ as it is impossible to correctly support them.
DMA address space is limited on some architectures and an allocation
failure can be determined by:
- checking if dma_alloc_coherent returns NULL or dma_map_sg returns 0
- checking if dma_alloc_coherent() returns NULL or dma_map_sg returns 0
- checking the returned dma_addr_t of dma_map_single and dma_map_page
- checking the dma_addr_t returned from dma_map_single() and dma_map_page()
by using dma_mapping_error():
dma_addr_t dma_handle;
@ -794,7 +848,7 @@ Example 2: (if buffers are allocated in a loop, unmap all mapped buffers when
dma_unmap_single(array[i].dma_addr);
}
Networking drivers must call dev_kfree_skb to free the socket buffer
Networking drivers must call dev_kfree_skb() to free the socket buffer
and return NETDEV_TX_OK if the DMA mapping fails on the transmit hook
(ndo_start_xmit). This means that the socket buffer is just dropped in
the failure case.
@ -831,7 +885,7 @@ transform some example code.
DEFINE_DMA_UNMAP_LEN(len);
};
2) Use dma_unmap_{addr,len}_set to set these values.
2) Use dma_unmap_{addr,len}_set() to set these values.
Example, before:
ringp->mapping = FOO;
@ -842,7 +896,7 @@ transform some example code.
dma_unmap_addr_set(ringp, mapping, FOO);
dma_unmap_len_set(ringp, len, BAR);
3) Use dma_unmap_{addr,len} to access these values.
3) Use dma_unmap_{addr,len}() to access these values.
Example, before:
dma_unmap_single(dev, ringp->mapping, ringp->len,

148
Documentation/DMA-API.txt
View File

@ -4,22 +4,26 @@
James E.J. Bottomley <James.Bottomley@HansenPartnership.com>
This document describes the DMA API. For a more gentle introduction
of the API (and actual examples) see
Documentation/DMA-API-HOWTO.txt.
of the API (and actual examples), see Documentation/DMA-API-HOWTO.txt.
This API is split into two pieces. Part I describes the API. Part II
describes the extensions to the API for supporting non-consistent
memory machines. Unless you know that your driver absolutely has to
support non-consistent platforms (this is usually only legacy
platforms) you should only use the API described in part I.
This API is split into two pieces. Part I describes the basic API.
Part II describes extensions for supporting non-consistent memory
machines. Unless you know that your driver absolutely has to support
non-consistent platforms (this is usually only legacy platforms) you
should only use the API described in part I.
Part I - dma_ API
-------------------------------------
To get the dma_ API, you must #include <linux/dma-mapping.h>
To get the dma_ API, you must #include <linux/dma-mapping.h>. This
provides dma_addr_t and the interfaces described below.
A dma_addr_t can hold any valid DMA or bus address for the platform. It
can be given to a device to use as a DMA source or target. A CPU cannot
reference a dma_addr_t directly because there may be translation between
its physical address space and the bus address space.
Part Ia - Using large dma-coherent buffers
Part Ia - Using large DMA-coherent buffers
------------------------------------------
void *
@ -33,20 +37,21 @@ to make sure to flush the processor's write buffers before telling
devices to read that memory.)
This routine allocates a region of <size> bytes of consistent memory.
It also returns a <dma_handle> which may be cast to an unsigned
integer the same width as the bus and used as the physical address
base of the region.
Returns: a pointer to the allocated region (in the processor's virtual
It returns a pointer to the allocated region (in the processor's virtual
address space) or NULL if the allocation failed.
It also returns a <dma_handle> which may be cast to an unsigned integer the
same width as the bus and given to the device as the bus address base of
the region.
Note: consistent memory can be expensive on some platforms, and the
minimum allocation length may be as big as a page, so you should
consolidate your requests for consistent memory as much as possible.
The simplest way to do that is to use the dma_pool calls (see below).
The flag parameter (dma_alloc_coherent only) allows the caller to
specify the GFP_ flags (see kmalloc) for the allocation (the
The flag parameter (dma_alloc_coherent() only) allows the caller to
specify the GFP_ flags (see kmalloc()) for the allocation (the
implementation may choose to ignore flags that affect the location of
the returned memory, like GFP_DMA).
@ -61,24 +66,24 @@ void
dma_free_coherent(struct device *dev, size_t size, void *cpu_addr,
dma_addr_t dma_handle)
Free the region of consistent memory you previously allocated. dev,
size and dma_handle must all be the same as those passed into the
consistent allocate. cpu_addr must be the virtual address returned by
the consistent allocate.
Free a region of consistent memory you previously allocated. dev,
size and dma_handle must all be the same as those passed into
dma_alloc_coherent(). cpu_addr must be the virtual address returned by
the dma_alloc_coherent().
Note that unlike their sibling allocation calls, these routines
may only be called with IRQs enabled.
Part Ib - Using small dma-coherent buffers
Part Ib - Using small DMA-coherent buffers
------------------------------------------
To get this part of the dma_ API, you must #include <linux/dmapool.h>
Many drivers need lots of small dma-coherent memory regions for DMA
Many drivers need lots of small DMA-coherent memory regions for DMA
descriptors or I/O buffers. Rather than allocating in units of a page
or more using dma_alloc_coherent(), you can use DMA pools. These work
much like a struct kmem_cache, except that they use the dma-coherent allocator,
much like a struct kmem_cache, except that they use the DMA-coherent allocator,
not __get_free_pages(). Also, they understand common hardware constraints
for alignment, like queue heads needing to be aligned on N-byte boundaries.
@ -87,7 +92,7 @@ for alignment, like queue heads needing to be aligned on N-byte boundaries.
dma_pool_create(const char *name, struct device *dev,
size_t size, size_t align, size_t alloc);
The pool create() routines initialize a pool of dma-coherent buffers
dma_pool_create() initializes a pool of DMA-coherent buffers
for use with a given device. It must be called in a context which
can sleep.
@ -102,25 +107,26 @@ from this pool must not cross 4KByte boundaries.
void *dma_pool_alloc(struct dma_pool *pool, gfp_t gfp_flags,
dma_addr_t *dma_handle);
This allocates memory from the pool; the returned memory will meet the size
and alignment requirements specified at creation time. Pass GFP_ATOMIC to
prevent blocking, or if it's permitted (not in_interrupt, not holding SMP locks),
pass GFP_KERNEL to allow blocking. Like dma_alloc_coherent(), this returns
two values: an address usable by the cpu, and the dma address usable by the
pool's device.
This allocates memory from the pool; the returned memory will meet the
size and alignment requirements specified at creation time. Pass
GFP_ATOMIC to prevent blocking, or if it's permitted (not
in_interrupt, not holding SMP locks), pass GFP_KERNEL to allow
blocking. Like dma_alloc_coherent(), this returns two values: an
address usable by the CPU, and the DMA address usable by the pool's
device.
void dma_pool_free(struct dma_pool *pool, void *vaddr,
dma_addr_t addr);
This puts memory back into the pool. The pool is what was passed to
the pool allocation routine; the cpu (vaddr) and dma addresses are what
dma_pool_alloc(); the CPU (vaddr) and DMA addresses are what
were returned when that routine allocated the memory being freed.
void dma_pool_destroy(struct dma_pool *pool);
The pool destroy() routines free the resources of the pool. They must be
dma_pool_destroy() frees the resources of the pool. It must be
called in a context which can sleep. Make sure you've freed all allocated
memory back to the pool before you destroy it.
@ -187,9 +193,9 @@ dma_map_single(struct device *dev, void *cpu_addr, size_t size,
enum dma_data_direction direction)
Maps a piece of processor virtual memory so it can be accessed by the
device and returns the physical handle of the memory.
device and returns the bus address of the memory.
The direction for both api's may be converted freely by casting.
The direction for both APIs may be converted freely by casting.
However the dma_ API uses a strongly typed enumerator for its
direction:
@ -198,31 +204,30 @@ DMA_TO_DEVICE data is going from the memory to the device
DMA_FROM_DEVICE data is coming from the device to the memory
DMA_BIDIRECTIONAL direction isn't known
Notes: Not all memory regions in a machine can be mapped by this
API. Further, regions that appear to be physically contiguous in
kernel virtual space may not be contiguous as physical memory. Since
this API does not provide any scatter/gather capability, it will fail
if the user tries to map a non-physically contiguous piece of memory.
For this reason, it is recommended that memory mapped by this API be
obtained only from sources which guarantee it to be physically contiguous
(like kmalloc).
Notes: Not all memory regions in a machine can be mapped by this API.
Further, contiguous kernel virtual space may not be contiguous as
physical memory. Since this API does not provide any scatter/gather
capability, it will fail if the user tries to map a non-physically
contiguous piece of memory. For this reason, memory to be mapped by
this API should be obtained from sources which guarantee it to be
physically contiguous (like kmalloc).
Further, the physical address of the memory must be within the
dma_mask of the device (the dma_mask represents a bit mask of the
addressable region for the device. I.e., if the physical address of
the memory anded with the dma_mask is still equal to the physical
address, then the device can perform DMA to the memory). In order to
Further, the bus address of the memory must be within the
dma_mask of the device (the dma_mask is a bit mask of the
addressable region for the device, i.e., if the bus address of
the memory ANDed with the dma_mask is still equal to the bus
address, then the device can perform DMA to the memory). To
ensure that the memory allocated by kmalloc is within the dma_mask,
the driver may specify various platform-dependent flags to restrict
the physical memory range of the allocation (e.g. on x86, GFP_DMA
guarantees to be within the first 16Mb of available physical memory,
the bus address range of the allocation (e.g., on x86, GFP_DMA
guarantees to be within the first 16MB of available bus addresses,
as required by ISA devices).
Note also that the above constraints on physical contiguity and
dma_mask may not apply if the platform has an IOMMU (a device which
supplies a physical to virtual mapping between the I/O memory bus and
the device). However, to be portable, device driver writers may *not*
assume that such an IOMMU exists.
maps an I/O bus address to a physical memory address). However, to be
portable, device driver writers may *not* assume that such an IOMMU
exists.
Warnings: Memory coherency operates at a granularity called the cache
line width. In order for memory mapped by this API to operate
@ -281,9 +286,9 @@ cache width is.
int
dma_mapping_error(struct device *dev, dma_addr_t dma_addr)
In some circumstances dma_map_single and dma_map_page will fail to create
In some circumstances dma_map_single() and dma_map_page() will fail to create
a mapping. A driver can check for these errors by testing the returned
dma address with dma_mapping_error(). A non-zero return value means the mapping
DMA address with dma_mapping_error(). A non-zero return value means the mapping
could not be created and the driver should take appropriate action (e.g.
reduce current DMA mapping usage or delay and try again later).
@ -291,7 +296,7 @@ reduce current DMA mapping usage or delay and try again later).
dma_map_sg(struct device *dev, struct scatterlist *sg,
int nents, enum dma_data_direction direction)
Returns: the number of physical segments mapped (this may be shorter
Returns: the number of bus address segments mapped (this may be shorter
than <nents> passed in if some elements of the scatter/gather list are
physically or virtually adjacent and an IOMMU maps them with a single
entry).
@ -299,7 +304,7 @@ entry).
Please note that the sg cannot be mapped again if it has been mapped once.
The mapping process is allowed to destroy information in the sg.
As with the other mapping interfaces, dma_map_sg can fail. When it
As with the other mapping interfaces, dma_map_sg() can fail. When it
does, 0 is returned and a driver must take appropriate action. It is
critical that the driver do something, in the case of a block driver
aborting the request or even oopsing is better than doing nothing and
@ -335,7 +340,7 @@ must be the same as those and passed in to the scatter/gather mapping
API.
Note: <nents> must be the number you passed in, *not* the number of
physical entries returned.
bus address entries returned.
void
dma_sync_single_for_cpu(struct device *dev, dma_addr_t dma_handle, size_t size,
@ -350,7 +355,7 @@ void
dma_sync_sg_for_device(struct device *dev, struct scatterlist *sg, int nelems,
enum dma_data_direction direction)
Synchronise a single contiguous or scatter/gather mapping for the cpu
Synchronise a single contiguous or scatter/gather mapping for the CPU
and device. With the sync_sg API, all the parameters must be the same
as those passed into the single mapping API. With the sync_single API,
you can use dma_handle and size parameters that aren't identical to
@ -391,10 +396,10 @@ The four functions above are just like the counterpart functions
without the _attrs suffixes, except that they pass an optional
struct dma_attrs*.
struct dma_attrs encapsulates a set of "dma attributes". For the
struct dma_attrs encapsulates a set of "DMA attributes". For the
definition of struct dma_attrs see linux/dma-attrs.h.
The interpretation of dma attributes is architecture-specific, and
The interpretation of DMA attributes is architecture-specific, and
each attribute should be documented in Documentation/DMA-attributes.txt.
If struct dma_attrs* is NULL, the semantics of each of these
@ -458,7 +463,7 @@ Note: where the platform can return consistent memory, it will
guarantee that the sync points become nops.
Warning: Handling non-consistent memory is a real pain. You should
only ever use this API if you positively know your driver will be
only use this API if you positively know your driver will be
required to work on one of the rare (usually non-PCI) architectures
that simply cannot make consistent memory.
@ -492,30 +497,29 @@ continuing on for size. Again, you *must* observe the cache line
boundaries when doing this.
int
dma_declare_coherent_memory(struct device *dev, dma_addr_t bus_addr,
dma_declare_coherent_memory(struct device *dev, phys_addr_t phys_addr,
dma_addr_t device_addr, size_t size, int
flags)
Declare region of memory to be handed out by dma_alloc_coherent when
Declare region of memory to be handed out by dma_alloc_coherent() when
it's asked for coherent memory for this device.
bus_addr is the physical address to which the memory is currently
assigned in the bus responding region (this will be used by the
platform to perform the mapping).
phys_addr is the CPU physical address to which the memory is currently
assigned (this will be ioremapped so the CPU can access the region).
device_addr is the physical address the device needs to be programmed
with actually to address this memory (this will be handed out as the
device_addr is the bus address the device needs to be programmed
with to actually address this memory (this will be handed out as the
dma_addr_t in dma_alloc_coherent()).
size is the size of the area (must be multiples of PAGE_SIZE).
flags can be or'd together and are:
flags can be ORed together and are:
DMA_MEMORY_MAP - request that the memory returned from
dma_alloc_coherent() be directly writable.
DMA_MEMORY_IO - request that the memory returned from
dma_alloc_coherent() be addressable using read/write/memcpy_toio etc.
dma_alloc_coherent() be addressable using read()/write()/memcpy_toio() etc.
One or both of these flags must be present.
@ -572,7 +576,7 @@ region is occupied.
Part III - Debug drivers use of the DMA-API
-------------------------------------------
The DMA-API as described above as some constraints. DMA addresses must be
The DMA-API as described above has some constraints. DMA addresses must be
released with the corresponding function with the same size for example. With
the advent of hardware IOMMUs it becomes more and more important that drivers
do not violate those constraints. In the worst case such a violation can
@ -690,11 +694,11 @@ architectural default.
void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr);
dma-debug interface debug_dma_mapping_error() to debug drivers that fail
to check dma mapping errors on addresses returned by dma_map_single() and
to check DMA mapping errors on addresses returned by dma_map_single() and
dma_map_page() interfaces. This interface clears a flag set by
debug_dma_map_page() to indicate that dma_mapping_error() has been called by
the driver. When driver does unmap, debug_dma_unmap() checks the flag and if
this flag is still set, prints warning message that includes call trace that
leads up to the unmap. This interface can be called from dma_mapping_error()
routines to enable dma mapping error check debugging.
routines to enable DMA mapping error check debugging.

4
Documentation/DMA-ISA-LPC.txt
View File

@ -16,7 +16,7 @@ To do ISA style DMA you need to include two headers:
#include <asm/dma.h>
The first is the generic DMA API used to convert virtual addresses to
physical addresses (see Documentation/DMA-API.txt for details).
bus addresses (see Documentation/DMA-API.txt for details).
The second contains the routines specific to ISA DMA transfers. Since
this is not present on all platforms make sure you construct your
@ -50,7 +50,7 @@ early as possible and not release it until the driver is unloaded.)
Part III - Address translation
------------------------------
To translate the virtual address to a physical use the normal DMA
To translate the virtual address to a bus address, use the normal DMA
API. Do _not_ use isa_virt_to_phys() even though it does the same
thing. The reason for this is that the function isa_virt_to_phys()
will require a Kconfig dependency to ISA, not just ISA_DMA_API which

2
Documentation/DMA-attributes.txt
View File

@ -98,5 +98,5 @@ DMA_ATTR_FORCE_CONTIGUOUS
By default DMA-mapping subsystem is allowed to assemble the buffer
allocated by dma_alloc_attrs() function from individual pages if it can
be mapped as contiguous chunk into device dma address space. By
specifing this attribute the allocated buffer is forced to be contiguous
specifying this attribute the allocated buffer is forced to be contiguous
also in physical memory.

3
Documentation/DocBook/Makefile
View File

@ -14,7 +14,8 @@ DOCBOOKS := z8530book.xml device-drivers.xml \
genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml \
80211.xml debugobjects.xml sh.xml regulator.xml \
alsa-driver-api.xml writing-an-alsa-driver.xml \
tracepoint.xml drm.xml media_api.xml w1.xml
tracepoint.xml drm.xml media_api.xml w1.xml \
writing_musb_glue_layer.xml
include Documentation/DocBook/media/Makefile

2
Documentation/DocBook/filesystems.tmpl
View File

@ -62,7 +62,7 @@
!Efs/mpage.c
!Efs/namei.c
!Efs/buffer.c
!Efs/bio.c
!Eblock/bio.c
!Efs/seq_file.c
!Efs/filesystems.c
!Efs/fs-writeback.c

15
Documentation/DocBook/media/v4l/io.xml
View File

@ -125,7 +125,7 @@ location of the buffers in device memory can be determined with the
<structfield>m.offset</structfield> and <structfield>length</structfield>
returned in a &v4l2-buffer; are passed as sixth and second parameter to the
<function>mmap()</function> function. When using the multi-planar API,
struct &v4l2-buffer; contains an array of &v4l2-plane; structures, each
&v4l2-buffer; contains an array of &v4l2-plane; structures, each
containing its own <structfield>m.offset</structfield> and
<structfield>length</structfield>. When using the multi-planar API, every
plane of every buffer has to be mapped separately, so the number of
@ -699,7 +699,12 @@ linkend="v4l2-buf-type" /></entry>
buffer. It depends on the negotiated data format and may change with
each buffer for compressed variable size data like JPEG images.
Drivers must set this field when <structfield>type</structfield>
refers to an input stream, applications when it refers to an output stream.</entry>
refers to an input stream, applications when it refers to an output stream.
If the application sets this to 0 for an output stream, then
<structfield>bytesused</structfield> will be set to the size of the
buffer (see the <structfield>length</structfield> field of this struct) by
the driver. For multiplanar formats this field is ignored and the
<structfield>planes</structfield> pointer is used instead.</entry>
</row>
<row>
<entry>__u32</entry>
@ -861,7 +866,11 @@ should set this to 0.</entry>
<entry></entry>
<entry>The number of bytes occupied by data in the plane
(its payload). Drivers must set this field when <structfield>type</structfield>
refers to an input stream, applications when it refers to an output stream.</entry>
refers to an input stream, applications when it refers to an output stream.
If the application sets this to 0 for an output stream, then
<structfield>bytesused</structfield> will be set to the size of the
plane (see the <structfield>length</structfield> field of this struct)
by the driver.</entry>
</row>
<row>
<entry>__u32</entry>

8
Documentation/DocBook/media/v4l/media-ioc-enum-links.xml
View File

@ -79,13 +79,13 @@
<entry>Entity id, set by the application.</entry>
</row>
<row>
<entry>struct &media-pad-desc;</entry>
<entry>&media-pad-desc;</entry>
<entry>*<structfield>pads</structfield></entry>
<entry>Pointer to a pads array allocated by the application. Ignored
if NULL.</entry>
</row>
<row>
<entry>struct &media-link-desc;</entry>
<entry>&media-link-desc;</entry>
<entry>*<structfield>links</structfield></entry>
<entry>Pointer to a links array allocated by the application. Ignored
if NULL.</entry>
@ -153,12 +153,12 @@
&cs-str;
<tbody valign="top">
<row>
<entry>struct &media-pad-desc;</entry>
<entry>&media-pad-desc;</entry>
<entry><structfield>source</structfield></entry>
<entry>Pad at the origin of this link.</entry>
</row>
<row>
<entry>struct &media-pad-desc;</entry>
<entry>&media-pad-desc;</entry>
<entry><structfield>sink</structfield></entry>
<entry>Pad at the target of this link.</entry>
</row>

4
Documentation/DocBook/media/v4l/pixfmt.xml
View File

@ -772,7 +772,7 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
</row>
<row id="V4L2-PIX-FMT-H264-MVC">
<entry><constant>V4L2_PIX_FMT_H264_MVC</constant></entry>
<entry>'MVC'</entry>
<entry>'M264'</entry>
<entry>H264 MVC video elementary stream.</entry>
</row>
<row id="V4L2-PIX-FMT-H263">
@ -812,7 +812,7 @@ extended control <constant>V4L2_CID_MPEG_STREAM_TYPE</constant>, see
</row>
<row id="V4L2-PIX-FMT-VP8">
<entry><constant>V4L2_PIX_FMT_VP8</constant></entry>
<entry>'VP8'</entry>
<entry>'VP80'</entry>
<entry>VP8 video elementary stream.</entry>
</row>
</tbody>

760
Documentation/DocBook/media/v4l/subdev-formats.xml
View File

@ -1898,6 +1898,134 @@
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-UYVY10-2X10">
<entry>V4L2_MBUS_FMT_UYVY10_2X10</entry>
<entry>0x2018</entry>
<entry></entry>
&dash-ent-22;
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-22;
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-22;
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-22;
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-VYUY10-2X10">
<entry>V4L2_MBUS_FMT_VYUY10_2X10</entry>
<entry>0x2019</entry>
<entry></entry>
&dash-ent-22;
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-22;
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-22;
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-22;
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-YUYV10-2X10">
<entry>V4L2_MBUS_FMT_YUYV10_2X10</entry>
<entry>0x200b</entry>
@ -2308,6 +2436,110 @@
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-UYVY10-1X20">
<entry>V4L2_MBUS_FMT_UYVY10_1X20</entry>
<entry>0x201a</entry>
<entry></entry>
&dash-ent-12;
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-12;
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-VYUY10-1X20">
<entry>V4L2_MBUS_FMT_VYUY10_1X20</entry>
<entry>0x201b</entry>
<entry></entry>
&dash-ent-12;
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-12;
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-YUYV10-1X20">
<entry>V4L2_MBUS_FMT_YUYV10_1X20</entry>
<entry>0x200d</entry>
@ -2486,6 +2718,534 @@
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-UYVY12-2X12">
<entry>V4L2_MBUS_FMT_UYVY12_2X12</entry>
<entry>0x201c</entry>
<entry></entry>
&dash-ent-20;
<entry>u<subscript>11</subscript></entry>
<entry>u<subscript>10</subscript></entry>
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>v<subscript>11</subscript></entry>
<entry>v<subscript>10</subscript></entry>
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-VYUY12-2X12">
<entry>V4L2_MBUS_FMT_VYUY12_2X12</entry>
<entry>0x201d</entry>
<entry></entry>
&dash-ent-20;
<entry>v<subscript>11</subscript></entry>
<entry>v<subscript>10</subscript></entry>
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>u<subscript>11</subscript></entry>
<entry>u<subscript>10</subscript></entry>
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-YUYV12-2X12">
<entry>V4L2_MBUS_FMT_YUYV12_2X12</entry>
<entry>0x201e</entry>
<entry></entry>
&dash-ent-20;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>u<subscript>11</subscript></entry>
<entry>u<subscript>10</subscript></entry>
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>v<subscript>11</subscript></entry>
<entry>v<subscript>10</subscript></entry>
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-YVYU12-2X12">
<entry>V4L2_MBUS_FMT_YVYU12_2X12</entry>
<entry>0x201f</entry>
<entry></entry>
&dash-ent-20;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>v<subscript>11</subscript></entry>
<entry>v<subscript>10</subscript></entry>
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-20;
<entry>u<subscript>11</subscript></entry>
<entry>u<subscript>10</subscript></entry>
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-UYVY12-1X24">
<entry>V4L2_MBUS_FMT_UYVY12_1X24</entry>
<entry>0x2020</entry>
<entry></entry>
&dash-ent-8;
<entry>u<subscript>11</subscript></entry>
<entry>u<subscript>10</subscript></entry>
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-8;
<entry>v<subscript>11</subscript></entry>
<entry>v<subscript>10</subscript></entry>
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-VYUY12-1X24">
<entry>V4L2_MBUS_FMT_VYUY12_1X24</entry>
<entry>0x2021</entry>
<entry></entry>
&dash-ent-8;
<entry>v<subscript>11</subscript></entry>
<entry>v<subscript>10</subscript></entry>
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-8;
<entry>u<subscript>11</subscript></entry>
<entry>u<subscript>10</subscript></entry>
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-YUYV12-1X24">
<entry>V4L2_MBUS_FMT_YUYV12_1X24</entry>
<entry>0x2022</entry>
<entry></entry>
&dash-ent-8;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
<entry>u<subscript>11</subscript></entry>
<entry>u<subscript>10</subscript></entry>
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-8;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
<entry>v<subscript>11</subscript></entry>
<entry>v<subscript>10</subscript></entry>
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row id="V4L2-MBUS-FMT-YVYU12-1X24">
<entry>V4L2_MBUS_FMT_YVYU12_1X24</entry>
<entry>0x2023</entry>
<entry></entry>
&dash-ent-8;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
<entry>v<subscript>11</subscript></entry>
<entry>v<subscript>10</subscript></entry>
<entry>v<subscript>9</subscript></entry>
<entry>v<subscript>8</subscript></entry>
<entry>v<subscript>7</subscript></entry>
<entry>v<subscript>6</subscript></entry>
<entry>v<subscript>5</subscript></entry>
<entry>v<subscript>4</subscript></entry>
<entry>v<subscript>3</subscript></entry>
<entry>v<subscript>2</subscript></entry>
<entry>v<subscript>1</subscript></entry>
<entry>v<subscript>0</subscript></entry>
</row>
<row>
<entry></entry>
<entry></entry>
<entry></entry>
&dash-ent-8;
<entry>y<subscript>11</subscript></entry>
<entry>y<subscript>10</subscript></entry>
<entry>y<subscript>9</subscript></entry>
<entry>y<subscript>8</subscript></entry>
<entry>y<subscript>7</subscript></entry>
<entry>y<subscript>6</subscript></entry>
<entry>y<subscript>5</subscript></entry>
<entry>y<subscript>4</subscript></entry>
<entry>y<subscript>3</subscript></entry>
<entry>y<subscript>2</subscript></entry>
<entry>y<subscript>1</subscript></entry>
<entry>y<subscript>0</subscript></entry>
<entry>u<subscript>11</subscript></entry>
<entry>u<subscript>10</subscript></entry>
<entry>u<subscript>9</subscript></entry>
<entry>u<subscript>8</subscript></entry>
<entry>u<subscript>7</subscript></entry>
<entry>u<subscript>6</subscript></entry>
<entry>u<subscript>5</subscript></entry>
<entry>u<subscript>4</subscript></entry>
<entry>u<subscript>3</subscript></entry>
<entry>u<subscript>2</subscript></entry>
<entry>u<subscript>1</subscript></entry>
<entry>u<subscript>0</subscript></entry>
</row>
</tbody>
</tgroup>
</table>

33
Documentation/DocBook/media/v4l/vidioc-dqevent.xml
View File

@ -242,6 +242,22 @@
</tgroup>
</table>
<table frame="none" pgwide="1" id="v4l2-event-src-change">
<title>struct <structname>v4l2_event_src_change</structname></title>
<tgroup cols="3">
&cs-str;
<tbody valign="top">
<row>
<entry>__u32</entry>
<entry><structfield>changes</structfield></entry>
<entry>
A bitmask that tells what has changed. See <xref linkend="src-changes-flags" />.
</entry>
</row>
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="changes-flags">
<title>Changes</title>
<tgroup cols="3">
@ -270,6 +286,23 @@
</tbody>
</tgroup>
</table>
<table pgwide="1" frame="none" id="src-changes-flags">
<title>Source Changes</title>
<tgroup cols="3">
&cs-def;
<tbody valign="top">
<row>
<entry><constant>V4L2_EVENT_SRC_CH_RESOLUTION</constant></entry>
<entry>0x0001</entry>
<entry>This event gets triggered when a resolution change is
detected at an input. This can come from an input connector or
from a video decoder.
</entry>
</row>
</tbody>
</tgroup>
</table>
</refsect1>
<refsect1>
&return-value;

27
Documentation/DocBook/media/v4l/vidioc-dv-timings-cap.xml
View File

@ -1,11 +1,12 @@
<refentry id="vidioc-dv-timings-cap">
<refmeta>
<refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP</refentrytitle>
<refentrytitle>ioctl VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_DV_TIMINGS_CAP</refname>
<refname>VIDIOC_SUBDEV_DV_TIMINGS_CAP</refname>
<refpurpose>The capabilities of the Digital Video receiver/transmitter</refpurpose>
</refnamediv>
@ -33,7 +34,7 @@
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_DV_TIMINGS_CAP</para>
<para>VIDIOC_DV_TIMINGS_CAP, VIDIOC_SUBDEV_DV_TIMINGS_CAP</para>
</listitem>
</varlistentry>
<varlistentry>
@ -54,10 +55,19 @@
interface and may change in the future.</para>
</note>
<para>To query the capabilities of the DV receiver/transmitter applications can call
this ioctl and the driver will fill in the structure. Note that drivers may return
<para>To query the capabilities of the DV receiver/transmitter applications
can call the <constant>VIDIOC_DV_TIMINGS_CAP</constant> ioctl on a video node
and the driver will fill in the structure. Note that drivers may return
different values after switching the video input or output.</para>
<para>When implemented by the driver DV capabilities of subdevices can be
queried by calling the <constant>VIDIOC_SUBDEV_DV_TIMINGS_CAP</constant> ioctl
directly on a subdevice node. The capabilities are specific to inputs (for DV
receivers) or outputs (for DV transmitters), applications must specify the
desired pad number in the &v4l2-dv-timings-cap; <structfield>pad</structfield>
field. Attempts to query capabilities on a pad that doesn't support them will
return an &EINVAL;.</para>
<table pgwide="1" frame="none" id="v4l2-bt-timings-cap">
<title>struct <structname>v4l2_bt_timings_cap</structname></title>
<tgroup cols="3">
@ -127,7 +137,14 @@ different values after switching the video input or output.</para>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[3]</entry>
<entry><structfield>pad</structfield></entry>
<entry>Pad number as reported by the media controller API. This field
is only used when operating on a subdevice node. When operating on a
video node applications must set this field to zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
<entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
</row>
<row>

30
Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml
View File

@ -1,11 +1,12 @@
<refentry id="vidioc-enum-dv-timings">
<refmeta>
<refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS</refentrytitle>
<refentrytitle>ioctl VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refentrytitle>
&manvol;
</refmeta>
<refnamediv>
<refname>VIDIOC_ENUM_DV_TIMINGS</refname>
<refname>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</refname>
<refpurpose>Enumerate supported Digital Video timings</refpurpose>
</refnamediv>
@ -33,7 +34,7 @@
<varlistentry>
<term><parameter>request</parameter></term>
<listitem>
<para>VIDIOC_ENUM_DV_TIMINGS</para>
<para>VIDIOC_ENUM_DV_TIMINGS, VIDIOC_SUBDEV_ENUM_DV_TIMINGS</para>
</listitem>
</varlistentry>
<varlistentry>
@ -61,14 +62,21 @@ standards or even custom timings that are not in this list.</para>
<para>To query the available timings, applications initialize the
<structfield>index</structfield> field and zero the reserved array of &v4l2-enum-dv-timings;
and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl with a pointer to this
structure. Drivers fill the rest of the structure or return an
and call the <constant>VIDIOC_ENUM_DV_TIMINGS</constant> ioctl on a video node with a
pointer to this structure. Drivers fill the rest of the structure or return an
&EINVAL; when the index is out of bounds. To enumerate all supported DV timings,
applications shall begin at index zero, incrementing by one until the
driver returns <errorcode>EINVAL</errorcode>. Note that drivers may enumerate a
different set of DV timings after switching the video input or
output.</para>
<para>When implemented by the driver DV timings of subdevices can be queried
by calling the <constant>VIDIOC_SUBDEV_ENUM_DV_TIMINGS</constant> ioctl directly
on a subdevice node. The DV timings are specific to inputs (for DV receivers) or
outputs (for DV transmitters), applications must specify the desired pad number
in the &v4l2-enum-dv-timings; <structfield>pad</structfield> field. Attempts to
enumerate timings on a pad that doesn't support them will return an &EINVAL;.</para>
<table pgwide="1" frame="none" id="v4l2-enum-dv-timings">
<title>struct <structname>v4l2_enum_dv_timings</structname></title>
<tgroup cols="3">
@ -82,8 +90,16 @@ application.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[3]</entry>
<entry>Reserved for future extensions. Drivers must set the array to zero.</entry>
<entry><structfield>pad</structfield></entry>
<entry>Pad number as reported by the media controller API. This field
is only used when operating on a subdevice node. When operating on a
video node applications must set this field to zero.</entry>
</row>
<row>
<entry>__u32</entry>
<entry><structfield>reserved</structfield>[2]</entry>
<entry>Reserved for future extensions. Drivers and applications must
set the array to zero.</entry>
</row>
<row>
<entry>&v4l2-dv-timings;</entry>
@ -103,7 +119,7 @@ application.</entry>
<term><errorcode>EINVAL</errorcode></term>
<listitem>
<para>The &v4l2-enum-dv-timings; <structfield>index</structfield>
is out of bounds.</para>
is out of bounds or the <structfield>pad</structfield> number is invalid.</para>
</listitem>
</varlistentry>
<varlistentry>

20
Documentation/DocBook/media/v4l/vidioc-subscribe-event.xml
View File

@ -154,6 +154,26 @@
frame interval in between them.</para>
</entry>
</row>
<row>
<entry><constant>V4L2_EVENT_SOURCE_CHANGE</constant></entry>
<entry>5</entry>
<entry>
<para>This event is triggered when a source parameter change is
detected during runtime by the video device. It can be a
runtime resolution change triggered by a video decoder or the
format change happening on an input connector.
This event requires that the <structfield>id</structfield>
matches the input index (when used with a video device node)
or the pad index (when used with a subdevice node) from which
you want to receive events.</para>
<para>This event has a &v4l2-event-src-change; associated
with it. The <structfield>changes</structfield> bitfield denotes
what has changed for the subscribed pad. If multiple events
occurred before application could dequeue them, then the changes
will have the ORed value of all the events generated.</para>
</entry>
</row>
<row>
<entry><constant>V4L2_EVENT_PRIVATE_START</constant></entry>
<entry>0x08000000</entry>

873
Documentation/DocBook/writing_musb_glue_layer.tmpl Normal file
View File

@ -0,0 +1,873 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []>
<book id="Writing-MUSB-Glue-Layer">
<bookinfo>
<title>Writing an MUSB Glue Layer</title>
<authorgroup>
<author>
<firstname>Apelete</firstname>
<surname>Seketeli</surname>
<affiliation>
<address>
<email>apelete at seketeli.net</email>
</address>
</affiliation>
</author>
</authorgroup>
<copyright>
<year>2014</year>
<holder>Apelete Seketeli</holder>
</copyright>
<legalnotice>
<para>
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.
</para>
<para>
This documentation is distributed in the hope that it will be
useful, but WITHOUT ANY WARRANTY; without even the implied
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
See the GNU General Public License for more details.
</para>
<para>
You should have received a copy of the GNU General Public License
along with this documentation; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
02111-1307 USA
</para>
<para>
For more details see the file COPYING in the Linux kernel source
tree.
</para>
</legalnotice>
</bookinfo>
<toc></toc>
<chapter id="introduction">
<title>Introduction</title>
<para>
The Linux MUSB subsystem is part of the larger Linux USB
subsystem. It provides support for embedded USB Device Controllers
(UDC) that do not use Universal Host Controller Interface (UHCI)
or Open Host Controller Interface (OHCI).
</para>
<para>
Instead, these embedded UDC rely on the USB On-the-Go (OTG)
specification which they implement at least partially. The silicon
reference design used in most cases is the Multipoint USB
Highspeed Dual-Role Controller (MUSB HDRC) found in the Mentor
Graphics Inventra™ design.
</para>
<para>
As a self-taught exercise I have written an MUSB glue layer for
the Ingenic JZ4740 SoC, modelled after the many MUSB glue layers
in the kernel source tree. This layer can be found at
drivers/usb/musb/jz4740.c. In this documentation I will walk
through the basics of the jz4740.c glue layer, explaining the
different pieces and what needs to be done in order to write your
own device glue layer.
</para>
</chapter>
<chapter id="linux-musb-basics">
<title>Linux MUSB Basics</title>
<para>
To get started on the topic, please read USB On-the-Go Basics (see
Resources) which provides an introduction of USB OTG operation at
the hardware level. A couple of wiki pages by Texas Instruments
and Analog Devices also provide an overview of the Linux kernel
MUSB configuration, albeit focused on some specific devices
provided by these companies. Finally, getting acquainted with the
USB specification at USB home page may come in handy, with
practical instance provided through the Writing USB Device Drivers
documentation (again, see Resources).
</para>
<para>
Linux USB stack is a layered architecture in which the MUSB
controller hardware sits at the lowest. The MUSB controller driver
abstract the MUSB controller hardware to the Linux USB stack.
</para>
<programlisting>
------------------------
| | &lt;------- drivers/usb/gadget
| Linux USB Core Stack | &lt;------- drivers/usb/host
| | &lt;------- drivers/usb/core
------------------------
⬍
--------------------------
| | &lt;------ drivers/usb/musb/musb_gadget.c
| MUSB Controller driver | &lt;------ drivers/usb/musb/musb_host.c
| | &lt;------ drivers/usb/musb/musb_core.c
--------------------------
⬍
---------------------------------
| MUSB Platform Specific Driver |
| | &lt;-- drivers/usb/musb/jz4740.c
| aka &quot;Glue Layer&quot; |
---------------------------------
⬍
---------------------------------
| MUSB Controller Hardware |
---------------------------------
</programlisting>
<para>
As outlined above, the glue layer is actually the platform
specific code sitting in between the controller driver and the
controller hardware.
</para>
<para>
Just like a Linux USB driver needs to register itself with the
Linux USB subsystem, the MUSB glue layer needs first to register
itself with the MUSB controller driver. This will allow the
controller driver to know about which device the glue layer
supports and which functions to call when a supported device is
detected or released; remember we are talking about an embedded
controller chip here, so no insertion or removal at run-time.
</para>
<para>
All of this information is passed to the MUSB controller driver
through a platform_driver structure defined in the glue layer as:
</para>
<programlisting linenumbering="numbered">
static struct platform_driver jz4740_driver = {
.probe = jz4740_probe,
.remove = jz4740_remove,
.driver = {
.name = "musb-jz4740",
},
};
</programlisting>
<para>
The probe and remove function pointers are called when a matching
device is detected and, respectively, released. The name string
describes the device supported by this glue layer. In the current
case it matches a platform_device structure declared in
arch/mips/jz4740/platform.c. Note that we are not using device
tree bindings here.
</para>
<para>
In order to register itself to the controller driver, the glue
layer goes through a few steps, basically allocating the
controller hardware resources and initialising a couple of
circuits. To do so, it needs to keep track of the information used
throughout these steps. This is done by defining a private
jz4740_glue structure:
</para>
<programlisting linenumbering="numbered">
struct jz4740_glue {
struct device *dev;
struct platform_device *musb;
struct clk *clk;
};
</programlisting>
<para>
The dev and musb members are both device structure variables. The
first one holds generic information about the device, since it's
the basic device structure, and the latter holds information more
closely related to the subsystem the device is registered to. The
clk variable keeps information related to the device clock
operation.
</para>
<para>
Let's go through the steps of the probe function that leads the
glue layer to register itself to the controller driver.
</para>
<para>
N.B.: For the sake of readability each function will be split in
logical parts, each part being shown as if it was independent from
the others.
</para>
<programlisting linenumbering="numbered">
static int jz4740_probe(struct platform_device *pdev)
{
struct platform_device *musb;
struct jz4740_glue *glue;
struct clk *clk;
int ret;
glue = devm_kzalloc(&amp;pdev->dev, sizeof(*glue), GFP_KERNEL);
if (!glue)
return -ENOMEM;
musb = platform_device_alloc("musb-hdrc", PLATFORM_DEVID_AUTO);
if (!musb) {
dev_err(&amp;pdev->dev, "failed to allocate musb device\n");
return -ENOMEM;
}
clk = devm_clk_get(&amp;pdev->dev, "udc");
if (IS_ERR(clk)) {
dev_err(&amp;pdev->dev, "failed to get clock\n");
ret = PTR_ERR(clk);
goto err_platform_device_put;
}
ret = clk_prepare_enable(clk);
if (ret) {
dev_err(&amp;pdev->dev, "failed to enable clock\n");
goto err_platform_device_put;
}
musb->dev.parent = &amp;pdev->dev;
glue->dev = &amp;pdev->dev;
glue->musb = musb;
glue->clk = clk;
return 0;
err_platform_device_put:
platform_device_put(musb);
return ret;
}
</programlisting>
<para>
The first few lines of the probe function allocate and assign the
glue, musb and clk variables. The GFP_KERNEL flag (line 8) allows
the allocation process to sleep and wait for memory, thus being
usable in a blocking situation. The PLATFORM_DEVID_AUTO flag (line
12) allows automatic allocation and management of device IDs in
order to avoid device namespace collisions with explicit IDs. With
devm_clk_get() (line 18) the glue layer allocates the clock -- the
<literal>devm_</literal> prefix indicates that clk_get() is
managed: it automatically frees the allocated clock resource data
when the device is released -- and enable it.
</para>
<para>
Then comes the registration steps:
</para>
<programlisting linenumbering="numbered">
static int jz4740_probe(struct platform_device *pdev)
{
struct musb_hdrc_platform_data *pdata = &amp;jz4740_musb_platform_data;
pdata->platform_ops = &amp;jz4740_musb_ops;
platform_set_drvdata(pdev, glue);
ret = platform_device_add_resources(musb, pdev->resource,
pdev->num_resources);
if (ret) {
dev_err(&amp;pdev->dev, "failed to add resources\n");
goto err_clk_disable;
}
ret = platform_device_add_data(musb, pdata, sizeof(*pdata));
if (ret) {
dev_err(&amp;pdev->dev, "failed to add platform_data\n");
goto err_clk_disable;
}
return 0;
err_clk_disable:
clk_disable_unprepare(clk);
err_platform_device_put:
platform_device_put(musb);
return ret;
}
</programlisting>
<para>
The first step is to pass the device data privately held by the
glue layer on to the controller driver through
platform_set_drvdata() (line 7). Next is passing on the device
resources information, also privately held at that point, through
platform_device_add_resources() (line 9).
</para>
<para>
Finally comes passing on the platform specific data to the
controller driver (line 16). Platform data will be discussed in
<link linkend="device-platform-data">Chapter 4</link>, but here
we are looking at the platform_ops function pointer (line 5) in
musb_hdrc_platform_data structure (line 3). This function
pointer allows the MUSB controller driver to know which function
to call for device operation:
</para>
<programlisting linenumbering="numbered">
static const struct musb_platform_ops jz4740_musb_ops = {
.init = jz4740_musb_init,
.exit = jz4740_musb_exit,
};
</programlisting>
<para>
Here we have the minimal case where only init and exit functions
are called by the controller driver when needed. Fact is the
JZ4740 MUSB controller is a basic controller, lacking some
features found in other controllers, otherwise we may also have
pointers to a few other functions like a power management function
or a function to switch between OTG and non-OTG modes, for
instance.
</para>
<para>
At that point of the registration process, the controller driver
actually calls the init function:
</para>
<programlisting linenumbering="numbered">
static int jz4740_musb_init(struct musb *musb)
{
musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
if (!musb->xceiv) {
pr_err("HS UDC: no transceiver configured\n");
return -ENODEV;
}
/* Silicon does not implement ConfigData register.
* Set dyn_fifo to avoid reading EP config from hardware.
*/
musb->dyn_fifo = true;
musb->isr = jz4740_musb_interrupt;
return 0;
}
</programlisting>
<para>
The goal of jz4740_musb_init() is to get hold of the transceiver
driver data of the MUSB controller hardware and pass it on to the
MUSB controller driver, as usual. The transceiver is the circuitry
inside the controller hardware responsible for sending/receiving
the USB data. Since it is an implementation of the physical layer
of the OSI model, the transceiver is also referred to as PHY.
</para>
<para>
Getting hold of the MUSB PHY driver data is done with
usb_get_phy() which returns a pointer to the structure
containing the driver instance data. The next couple of
instructions (line 12 and 14) are used as a quirk and to setup
IRQ handling respectively. Quirks and IRQ handling will be
discussed later in <link linkend="device-quirks">Chapter
5</link> and <link linkend="handling-irqs">Chapter 3</link>.
</para>
<programlisting linenumbering="numbered">
static int jz4740_musb_exit(struct musb *musb)
{
usb_put_phy(musb->xceiv);
return 0;
}
</programlisting>
<para>
Acting as the counterpart of init, the exit function releases the
MUSB PHY driver when the controller hardware itself is about to be
released.
</para>
<para>
Again, note that init and exit are fairly simple in this case due
to the basic set of features of the JZ4740 controller hardware.
When writing an musb glue layer for a more complex controller
hardware, you might need to take care of more processing in those
two functions.
</para>
<para>
Returning from the init function, the MUSB controller driver jumps
back into the probe function:
</para>
<programlisting linenumbering="numbered">
static int jz4740_probe(struct platform_device *pdev)
{
ret = platform_device_add(musb);
if (ret) {
dev_err(&amp;pdev->dev, "failed to register musb device\n");
goto err_clk_disable;
}
return 0;
err_clk_disable:
clk_disable_unprepare(clk);
err_platform_device_put:
platform_device_put(musb);
return ret;
}
</programlisting>
<para>
This is the last part of the device registration process where the
glue layer adds the controller hardware device to Linux kernel
device hierarchy: at this stage, all known information about the
device is passed on to the Linux USB core stack.
</para>
<programlisting linenumbering="numbered">
static int jz4740_remove(struct platform_device *pdev)
{
struct jz4740_glue *glue = platform_get_drvdata(pdev);
platform_device_unregister(glue->musb);
clk_disable_unprepare(glue->clk);
return 0;
}
</programlisting>
<para>
Acting as the counterpart of probe, the remove function unregister
the MUSB controller hardware (line 5) and disable the clock (line
6), allowing it to be gated.
</para>
</chapter>
<chapter id="handling-irqs">
<title>Handling IRQs</title>
<para>
Additionally to the MUSB controller hardware basic setup and
registration, the glue layer is also responsible for handling the
IRQs:
</para>
<programlisting linenumbering="numbered">
static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
{
unsigned long flags;
irqreturn_t retval = IRQ_NONE;
struct musb *musb = __hci;
spin_lock_irqsave(&amp;musb->lock, flags);
musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
/*
* The controller is gadget only, the state of the host mode IRQ bits is
* undefined. Mask them to make sure that the musb driver core will
* never see them set
*/
musb->int_usb &amp;= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
MUSB_INTR_RESET | MUSB_INTR_SOF;
if (musb->int_usb || musb->int_tx || musb->int_rx)
retval = musb_interrupt(musb);
spin_unlock_irqrestore(&amp;musb->lock, flags);
return retval;
}
</programlisting>
<para>
Here the glue layer mostly has to read the relevant hardware
registers and pass their values on to the controller driver which
will handle the actual event that triggered the IRQ.
</para>
<para>
The interrupt handler critical section is protected by the
spin_lock_irqsave() and counterpart spin_unlock_irqrestore()
functions (line 7 and 24 respectively), which prevent the
interrupt handler code to be run by two different threads at the
same time.
</para>
<para>
Then the relevant interrupt registers are read (line 9 to 11):
</para>
<itemizedlist>
<listitem>
<para>
MUSB_INTRUSB: indicates which USB interrupts are currently
active,
</para>
</listitem>
<listitem>
<para>
MUSB_INTRTX: indicates which of the interrupts for TX
endpoints are currently active,
</para>
</listitem>
<listitem>
<para>
MUSB_INTRRX: indicates which of the interrupts for TX
endpoints are currently active.
</para>
</listitem>
</itemizedlist>
<para>
Note that musb_readb() is used to read 8-bit registers at most,
while musb_readw() allows us to read at most 16-bit registers.
There are other functions that can be used depending on the size
of your device registers. See musb_io.h for more information.
</para>
<para>
Instruction on line 18 is another quirk specific to the JZ4740
USB device controller, which will be discussed later in <link
linkend="device-quirks">Chapter 5</link>.
</para>
<para>
The glue layer still needs to register the IRQ handler though.
Remember the instruction on line 14 of the init function:
</para>
<programlisting linenumbering="numbered">
static int jz4740_musb_init(struct musb *musb)
{
musb->isr = jz4740_musb_interrupt;
return 0;
}
</programlisting>
<para>
This instruction sets a pointer to the glue layer IRQ handler
function, in order for the controller hardware to call the handler
back when an IRQ comes from the controller hardware. The interrupt
handler is now implemented and registered.
</para>
</chapter>
<chapter id="device-platform-data">
<title>Device Platform Data</title>
<para>
In order to write an MUSB glue layer, you need to have some data
describing the hardware capabilities of your controller hardware,
which is called the platform data.
</para>
<para>
Platform data is specific to your hardware, though it may cover a
broad range of devices, and is generally found somewhere in the
arch/ directory, depending on your device architecture.
</para>
<para>
For instance, platform data for the JZ4740 SoC is found in
arch/mips/jz4740/platform.c. In the platform.c file each device of
the JZ4740 SoC is described through a set of structures.
</para>
<para>
Here is the part of arch/mips/jz4740/platform.c that covers the
USB Device Controller (UDC):
</para>
<programlisting linenumbering="numbered">
/* USB Device Controller */
struct platform_device jz4740_udc_xceiv_device = {
.name = "usb_phy_gen_xceiv",
.id = 0,
};
static struct resource jz4740_udc_resources[] = {
[0] = {
.start = JZ4740_UDC_BASE_ADDR,
.end = JZ4740_UDC_BASE_ADDR + 0x10000 - 1,
.flags = IORESOURCE_MEM,
},
[1] = {
.start = JZ4740_IRQ_UDC,
.end = JZ4740_IRQ_UDC,
.flags = IORESOURCE_IRQ,
.name = "mc",
},
};
struct platform_device jz4740_udc_device = {
.name = "musb-jz4740",
.id = -1,
.dev = {
.dma_mask = &amp;jz4740_udc_device.dev.coherent_dma_mask,
.coherent_dma_mask = DMA_BIT_MASK(32),
},
.num_resources = ARRAY_SIZE(jz4740_udc_resources),
.resource = jz4740_udc_resources,
};
</programlisting>
<para>
The jz4740_udc_xceiv_device platform device structure (line 2)
describes the UDC transceiver with a name and id number.
</para>
<para>
At the time of this writing, note that
&quot;usb_phy_gen_xceiv&quot; is the specific name to be used for
all transceivers that are either built-in with reference USB IP or
autonomous and doesn't require any PHY programming. You will need
to set CONFIG_NOP_USB_XCEIV=y in the kernel configuration to make
use of the corresponding transceiver driver. The id field could be
set to -1 (equivalent to PLATFORM_DEVID_NONE), -2 (equivalent to
PLATFORM_DEVID_AUTO) or start with 0 for the first device of this
kind if we want a specific id number.
</para>
<para>
The jz4740_udc_resources resource structure (line 7) defines the
UDC registers base addresses.
</para>
<para>
The first array (line 9 to 11) defines the UDC registers base
memory addresses: start points to the first register memory
address, end points to the last register memory address and the
flags member defines the type of resource we are dealing with. So
IORESOURCE_MEM is used to define the registers memory addresses.
The second array (line 14 to 17) defines the UDC IRQ registers
addresses. Since there is only one IRQ register available for the
JZ4740 UDC, start and end point at the same address. The
IORESOURCE_IRQ flag tells that we are dealing with IRQ resources,
and the name &quot;mc&quot; is in fact hard-coded in the MUSB core
in order for the controller driver to retrieve this IRQ resource
by querying it by its name.
</para>
<para>
Finally, the jz4740_udc_device platform device structure (line 21)
describes the UDC itself.
</para>
<para>
The &quot;musb-jz4740&quot; name (line 22) defines the MUSB
driver that is used for this device; remember this is in fact
the name that we used in the jz4740_driver platform driver
structure in <link linkend="linux-musb-basics">Chapter
2</link>. The id field (line 23) is set to -1 (equivalent to
PLATFORM_DEVID_NONE) since we do not need an id for the device:
the MUSB controller driver was already set to allocate an
automatic id in <link linkend="linux-musb-basics">Chapter
2</link>. In the dev field we care for DMA related information
here. The dma_mask field (line 25) defines the width of the DMA
mask that is going to be used, and coherent_dma_mask (line 26)
has the same purpose but for the alloc_coherent DMA mappings: in
both cases we are using a 32 bits mask. Then the resource field
(line 29) is simply a pointer to the resource structure defined
before, while the num_resources field (line 28) keeps track of
the number of arrays defined in the resource structure (in this
case there were two resource arrays defined before).
</para>
<para>
With this quick overview of the UDC platform data at the arch/
level now done, let's get back to the MUSB glue layer specific
platform data in drivers/usb/musb/jz4740.c:
</para>
<programlisting linenumbering="numbered">
static struct musb_hdrc_config jz4740_musb_config = {
/* Silicon does not implement USB OTG. */
.multipoint = 0,
/* Max EPs scanned, driver will decide which EP can be used. */
.num_eps = 4,
/* RAMbits needed to configure EPs from table */
.ram_bits = 9,
.fifo_cfg = jz4740_musb_fifo_cfg,
.fifo_cfg_size = ARRAY_SIZE(jz4740_musb_fifo_cfg),
};
static struct musb_hdrc_platform_data jz4740_musb_platform_data = {
.mode = MUSB_PERIPHERAL,
.config = &amp;jz4740_musb_config,
};
</programlisting>
<para>
First the glue layer configures some aspects of the controller
driver operation related to the controller hardware specifics.
This is done through the jz4740_musb_config musb_hdrc_config
structure.
</para>
<para>
Defining the OTG capability of the controller hardware, the
multipoint member (line 3) is set to 0 (equivalent to false)
since the JZ4740 UDC is not OTG compatible. Then num_eps (line
5) defines the number of USB endpoints of the controller
hardware, including endpoint 0: here we have 3 endpoints +
endpoint 0. Next is ram_bits (line 7) which is the width of the
RAM address bus for the MUSB controller hardware. This
information is needed when the controller driver cannot
automatically configure endpoints by reading the relevant
controller hardware registers. This issue will be discussed when
we get to device quirks in <link linkend="device-quirks">Chapter
5</link>. Last two fields (line 8 and 9) are also about device
quirks: fifo_cfg points to the USB endpoints configuration table
and fifo_cfg_size keeps track of the size of the number of
entries in that configuration table. More on that later in <link
linkend="device-quirks">Chapter 5</link>.
</para>
<para>
Then this configuration is embedded inside
jz4740_musb_platform_data musb_hdrc_platform_data structure (line
11): config is a pointer to the configuration structure itself,
and mode tells the controller driver if the controller hardware
may be used as MUSB_HOST only, MUSB_PERIPHERAL only or MUSB_OTG
which is a dual mode.
</para>
<para>
Remember that jz4740_musb_platform_data is then used to convey
platform data information as we have seen in the probe function
in <link linkend="linux-musb-basics">Chapter 2</link>
</para>
</chapter>
<chapter id="device-quirks">
<title>Device Quirks</title>
<para>
Completing the platform data specific to your device, you may also
need to write some code in the glue layer to work around some
device specific limitations. These quirks may be due to some
hardware bugs, or simply be the result of an incomplete
implementation of the USB On-the-Go specification.
</para>
<para>
The JZ4740 UDC exhibits such quirks, some of which we will discuss
here for the sake of insight even though these might not be found
in the controller hardware you are working on.
</para>
<para>
Let's get back to the init function first:
</para>
<programlisting linenumbering="numbered">
static int jz4740_musb_init(struct musb *musb)
{
musb->xceiv = usb_get_phy(USB_PHY_TYPE_USB2);
if (!musb->xceiv) {
pr_err("HS UDC: no transceiver configured\n");
return -ENODEV;
}
/* Silicon does not implement ConfigData register.
* Set dyn_fifo to avoid reading EP config from hardware.
*/
musb->dyn_fifo = true;
musb->isr = jz4740_musb_interrupt;
return 0;
}
</programlisting>
<para>
Instruction on line 12 helps the MUSB controller driver to work
around the fact that the controller hardware is missing registers
that are used for USB endpoints configuration.
</para>
<para>
Without these registers, the controller driver is unable to read
the endpoints configuration from the hardware, so we use line 12
instruction to bypass reading the configuration from silicon, and
rely on a hard-coded table that describes the endpoints
configuration instead:
</para>
<programlisting linenumbering="numbered">
static struct musb_fifo_cfg jz4740_musb_fifo_cfg[] = {
{ .hw_ep_num = 1, .style = FIFO_TX, .maxpacket = 512, },
{ .hw_ep_num = 1, .style = FIFO_RX, .maxpacket = 512, },
{ .hw_ep_num = 2, .style = FIFO_TX, .maxpacket = 64, },
};
</programlisting>
<para>
Looking at the configuration table above, we see that each
endpoints is described by three fields: hw_ep_num is the endpoint
number, style is its direction (either FIFO_TX for the controller
driver to send packets in the controller hardware, or FIFO_RX to
receive packets from hardware), and maxpacket defines the maximum
size of each data packet that can be transmitted over that
endpoint. Reading from the table, the controller driver knows that
endpoint 1 can be used to send and receive USB data packets of 512
bytes at once (this is in fact a bulk in/out endpoint), and
endpoint 2 can be used to send data packets of 64 bytes at once
(this is in fact an interrupt endpoint).
</para>
<para>
Note that there is no information about endpoint 0 here: that one
is implemented by default in every silicon design, with a
predefined configuration according to the USB specification. For
more examples of endpoint configuration tables, see musb_core.c.
</para>
<para>
Let's now get back to the interrupt handler function:
</para>
<programlisting linenumbering="numbered">
static irqreturn_t jz4740_musb_interrupt(int irq, void *__hci)
{
unsigned long flags;
irqreturn_t retval = IRQ_NONE;
struct musb *musb = __hci;
spin_lock_irqsave(&amp;musb->lock, flags);
musb->int_usb = musb_readb(musb->mregs, MUSB_INTRUSB);
musb->int_tx = musb_readw(musb->mregs, MUSB_INTRTX);
musb->int_rx = musb_readw(musb->mregs, MUSB_INTRRX);
/*
* The controller is gadget only, the state of the host mode IRQ bits is
* undefined. Mask them to make sure that the musb driver core will
* never see them set
*/
musb->int_usb &amp;= MUSB_INTR_SUSPEND | MUSB_INTR_RESUME |
MUSB_INTR_RESET | MUSB_INTR_SOF;
if (musb->int_usb || musb->int_tx || musb->int_rx)
retval = musb_interrupt(musb);
spin_unlock_irqrestore(&amp;musb->lock, flags);
return retval;
}
</programlisting>
<para>
Instruction on line 18 above is a way for the controller driver to
work around the fact that some interrupt bits used for USB host
mode operation are missing in the MUSB_INTRUSB register, thus left
in an undefined hardware state, since this MUSB controller
hardware is used in peripheral mode only. As a consequence, the
glue layer masks these missing bits out to avoid parasite
interrupts by doing a logical AND operation between the value read
from MUSB_INTRUSB and the bits that are actually implemented in
the register.
</para>
<para>
These are only a couple of the quirks found in the JZ4740 USB
device controller. Some others were directly addressed in the MUSB
core since the fixes were generic enough to provide a better
handling of the issues for others controller hardware eventually.
</para>
</chapter>
<chapter id="conclusion">
<title>Conclusion</title>
<para>
Writing a Linux MUSB glue layer should be a more accessible task,
as this documentation tries to show the ins and outs of this
exercise.
</para>
<para>
The JZ4740 USB device controller being fairly simple, I hope its
glue layer serves as a good example for the curious mind. Used
with the current MUSB glue layers, this documentation should
provide enough guidance to get started; should anything gets out
of hand, the linux-usb mailing list archive is another helpful
resource to browse through.
</para>
</chapter>
<chapter id="acknowledgements">
<title>Acknowledgements</title>
<para>
Many thanks to Lars-Peter Clausen and Maarten ter Huurne for
answering my questions while I was writing the JZ4740 glue layer
and for helping me out getting the code in good shape.
</para>
<para>
I would also like to thank the Qi-Hardware community at large for
its cheerful guidance and support.
</para>
</chapter>
<chapter id="resources">
<title>Resources</title>
<para>
USB Home Page:
<ulink url="http://www.usb.org">http://www.usb.org</ulink>
</para>
<para>
linux-usb Mailing List Archives:
<ulink url="http://marc.info/?l=linux-usb">http://marc.info/?l=linux-usb</ulink>
</para>
<para>
USB On-the-Go Basics:
<ulink url="http://www.maximintegrated.com/app-notes/index.mvp/id/1822">http://www.maximintegrated.com/app-notes/index.mvp/id/1822</ulink>
</para>
<para>
Writing USB Device Drivers:
<ulink url="https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html">https://www.kernel.org/doc/htmldocs/writing_usb_driver/index.html</ulink>
</para>
<para>
Texas Instruments USB Configuration Wiki Page:
<ulink url="http://processors.wiki.ti.com/index.php/Usbgeneralpage">http://processors.wiki.ti.com/index.php/Usbgeneralpage</ulink>
</para>
<para>
Analog Devices Blackfin MUSB Configuration:
<ulink url="http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb">http://docs.blackfin.uclinux.org/doku.php?id=linux-kernel:drivers:musb</ulink>
</para>
</chapter>
</book>

3
Documentation/IRQ-domain.txt
View File

@ -41,8 +41,7 @@ An interrupt controller driver creates and registers an irq_domain by
calling one of the irq_domain_add_*() functions (each mapping method
has a different allocator function, more on that later). The function
will return a pointer to the irq_domain on success. The caller must
provide the allocator function with an irq_domain_ops structure with
the .map callback populated as a minimum.
provide the allocator function with an irq_domain_ops structure.
In most cases, the irq_domain will begin empty without any mappings
between hwirq and IRQ numbers. Mappings are added to the irq_domain

2
Documentation/RCU/00-INDEX
View File

@ -12,6 +12,8 @@ lockdep-splat.txt
- RCU Lockdep splats explained.
NMI-RCU.txt
- Using RCU to Protect Dynamic NMI Handlers
rcu_dereference.txt
- Proper care and feeding of return values from rcu_dereference()
rcubarrier.txt
- RCU and Unloadable Modules
rculist_nulls.txt

12
Documentation/RCU/checklist.txt
View File

@ -114,12 +114,16 @@ over a rather long period of time, but improvements are always welcome!
http://www.openvms.compaq.com/wizard/wiz_2637.html
The rcu_dereference() primitive is also an excellent
documentation aid, letting the person reading the code
know exactly which pointers are protected by RCU.
documentation aid, letting the person reading the
code know exactly which pointers are protected by RCU.
Please note that compilers can also reorder code, and
they are becoming increasingly aggressive about doing
just that. The rcu_dereference() primitive therefore
also prevents destructive compiler optimizations.
just that. The rcu_dereference() primitive therefore also
prevents destructive compiler optimizations. However,
with a bit of devious creativity, it is possible to
mishandle the return value from rcu_dereference().
Please see rcu_dereference.txt in this directory for
more information.
The rcu_dereference() primitive is used by the
various "_rcu()" list-traversal primitives, such

371
Documentation/RCU/rcu_dereference.txt Normal file
View File

@ -0,0 +1,371 @@
PROPER CARE AND FEEDING OF RETURN VALUES FROM rcu_dereference()
Most of the time, you can use values from rcu_dereference() or one of
the similar primitives without worries. Dereferencing (prefix "*"),
field selection ("->"), assignment ("="), address-of ("&"), addition and
subtraction of constants, and casts all work quite naturally and safely.
It is nevertheless possible to get into trouble with other operations.
Follow these rules to keep your RCU code working properly:
o You must use one of the rcu_dereference() family of primitives
to load an RCU-protected pointer, otherwise CONFIG_PROVE_RCU
will complain. Worse yet, your code can see random memory-corruption
bugs due to games that compilers and DEC Alpha can play.
Without one of the rcu_dereference() primitives, compilers
can reload the value, and won't your code have fun with two
different values for a single pointer! Without rcu_dereference(),
DEC Alpha can load a pointer, dereference that pointer, and
return data preceding initialization that preceded the store of
the pointer.
In addition, the volatile cast in rcu_dereference() prevents the
compiler from deducing the resulting pointer value. Please see
the section entitled "EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH"
for an example where the compiler can in fact deduce the exact
value of the pointer, and thus cause misordering.
o Do not use single-element RCU-protected arrays. The compiler
is within its right to assume that the value of an index into
such an array must necessarily evaluate to zero. The compiler
could then substitute the constant zero for the computation, so
that the array index no longer depended on the value returned
by rcu_dereference(). If the array index no longer depends
on rcu_dereference(), then both the compiler and the CPU
are within their rights to order the array access before the
rcu_dereference(), which can cause the array access to return
garbage.
o Avoid cancellation when using the "+" and "-" infix arithmetic
operators. For example, for a given variable "x", avoid
"(x-x)". There are similar arithmetic pitfalls from other
arithmetic operatiors, such as "(x*0)", "(x/(x+1))" or "(x%1)".
The compiler is within its rights to substitute zero for all of
these expressions, so that subsequent accesses no longer depend
on the rcu_dereference(), again possibly resulting in bugs due
to misordering.
Of course, if "p" is a pointer from rcu_dereference(), and "a"
and "b" are integers that happen to be equal, the expression
"p+a-b" is safe because its value still necessarily depends on
the rcu_dereference(), thus maintaining proper ordering.
o Avoid all-zero operands to the bitwise "&" operator, and
similarly avoid all-ones operands to the bitwise "|" operator.
If the compiler is able to deduce the value of such operands,
it is within its rights to substitute the corresponding constant
for the bitwise operation. Once again, this causes subsequent
accesses to no longer depend on the rcu_dereference(), causing
bugs due to misordering.
Please note that single-bit operands to bitwise "&" can also
be dangerous. At this point, the compiler knows that the
resulting value can only take on one of two possible values.
Therefore, a very small amount of additional information will
allow the compiler to deduce the exact value, which again can
result in misordering.
o If you are using RCU to protect JITed functions, so that the
"()" function-invocation operator is applied to a value obtained
(directly or indirectly) from rcu_dereference(), you may need to
interact directly with the hardware to flush instruction caches.
This issue arises on some systems when a newly JITed function is
using the same memory that was used by an earlier JITed function.
o Do not use the results from the boolean "&&" and "||" when
dereferencing. For example, the following (rather improbable)
code is buggy:
int a[2];
int index;
int force_zero_index = 1;
...
r1 = rcu_dereference(i1)
r2 = a[r1 && force_zero_index]; /* BUGGY!!! */
The reason this is buggy is that "&&" and "||" are often compiled
using branches. While weak-memory machines such as ARM or PowerPC
do order stores after such branches, they can speculate loads,
which can result in misordering bugs.
o Do not use the results from relational operators ("==", "!=",
">", ">=", "<", or "<=") when dereferencing. For example,
the following (quite strange) code is buggy:
int a[2];
int index;
int flip_index = 0;
...
r1 = rcu_dereference(i1)
r2 = a[r1 != flip_index]; /* BUGGY!!! */
As before, the reason this is buggy is that relational operators
are often compiled using branches. And as before, although
weak-memory machines such as ARM or PowerPC do order stores
after such branches, but can speculate loads, which can again
result in misordering bugs.
o Be very careful about comparing pointers obtained from
rcu_dereference() against non-NULL values. As Linus Torvalds
explained, if the two pointers are equal, the compiler could
substitute the pointer you are comparing against for the pointer
obtained from rcu_dereference(). For example:
p = rcu_dereference(gp);
if (p == &default_struct)
do_default(p->a);
Because the compiler now knows that the value of "p" is exactly
the address of the variable "default_struct", it is free to
transform this code into the following:
p = rcu_dereference(gp);
if (p == &default_struct)
do_default(default_struct.a);
On ARM and Power hardware, the load from "default_struct.a"
can now be speculated, such that it might happen before the
rcu_dereference(). This could result in bugs due to misordering.
However, comparisons are OK in the following cases:
o The comparison was against the NULL pointer. If the
compiler knows that the pointer is NULL, you had better
not be dereferencing it anyway. If the comparison is
non-equal, the compiler is none the wiser. Therefore,
it is safe to compare pointers from rcu_dereference()
against NULL pointers.
o The pointer is never dereferenced after being compared.
Since there are no subsequent dereferences, the compiler
cannot use anything it learned from the comparison
to reorder the non-existent subsequent dereferences.
This sort of comparison occurs frequently when scanning
RCU-protected circular linked lists.
o The comparison is against a pointer that references memory
that was initialized "a long time ago." The reason
this is safe is that even if misordering occurs, the
misordering will not affect the accesses that follow
the comparison. So exactly how long ago is "a long
time ago"? Here are some possibilities:
o Compile time.
o Boot time.
o Module-init time for module code.
o Prior to kthread creation for kthread code.
o During some prior acquisition of the lock that
we now hold.
o Before mod_timer() time for a timer handler.
There are many other possibilities involving the Linux
kernel's wide array of primitives that cause code to
be invoked at a later time.
o The pointer being compared against also came from
rcu_dereference(). In this case, both pointers depend
on one rcu_dereference() or another, so you get proper
ordering either way.
That said, this situation can make certain RCU usage
bugs more likely to happen. Which can be a good thing,
at least if they happen during testing. An example
of such an RCU usage bug is shown in the section titled
"EXAMPLE OF AMPLIFIED RCU-USAGE BUG".
o All of the accesses following the comparison are stores,
so that a control dependency preserves the needed ordering.
That said, it is easy to get control dependencies wrong.
Please see the "CONTROL DEPENDENCIES" section of
Documentation/memory-barriers.txt for more details.
o The pointers are not equal -and- the compiler does
not have enough information to deduce the value of the
pointer. Note that the volatile cast in rcu_dereference()
will normally prevent the compiler from knowing too much.
o Disable any value-speculation optimizations that your compiler
might provide, especially if you are making use of feedback-based
optimizations that take data collected from prior runs. Such
value-speculation optimizations reorder operations by design.
There is one exception to this rule: Value-speculation
optimizations that leverage the branch-prediction hardware are
safe on strongly ordered systems (such as x86), but not on weakly
ordered systems (such as ARM or Power). Choose your compiler
command-line options wisely!
EXAMPLE OF AMPLIFIED RCU-USAGE BUG
Because updaters can run concurrently with RCU readers, RCU readers can
see stale and/or inconsistent values. If RCU readers need fresh or
consistent values, which they sometimes do, they need to take proper
precautions. To see this, consider the following code fragment:
struct foo {
int a;
int b;
int c;
};
struct foo *gp1;
struct foo *gp2;
void updater(void)
{
struct foo *p;
p = kmalloc(...);
if (p == NULL)
deal_with_it();
p->a = 42; /* Each field in its own cache line. */
p->b = 43;
p->c = 44;
rcu_assign_pointer(gp1, p);
p->b = 143;
p->c = 144;
rcu_assign_pointer(gp2, p);
}
void reader(void)
{
struct foo *p;
struct foo *q;
int r1, r2;
p = rcu_dereference(gp2);
if (p == NULL)
return;
r1 = p->b; /* Guaranteed to get 143. */
q = rcu_dereference(gp1); /* Guaranteed non-NULL. */
if (p == q) {
/* The compiler decides that q->c is same as p->c. */
r2 = p->c; /* Could get 44 on weakly order system. */
}
do_something_with(r1, r2);
}
You might be surprised that the outcome (r1 == 143 && r2 == 44) is possible,
but you should not be. After all, the updater might have been invoked
a second time between the time reader() loaded into "r1" and the time
that it loaded into "r2". The fact that this same result can occur due
to some reordering from the compiler and CPUs is beside the point.
But suppose that the reader needs a consistent view?
Then one approach is to use locking, for example, as follows:
struct foo {
int a;
int b;
int c;
spinlock_t lock;
};
struct foo *gp1;
struct foo *gp2;
void updater(void)
{
struct foo *p;
p = kmalloc(...);
if (p == NULL)
deal_with_it();
spin_lock(&p->lock);
p->a = 42; /* Each field in its own cache line. */
p->b = 43;
p->c = 44;
spin_unlock(&p->lock);
rcu_assign_pointer(gp1, p);
spin_lock(&p->lock);
p->b = 143;
p->c = 144;
spin_unlock(&p->lock);
rcu_assign_pointer(gp2, p);
}
void reader(void)
{
struct foo *p;
struct foo *q;
int r1, r2;
p = rcu_dereference(gp2);
if (p == NULL)
return;
spin_lock(&p->lock);
r1 = p->b; /* Guaranteed to get 143. */
q = rcu_dereference(gp1); /* Guaranteed non-NULL. */
if (p == q) {
/* The compiler decides that q->c is same as p->c. */
r2 = p->c; /* Locking guarantees r2 == 144. */
}
spin_unlock(&p->lock);
do_something_with(r1, r2);
}
As always, use the right tool for the job!
EXAMPLE WHERE THE COMPILER KNOWS TOO MUCH
If a pointer obtained from rcu_dereference() compares not-equal to some
other pointer, the compiler normally has no clue what the value of the
first pointer might be. This lack of knowledge prevents the compiler
from carrying out optimizations that otherwise might destroy the ordering
guarantees that RCU depends on. And the volatile cast in rcu_dereference()
should prevent the compiler from guessing the value.
But without rcu_dereference(), the compiler knows more than you might
expect. Consider the following code fragment:
struct foo {
int a;
int b;
};
static struct foo variable1;
static struct foo variable2;
static struct foo *gp = &variable1;
void updater(void)
{
initialize_foo(&variable2);
rcu_assign_pointer(gp, &variable2);
/*
* The above is the only store to gp in this translation unit,
* and the address of gp is not exported in any way.
*/
}
int reader(void)
{
struct foo *p;
p = gp;
barrier();
if (p == &variable1)
return p->a; /* Must be variable1.a. */
else
return p->b; /* Must be variable2.b. */
}
Because the compiler can see all stores to "gp", it knows that the only
possible values of "gp" are "variable1" on the one hand and "variable2"
on the other. The comparison in reader() therefore tells the compiler
the exact value of "p" even in the not-equals case. This allows the
compiler to make the return values independent of the load from "gp",
in turn destroying the ordering between this load and the loads of the
return values. This can result in "p->b" returning pre-initialization
garbage values.
In short, rcu_dereference() is -not- optional when you are going to
dereference the resulting pointer.

2
Documentation/RCU/stallwarn.txt
View File

@ -24,7 +24,7 @@ CONFIG_RCU_CPU_STALL_TIMEOUT
timing of the next warning for the current stall.
Stall-warning messages may be enabled and disabled completely via
/sys/module/rcutree/parameters/rcu_cpu_stall_suppress.
/sys/module/rcupdate/parameters/rcu_cpu_stall_suppress.
CONFIG_RCU_CPU_STALL_VERBOSE

57
Documentation/RCU/whatisRCU.txt
View File

@ -326,11 +326,11 @@ used as follows:
a. synchronize_rcu() rcu_read_lock() / rcu_read_unlock()
call_rcu() rcu_dereference()
b. call_rcu_bh() rcu_read_lock_bh() / rcu_read_unlock_bh()
rcu_dereference_bh()
b. synchronize_rcu_bh() rcu_read_lock_bh() / rcu_read_unlock_bh()
call_rcu_bh() rcu_dereference_bh()
c. synchronize_sched() rcu_read_lock_sched() / rcu_read_unlock_sched()
preempt_disable() / preempt_enable()
call_rcu_sched() preempt_disable() / preempt_enable()
local_irq_save() / local_irq_restore()
hardirq enter / hardirq exit
NMI enter / NMI exit
@ -794,10 +794,22 @@ in docbook. Here is the list, by category.
RCU list traversal:
list_entry_rcu
list_first_entry_rcu
list_next_rcu
list_for_each_entry_rcu
hlist_for_each_entry_rcu
hlist_nulls_for_each_entry_rcu
list_for_each_entry_continue_rcu
hlist_first_rcu
hlist_next_rcu
hlist_pprev_rcu
hlist_for_each_entry_rcu
hlist_for_each_entry_rcu_bh
hlist_for_each_entry_continue_rcu
hlist_for_each_entry_continue_rcu_bh
hlist_nulls_first_rcu
hlist_nulls_for_each_entry_rcu
hlist_bl_first_rcu
hlist_bl_for_each_entry_rcu
RCU pointer/list update:
@ -806,28 +818,38 @@ RCU pointer/list update:
list_add_tail_rcu
list_del_rcu
list_replace_rcu
hlist_del_rcu
hlist_add_after_rcu
hlist_add_before_rcu
hlist_add_head_rcu
hlist_del_rcu
hlist_del_init_rcu
hlist_replace_rcu
list_splice_init_rcu()
hlist_nulls_del_init_rcu
hlist_nulls_del_rcu
hlist_nulls_add_head_rcu
hlist_bl_add_head_rcu
hlist_bl_del_init_rcu
hlist_bl_del_rcu
hlist_bl_set_first_rcu
RCU: Critical sections Grace period Barrier
rcu_read_lock synchronize_net rcu_barrier
rcu_read_unlock synchronize_rcu
rcu_dereference synchronize_rcu_expedited
call_rcu
kfree_rcu
rcu_read_lock_held call_rcu
rcu_dereference_check kfree_rcu
rcu_dereference_protected
bh: Critical sections Grace period Barrier
rcu_read_lock_bh call_rcu_bh rcu_barrier_bh
rcu_read_unlock_bh synchronize_rcu_bh
rcu_dereference_bh synchronize_rcu_bh_expedited
rcu_dereference_bh_check
rcu_dereference_bh_protected
rcu_read_lock_bh_held
sched: Critical sections Grace period Barrier
@ -835,7 +857,12 @@ sched: Critical sections Grace period Barrier
rcu_read_unlock_sched call_rcu_sched
[preempt_disable] synchronize_sched_expedited
[and friends]
rcu_read_lock_sched_notrace
rcu_read_unlock_sched_notrace
rcu_dereference_sched
rcu_dereference_sched_check
rcu_dereference_sched_protected
rcu_read_lock_sched_held
SRCU: Critical sections Grace period Barrier
@ -843,6 +870,8 @@ SRCU: Critical sections Grace period Barrier
srcu_read_lock synchronize_srcu srcu_barrier
srcu_read_unlock call_srcu
srcu_dereference synchronize_srcu_expedited
srcu_dereference_check
srcu_read_lock_held
SRCU: Initialization/cleanup
init_srcu_struct
@ -850,9 +879,13 @@ SRCU: Initialization/cleanup
All: lockdep-checked RCU-protected pointer access
rcu_dereference_check
rcu_dereference_protected
rcu_access_index
rcu_access_pointer
rcu_dereference_index_check
rcu_dereference_raw
rcu_lockdep_assert
rcu_sleep_check
RCU_NONIDLE
See the comment headers in the source code (or the docbook generated
from them) for more information.

22
Documentation/SubmittingPatches
View File

@ -132,6 +132,20 @@ Example:
platform_set_drvdata(), but left the variable "dev" unused,
delete it.
If your patch fixes a bug in a specific commit, e.g. you found an issue using
git-bisect, please use the 'Fixes:' tag with the first 12 characters of the
SHA-1 ID, and the one line summary.
Example:
Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
The following git-config settings can be used to add a pretty format for
outputting the above style in the git log or git show commands
[core]
abbrev = 12
[pretty]
fixes = Fixes: %h (\"%s\")
3) Separate your changes.
@ -443,7 +457,7 @@ person it names. This tag documents that potentially interested parties
have been included in the discussion
14) Using Reported-by:, Tested-by:, Reviewed-by: and Suggested-by:
14) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
If this patch fixes a problem reported by somebody else, consider adding a
Reported-by: tag to credit the reporter for their contribution. Please
@ -498,6 +512,12 @@ idea was not posted in a public forum. That said, if we diligently credit our
idea reporters, they will, hopefully, be inspired to help us again in the
future.
A Fixes: tag indicates that the patch fixes an issue in a previous commit. It
is used to make it easy to determine where a bug originated, which can help
review a bug fix. This tag also assists the stable kernel team in determining
which stable kernel versions should receive your fix. This is the preferred
method for indicating a bug fixed by the patch. See #2 above for more details.
15) The canonical patch format

2
Documentation/acpi/enumeration.txt
View File

@ -296,7 +296,7 @@ specifies the path to the controller. In order to use these GPIOs in Linux
we need to translate them to the corresponding Linux GPIO descriptors.
There is a standard GPIO API for that and is documented in
Documentation/gpio.txt.
Documentation/gpio/.
In the above example we can get the corresponding two GPIO descriptors with
a code like this:

2
Documentation/arm/00-INDEX
View File

@ -46,5 +46,7 @@ swp_emulation
- SWP/SWPB emulation handler/logging description
tcm.txt
- ARM Tightly Coupled Memory
uefi.txt
- [U]EFI configuration and runtime services documentation
vlocks.txt
- Voting locks, low-level mechanism relying on memory system atomic writes.

5
Documentation/arm/Marvell/README
View File

@ -234,6 +234,11 @@ Berlin family (Digital Entertainment)
Core: Marvell PJ4B (ARMv7), Tauros3 L2CC
Homepage: http://www.marvell.com/digital-entertainment/armada-1500/
Product Brief: http://www.marvell.com/digital-entertainment/armada-1500/assets/Marvell-ARMADA-1500-Product-Brief.pdf
88DE3114, Armada 1500 Pro
Design name: BG2-Q
Core: Quad Core ARM Cortex-A9, PL310 L2CC
Homepage: http://www.marvell.com/digital-entertainment/armada-1500-pro/
Product Brief: http://www.marvell.com/digital-entertainment/armada-1500-pro/assets/Marvell_ARMADA_1500_PRO-01_product_brief.pdf
88DE????
Design name: BG3
Core: ARM Cortex-A15, CA15 integrated L2CC

9
Documentation/arm/memory.txt
View File

@ -41,16 +41,9 @@ fffe8000 fffeffff DTCM mapping area for platforms with
fffe0000 fffe7fff ITCM mapping area for platforms with
ITCM mounted inside the CPU.
fff00000 fffdffff Fixmap mapping region. Addresses provided
ffc00000 ffdfffff Fixmap mapping region. Addresses provided
by fix_to_virt() will be located here.
ffc00000 ffefffff DMA memory mapping region. Memory returned
by the dma_alloc_xxx functions will be
dynamically mapped here.
ff000000 ffbfffff Reserved for future expansion of DMA
mapping region.
fee00000 feffffff Mapping of PCI I/O space. This is a static
mapping within the vmalloc space.

18
Documentation/arm/sti/stih407-overview.txt Normal file
View File

@ -0,0 +1,18 @@
STiH407 Overview
================
Introduction
------------
The STiH407 is the new generation of SoC for Multi-HD, AVC set-top boxes
and server/connected client application for satellite, cable, terrestrial
and IP-STB markets.
Features
- ARM Cortex-A9 1.5 GHz dual core CPU (28nm)
- SATA2, USB 3.0, PCIe, Gbit Ethernet
Document Author
---------------
Maxime Coquelin <maxime.coquelin@st.com>, (c) 2014 ST Microelectronics

64
Documentation/arm/uefi.txt Normal file
View File

@ -0,0 +1,64 @@
UEFI, the Unified Extensible Firmware Interface, is a specification
governing the behaviours of compatible firmware interfaces. It is
maintained by the UEFI Forum - http://www.uefi.org/.
UEFI is an evolution of its predecessor 'EFI', so the terms EFI and
UEFI are used somewhat interchangeably in this document and associated
source code. As a rule, anything new uses 'UEFI', whereas 'EFI' refers
to legacy code or specifications.
UEFI support in Linux
=====================
Booting on a platform with firmware compliant with the UEFI specification
makes it possible for the kernel to support additional features:
- UEFI Runtime Services
- Retrieving various configuration information through the standardised
interface of UEFI configuration tables. (ACPI, SMBIOS, ...)
For actually enabling [U]EFI support, enable:
- CONFIG_EFI=y
- CONFIG_EFI_VARS=y or m
The implementation depends on receiving information about the UEFI environment
in a Flattened Device Tree (FDT) - so is only available with CONFIG_OF.
UEFI stub
=========
The "stub" is a feature that extends the Image/zImage into a valid UEFI
PE/COFF executable, including a loader application that makes it possible to
load the kernel directly from the UEFI shell, boot menu, or one of the
lightweight bootloaders like Gummiboot or rEFInd.
The kernel image built with stub support remains a valid kernel image for
booting in non-UEFI environments.
UEFI kernel support on ARM
==========================
UEFI kernel support on the ARM architectures (arm and arm64) is only available
when boot is performed through the stub.
When booting in UEFI mode, the stub deletes any memory nodes from a provided DT.
Instead, the kernel reads the UEFI memory map.
The stub populates the FDT /chosen node with (and the kernel scans for) the
following parameters:
________________________________________________________________________________
Name | Size | Description
================================================================================
linux,uefi-system-table | 64-bit | Physical address of the UEFI System Table.
--------------------------------------------------------------------------------
linux,uefi-mmap-start | 64-bit | Physical address of the UEFI memory map,
| | populated by the UEFI GetMemoryMap() call.
--------------------------------------------------------------------------------
linux,uefi-mmap-size | 32-bit | Size in bytes of the UEFI memory map
| | pointed to in previous entry.
--------------------------------------------------------------------------------
linux,uefi-mmap-desc-size | 32-bit | Size in bytes of each entry in the UEFI
| | memory map.
--------------------------------------------------------------------------------
linux,uefi-mmap-desc-ver | 32-bit | Version of the mmap descriptor format.
--------------------------------------------------------------------------------
linux,uefi-stub-kern-ver | string | Copy of linux_banner from build.
--------------------------------------------------------------------------------
For verbose debug messages, specify 'uefi_debug' on the kernel command line.

4
Documentation/arm64/booting.txt
View File

@ -85,6 +85,10 @@ The decompressed kernel image contains a 64-byte header as follows:
Header notes:
- code0/code1 are responsible for branching to stext.
- when booting through EFI, code0/code1 are initially skipped.
res5 is an offset to the PE header and the PE header has the EFI
entry point (efi_stub_entry). When the stub has done its work, it
jumps to code0 to resume the normal boot process.
The image must be placed at the specified offset (currently 0x80000)
from the start of the system RAM and called there. The start of the

31
Documentation/atomic_ops.txt
View File

@ -285,15 +285,13 @@ If a caller requires memory barrier semantics around an atomic_t
operation which does not return a value, a set of interfaces are
defined which accomplish this:
void smp_mb__before_atomic_dec(void);
void smp_mb__after_atomic_dec(void);
void smp_mb__before_atomic_inc(void);
void smp_mb__after_atomic_inc(void);
void smp_mb__before_atomic(void);
void smp_mb__after_atomic(void);
For example, smp_mb__before_atomic_dec() can be used like so:
For example, smp_mb__before_atomic() can be used like so:
obj->dead = 1;
smp_mb__before_atomic_dec();
smp_mb__before_atomic();
atomic_dec(&obj->ref_count);
It makes sure that all memory operations preceding the atomic_dec()
@ -302,15 +300,10 @@ operation. In the above example, it guarantees that the assignment of
"1" to obj->dead will be globally visible to other cpus before the
atomic counter decrement.
Without the explicit smp_mb__before_atomic_dec() call, the
Without the explicit smp_mb__before_atomic() call, the
implementation could legally allow the atomic counter update visible
to other cpus before the "obj->dead = 1;" assignment.
The other three interfaces listed are used to provide explicit
ordering with respect to memory operations after an atomic_dec() call
(smp_mb__after_atomic_dec()) and around atomic_inc() calls
(smp_mb__{before,after}_atomic_inc()).
A missing memory barrier in the cases where they are required by the
atomic_t implementation above can have disastrous results. Here is
an example, which follows a pattern occurring frequently in the Linux
@ -487,12 +480,12 @@ Finally there is the basic operation:
Which returns a boolean indicating if bit "nr" is set in the bitmask
pointed to by "addr".
If explicit memory barriers are required around clear_bit() (which
does not return a value, and thus does not need to provide memory
barrier semantics), two interfaces are provided:
If explicit memory barriers are required around {set,clear}_bit() (which do
not return a value, and thus does not need to provide memory barrier
semantics), two interfaces are provided:
void smp_mb__before_clear_bit(void);
void smp_mb__after_clear_bit(void);
void smp_mb__before_atomic(void);
void smp_mb__after_atomic(void);
They are used as follows, and are akin to their atomic_t operation
brothers:
@ -500,13 +493,13 @@ brothers:
/* All memory operations before this call will
* be globally visible before the clear_bit().
*/
smp_mb__before_clear_bit();
smp_mb__before_atomic();
clear_bit( ... );
/* The clear_bit() will be visible before all
* subsequent memory operations.
*/
smp_mb__after_clear_bit();
smp_mb__after_atomic();
There are two special bitops with lock barrier semantics (acquire/release,
same as spinlocks). These operate in the same way as their non-_lock/unlock

21
Documentation/cgroups/memory.txt
View File

@ -270,6 +270,11 @@ When oom event notifier is registered, event will be delivered.
2.7 Kernel Memory Extension (CONFIG_MEMCG_KMEM)
WARNING: Current implementation lacks reclaim support. That means allocation
attempts will fail when close to the limit even if there are plenty of
kmem available for reclaim. That makes this option unusable in real
life so DO NOT SELECT IT unless for development purposes.
With the Kernel memory extension, the Memory Controller is able to limit
the amount of kernel memory used by the system. Kernel memory is fundamentally
different than user memory, since it can't be swapped out, which makes it
@ -535,16 +540,13 @@ Note:
5.3 swappiness
Similar to /proc/sys/vm/swappiness, but affecting a hierarchy of groups only.
Please note that unlike the global swappiness, memcg knob set to 0
really prevents from any swapping even if there is a swap storage
available. This might lead to memcg OOM killer if there are no file
pages to reclaim.
Overrides /proc/sys/vm/swappiness for the particular group. The tunable
in the root cgroup corresponds to the global swappiness setting.
Following cgroups' swappiness can't be changed.
- root cgroup (uses /proc/sys/vm/swappiness).
- a cgroup which uses hierarchy and it has other cgroup(s) below it.
- a cgroup which uses hierarchy and not the root of hierarchy.
Please note that unlike during the global reclaim, limit reclaim
enforces that 0 swappiness really prevents from any swapping even if
there is a swap storage available. This might lead to memcg OOM killer
if there are no file pages to reclaim.
5.4 failcnt
@ -754,7 +756,6 @@ You can disable the OOM-killer by writing "1" to memory.oom_control file, as:
#echo 1 > memory.oom_control
This operation is only allowed to the top cgroup of a sub-hierarchy.
If OOM-killer is disabled, tasks under cgroup will hang/sleep
in memory cgroup's OOM-waitqueue when they request accountable memory.

16
Documentation/clk.txt
View File

@ -68,21 +68,27 @@ the operations defined in clk.h:
int (*is_enabled)(struct clk_hw *hw);
unsigned long (*recalc_rate)(struct clk_hw *hw,
unsigned long parent_rate);
long (*round_rate)(struct clk_hw *hw, unsigned long,
unsigned long *);
long (*round_rate)(struct clk_hw *hw,
unsigned long rate,
unsigned long *parent_rate);
long (*determine_rate)(struct clk_hw *hw,
unsigned long rate,
unsigned long *best_parent_rate,
struct clk **best_parent_clk);
int (*set_parent)(struct clk_hw *hw, u8 index);
u8 (*get_parent)(struct clk_hw *hw);
int (*set_rate)(struct clk_hw *hw, unsigned long);
int (*set_rate)(struct clk_hw *hw,
unsigned long rate,
unsigned long parent_rate);
int (*set_rate_and_parent)(struct clk_hw *hw,
unsigned long rate,
unsigned long parent_rate, u8 index);
unsigned long parent_rate,
u8 index);
unsigned long (*recalc_accuracy)(struct clk_hw *hw,
unsigned long parent_accuracy);
unsigned long parent_accuracy);
void (*init)(struct clk_hw *hw);
int (*debug_init)(struct clk_hw *hw,
struct dentry *dentry);
};
Part 3 - hardware clk implementations

15
Documentation/connector/connector.txt
View File

@ -24,7 +24,8 @@ netlink based networking for inter-process communication in a significantly
easier way:
int cn_add_callback(struct cb_id *id, char *name, void (*callback) (struct cn_msg *, struct netlink_skb_parms *));
void cn_netlink_send(struct cn_msg *msg, u32 __group, int gfp_mask);
void cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __group, int gfp_mask);
void cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __group, int gfp_mask);
struct cb_id
{
@ -71,15 +72,21 @@ void cn_del_callback(struct cb_id *id);
struct cb_id *id - unique connector's user identifier.
int cn_netlink_send(struct cn_msg *msg, u32 __groups, int gfp_mask);
int cn_netlink_send_multi(struct cn_msg *msg, u16 len, u32 portid, u32 __groups, int gfp_mask);
int cn_netlink_send(struct cn_msg *msg, u32 portid, u32 __groups, int gfp_mask);
Sends message to the specified groups. It can be safely called from
softirq context, but may silently fail under strong memory pressure.
If there are no listeners for given group -ESRCH can be returned.
struct cn_msg * - message header(with attached data).
u16 len - for *_multi multiple cn_msg messages can be sent
u32 port - destination port.
If non-zero the message will be sent to the
given port, which should be set to the
original sender.
u32 __group - destination group.
If __group is zero, then appropriate group will
If port and __group is zero, then appropriate group will
be searched through all registered connector users,
and message will be delivered to the group which was
created for user with the same ID as in msg.
@ -111,7 +118,7 @@ acknowledge number MUST be the same + 1.
If we receive a message and its sequence number is not equal to one we
are expecting, then it is a new message. If we receive a message and
its sequence number is the same as one we are expecting, but its
acknowledge is not equal to the acknowledge number in the original
acknowledge is not equal to the sequence number in the original
message + 1, then it is a new message.
Obviously, the protocol header contains the above id.

29
Documentation/cpu-freq/core.txt
View File

@ -20,6 +20,7 @@ Contents:
---------
1. CPUFreq core and interfaces
2. CPUFreq notifiers
3. CPUFreq Table Generation with Operating Performance Point (OPP)
1. General Information
=======================
@ -92,3 +93,31 @@ values:
cpu - number of the affected CPU
old - old frequency
new - new frequency
3. CPUFreq Table Generation with Operating Performance Point (OPP)
==================================================================
For details about OPP, see Documentation/power/opp.txt
dev_pm_opp_init_cpufreq_table - cpufreq framework typically is initialized with
cpufreq_frequency_table_cpuinfo which is provided with the list of
frequencies that are available for operation. This function provides
a ready to use conversion routine to translate the OPP layer's internal
information about the available frequencies into a format readily
providable to cpufreq.
WARNING: Do not use this function in interrupt context.
Example:
soc_pm_init()
{
/* Do things */
r = dev_pm_opp_init_cpufreq_table(dev, &freq_table);
if (!r)
cpufreq_frequency_table_cpuinfo(policy, freq_table);
/* Do other things */
}
NOTE: This function is available only if CONFIG_CPU_FREQ is enabled in
addition to CONFIG_PM_OPP.
dev_pm_opp_free_cpufreq_table - Free up the table allocated by dev_pm_opp_init_cpufreq_table

19
Documentation/cpu-freq/cpu-drivers.txt
View File

@ -228,3 +228,22 @@ is the corresponding frequency table helper for the ->target
stage. Just pass the values to this function, and the unsigned int
index returns the number of the frequency table entry which contains
the frequency the CPU shall be set to.
The following macros can be used as iterators over cpufreq_frequency_table:
cpufreq_for_each_entry(pos, table) - iterates over all entries of frequency
table.
cpufreq-for_each_valid_entry(pos, table) - iterates over all entries,
excluding CPUFREQ_ENTRY_INVALID frequencies.
Use arguments "pos" - a cpufreq_frequency_table * as a loop cursor and
"table" - the cpufreq_frequency_table * you want to iterate over.
For example:
struct cpufreq_frequency_table *pos, *driver_freq_table;
cpufreq_for_each_entry(pos, driver_freq_table) {
/* Do something with pos */
pos->frequency = ...
}

4
Documentation/cpu-freq/index.txt
View File

@ -35,8 +35,8 @@ Mailing List
------------
There is a CPU frequency changing CVS commit and general list where
you can report bugs, problems or submit patches. To post a message,
send an email to cpufreq@vger.kernel.org, to subscribe go to
http://vger.kernel.org/vger-lists.html#cpufreq and follow the
send an email to linux-pm@vger.kernel.org, to subscribe go to
http://vger.kernel.org/vger-lists.html#linux-pm and follow the
instructions there.
Links

19
Documentation/devicetree/bindings/arm/armada-370-xp-pmsu.txt
View File

@ -1,20 +1,21 @@
Power Management Service Unit(PMSU)
-----------------------------------
Available on Marvell SOCs: Armada 370 and Armada XP
Available on Marvell SOCs: Armada 370, Armada 38x and Armada XP
Required properties:
- compatible: "marvell,armada-370-xp-pmsu"
- compatible: should be one of:
- "marvell,armada-370-pmsu" for Armada 370 or Armada XP
- "marvell,armada-380-pmsu" for Armada 38x
- "marvell,armada-370-xp-pmsu" was used for Armada 370/XP but is now
deprecated and will be removed
- reg: Should contain PMSU registers location and length. First pair
for the per-CPU SW Reset Control registers, second pair for the
Power Management Service Unit.
- reg: Should contain PMSU registers location and length.
Example:
armada-370-xp-pmsu@d0022000 {
compatible = "marvell,armada-370-xp-pmsu";
reg = <0xd0022100 0x430>,
<0xd0020800 0x20>;
armada-370-xp-pmsu@22000 {
compatible = "marvell,armada-370-pmsu";
reg = <0x22000 0x1000>;
};

14
Documentation/devicetree/bindings/arm/armada-cpu-reset.txt Normal file
View File

@ -0,0 +1,14 @@
Marvell Armada CPU reset controller
===================================
Required properties:
- compatible: Should be "marvell,armada-370-cpu-reset".
- reg: should be register base and length as documented in the
datasheet for the CPU reset registers
cpurst: cpurst@20800 {
compatible = "marvell,armada-370-cpu-reset";
reg = <0x20800 0x20>;
};

12
Documentation/devicetree/bindings/arm/axxia.txt Normal file
View File

@ -0,0 +1,12 @@
Axxia AXM55xx device tree bindings
Boards using the AXM55xx SoC need to have the following properties:
Required root node property:
- compatible = "lsi,axm5516"
Boards:
LSI AXM5516 Validation board (Amarillo)
compatible = "lsi,axm5516-amarillo", "lsi,axm5516"

32
Documentation/devicetree/bindings/arm/coherency-fabric.txt
View File

@ -1,16 +1,33 @@
Coherency fabric
----------------
Available on Marvell SOCs: Armada 370 and Armada XP
Available on Marvell SOCs: Armada 370, Armada 375, Armada 38x and Armada XP
Required properties:
- compatible: "marvell,coherency-fabric"
- compatible: the possible values are:
* "marvell,coherency-fabric", to be used for the coherency fabric of
the Armada 370 and Armada XP.
* "marvell,armada-375-coherency-fabric", for the Armada 375 coherency
fabric.
* "marvell,armada-380-coherency-fabric", for the Armada 38x coherency
fabric.
- reg: Should contain coherency fabric registers location and
length. First pair for the coherency fabric registers, second pair
for the per-CPU fabric registers registers.
length.
Example:
* For "marvell,coherency-fabric", the first pair for the coherency
fabric registers, second pair for the per-CPU fabric registers.
* For "marvell,armada-375-coherency-fabric", only one pair is needed
for the per-CPU fabric registers.
* For "marvell,armada-380-coherency-fabric", only one pair is needed
for the per-CPU fabric registers.
Examples:
coherency-fabric@d0020200 {
compatible = "marvell,coherency-fabric";
@ -19,3 +36,8 @@ coherency-fabric@d0020200 {
};
coherency-fabric@21810 {
compatible = "marvell,armada-375-coherency-fabric";
reg = <0x21810 0x1c>;
};

8
Documentation/devicetree/bindings/arm/cpus.txt
View File

@ -178,13 +178,19 @@ nodes to be present and contain the properties described below.
Usage and definition depend on ARM architecture version.
# On ARM v8 64-bit this property is required and must
be one of:
"spin-table"
"psci"
"spin-table"
# On ARM 32-bit systems this property is optional and
can be one of:
"allwinner,sun6i-a31"
"arm,psci"
"marvell,armada-375-smp"
"marvell,armada-380-smp"
"marvell,armada-xp-smp"
"qcom,gcc-msm8660"
"qcom,kpss-acc-v1"
"qcom,kpss-acc-v2"
"rockchip,rk3066-smp"
- cpu-release-addr
Usage: required for systems that have an "enable-method"

38
Documentation/devicetree/bindings/arm/exynos/smp-sysram.txt Normal file
View File

@ -0,0 +1,38 @@
Samsung Exynos SYSRAM for SMP bringup:
------------------------------------
Samsung SMP-capable Exynos SoCs use part of the SYSRAM for the bringup
of the secondary cores. Once the core gets powered up it executes the
code that is residing at some specific location of the SYSRAM.
Therefore reserved section sub-nodes have to be added to the mmio-sram
declaration. These nodes are of two types depending upon secure or
non-secure execution environment.
Required sub-node properties:
- compatible : depending upon boot mode, should be
"samsung,exynos4210-sysram" : for Secure SYSRAM
"samsung,exynos4210-sysram-ns" : for Non-secure SYSRAM
The rest of the properties should follow the generic mmio-sram discription
found in ../../misc/sysram.txt
Example:
sysram@02020000 {
compatible = "mmio-sram";
reg = <0x02020000 0x54000>;
#address-cells = <1>;
#size-cells = <1>;
ranges = <0 0x02020000 0x54000>;
smp-sysram@0 {
compatible = "samsung,exynos4210-sysram";
reg = <0x0 0x1000>;
};
smp-sysram@53000 {
compatible = "samsung,exynos4210-sysram-ns";
reg = <0x53000 0x1000>;
};
};

7
Documentation/devicetree/bindings/arm/global_timer.txt
View File

@ -4,8 +4,11 @@
** Timer node required properties:
- compatible : Should be "arm,cortex-a9-global-timer"
Driver supports versions r2p0 and above.
- compatible : should contain
* "arm,cortex-a5-global-timer" for Cortex-A5 global timers.
* "arm,cortex-a9-global-timer" for Cortex-A9 global
timers or any compatible implementation. Note: driver
supports versions r2p0 and above.
- interrupts : One interrupt to each core

102
Documentation/devicetree/bindings/arm/marvell,berlin.txt
View File

@ -12,6 +12,7 @@ SoC and board used. Currently known SoC compatibles are:
"marvell,berlin2" for Marvell Armada 1500 (BG2, 88DE3100),
"marvell,berlin2cd" for Marvell Armada 1500-mini (BG2CD, 88DE3005)
"marvell,berlin2ct" for Marvell Armada ? (BG2CT, 88DE????)
"marvell,berlin2q" for Marvell Armada 1500-pro (BG2Q, 88DE3114)
"marvell,berlin3" for Marvell Armada ? (BG3, 88DE????)
* Example:
@ -22,3 +23,104 @@ SoC and board used. Currently known SoC compatibles are:
...
}
* Marvell Berlin2 chip control binding
Marvell Berlin SoCs have a chip control register set providing several
individual registers dealing with pinmux, padmux, clock, reset, and secondary
CPU boot address. Unfortunately, the individual registers are spread among the
chip control registers, so there should be a single DT node only providing the
different functions which are described below.
Required properties:
- compatible: shall be one of
"marvell,berlin2-chip-ctrl" for BG2
"marvell,berlin2cd-chip-ctrl" for BG2CD
"marvell,berlin2q-chip-ctrl" for BG2Q
- reg: address and length of following register sets for
BG2/BG2CD: chip control register set
BG2Q: chip control register set and cpu pll registers
* Marvell Berlin2 system control binding
Marvell Berlin SoCs have a system control register set providing several
individual registers dealing with pinmux, padmux, and reset.
Required properties:
- compatible: should be one of
"marvell,berlin2-system-ctrl" for BG2
"marvell,berlin2cd-system-ctrl" for BG2CD
"marvell,berlin2q-system-ctrl" for BG2Q
- reg: address and length of the system control register set
* Clock provider binding
As clock related registers are spread among the chip control registers, the
chip control node also provides the clocks. Marvell Berlin2 (BG2, BG2CD, BG2Q)
SoCs share the same IP for PLLs and clocks, with some minor differences in
features and register layout.
Required properties:
- #clock-cells: shall be set to 1
- clocks: clock specifiers referencing the core clock input clocks
- clock-names: array of strings describing the input clock specifiers above.
Allowed clock-names for the reference clocks are
"refclk" for the SoCs osciallator input on all SoCs,
and SoC-specific input clocks for
BG2/BG2CD: "video_ext0" for the external video clock input
Clocks provided by core clocks shall be referenced by a clock specifier
indexing one of the provided clocks. Refer to dt-bindings/clock/berlin<soc>.h
for the corresponding index mapping.
* Pin controller binding
Pin control registers are part of both register sets, chip control and system
control. The pins controlled are organized in groups, so no actual pin
information is needed.
A pin-controller node should contain subnodes representing the pin group
configurations, one per function. Each subnode has the group name and the muxing
function used.
Be aware the Marvell Berlin datasheets use the keyword 'mode' for what is called
a 'function' in the pin-controller subsystem.
Required subnode-properties:
- groups: a list of strings describing the group names.
- function: a string describing the function used to mux the groups.
Example:
chip: chip-control@ea0000 {
compatible = "marvell,berlin2-chip-ctrl";
#clock-cells = <1>;
reg = <0xea0000 0x400>;
clocks = <&refclk>, <&externaldev 0>;
clock-names = "refclk", "video_ext0";
spi1_pmux: spi1-pmux {
groups = "G0";
function = "spi1";
};
};
sysctrl: system-controller@d000 {
compatible = "marvell,berlin2-system-ctrl";
reg = <0xd000 0x100>;
uart0_pmux: uart0-pmux {
groups = "GSM4";
function = "uart0";
};
uart1_pmux: uart1-pmux {
groups = "GSM5";
function = "uart1";
};
uart2_pmux: uart2-pmux {
groups = "GSM3";
function = "uart2";
};
};

2
Documentation/devicetree/bindings/arm/omap/l3-noc.txt
View File

@ -6,6 +6,8 @@ provided by Arteris.
Required properties:
- compatible : Should be "ti,omap3-l3-smx" for OMAP3 family
Should be "ti,omap4-l3-noc" for OMAP4 family
Should be "ti,dra7-l3-noc" for DRA7 family
Should be "ti,am4372-l3-noc" for AM43 family
- reg: Contains L3 register address range for each noc domain.
- ti,hwmods: "l3_main_1", ... One hwmod for each noc domain.

18
Documentation/devicetree/bindings/arm/omap/omap.txt
View File

@ -80,7 +80,10 @@ SoCs:
compatible = "ti,omap5432", "ti,omap5"
- DRA742
compatible = "ti,dra7xx", "ti,dra7"
compatible = "ti,dra742", "ti,dra74", "ti,dra7"
- DRA722
compatible = "ti,dra722", "ti,dra72", "ti,dra7"
- AM4372
compatible = "ti,am4372", "ti,am43"
@ -102,6 +105,12 @@ Boards:
- OMAP4 DuoVero with Parlor : Commercial expansion board with daughter board
compatible = "gumstix,omap4-duovero-parlor", "gumstix,omap4-duovero", "ti,omap4430", "ti,omap4";
- OMAP4 VAR-STK-OM44 : Commercial dev kit with VAR-OM44CustomBoard and VAR-SOM-OM44 w/WLAN
compatible = "variscite,var-stk-om44", "variscite,var-som-om44", "ti,omap4460", "ti,omap4";
- OMAP4 VAR-DVK-OM44 : Commercial dev kit with VAR-OM44CustomBoard, VAR-SOM-OM44 w/WLAN and LCD touchscreen
compatible = "variscite,var-dvk-om44", "variscite,var-som-om44", "ti,omap4460", "ti,omap4";
- OMAP3 EVM : Software Development Board for OMAP35x, AM/DM37x
compatible = "ti,omap3-evm", "ti,omap3"
@ -120,5 +129,8 @@ Boards:
- AM437x GP EVM
compatible = "ti,am437x-gp-evm", "ti,am4372", "ti,am43"
- DRA7 EVM: Software Developement Board for DRA7XX
compatible = "ti,dra7-evm", "ti,dra7"
- DRA742 EVM: Software Development Board for DRA742
compatible = "ti,dra7-evm", "ti,dra742", "ti,dra74", "ti,dra7"
- DRA722 EVM: Software Development Board for DRA722
compatible = "ti,dra72-evm", "ti,dra722", "ti,dra72", "ti,dra7"

1
Documentation/devicetree/bindings/arm/pmu.txt
View File

@ -8,6 +8,7 @@ Required properties:
- compatible : should be one of
"arm,armv8-pmuv3"
"arm,cortex-a17-pmu"
"arm,cortex-a15-pmu"
"arm,cortex-a12-pmu"
"arm,cortex-a9-pmu"

37
Documentation/devicetree/bindings/arm/psci.txt
View File

@ -21,7 +21,15 @@ to #0.
Main node required properties:
- compatible : Must be "arm,psci"
- compatible : should contain at least one of:
* "arm,psci" : for implementations complying to PSCI versions prior to
0.2. For these cases function IDs must be provided.
* "arm,psci-0.2" : for implementations complying to PSCI 0.2. Function
IDs are not required and should be ignored by an OS with PSCI 0.2
support, but are permitted to be present for compatibility with
existing software when "arm,psci" is later in the compatible list.
- method : The method of calling the PSCI firmware. Permitted
values are:
@ -45,6 +53,8 @@ Main node optional properties:
Example:
Case 1: PSCI v0.1 only.
psci {
compatible = "arm,psci";
method = "smc";
@ -53,3 +63,28 @@ Example:
cpu_on = <0x95c10002>;
migrate = <0x95c10003>;
};
Case 2: PSCI v0.2 only
psci {
compatible = "arm,psci-0.2";
method = "smc";
};
Case 3: PSCI v0.2 and PSCI v0.1.
A DTB may provide IDs for use by kernels without PSCI 0.2 support,
enabling firmware and hypervisors to support existing and new kernels.
These IDs will be ignored by kernels with PSCI 0.2 support, which will
use the standard PSCI 0.2 IDs exclusively.
psci {
compatible = "arm,psci-0.2", "arm,psci";
method = "hvc";
cpu_on = < arbitrary value >;
cpu_off = < arbitrary value >;
...
};

10
Documentation/devicetree/bindings/arm/rockchip.txt Normal file
View File

@ -0,0 +1,10 @@
Rockchip platforms device tree bindings
---------------------------------------
- bq Curie 2 tablet:
Required root node properties:
- compatible = "mundoreader,bq-curie2", "rockchip,rk3066a";
- Radxa Rock board:
Required root node properties:
- compatible = "radxa,rock", "rockchip,rk3188";

4
Documentation/devicetree/bindings/arm/samsung/pmu.txt
View File

@ -2,6 +2,10 @@ SAMSUNG Exynos SoC series PMU Registers
Properties:
- compatible : should contain two values. First value must be one from following list:
- "samsung,exynos3250-pmu" - for Exynos3250 SoC,
- "samsung,exynos4210-pmu" - for Exynos4210 SoC,
- "samsung,exynos4212-pmu" - for Exynos4212 SoC,
- "samsung,exynos4412-pmu" - for Exynos4412 SoC,
- "samsung,exynos5250-pmu" - for Exynos5250 SoC,
- "samsung,exynos5420-pmu" - for Exynos5420 SoC.
second value must be always "syscon".

11
Documentation/devicetree/bindings/arm/samsung/sysreg.txt
View File

@ -1,8 +1,10 @@
SAMSUNG S5P/Exynos SoC series System Registers (SYSREG)
Properties:
- compatible : should contain "samsung,<chip name>-sysreg", "syscon";
For Exynos4 SoC series it should be "samsung,exynos4-sysreg", "syscon";
- compatible : should contain two values. First value must be one from following list:
- "samsung,exynos4-sysreg" - for Exynos4 based SoCs,
- "samsung,exynos5-sysreg" - for Exynos5 based SoCs.
second value must be always "syscon".
- reg : offset and length of the register set.
Example:
@ -10,3 +12,8 @@ Example:
compatible = "samsung,exynos4-sysreg", "syscon";
reg = <0x10010000 0x400>;
};
syscon@10050000 {
compatible = "samsung,exynos5-sysreg", "syscon";
reg = <0x10050000 0x5000>;
};

15
Documentation/devicetree/bindings/arm/sti.txt Normal file
View File

@ -0,0 +1,15 @@
ST STi Platforms Device Tree Bindings
---------------------------------------
Boards with the ST STiH415 SoC shall have the following properties:
Required root node property:
compatible = "st,stih415";
Boards with the ST STiH416 SoC shall have the following properties:
Required root node property:
compatible = "st,stih416";
Boards with the ST STiH407 SoC shall have the following properties:
Required root node property:
compatible = "st,stih407";

79
Documentation/devicetree/bindings/arm/vexpress-sysreg.txt
View File

@ -8,6 +8,8 @@ interrupt generation, MMC and NOR Flash control etc.
Required node properties:
- compatible value : = "arm,vexpress,sysreg";
- reg : physical base address and the size of the registers window
Deprecated properties, replaced by GPIO subnodes (see below):
- gpio-controller : specifies that the node is a GPIO controller
- #gpio-cells : size of the GPIO specifier, should be 2:
- first cell is the pseudo-GPIO line number:
@ -16,35 +18,86 @@ Required node properties:
2 - NOR FLASH WPn
- second cell can take standard GPIO flags (currently ignored).
Control registers providing pseudo-GPIO lines must be represented
by subnodes, each of them requiring the following properties:
- compatible value : one of
"arm,vexpress-sysreg,sys_led"
"arm,vexpress-sysreg,sys_mci"
"arm,vexpress-sysreg,sys_flash"
- gpio-controller : makes the node a GPIO controller
- #gpio-cells : size of the GPIO specifier, must be 2:
- first cell is the function number:
- for sys_led : 0..7 = LED 0..7
- for sys_mci : 0 = MMC CARDIN, 1 = MMC WPROT
- for sys_flash : 0 = NOR FLASH WPn
- second cell can take standard GPIO flags (currently ignored).
Example:
v2m_sysreg: sysreg@10000000 {
compatible = "arm,vexpress-sysreg";
reg = <0x10000000 0x1000>;
gpio-controller;
#gpio-cells = <2>;
v2m_led_gpios: sys_led@08 {
compatible = "arm,vexpress-sysreg,sys_led";
gpio-controller;
#gpio-cells = <2>;
};
v2m_mmc_gpios: sys_mci@48 {
compatible = "arm,vexpress-sysreg,sys_mci";
gpio-controller;
#gpio-cells = <2>;
};
v2m_flash_gpios: sys_flash@4c {
compatible = "arm,vexpress-sysreg,sys_flash";
gpio-controller;
#gpio-cells = <2>;
};
};
This block also can also act a bridge to the platform's configuration
bus via "system control" interface, addressing devices with site number,
position in the board stack, config controller, function and device
numbers - see motherboard's TRM for more details.
The node describing a config device must refer to the sysreg node via
"arm,vexpress,config-bridge" phandle (can be also defined in the node's
parent) and relies on the board topology properties - see main vexpress
node documentation for more details. It must also define the following
property:
- arm,vexpress-sysreg,func : must contain two cells:
- first cell defines function number (eg. 1 for clock generator,
2 for voltage regulators etc.)
- device number (eg. osc 0, osc 1 etc.)
numbers - see motherboard's TRM for more details. All configuration
controller accessible via this interface must reference the sysreg
node via "arm,vexpress,config-bridge" phandle and define appropriate
topology properties - see main vexpress node documentation for more
details. Each child of such node describes one function and must
define the following properties:
- compatible value : must be one of (corresponding to the TRM):
"arm,vexpress-amp"
"arm,vexpress-dvimode"
"arm,vexpress-energy"
"arm,vexpress-muxfpga"
"arm,vexpress-osc"
"arm,vexpress-power"
"arm,vexpress-reboot"
"arm,vexpress-reset"
"arm,vexpress-scc"
"arm,vexpress-shutdown"
"arm,vexpress-temp"
"arm,vexpress-volt"
- arm,vexpress-sysreg,func : must contain a set of two cells long groups:
- first cell of each group defines the function number
(eg. 1 for clock generator, 2 for voltage regulators etc.)
- second cell of each group defines device number (eg. osc 0,
osc 1 etc.)
- some functions (eg. energy meter, with its 64 bit long counter)
are using more than one function/device number pair
Example:
mcc {
compatible = "arm,vexpress,config-bus";
arm,vexpress,config-bridge = <&v2m_sysreg>;
osc@0 {
compatible = "arm,vexpress-osc";
arm,vexpress-sysreg,func = <1 0>;
};
energy@0 {
compatible = "arm,vexpress-energy";
arm,vexpress-sysreg,func = <13 0>, <13 1>;
};
};

15
Documentation/devicetree/bindings/arm/vexpress.txt
View File

@ -80,12 +80,17 @@ but also control clock generators, voltage regulators, gather
environmental data like temperature, power consumption etc. Even
the video output switch (FPGA) is controlled that way.
Nodes describing devices controlled by this infrastructure should
point at the bridge device node:
The controllers are not mapped into normal memory address space
and must be accessed through bridges - other devices capable
of generating transactions on the configuration bus.
The nodes describing configuration controllers must define
the following properties:
- compatible value:
compatible = "arm,vexpress,config-bus";
- bridge phandle:
arm,vexpress,config-bridge = <phandle>;
This property can be also defined in a parent node (eg. for a DCC)
and is effective for all children.
and children describing available functions.
Platform topology
@ -197,7 +202,7 @@ Example of a VE tile description (simplified)
};
dcc {
compatible = "simple-bus";
compatible = "arm,vexpress,config-bus";
arm,vexpress,config-bridge = <&v2m_sysreg>;
osc@0 {

30
Documentation/devicetree/bindings/bus/brcm,gisb-arb.txt Normal file
View File

@ -0,0 +1,30 @@
Broadcom GISB bus Arbiter controller
Required properties:
- compatible: should be "brcm,gisb-arb"
- reg: specifies the base physical address and size of the registers
- interrupt-parent: specifies the phandle to the parent interrupt controller
this arbiter gets interrupt line from
- interrupts: specifies the two interrupts (timeout and TEA) to be used from
the parent interrupt controller
Optional properties:
- brcm,gisb-arb-master-mask: 32-bits wide bitmask used to specify which GISB
masters are valid at the system level
- brcm,gisb-arb-master-names: string list of the litteral name of the GISB
masters. Should match the number of bits set in brcm,gisb-master-mask and
the order in which they appear
Example:
gisb-arb@f0400000 {
compatible = "brcm,gisb-arb";
reg = <0xf0400000 0x800>;
interrupts = <0>, <2>;
interrupt-parent = <&sun_l2_intc>;
brcm,gisb-arb-master-mask = <0x7>;
brcm,gisb-arb-master-names = "bsp_0", "scpu_0", "cpu_0";
};

2
Documentation/devicetree/bindings/bus/mvebu-mbus.txt
View File

@ -197,7 +197,7 @@ to be set by the operating system and that are guaranteed to be free of overlaps
with one another or with the system memory ranges.
Each entry in the property refers to exactly one window. If the operating system
choses to use a different set of mbus windows, it must ensure that any address
chooses to use a different set of mbus windows, it must ensure that any address
translations performed from downstream devices are adapted accordingly.
The operating system may insert additional mbus windows that do not conflict

4
Documentation/devicetree/bindings/clock/altr_socfpga.txt
View File

@ -21,8 +21,8 @@ Optional properties:
- fixed-divider : If clocks have a fixed divider value, use this property.
- clk-gate : For "socfpga-gate-clk", clk-gate contains the gating register
and the bit index.
- div-reg : For "socfpga-gate-clk", div-reg contains the divider register, bit shift,
and width.
- div-reg : For "socfpga-gate-clk" and "socfpga-periph-clock", div-reg contains
the divider register, bit shift, and width.
- clk-phase : For the sdmmc_clk, contains the value of the clock phase that controls
the SDMMC CIU clock. The first value is the clk_sample(smpsel), and the second
value is the cclk_in_drv(drvsel). The clk-phase is used to enable the correct

128
Documentation/devicetree/bindings/clock/at91-clock.txt
View File

@ -6,6 +6,16 @@ This binding uses the common clock binding[1].
Required properties:
- compatible : shall be one of the following:
"atmel,at91sam9x5-sckc":
at91 SCKC (Slow Clock Controller)
This node contains the slow clock definitions.
"atmel,at91sam9x5-clk-slow-osc":
at91 slow oscillator
"atmel,at91sam9x5-clk-slow-rc-osc":
at91 internal slow RC oscillator
"atmel,at91rm9200-pmc" or
"atmel,at91sam9g45-pmc" or
"atmel,at91sam9n12-pmc" or
@ -15,8 +25,18 @@ Required properties:
All at91 specific clocks (clocks defined below) must be child
node of the PMC node.
"atmel,at91sam9x5-clk-slow" (under sckc node)
or
"atmel,at91sam9260-clk-slow" (under pmc node):
at91 slow clk
"atmel,at91rm9200-clk-main-osc"
"atmel,at91sam9x5-clk-main-rc-osc"
at91 main clk sources
"atmel,at91sam9x5-clk-main"
"atmel,at91rm9200-clk-main":
at91 main oscillator
at91 main clock
"atmel,at91rm9200-clk-master" or
"atmel,at91sam9x5-clk-master":
@ -54,6 +74,63 @@ Required properties:
"atmel,at91sam9x5-clk-utmi":
at91 utmi clock
Required properties for SCKC node:
- reg : defines the IO memory reserved for the SCKC.
- #size-cells : shall be 0 (reg is used to encode clk id).
- #address-cells : shall be 1 (reg is used to encode clk id).
For example:
sckc: sckc@fffffe50 {
compatible = "atmel,sama5d3-pmc";
reg = <0xfffffe50 0x4>
#size-cells = <0>;
#address-cells = <1>;
/* put at91 slow clocks here */
};
Required properties for internal slow RC oscillator:
- #clock-cells : from common clock binding; shall be set to 0.
- clock-frequency : define the internal RC oscillator frequency.
Optional properties:
- clock-accuracy : define the internal RC oscillator accuracy.
For example:
slow_rc_osc: slow_rc_osc {
compatible = "atmel,at91sam9x5-clk-slow-rc-osc";
clock-frequency = <32768>;
clock-accuracy = <50000000>;
};
Required properties for slow oscillator:
- #clock-cells : from common clock binding; shall be set to 0.
- clocks : shall encode the main osc source clk sources (see atmel datasheet).
Optional properties:
- atmel,osc-bypass : boolean property. Set this when a clock signal is directly
provided on XIN.
For example:
slow_osc: slow_osc {
compatible = "atmel,at91rm9200-clk-slow-osc";
#clock-cells = <0>;
clocks = <&slow_xtal>;
};
Required properties for slow clock:
- #clock-cells : from common clock binding; shall be set to 0.
- clocks : shall encode the slow clk sources (see atmel datasheet).
For example:
clk32k: slck {
compatible = "atmel,at91sam9x5-clk-slow";
#clock-cells = <0>;
clocks = <&slow_rc_osc &slow_osc>;
};
Required properties for PMC node:
- reg : defines the IO memory reserved for the PMC.
- #size-cells : shall be 0 (reg is used to encode clk id).
@ -85,24 +162,57 @@ For example:
/* put at91 clocks here */
};
Required properties for main clock internal RC oscillator:
- interrupt-parent : must reference the PMC node.
- interrupts : shall be set to "<0>".
- clock-frequency : define the internal RC oscillator frequency.
Optional properties:
- clock-accuracy : define the internal RC oscillator accuracy.
For example:
main_rc_osc: main_rc_osc {
compatible = "atmel,at91sam9x5-clk-main-rc-osc";
interrupt-parent = <&pmc>;
interrupts = <0>;
clock-frequency = <12000000>;
clock-accuracy = <50000000>;
};
Required properties for main clock oscillator:
- interrupt-parent : must reference the PMC node.
- interrupts : shall be set to "<0>".
- #clock-cells : from common clock binding; shall be set to 0.
- clocks : shall encode the main osc source clk sources (see atmel datasheet).
Optional properties:
- atmel,osc-bypass : boolean property. Specified if a clock signal is provided
on XIN.
clock signal is directly provided on XIN pin.
For example:
main_osc: main_osc {
compatible = "atmel,at91rm9200-clk-main-osc";
interrupt-parent = <&pmc>;
interrupts = <0>;
#clock-cells = <0>;
clocks = <&main_xtal>;
};
Required properties for main clock:
- interrupt-parent : must reference the PMC node.
- interrupts : shall be set to "<0>".
- #clock-cells : from common clock binding; shall be set to 0.
- clocks (optional if clock-frequency is provided) : shall be the slow clock
phandle. This clock is used to calculate the main clock rate if
"clock-frequency" is not provided.
- clock-frequency : the main oscillator frequency.Prefer the use of
"clock-frequency" over automatic clock rate calculation.
- clocks : shall encode the main clk sources (see atmel datasheet).
For example:
main: mainck {
compatible = "atmel,at91rm9200-clk-main";
compatible = "atmel,at91sam9x5-clk-main";
interrupt-parent = <&pmc>;
interrupts = <0>;
#clock-cells = <0>;
clocks = <&ck32k>;
clock-frequency = <18432000>;
clocks = <&main_rc_osc &main_osc>;
};
Required properties for master clock:

116
Documentation/devicetree/bindings/clock/bcm-kona-clock.txt
View File

@ -10,12 +10,12 @@ This binding uses the common clock binding:
Required properties:
- compatible
Shall have one of the following values:
- "brcm,bcm11351-root-ccu"
- "brcm,bcm11351-aon-ccu"
- "brcm,bcm11351-hub-ccu"
- "brcm,bcm11351-master-ccu"
- "brcm,bcm11351-slave-ccu"
Shall have a value of the form "brcm,<model>-<which>-ccu",
where <model> is a Broadcom SoC model number and <which> is
the name of a defined CCU. For example:
"brcm,bcm11351-root-ccu"
The compatible strings used for each supported SoC family
are defined below.
- reg
Shall define the base and range of the address space
containing clock control registers
@ -26,12 +26,48 @@ Required properties:
Shall be an ordered list of strings defining the names of
the clocks provided by the CCU.
Device tree example:
BCM281XX family SoCs use Kona CCUs. The following table defines
the set of CCUs and clock specifiers for BCM281XX clocks. When
a clock consumer references a clocks, its symbolic specifier
(rather than its numeric index value) should be used. These
specifiers are defined in "include/dt-bindings/clock/bcm281xx.h".
slave_ccu: slave_ccu {
compatible = "brcm,bcm11351-slave-ccu";
reg = <0x3e011000 0x0f00>;
#clock-cells = <1>;
clock-output-names = "uartb",
"uartb2",
"uartb3",
"uartb4";
};
ref_crystal_clk: ref_crystal {
#clock-cells = <0>;
compatible = "fixed-clock";
clock-frequency = <26000000>;
};
uart@3e002000 {
compatible = "brcm,bcm11351-dw-apb-uart", "snps,dw-apb-uart";
status = "disabled";
reg = <0x3e002000 0x1000>;
clocks = <&slave_ccu BCM281XX_SLAVE_CCU_UARTB3>;
interrupts = <GIC_SPI 65 IRQ_TYPE_LEVEL_HIGH>;
reg-shift = <2>;
reg-io-width = <4>;
};
BCM281XX family
---------------
CCU compatible string values for SoCs in the BCM281XX family are:
"brcm,bcm11351-root-ccu"
"brcm,bcm11351-aon-ccu"
"brcm,bcm11351-hub-ccu"
"brcm,bcm11351-master-ccu"
"brcm,bcm11351-slave-ccu"
The following table defines the set of CCUs and clock specifiers for
BCM281XX family clocks. When a clock consumer references a clocks,
its symbolic specifier (rather than its numeric index value) should
be used. These specifiers are defined in:
"include/dt-bindings/clock/bcm281xx.h"
CCU Clock Type Index Specifier
--- ----- ---- ----- ---------
@ -64,30 +100,40 @@ specifiers are defined in "include/dt-bindings/clock/bcm281xx.h".
slave pwm peri 9 BCM281XX_SLAVE_CCU_PWM
Device tree example:
BCM21664 family
---------------
CCU compatible string values for SoCs in the BCM21664 family are:
"brcm,bcm21664-root-ccu"
"brcm,bcm21664-aon-ccu"
"brcm,bcm21664-master-ccu"
"brcm,bcm21664-slave-ccu"
slave_ccu: slave_ccu {
compatible = "brcm,bcm11351-slave-ccu";
reg = <0x3e011000 0x0f00>;
#clock-cells = <1>;
clock-output-names = "uartb",
"uartb2",
"uartb3",
"uartb4";
};
The following table defines the set of CCUs and clock specifiers for
BCM21664 family clocks. When a clock consumer references a clocks,
its symbolic specifier (rather than its numeric index value) should
be used. These specifiers are defined in:
"include/dt-bindings/clock/bcm21664.h"
ref_crystal_clk: ref_crystal {
#clock-cells = <0>;
compatible = "fixed-clock";
clock-frequency = <26000000>;
};
CCU Clock Type Index Specifier
--- ----- ---- ----- ---------
root frac_1m peri 0 BCM21664_ROOT_CCU_FRAC_1M
uart@3e002000 {
compatible = "brcm,bcm11351-dw-apb-uart", "snps,dw-apb-uart";
status = "disabled";
reg = <0x3e002000 0x1000>;
clocks = <&slave_ccu BCM281XX_SLAVE_CCU_UARTB3>;
interrupts = <GIC_SPI 65 IRQ_TYPE_LEVEL_HIGH>;
reg-shift = <2>;
reg-io-width = <4>;
};
aon hub_timer peri 0 BCM21664_AON_CCU_HUB_TIMER
master sdio1 peri 0 BCM21664_MASTER_CCU_SDIO1
master sdio2 peri 1 BCM21664_MASTER_CCU_SDIO2
master sdio3 peri 2 BCM21664_MASTER_CCU_SDIO3
master sdio4 peri 3 BCM21664_MASTER_CCU_SDIO4
master sdio1_sleep peri 4 BCM21664_MASTER_CCU_SDIO1_SLEEP
master sdio2_sleep peri 5 BCM21664_MASTER_CCU_SDIO2_SLEEP
master sdio3_sleep peri 6 BCM21664_MASTER_CCU_SDIO3_SLEEP
master sdio4_sleep peri 7 BCM21664_MASTER_CCU_SDIO4_SLEEP
slave uartb peri 0 BCM21664_SLAVE_CCU_UARTB
slave uartb2 peri 1 BCM21664_SLAVE_CCU_UARTB2
slave uartb3 peri 2 BCM21664_SLAVE_CCU_UARTB3
slave uartb4 peri 3 BCM21664_SLAVE_CCU_UARTB4
slave bsc1 peri 4 BCM21664_SLAVE_CCU_BSC1
slave bsc2 peri 5 BCM21664_SLAVE_CCU_BSC2
slave bsc3 peri 6 BCM21664_SLAVE_CCU_BSC3
slave bsc4 peri 7 BCM21664_SLAVE_CCU_BSC4

9
Documentation/devicetree/bindings/clock/clock-bindings.txt
View File

@ -44,10 +44,9 @@ For example:
clocks by index. The names should reflect the clock output signal
names for the device.
clock-indices: If the identifyng number for the clocks in the node
is not linear from zero, then the this mapping allows
the mapping of identifiers into the clock-output-names
array.
clock-indices: If the identifying number for the clocks in the node
is not linear from zero, then this allows the mapping of
identifiers into the clock-output-names array.
For example, if we have two clocks <&oscillator 1> and <&oscillator 3>:
@ -58,7 +57,7 @@ For example, if we have two clocks <&oscillator 1> and <&oscillator 3>:
clock-output-names = "clka", "clkb";
}
This ensures we do not have any empty nodes in clock-output-names
This ensures we do not have any empty strings in clock-output-names
==Clock consumers==

41
Documentation/devicetree/bindings/clock/exynos3250-clock.txt Normal file
View File

@ -0,0 +1,41 @@
* Samsung Exynos3250 Clock Controller
The Exynos3250 clock controller generates and supplies clock to various
controllers within the Exynos3250 SoC.
Required Properties:
- compatible: should be one of the following.
- "samsung,exynos3250-cmu" - controller compatible with Exynos3250 SoC.
- reg: physical base address of the controller and length of memory mapped
region.
- #clock-cells: should be 1.
Each clock is assigned an identifier and client nodes can use this identifier
to specify the clock which they consume.
All available clocks are defined as preprocessor macros in
dt-bindings/clock/exynos3250.h header and can be used in device
tree sources.
Example 1: An example of a clock controller node is listed below.
cmu: clock-controller@10030000 {
compatible = "samsung,exynos3250-cmu";
reg = <0x10030000 0x20000>;
#clock-cells = <1>;
};
Example 2: UART controller node that consumes the clock generated by the clock
controller. Refer to the standard clock bindings for information
about 'clocks' and 'clock-names' property.
serial@13800000 {
compatible = "samsung,exynos4210-uart";
reg = <0x13800000 0x100>;
interrupts = <0 109 0>;
clocks = <&cmu CLK_UART0>, <&cmu CLK_SCLK_UART0>;
clock-names = "uart", "clk_uart_baud0";
};

190
Documentation/devicetree/bindings/clock/exynos5260-clock.txt Normal file
View File

@ -0,0 +1,190 @@
* Samsung Exynos5260 Clock Controller
Exynos5260 has 13 clock controllers which are instantiated
independently from the device-tree. These clock controllers
generate and supply clocks to various hardware blocks within
the SoC.
Each clock is assigned an identifier and client nodes can use
this identifier to specify the clock which they consume. All
available clocks are defined as preprocessor macros in
dt-bindings/clock/exynos5260-clk.h header and can be used in
device tree sources.
External clocks:
There are several clocks that are generated outside the SoC. It
is expected that they are defined using standard clock bindings
with following clock-output-names:
- "fin_pll" - PLL input clock from XXTI
- "xrtcxti" - input clock from XRTCXTI
- "ioclk_pcm_extclk" - pcm external operation clock
- "ioclk_spdif_extclk" - spdif external operation clock
- "ioclk_i2s_cdclk" - i2s0 codec clock
Phy clocks:
There are several clocks which are generated by specific PHYs.
These clocks are fed into the clock controller and then routed to
the hardware blocks. These clocks are defined as fixed clocks in the
driver with following names:
- "phyclk_dptx_phy_ch3_txd_clk" - dp phy clock for channel 3
- "phyclk_dptx_phy_ch2_txd_clk" - dp phy clock for channel 2
- "phyclk_dptx_phy_ch1_txd_clk" - dp phy clock for channel 1
- "phyclk_dptx_phy_ch0_txd_clk" - dp phy clock for channel 0
- "phyclk_hdmi_phy_tmds_clko" - hdmi phy tmds clock
- "phyclk_hdmi_phy_pixel_clko" - hdmi phy pixel clock
- "phyclk_hdmi_link_o_tmds_clkhi" - hdmi phy for hdmi link
- "phyclk_dptx_phy_o_ref_clk_24m" - dp phy reference clock
- "phyclk_dptx_phy_clk_div2"
- "phyclk_mipi_dphy_4l_m_rxclkesc0"
- "phyclk_usbhost20_phy_phyclock" - usb 2.0 phy clock
- "phyclk_usbhost20_phy_freeclk"
- "phyclk_usbhost20_phy_clk48mohci"
- "phyclk_usbdrd30_udrd30_pipe_pclk"
- "phyclk_usbdrd30_udrd30_phyclock" - usb 3.0 phy clock
Required Properties for Clock Controller:
- compatible: should be one of the following.
1) "samsung,exynos5260-clock-top"
2) "samsung,exynos5260-clock-peri"
3) "samsung,exynos5260-clock-egl"
4) "samsung,exynos5260-clock-kfc"
5) "samsung,exynos5260-clock-g2d"
6) "samsung,exynos5260-clock-mif"
7) "samsung,exynos5260-clock-mfc"
8) "samsung,exynos5260-clock-g3d"
9) "samsung,exynos5260-clock-fsys"
10) "samsung,exynos5260-clock-aud"
11) "samsung,exynos5260-clock-isp"
12) "samsung,exynos5260-clock-gscl"
13) "samsung,exynos5260-clock-disp"
- reg: physical base address of the controller and the length of
memory mapped region.
- #clock-cells: should be 1.
- clocks: list of clock identifiers which are fed as the input to
the given clock controller. Please refer the next section to find
the input clocks for a given controller.
- clock-names: list of names of clocks which are fed as the input
to the given clock controller.
Input clocks for top clock controller:
- fin_pll
- dout_mem_pll
- dout_bus_pll
- dout_media_pll
Input clocks for peri clock controller:
- fin_pll
- ioclk_pcm_extclk
- ioclk_i2s_cdclk
- ioclk_spdif_extclk
- phyclk_hdmi_phy_ref_cko
- dout_aclk_peri_66
- dout_sclk_peri_uart0
- dout_sclk_peri_uart1
- dout_sclk_peri_uart2
- dout_sclk_peri_spi0_b
- dout_sclk_peri_spi1_b
- dout_sclk_peri_spi2_b
- dout_aclk_peri_aud
- dout_sclk_peri_spi0_b
Input clocks for egl clock controller:
- fin_pll
- dout_bus_pll
Input clocks for kfc clock controller:
- fin_pll
- dout_media_pll
Input clocks for g2d clock controller:
- fin_pll
- dout_aclk_g2d_333
Input clocks for mif clock controller:
- fin_pll
Input clocks for mfc clock controller:
- fin_pll
- dout_aclk_mfc_333
Input clocks for g3d clock controller:
- fin_pll
Input clocks for fsys clock controller:
- fin_pll
- phyclk_usbhost20_phy_phyclock
- phyclk_usbhost20_phy_freeclk
- phyclk_usbhost20_phy_clk48mohci
- phyclk_usbdrd30_udrd30_pipe_pclk
- phyclk_usbdrd30_udrd30_phyclock
- dout_aclk_fsys_200
Input clocks for aud clock controller:
- fin_pll
- fout_aud_pll
- ioclk_i2s_cdclk
- ioclk_pcm_extclk
Input clocks for isp clock controller:
- fin_pll
- dout_aclk_isp1_266
- dout_aclk_isp1_400
- mout_aclk_isp1_266
Input clocks for gscl clock controller:
- fin_pll
- dout_aclk_gscl_400
- dout_aclk_gscl_333
Input clocks for disp clock controller:
- fin_pll
- phyclk_dptx_phy_ch3_txd_clk
- phyclk_dptx_phy_ch2_txd_clk
- phyclk_dptx_phy_ch1_txd_clk
- phyclk_dptx_phy_ch0_txd_clk
- phyclk_hdmi_phy_tmds_clko
- phyclk_hdmi_phy_ref_clko
- phyclk_hdmi_phy_pixel_clko
- phyclk_hdmi_link_o_tmds_clkhi
- phyclk_mipi_dphy_4l_m_txbyte_clkhs
- phyclk_dptx_phy_o_ref_clk_24m
- phyclk_dptx_phy_clk_div2
- phyclk_mipi_dphy_4l_m_rxclkesc0
- phyclk_hdmi_phy_ref_cko
- ioclk_spdif_extclk
- dout_aclk_peri_aud
- dout_aclk_disp_222
- dout_sclk_disp_pixel
- dout_aclk_disp_333
Example 1: An example of a clock controller node is listed below.
clock_mfc: clock-controller@11090000 {
compatible = "samsung,exynos5260-clock-mfc";
clock = <&fin_pll>, <&clock_top TOP_DOUT_ACLK_MFC_333>;
clock-names = "fin_pll", "dout_aclk_mfc_333";
reg = <0x11090000 0x10000>;
#clock-cells = <1>;
};
Example 2: UART controller node that consumes the clock generated by the
peri clock controller. Refer to the standard clock bindings for
information about 'clocks' and 'clock-names' property.
serial@12C00000 {
compatible = "samsung,exynos4210-uart";
reg = <0x12C00000 0x100>;
interrupts = <0 146 0>;
clocks = <&clock_peri PERI_PCLK_UART0>, <&clock_peri PERI_SCLK_UART0>;
clock-names = "uart", "clk_uart_baud0";
};

45
Documentation/devicetree/bindings/clock/exynos5410-clock.txt Normal file
View File

@ -0,0 +1,45 @@
* Samsung Exynos5410 Clock Controller
The Exynos5410 clock controller generates and supplies clock to various
controllers within the Exynos5410 SoC.
Required Properties:
- compatible: should be "samsung,exynos5410-clock"
- reg: physical base address of the controller and length of memory mapped
region.
- #clock-cells: should be 1.
All available clocks are defined as preprocessor macros in
dt-bindings/clock/exynos5410.h header and can be used in device
tree sources.
External clock:
There is clock that is generated outside the SoC. It
is expected that it is defined using standard clock bindings
with following clock-output-name:
- "fin_pll" - PLL input clock from XXTI
Example 1: An example of a clock controller node is listed below.
clock: clock-controller@0x10010000 {
compatible = "samsung,exynos5410-clock";
reg = <0x10010000 0x30000>;
#clock-cells = <1>;
};
Example 2: UART controller node that consumes the clock generated by the clock
controller. Refer to the standard clock bindings for information
about 'clocks' and 'clock-names' property.
serial@12C20000 {
compatible = "samsung,exynos4210-uart";
reg = <0x12C00000 0x100>;
interrupts = <0 51 0>;
clocks = <&clock CLK_UART0>, <&clock CLK_SCLK_UART0>;
clock-names = "uart", "clk_uart_baud0";
};

3
Documentation/devicetree/bindings/clock/exynos5420-clock.txt
View File

@ -1,12 +1,13 @@
* Samsung Exynos5420 Clock Controller
The Exynos5420 clock controller generates and supplies clock to various
controllers within the Exynos5420 SoC.
controllers within the Exynos5420 SoC and for the Exynos5800 SoC.
Required Properties:
- compatible: should be one of the following.
- "samsung,exynos5420-clock" - controller compatible with Exynos5420 SoC.
- "samsung,exynos5800-clock" - controller compatible with Exynos5800 SoC.
- reg: physical base address of the controller and length of memory mapped
region.

1
Documentation/devicetree/bindings/clock/fixed-clock.txt
View File

@ -12,7 +12,6 @@ Required properties:
Optional properties:
- clock-accuracy : accuracy of clock in ppb (parts per billion).
Should be a single cell.
- gpios : From common gpio binding; gpio connection to clock enable pin.
- clock-output-names : From common clock binding.
Example:

31
Documentation/devicetree/bindings/clock/hix5hd2-clock.txt Normal file
View File

@ -0,0 +1,31 @@
* Hisilicon Hix5hd2 Clock Controller
The hix5hd2 clock controller generates and supplies clock to various
controllers within the hix5hd2 SoC.
Required Properties:
- compatible: should be "hisilicon,hix5hd2-clock"
- reg: Address and length of the register set
- #clock-cells: Should be <1>
Each clock is assigned an identifier and client nodes use this identifier
to specify the clock which they consume.
All these identifier could be found in <dt-bindings/clock/hix5hd2-clock.h>.
Examples:
clock: clock@f8a22000 {
compatible = "hisilicon,hix5hd2-clock";
reg = <0xf8a22000 0x1000>;
#clock-cells = <1>;
};
uart0: uart@f8b00000 {
compatible = "arm,pl011", "arm,primecell";
reg = <0xf8b00000 0x1000>;
interrupts = <0 49 4>;
clocks = <&clock HIX5HD2_FIXED_83M>;
clock-names = "apb_pclk";
status = "disabled";
};

3
Documentation/devicetree/bindings/clock/imx25-clock.txt
View File

@ -139,6 +139,9 @@ clocks and IDs.
uart5_ipg 124
reserved 125
wdt_ipg 126
cko_div 127
cko_sel 128
cko 129
Examples:

7
Documentation/devicetree/bindings/clock/imx27-clock.txt
View File

@ -98,7 +98,12 @@ clocks and IDs.
fpm 83
mpll_osc_sel 84
mpll_sel 85
spll_gate 86
spll_gate 86
mshc_div 87
rtic_ipg_gate 88
mshc_ipg_gate 89
rtic_ahb_gate 90
mshc_baud_gate 91
Examples:

1
Documentation/devicetree/bindings/clock/imx6q-clock.txt
View File

@ -220,6 +220,7 @@ clocks and IDs.
lvds2_sel 205
lvds1_gate 206
lvds2_gate 207
esai_ahb 208
Examples:

13
Documentation/devicetree/bindings/clock/imx6sx-clock.txt Normal file
View File

@ -0,0 +1,13 @@
* Clock bindings for Freescale i.MX6 SoloX
Required properties:
- compatible: Should be "fsl,imx6sx-ccm"
- reg: Address and length of the register set
- #clock-cells: Should be <1>
- clocks: list of clock specifiers, must contain an entry for each required
entry in clock-names
- clock-names: should include entries "ckil", "osc", "ipp_di0" and "ipp_di1"
The clock consumer should specify the desired clock by having the clock
ID in its "clocks" phandle cell. See include/dt-bindings/clock/imx6sx-clock.h
for the full list of i.MX6 SoloX clock IDs.

29
Documentation/devicetree/bindings/clock/lsi,axm5516-clks.txt Normal file
View File

@ -0,0 +1,29 @@
AXM5516 clock driver bindings
-----------------------------
Required properties :
- compatible : shall contain "lsi,axm5516-clks"
- reg : shall contain base register location and length
- #clock-cells : shall contain 1
The consumer specifies the desired clock by having the clock ID in its "clocks"
phandle cell. See <dt-bindings/clock/lsi,axxia-clock.h> for the list of
supported clock IDs.
Example:
clks: clock-controller@2010020000 {
compatible = "lsi,axm5516-clks";
#clock-cells = <1>;
reg = <0x20 0x10020000 0 0x20000>;
};
serial0: uart@2010080000 {
compatible = "arm,pl011", "arm,primecell";
reg = <0x20 0x10080000 0 0x1000>;
interrupts = <GIC_SPI 56 IRQ_TYPE_LEVEL_HIGH>;
clocks = <&clks AXXIA_CLK_PER>;
clock-names = "apb_pclk";
};
};

8
Documentation/devicetree/bindings/clock/mvebu-core-clock.txt
View File

@ -29,6 +29,11 @@ The following is a list of provided IDs and clock names on Kirkwood and Dove:
2 = l2clk (L2 Cache clock derived from CPU0 clock)
3 = ddrclk (DDR controller clock derived from CPU0 clock)
The following is a list of provided IDs and clock names on Orion5x:
0 = tclk (Internal Bus clock)
1 = cpuclk (CPU0 clock)
2 = ddrclk (DDR controller clock derived from CPU0 clock)
Required properties:
- compatible : shall be one of the following:
"marvell,armada-370-core-clock" - For Armada 370 SoC core clocks
@ -38,6 +43,9 @@ Required properties:
"marvell,dove-core-clock" - for Dove SoC core clocks
"marvell,kirkwood-core-clock" - for Kirkwood SoC (except mv88f6180)
"marvell,mv88f6180-core-clock" - for Kirkwood MV88f6180 SoC
"marvell,mv88f5182-core-clock" - for Orion MV88F5182 SoC
"marvell,mv88f5281-core-clock" - for Orion MV88F5281 SoC
"marvell,mv88f6183-core-clock" - for Orion MV88F6183 SoC
- reg : shall be the register address of the Sample-At-Reset (SAR) register
- #clock-cells : from common clock binding; shall be set to 1

3
Documentation/devicetree/bindings/clock/qcom,gcc.txt
View File

@ -4,9 +4,12 @@ Qualcomm Global Clock & Reset Controller Binding
Required properties :
- compatible : shall contain only one of the following:
"qcom,gcc-apq8064"
"qcom,gcc-msm8660"
"qcom,gcc-msm8960"
"qcom,gcc-msm8974"
"qcom,gcc-msm8974pro"
"qcom,gcc-msm8974pro-ac"
- reg : shall contain base register location and length
- #clock-cells : shall contain 1

2
Documentation/devicetree/bindings/clock/renesas,cpg-mstp-clocks.txt
View File

@ -10,6 +10,8 @@ index in the group, from 0 to 31.
Required Properties:
- compatible: Must be one of the following
- "renesas,r7s72100-mstp-clocks" for R7S72100 (RZ) MSTP gate clocks
- "renesas,r8a7779-mstp-clocks" for R8A7779 (R-Car H1) MSTP gate clocks
- "renesas,r8a7790-mstp-clocks" for R8A7790 (R-Car H2) MSTP gate clocks
- "renesas,r8a7791-mstp-clocks" for R8A7791 (R-Car M2) MSTP gate clocks
- "renesas,cpg-mstp-clock" for generic MSTP gate clocks

41
Documentation/devicetree/bindings/clock/renesas,r8a7740-cpg-clocks.txt Normal file
View File

@ -0,0 +1,41 @@
These bindings should be considered EXPERIMENTAL for now.
* Renesas R8A7740 Clock Pulse Generator (CPG)
The CPG generates core clocks for the R8A7740 SoC. It includes three PLLs
and several fixed ratio and variable ratio dividers.
Required Properties:
- compatible: Must be "renesas,r8a7740-cpg-clocks"
- reg: Base address and length of the memory resource used by the CPG
- clocks: Reference to the three parent clocks
- #clock-cells: Must be 1
- clock-output-names: The names of the clocks. Supported clocks are
"system", "pllc0", "pllc1", "pllc2", "r", "usb24s", "i", "zg", "b",
"m1", "hp", "hpp", "usbp", "s", "zb", "m3", and "cp".
- renesas,mode: board-specific settings of the MD_CK* bits
Example
-------
cpg_clocks: cpg_clocks@e6150000 {
compatible = "renesas,r8a7740-cpg-clocks";
reg = <0xe6150000 0x10000>;
clocks = <&extal1_clk>, <&extal2_clk>, <&extalr_clk>;
#clock-cells = <1>;
clock-output-names = "system", "pllc0", "pllc1",
"pllc2", "r",
"usb24s",
"i", "zg", "b", "m1", "hp",
"hpp", "usbp", "s", "zb", "m3",
"cp";
};
&cpg_clocks {
renesas,mode = <0x05>;
};

27
Documentation/devicetree/bindings/clock/renesas,r8a7779-cpg-clocks.txt Normal file
View File

@ -0,0 +1,27 @@
* Renesas R8A7779 Clock Pulse Generator (CPG)
The CPG generates core clocks for the R8A7779. It includes one PLL and
several fixed ratio dividers
Required Properties:
- compatible: Must be "renesas,r8a7779-cpg-clocks"
- reg: Base address and length of the memory resource used by the CPG
- clocks: Reference to the parent clock
- #clock-cells: Must be 1
- clock-output-names: The names of the clocks. Supported clocks are "plla",
"z", "zs", "s", "s1", "p", "b", "out".
Example
-------
cpg_clocks: cpg_clocks@ffc80000 {
compatible = "renesas,r8a7779-cpg-clocks";
reg = <0 0xffc80000 0 0x30>;
clocks = <&extal_clk>;
#clock-cells = <1>;
clock-output-names = "plla", "z", "zs", "s", "s1", "p",
"b", "out";
};

50
Documentation/devicetree/bindings/clock/samsung,s3c2410-clock.txt Normal file
View File

@ -0,0 +1,50 @@
* Samsung S3C2410 Clock Controller
The S3C2410 clock controller generates and supplies clock to various controllers
within the SoC. The clock binding described here is applicable to the s3c2410,
s3c2440 and s3c2442 SoCs in the s3c24x family.
Required Properties:
- compatible: should be one of the following.
- "samsung,s3c2410-clock" - controller compatible with S3C2410 SoC.
- "samsung,s3c2440-clock" - controller compatible with S3C2440 SoC.
- "samsung,s3c2442-clock" - controller compatible with S3C2442 SoC.
- reg: physical base address of the controller and length of memory mapped
region.
- #clock-cells: should be 1.
Each clock is assigned an identifier and client nodes can use this identifier
to specify the clock which they consume. Some of the clocks are available only
on a particular SoC.
All available clocks are defined as preprocessor macros in
dt-bindings/clock/s3c2410.h header and can be used in device
tree sources.
External clocks:
The xti clock used as input for the plls is generated outside the SoC. It is
expected that is are defined using standard clock bindings with a
clock-output-names value of "xti".
Example: Clock controller node:
clocks: clock-controller@4c000000 {
compatible = "samsung,s3c2410-clock";
reg = <0x4c000000 0x20>;
#clock-cells = <1>;
};
Example: UART controller node that consumes the clock generated by the clock
controller (refer to the standard clock bindings for information about
"clocks" and "clock-names" properties):
serial@50004000 {
compatible = "samsung,s3c2440-uart";
reg = <0x50004000 0x4000>;
interrupts = <1 23 3 4>, <1 23 4 4>;
clock-names = "uart", "clk_uart_baud2";
clocks = <&clocks PCLK_UART0>, <&clocks PCLK_UART0>;
status = "disabled";
};

50
Documentation/devicetree/bindings/clock/samsung,s3c2412-clock.txt Normal file
View File

@ -0,0 +1,50 @@
* Samsung S3C2412 Clock Controller
The S3C2412 clock controller generates and supplies clock to various controllers
within the SoC. The clock binding described here is applicable to the s3c2412
and s3c2413 SoCs in the s3c24x family.
Required Properties:
- compatible: should be "samsung,s3c2412-clock"
- reg: physical base address of the controller and length of memory mapped
region.
- #clock-cells: should be 1.
Each clock is assigned an identifier and client nodes can use this identifier
to specify the clock which they consume. Some of the clocks are available only
on a particular SoC.
All available clocks are defined as preprocessor macros in
dt-bindings/clock/s3c2412.h header and can be used in device
tree sources.
External clocks:
There are several clocks that are generated outside the SoC. It is expected
that they are defined using standard clock bindings with following
clock-output-names:
- "xti" - crystal input - required,
- "ext" - external clock source - optional,
Example: Clock controller node:
clocks: clock-controller@4c000000 {
compatible = "samsung,s3c2412-clock";
reg = <0x4c000000 0x20>;
#clock-cells = <1>;
};
Example: UART controller node that consumes the clock generated by the clock
controller (refer to the standard clock bindings for information about
"clocks" and "clock-names" properties):
serial@50004000 {
compatible = "samsung,s3c2412-uart";
reg = <0x50004000 0x4000>;
interrupts = <1 23 3 4>, <1 23 4 4>;
clock-names = "uart", "clk_uart_baud2", "clk_uart_baud3";
clocks = <&clocks PCLK_UART0>, <&clocks PCLK_UART0>,
<&clocks SCLK_UART>;
status = "disabled";
};

56
Documentation/devicetree/bindings/clock/samsung,s3c2443-clock.txt Normal file
View File

@ -0,0 +1,56 @@
* Samsung S3C2443 Clock Controller
The S3C2443 clock controller generates and supplies clock to various controllers
within the SoC. The clock binding described here is applicable to all SoCs in
the s3c24x family starting with the s3c2443.
Required Properties:
- compatible: should be one of the following.
- "samsung,s3c2416-clock" - controller compatible with S3C2416 SoC.
- "samsung,s3c2443-clock" - controller compatible with S3C2443 SoC.
- "samsung,s3c2450-clock" - controller compatible with S3C2450 SoC.
- reg: physical base address of the controller and length of memory mapped
region.
- #clock-cells: should be 1.
Each clock is assigned an identifier and client nodes can use this identifier
to specify the clock which they consume. Some of the clocks are available only
on a particular SoC.
All available clocks are defined as preprocessor macros in
dt-bindings/clock/s3c2443.h header and can be used in device
tree sources.
External clocks:
There are several clocks that are generated outside the SoC. It is expected
that they are defined using standard clock bindings with following
clock-output-names:
- "xti" - crystal input - required,
- "ext" - external clock source - optional,
- "ext_i2s" - external I2S clock - optional,
- "ext_uart" - external uart clock - optional,
Example: Clock controller node:
clocks: clock-controller@4c000000 {
compatible = "samsung,s3c2416-clock";
reg = <0x4c000000 0x40>;
#clock-cells = <1>;
};
Example: UART controller node that consumes the clock generated by the clock
controller (refer to the standard clock bindings for information about
"clocks" and "clock-names" properties):
serial@50004000 {
compatible = "samsung,s3c2440-uart";
reg = <0x50004000 0x4000>;
interrupts = <1 23 3 4>, <1 23 4 4>;
clock-names = "uart", "clk_uart_baud2",
"clk_uart_baud3";
clocks = <&clocks PCLK_UART0>, <&clocks PCLK_UART0>,
<&clocks SCLK_UART>;
status = "disabled";
};

20
Documentation/devicetree/bindings/clock/ti-keystone-pllctrl.txt Normal file
View File

@ -0,0 +1,20 @@
* Device tree bindings for Texas Instruments keystone pll controller
The main pll controller used to drive theC66x CorePacs, the switch fabric,
and a majority of the peripheral clocks (all but the ARM CorePacs, DDR3 and
the NETCP modules) requires a PLL Controller to manage the various clock
divisions, gating, and synchronization.
Required properties:
- compatible: "ti,keystone-pllctrl", "syscon"
- reg: contains offset/length value for pll controller
registers space.
Example:
pllctrl: pll-controller@0x02310000 {
compatible = "ti,keystone-pllctrl", "syscon";
reg = <0x02310000 0x200>;
};

34
Documentation/devicetree/bindings/crypto/samsung-sss.txt Normal file
View File

@ -0,0 +1,34 @@
Samsung SoC SSS (Security SubSystem) module
The SSS module in S5PV210 SoC supports the following:
-- Feeder (FeedCtrl)
-- Advanced Encryption Standard (AES)
-- Data Encryption Standard (DES)/3DES
-- Public Key Accelerator (PKA)
-- SHA-1/SHA-256/MD5/HMAC (SHA-1/SHA-256/MD5)/PRNG
-- PRNG: Pseudo Random Number Generator
The SSS module in Exynos4 (Exynos4210) and
Exynos5 (Exynos5420 and Exynos5250) SoCs
supports the following also:
-- ARCFOUR (ARC4)
-- True Random Number Generator (TRNG)
-- Secure Key Manager
Required properties:
- compatible : Should contain entries for this and backward compatible
SSS versions:
- "samsung,s5pv210-secss" for S5PV210 SoC.
- "samsung,exynos4210-secss" for Exynos4210, Exynos4212, Exynos4412, Exynos5250,
Exynos5260 and Exynos5420 SoCs.
- reg : Offset and length of the register set for the module
- interrupts : interrupt specifiers of SSS module interrupts, should contain
following entries:
- first : feed control interrupt (required for all variants),
- second : hash interrupt (required only for samsung,s5pv210-secss).
- clocks : list of clock phandle and specifier pairs for all clocks listed in
clock-names property.
- clock-names : list of device clock input names; should contain one entry
"secss".

4
Documentation/devicetree/bindings/dma/dma.txt
View File

@ -14,7 +14,7 @@ Required property:
Optional properties:
- dma-channels: Number of DMA channels supported by the controller.
- dma-requests: Number of DMA requests signals supported by the
- dma-requests: Number of DMA request signals supported by the
controller.
Example:
@ -44,7 +44,7 @@ Required property:
#dma-cells property in the node referenced by phandle
containing DMA controller specific information. This
typically contains a DMA request line number or a
channel number, but can contain any data that is used
channel number, but can contain any data that is
required for configuring a channel.
- dma-names: Contains one identifier string for each DMA specifier in
the dmas property. The specific strings that can be used

2
Documentation/devicetree/bindings/dma/fsl-imx-sdma.txt
View File

@ -8,7 +8,7 @@ Required properties:
"fsl,imx51-sdma"
"fsl,imx53-sdma"
"fsl,imx6q-sdma"
The -to variants should be preferred since they allow to determnine the
The -to variants should be preferred since they allow to determine the
correct ROM script addresses needed for the driver to work without additional
firmware.
- reg : Should contain SDMA registers location and length

13
Documentation/devicetree/bindings/dma/ti-edma.txt
View File

@ -2,11 +2,8 @@ TI EDMA
Required properties:
- compatible : "ti,edma3"
- ti,edma-regions: Number of regions
- ti,edma-slots: Number of slots
- #dma-cells: Should be set to <1>
Clients should use a single channel number per DMA request.
- dma-channels: Specify total DMA channels per CC
- reg: Memory map for accessing module
- interrupt-parent: Interrupt controller the interrupt is routed through
- interrupts: Exactly 3 interrupts need to be specified in the order:
@ -17,6 +14,13 @@ Optional properties:
- ti,hwmods: Name of the hwmods associated to the EDMA
- ti,edma-xbar-event-map: Crossbar event to channel map
Deprecated properties:
Listed here in case one wants to boot an old kernel with new DTB. These
properties might need to be added to the new DTS files.
- ti,edma-regions: Number of regions
- ti,edma-slots: Number of slots
- dma-channels: Specify total DMA channels per CC
Example:
edma: edma@49000000 {
@ -26,9 +30,6 @@ edma: edma@49000000 {
compatible = "ti,edma3";
ti,hwmods = "tpcc", "tptc0", "tptc1", "tptc2";
#dma-cells = <1>;
dma-channels = <64>;
ti,edma-regions = <4>;
ti,edma-slots = <256>;
ti,edma-xbar-event-map = /bits/ 16 <1 12
2 13>;
};

2
Documentation/devicetree/bindings/gpio/gpio-mcp23s08.txt
View File

@ -54,7 +54,7 @@ Optional device specific properties:
IO 8-15 are bank 2. These chips have two different interrupt outputs:
One for bank 1 and another for bank 2. If irq-mirror is set, both
interrupts are generated regardless of the bank that an input change
occured on. If it is not set, the interrupt are only generated for the
occurred on. If it is not set, the interrupt are only generated for the
bank they belong to.
On devices with only one interrupt output this property is useless.

6
Documentation/devicetree/bindings/gpio/renesas,gpio-rcar.txt
View File

@ -21,6 +21,12 @@ Required Properties:
GPIO_ACTIVE_HIGH and GPIO_ACTIVE_LOW flags are supported.
- gpio-ranges: Range of pins managed by the GPIO controller.
Optional properties:
- clocks: Must contain a reference to the functional clock. The property is
mandatory if the hardware implements a controllable functional clock for
the GPIO instance.
Please refer to gpio.txt in this directory for details of gpio-ranges property
and the common GPIO bindings used by client devices.

44
Documentation/devicetree/bindings/hsi/client-devices.txt Normal file
View File

@ -0,0 +1,44 @@
Each HSI port is supposed to have one child node, which
symbols the remote device connected to the HSI port. The
following properties are standardized for HSI clients:
Required HSI configuration properties:
- hsi-channel-ids: A list of channel ids
- hsi-rx-mode: Receiver Bit transmission mode ("stream" or "frame")
- hsi-tx-mode: Transmitter Bit transmission mode ("stream" or "frame")
- hsi-mode: May be used instead hsi-rx-mode and hsi-tx-mode if
the transmission mode is the same for receiver and
transmitter
- hsi-speed-kbps: Max bit transmission speed in kbit/s
- hsi-flow: RX flow type ("synchronized" or "pipeline")
- hsi-arb-mode: Arbitration mode for TX frame ("round-robin", "priority")
Optional HSI configuration properties:
- hsi-channel-names: A list with one name per channel specified in the
hsi-channel-ids property
Device Tree node example for an HSI client:
hsi-controller {
hsi-port {
modem: hsi-client {
compatible = "nokia,n900-modem";
hsi-channel-ids = <0>, <1>, <2>, <3>;
hsi-channel-names = "mcsaab-control",
"speech-control",
"speech-data",
"mcsaab-data";
hsi-speed-kbps = <55000>;
hsi-mode = "frame";
hsi-flow = "synchronized";
hsi-arb-mode = "round-robin";
/* more client specific properties */
};
};
};

57
Documentation/devicetree/bindings/hsi/nokia-modem.txt Normal file
View File

@ -0,0 +1,57 @@
Nokia modem client bindings
The Nokia modem HSI client follows the common HSI client binding
and inherits all required properties. The following additional
properties are needed by the Nokia modem HSI client:
Required properties:
- compatible: Should be one of
"nokia,n900-modem"
- hsi-channel-names: Should contain the following strings
"mcsaab-control"
"speech-control"
"speech-data"
"mcsaab-data"
- gpios: Should provide a GPIO handler for each GPIO listed in
gpio-names
- gpio-names: Should contain the following strings
"cmt_apeslpx"
"cmt_rst_rq"
"cmt_en"
"cmt_rst"
"cmt_bsi"
- interrupts: Should be IRQ handle for modem's reset indication
Example:
&ssi_port {
modem: hsi-client {
compatible = "nokia,n900-modem";
pinctrl-names = "default";
pinctrl-0 = <&modem_pins>;
hsi-channel-ids = <0>, <1>, <2>, <3>;
hsi-channel-names = "mcsaab-control",
"speech-control",
"speech-data",
"mcsaab-data";
hsi-speed-kbps = <55000>;
hsi-mode = "frame";
hsi-flow = "synchronized";
hsi-arb-mode = "round-robin";
interrupts-extended = <&gpio3 8 IRQ_TYPE_EDGE_FALLING>; /* 72 */
gpios = <&gpio3 6 GPIO_ACTIVE_HIGH>, /* 70 */
<&gpio3 9 GPIO_ACTIVE_HIGH>, /* 73 */
<&gpio3 10 GPIO_ACTIVE_HIGH>, /* 74 */
<&gpio3 11 GPIO_ACTIVE_HIGH>, /* 75 */
<&gpio5 29 GPIO_ACTIVE_HIGH>; /* 157 */
gpio-names = "cmt_apeslpx",
"cmt_rst_rq",
"cmt_en",
"cmt_rst",
"cmt_bsi";
};
};

97
Documentation/devicetree/bindings/hsi/omap-ssi.txt Normal file
View File

@ -0,0 +1,97 @@
OMAP SSI controller bindings
OMAP Synchronous Serial Interface (SSI) controller implements a legacy
variant of MIPI's High Speed Synchronous Serial Interface (HSI).
Required properties:
- compatible: Should include "ti,omap3-ssi".
- reg-names: Contains the values "sys" and "gdd" (in this order).
- reg: Contains a matching register specifier for each entry
in reg-names.
- interrupt-names: Contains the value "gdd_mpu".
- interrupts: Contains matching interrupt information for each entry
in interrupt-names.
- ranges: Represents the bus address mapping between the main
controller node and the child nodes below.
- clock-names: Must include the following entries:
"ssi_ssr_fck": The OMAP clock of that name
"ssi_sst_fck": The OMAP clock of that name
"ssi_ick": The OMAP clock of that name
- clocks: Contains a matching clock specifier for each entry in
clock-names.
- #address-cells: Should be set to <1>
- #size-cells: Should be set to <1>
Each port is represented as a sub-node of the ti,omap3-ssi device.
Required Port sub-node properties:
- compatible: Should be set to the following value
ti,omap3-ssi-port (applicable to OMAP34xx devices)
- reg-names: Contains the values "tx" and "rx" (in this order).
- reg: Contains a matching register specifier for each entry
in reg-names.
- interrupt-parent Should be a phandle for the interrupt controller
- interrupts: Should contain interrupt specifiers for mpu interrupts
0 and 1 (in this order).
- ti,ssi-cawake-gpio: Defines which GPIO pin is used to signify CAWAKE
events for the port. This is an optional board-specific
property. If it's missing the port will not be
enabled.
Example for Nokia N900:
ssi-controller@48058000 {
compatible = "ti,omap3-ssi";
/* needed until hwmod is updated to use the compatible string */
ti,hwmods = "ssi";
reg = <0x48058000 0x1000>,
<0x48059000 0x1000>;
reg-names = "sys",
"gdd";
interrupts = <55>;
interrupt-names = "gdd_mpu";
clocks = <&ssi_ssr_fck>,
<&ssi_sst_fck>,
<&ssi_ick>;
clock-names = "ssi_ssr_fck",
"ssi_sst_fck",
"ssi_ick";
#address-cells = <1>;
#size-cells = <1>;
ranges;
ssi-port@4805a000 {
compatible = "ti,omap3-ssi-port";
reg = <0x4805a000 0x800>,
<0x4805a800 0x800>;
reg-names = "tx",
"rx";
interrupt-parent = <&intc>;
interrupts = <67>,
<68>;
ti,ssi-cawake-gpio = <&gpio5 23 GPIO_ACTIVE_HIGH>; /* 151 */
}
ssi-port@4805a000 {
compatible = "ti,omap3-ssi-port";
reg = <0x4805b000 0x800>,
<0x4805b800 0x800>;
reg-names = "tx",
"rx";
interrupt-parent = <&intc>;
interrupts = <69>,
<70>;
status = "disabled"; /* second port is not used on N900 */
}
}

Some files were not shown because too many files have changed in this diff Show More