redonkable
/
remarkable-linux
1
0
Fork 0
Code Releases Activity

Linux 3.16 

-----BEGIN PGP SIGNATURE-----
 Version: GnuPG v1
 
 iQEcBAABAgAGBQJT3rbVAAoJEHm+PkMAQRiGBc0H/0PcAqZ66KqBrjCaC7tlR9ZJ
 Oyv4usrPpVmJaCaYiNwc4KnkJXDfc/foEtZq32vYSb4d8xaOLta3DrT8YJTS7B7T
 Afdg8FbVdSjBD0S8It35XidmZlOaVrgGJGpDIRBRrqDwPPgbWpTeUR73bfkwoA/R
 ziW+78s0mquo9hN9Bdu3apr7XxVmzeIUx6lJxKPCoXNEGTsSC7ibCzZRzZDMpag/
 D1JrQbE0XevgEu5fWrJkcqKceUzi3I1wuKZvBIJm2aX5XDsKpYNfQL6ViJDW56dK
 LhrB8vex8gkQYSCVPyUKx4BjkdPourSICSKq+h0SwhOCpHVHPmG8XM3J4/U4a7U=
 =yoNZ
 -----END PGP SIGNATURE-----

Merge tag 'v3.16' into next

Linux 3.16
wifi-calibration
Paul Moore 2014-08-05 15:44:22 -04:00
parent 4fbe63d1c7 19583ca584
commit aa9e0de81b
9755 changed files with 496104 additions and 249563 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.gitignore vendored
View File

@ -22,7 +22,6 @@
*.lst
*.symtypes
*.order
modules.builtin
*.elf
*.bin
*.gz
@ -33,6 +32,8 @@ modules.builtin
*.lzo
*.patch
*.gcno
modules.builtin
Module.symvers
#
# Top-level generic files
@ -44,7 +45,6 @@ modules.builtin
/vmlinuz
/System.map
/Module.markers
/Module.symvers
#
# Debian directory (make deb-pkg)

5
.mailmap
View File

@ -62,6 +62,11 @@ Jeff Garzik <jgarzik@pretzel.yyz.us>
Jens Axboe <axboe@suse.de>
Jens Osterkamp <Jens.Osterkamp@de.ibm.com>
John Stultz <johnstul@us.ibm.com>
<josh@joshtriplett.org> <josh@freedesktop.org>
<josh@joshtriplett.org> <josh@kernel.org>
<josh@joshtriplett.org> <josht@linux.vnet.ibm.com>
<josh@joshtriplett.org> <josht@us.ibm.com>
<josh@joshtriplett.org> <josht@vnet.ibm.com>
Juha Yrjola <at solidboot.com>
Juha Yrjola <juha.yrjola@nokia.com>
Juha Yrjola <juha.yrjola@solidboot.com>

11
CREDITS
View File

@ -9,6 +9,10 @@
Linus
----------
M: Matt Mackal
E: mpm@selenic.com
D: SLOB slab allocator
N: Matti Aarnio
E: mea@nic.funet.fi
D: Alpha systems hacking, IPv6 and other network related stuff
@ -3507,10 +3511,11 @@ S: MacGregor A.C.T 2615
S: Australia
N: Josh Triplett
E: josh@freedesktop.org
P: 1024D/D0FE7AFB B24A 65C9 1D71 2AC2 DE87 CA26 189B 9946 D0FE 7AFB
D: rcutorture maintainer
E: josh@joshtriplett.org
P: 4096R/8AFF873D 758E 5042 E397 4BA3 3A9C 1E67 0ED9 A3DF 8AFF 873D
D: RCU and rcutorture
D: lock annotations, finding and fixing lock bugs
D: kernel tinification
N: Winfried Trümper
E: winni@xpilot.org

25
Documentation/ABI/stable/sysfs-devices-system-cpu 100644
View File

@ -0,0 +1,25 @@
What: /sys/devices/system/cpu/dscr_default
Date: 13-May-2014
KernelVersion: v3.15.0
Contact:
Description: Writes are equivalent to writing to
/sys/devices/system/cpu/cpuN/dscr on all CPUs.
Reads return the last written value or 0.
This value is not a global default: it is a way to set
all per-CPU defaults at the same time.
Values: 64 bit unsigned integer (bit field)
What: /sys/devices/system/cpu/cpu[0-9]+/dscr
Date: 13-May-2014
KernelVersion: v3.15.0
Contact:
Description: Default value for the Data Stream Control Register (DSCR) on
a CPU.
This default value is used when the kernel is executing and
for any process that has not set the DSCR itself.
If a process ever sets the DSCR (via direct access to the
SPR) that value will be persisted for that process and used
on any CPU where it executes (overriding the value described
here).
If set by a process it will be inherited by child processes.
Values: 64 bit unsigned integer (bit field)

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

2
Documentation/ABI/testing/ima_policy
View File

@ -23,7 +23,7 @@ Description:
[fowner]]
lsm: [[subj_user=] [subj_role=] [subj_type=]
[obj_user=] [obj_role=] [obj_type=]]
option: [[appraise_type=]]
option: [[appraise_type=]] [permit_directio]
base: func:= [BPRM_CHECK][MMAP_CHECK][FILE_CHECK][MODULE_CHECK]
mask:= [MAY_READ] [MAY_WRITE] [MAY_APPEND] [MAY_EXEC]

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 100644
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.

8
Documentation/ABI/testing/sysfs-class-net
View File

@ -169,6 +169,14 @@ Description:
"unknown", "notpresent", "down", "lowerlayerdown", "testing",
"dormant", "up".
What: /sys/class/net/<iface>/phys_port_id
Date: July 2013
KernelVersion: 3.12
Contact: netdev@vger.kernel.org
Description:
Indicates the interface unique physical port identifier within
the NIC, as a string.
What: /sys/class/net/<iface>/speed
Date: October 2009
KernelVersion: 2.6.33

149
Documentation/ABI/testing/sysfs-class-net-cdc_ncm 100644
View File

@ -0,0 +1,149 @@
What: /sys/class/net/<iface>/cdc_ncm/min_tx_pkt
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
The driver will pad NCM Transfer Blocks (NTBs) longer
than this to tx_max, allowing the device to receive
tx_max sized frames with no terminating short
packet. NTBs shorter than this limit are transmitted
as-is, without any padding, and are terminated with a
short USB packet.
Padding to tx_max allows the driver to transmit NTBs
back-to-back without any interleaving short USB
packets. This reduces the number of short packet
interrupts in the device, and represents a tradeoff
between USB bus bandwidth and device DMA optimization.
Set to 0 to pad all frames. Set greater than tx_max to
disable all padding.
What: /sys/class/net/<iface>/cdc_ncm/rx_max
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
The maximum NTB size for RX. Cannot exceed the
maximum value supported by the device. Must allow at
least one max sized datagram plus headers.
The actual limits are device dependent. See
dwNtbInMaxSize.
Note: Some devices will silently ignore changes to
this value, resulting in oversized NTBs and
corresponding framing errors.
What: /sys/class/net/<iface>/cdc_ncm/tx_max
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
The maximum NTB size for TX. Cannot exceed the
maximum value supported by the device. Must allow at
least one max sized datagram plus headers.
The actual limits are device dependent. See
dwNtbOutMaxSize.
What: /sys/class/net/<iface>/cdc_ncm/tx_timer_usecs
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
Datagram aggregation timeout in µs. The driver will
wait up to 3 times this timeout for more datagrams to
aggregate before transmitting an NTB frame.
Valid range: 5 to 4000000
Set to 0 to disable aggregation.
The following read-only attributes all represent fields of the
structure defined in section 6.2.1 "GetNtbParameters" of "Universal
Serial Bus Communications Class Subclass Specifications for Network
Control Model Devices" (CDC NCM), Revision 1.0 (Errata 1), November
24, 2010 from USB Implementers Forum, Inc. The descriptions are
quoted from table 6-3 of CDC NCM: "NTB Parameter Structure".
What: /sys/class/net/<iface>/cdc_ncm/bmNtbFormatsSupported
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
Bit 0: 16-bit NTB supported (set to 1)
Bit 1: 32-bit NTB supported
Bits 2 – 15: reserved (reset to zero; must be ignored by host)
What: /sys/class/net/<iface>/cdc_ncm/dwNtbInMaxSize
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
IN NTB Maximum Size in bytes
What: /sys/class/net/<iface>/cdc_ncm/wNdpInDivisor
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
Divisor used for IN NTB Datagram payload alignment
What: /sys/class/net/<iface>/cdc_ncm/wNdpInPayloadRemainder
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
Remainder used to align input datagram payload within
the NTB: (Payload Offset) mod (wNdpInDivisor) =
wNdpInPayloadRemainder
What: /sys/class/net/<iface>/cdc_ncm/wNdpInAlignment
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
NDP alignment modulus for NTBs on the IN pipe. Shall
be a power of 2, and shall be at least 4.
What: /sys/class/net/<iface>/cdc_ncm/dwNtbOutMaxSize
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
OUT NTB Maximum Size
What: /sys/class/net/<iface>/cdc_ncm/wNdpOutDivisor
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
OUT NTB Datagram alignment modulus
What: /sys/class/net/<iface>/cdc_ncm/wNdpOutPayloadRemainder
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
Remainder used to align output datagram payload
offsets within the NTB: Padding, shall be transmitted
as zero by function, and ignored by host. (Payload
Offset) mod (wNdpOutDivisor) = wNdpOutPayloadRemainder
What: /sys/class/net/<iface>/cdc_ncm/wNdpOutAlignment
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
NDP alignment modulus for use in NTBs on the OUT
pipe. Shall be a power of 2, and shall be at least 4.
What: /sys/class/net/<iface>/cdc_ncm/wNtbOutMaxDatagrams
Date: May 2014
KernelVersion: 3.16
Contact: Bjørn Mork <bjorn@mork.no>
Description:
Maximum number of datagrams that the host may pack
into a single OUT NTB. Zero means that the device
imposes no limit.

79
Documentation/ABI/testing/sysfs-class-net-queues 100644
View File

@ -0,0 +1,79 @@
What: /sys/class/<iface>/queues/rx-<queue>/rps_cpus
Date: March 2010
KernelVersion: 2.6.35
Contact: netdev@vger.kernel.org
Description:
Mask of the CPU(s) currently enabled to participate into the
Receive Packet Steering packet processing flow for this
network device queue. Possible values depend on the number
of available CPU(s) in the system.
What: /sys/class/<iface>/queues/rx-<queue>/rps_flow_cnt
Date: April 2010
KernelVersion: 2.6.35
Contact: netdev@vger.kernel.org
Description:
Number of Receive Packet Steering flows being currently
processed by this particular network device receive queue.
What: /sys/class/<iface>/queues/tx-<queue>/tx_timeout
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
Description:
Indicates the number of transmit timeout events seen by this
network interface transmit queue.
What: /sys/class/<iface>/queues/tx-<queue>/xps_cpus
Date: November 2010
KernelVersion: 2.6.38
Contact: netdev@vger.kernel.org
Description:
Mask of the CPU(s) currently enabled to participate into the
Transmit Packet Steering packet processing flow for this
network device transmit queue. Possible vaules depend on the
number of available CPU(s) in the system.
What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/hold_time
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
Description:
Indicates the hold time in milliseconds to measure the slack
of this particular network device transmit queue.
Default value is 1000.
What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/inflight
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
Description:
Indicates the number of bytes (objects) in flight on this
network device transmit queue.
What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
Description:
Indicates the current limit of bytes allowed to be queued
on this network device transmit queue. This value is clamped
to be within the bounds defined by limit_max and limit_min.
What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit_max
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
Description:
Indicates the absolute maximum limit of bytes allowed to be
queued on this network device transmit queue. See
include/linux/dynamic_queue_limits.h for the default value.
What: /sys/class/<iface>/queues/tx-<queue>/byte_queue_limits/limit_min
Date: November 2011
KernelVersion: 3.3
Contact: netdev@vger.kernel.org
Description:
Indicates the absolute minimum limit of bytes allowed to be
queued on this network device transmit queue. Default value is
0.

201
Documentation/ABI/testing/sysfs-class-net-statistics 100644
View File

@ -0,0 +1,201 @@
What: /sys/class/<iface>/statistics/collisions
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of collisions seen by this network device.
This value might not be relevant with all MAC layers.
What: /sys/class/<iface>/statistics/multicast
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of multicast packets received by this
network device.
What: /sys/class/<iface>/statistics/rx_bytes
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of bytes received by this network device.
See the network driver for the exact meaning of when this
value is incremented.
What: /sys/class/<iface>/statistics/rx_compressed
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of compressed packets received by this
network device. This value might only be relevant for interfaces
that support packet compression (e.g: PPP).
What: /sys/class/<iface>/statistics/rx_crc_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets received with a CRC (FCS) error
by this network device. Note that the specific meaning might
depend on the MAC layer used by the interface.
What: /sys/class/<iface>/statistics/rx_dropped
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets received by the network device
but dropped, that are not forwarded to the upper layers for
packet processing. See the network driver for the exact
meaning of this value.
What: /sys/class/<iface>/statistics/rx_fifo_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of receive FIFO errors seen by this
network device. See the network driver for the exact
meaning of this value.
What: /sys/class/<iface>/statistics/rx_frame_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of received frames with error, such as
alignment errors. Note that the specific meaning depends on
on the MAC layer protocol used. See the network driver for
the exact meaning of this value.
What: /sys/class/<iface>/statistics/rx_length_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of received error packet with a length
error, oversized or undersized. See the network driver for the
exact meaning of this value.
What: /sys/class/<iface>/statistics/rx_missed_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of received packets that have been missed
due to lack of capacity in the receive side. See the network
driver for the exact meaning of this value.
What: /sys/class/<iface>/statistics/rx_over_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of received packets that are oversized
compared to what the network device is configured to accept
(e.g: larger than MTU). See the network driver for the exact
meaning of this value.
What: /sys/class/<iface>/statistics/rx_packets
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the total number of good packets received by this
network device.
What: /sys/class/<iface>/statistics/tx_aborted_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets that have been aborted
during transmission by a network device (e.g: because of
a medium collision). See the network driver for the exact
meaning of this value.
What: /sys/class/<iface>/statistics/tx_bytes
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of bytes transmitted by a network
device. See the network driver for the exact meaning of this
value, in particular whether this accounts for all successfully
transmitted packets or all packets that have been queued for
transmission.
What: /sys/class/<iface>/statistics/tx_carrier_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets that could not be transmitted
because of carrier errors (e.g: physical link down). See the
network driver for the exact meaning of this value.
What: /sys/class/<iface>/statistics/tx_compressed
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of transmitted compressed packets. Note
this might only be relevant for devices that support
compression (e.g: PPP).
What: /sys/class/<iface>/statistics/tx_dropped
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets dropped during transmission.
See the driver for the exact reasons as to why the packets were
dropped.
What: /sys/class/<iface>/statistics/tx_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets in error during transmission by
a network device. See the driver for the exact reasons as to
why the packets were dropped.
What: /sys/class/<iface>/statistics/tx_fifo_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets having caused a transmit
FIFO error. See the driver for the exact reasons as to why the
packets were dropped.
What: /sys/class/<iface>/statistics/tx_heartbeat_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets transmitted that have been
reported as heartbeat errors. See the driver for the exact
reasons as to why the packets were dropped.
What: /sys/class/<iface>/statistics/tx_packets
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets transmitted by a network
device. See the driver for whether this reports the number of all
attempted or successful transmissions.
What: /sys/class/<iface>/statistics/tx_window_errors
Date: April 2005
KernelVersion: 2.6.12
Contact: netdev@vger.kernel.org
Description:
Indicates the number of packets not successfully transmitted
due to a window collision. The specific meaning depends on the
MAC layer used. On Ethernet this is usually used to report
late collisions errors.

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 100644
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 100644
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

14
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
================
@ -275,12 +280,9 @@ that is possible.
mcelog
------
In Linux 2.6.31+ the i386 kernel needs to run the mcelog utility
as a regular cronjob similar to the x86-64 kernel to process and log
machine check events when CONFIG_X86_NEW_MCE is enabled. Machine check
events are errors reported by the CPU. Processing them is strongly encouraged.
All x86-64 kernels since 2.6.4 require the mcelog utility to
process machine checks.
On x86 kernels the mcelog utility is needed to process and log machine check
events when CONFIG_X86_MCE is enabled. Machine check events are errors reported
by the CPU. Processing them is strongly encouraged.
Getting updated software
========================

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.

1
Documentation/DocBook/80211.tmpl
View File

@ -100,6 +100,7 @@
!Finclude/net/cfg80211.h wdev_priv
!Finclude/net/cfg80211.h ieee80211_iface_limit
!Finclude/net/cfg80211.h ieee80211_iface_combination
!Finclude/net/cfg80211.h cfg80211_check_combinations
</chapter>
<chapter>
<title>Actions and configuration</title>

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

1027
Documentation/DocBook/drm.tmpl
View File

File diff suppressed because it is too large Load Diff

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

2
Documentation/DocBook/gadget.tmpl
View File

@ -708,7 +708,7 @@ hardware level details could be very different.
<para>Systems need specialized hardware support to implement OTG,
notably including a special <emphasis>Mini-AB</emphasis> jack
and associated transciever to support <emphasis>Dual-Role</emphasis>
and associated transceiver to support <emphasis>Dual-Role</emphasis>
operation:
they can act either as a host, using the standard
Linux-USB host side driver stack,

4
Documentation/DocBook/genericirq.tmpl
View File

@ -182,7 +182,7 @@
<para>
Each interrupt is described by an interrupt descriptor structure
irq_desc. The interrupt is referenced by an 'unsigned int' numeric
value which selects the corresponding interrupt decription structure
value which selects the corresponding interrupt description structure
in the descriptor structures array.
The descriptor structure contains status information and pointers
to the interrupt flow method and the interrupt chip structure
@ -470,7 +470,7 @@ if (desc->irq_data.chip->irq_eoi)
<para>
To avoid copies of identical implementations of IRQ chips the
core provides a configurable generic interrupt chip
implementation. Developers should check carefuly whether the
implementation. Developers should check carefully whether the
generic chip fits their needs before implementing the same
functionality slightly differently themselves.
</para>

2
Documentation/DocBook/kernel-locking.tmpl
View File

@ -1760,7 +1760,7 @@ as it would be on UP.
</para>
<para>
There is a furthur optimization possible here: remember our original
There is a further optimization possible here: remember our original
cache code, where there were no reference counts and the caller simply
held the lock whenever using the object? This is still possible: if
you hold the lock, no one can delete the object, so you don't need to

6
Documentation/DocBook/libata.tmpl
View File

@ -677,7 +677,7 @@ and other resources, etc.
<listitem>
<para>
ATA_QCFLAG_ACTIVE is clared from qc->flags.
ATA_QCFLAG_ACTIVE is cleared from qc->flags.
</para>
</listitem>
@ -708,7 +708,7 @@ and other resources, etc.
<listitem>
<para>
qc->waiting is claread &amp; completed (in that order).
qc->waiting is cleared &amp; completed (in that order).
</para>
</listitem>
@ -1163,7 +1163,7 @@ and other resources, etc.
<para>
Once sense data is acquired, this type of errors can be
handled similary to other SCSI errors. Note that sense data
handled similarly to other SCSI errors. Note that sense data
may indicate ATA bus error (e.g. Sense Key 04h HARDWARE ERROR
&amp;&amp; ASC/ASCQ 47h/00h SCSI PARITY ERROR). In such
cases, the error should be considered as an ATA bus error and

4
Documentation/DocBook/media/Makefile
View File

@ -202,8 +202,8 @@ $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64
$(MEDIA_OBJ_DIR)/v4l2.xml: $(OBJIMGFILES)
@$($(quiet)gen_xml)
@(ln -sf $(MEDIA_SRC_DIR)/v4l/*xml $(MEDIA_OBJ_DIR)/)
@(ln -sf $(MEDIA_SRC_DIR)/dvb/*xml $(MEDIA_OBJ_DIR)/)
@(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/v4l/*xml $(MEDIA_OBJ_DIR)/)
@(ln -sf `cd $(MEDIA_SRC_DIR) && /bin/pwd`/dvb/*xml $(MEDIA_OBJ_DIR)/)
$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/uapi/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml
@$($(quiet)gen_xml)

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>

2
Documentation/DocBook/media_api.tmpl
View File

@ -68,7 +68,7 @@
several digital tv standards. While it is called as DVB API,
in fact it covers several different video standards including
DVB-T, DVB-S, DVB-C and ATSC. The API is currently being updated
to documment support also for DVB-S2, ISDB-T and ISDB-S.</para>
to document support also for DVB-S2, ISDB-T and ISDB-S.</para>
<para>The third part covers the Remote Controller API.</para>
<para>The fourth part covers the Media Controller API.</para>
<para>For additional information and for the latest development code,

30
Documentation/DocBook/mtdnand.tmpl
View File

@ -91,7 +91,7 @@
<listitem><para>
[MTD Interface]</para><para>
These functions provide the interface to the MTD kernel API.
They are not replacable and provide functionality
They are not replaceable and provide functionality
which is complete hardware independent.
</para></listitem>
<listitem><para>
@ -100,14 +100,14 @@
</para></listitem>
<listitem><para>
[GENERIC]</para><para>
Generic functions are not replacable and provide functionality
Generic functions are not replaceable and provide functionality
which is complete hardware independent.
</para></listitem>
<listitem><para>
[DEFAULT]</para><para>
Default functions provide hardware related functionality which is suitable
for most of the implementations. These functions can be replaced by the
board driver if neccecary. Those functions are called via pointers in the
board driver if necessary. Those functions are called via pointers in the
NAND chip description structure. The board driver can set the functions which
should be replaced by board dependent functions before calling nand_scan().
If the function pointer is NULL on entry to nand_scan() then the pointer
@ -264,7 +264,7 @@ static void board_hwcontrol(struct mtd_info *mtd, int cmd)
is set up nand_scan() is called. This function tries to
detect and identify then chip. If a chip is found all the
internal data fields are initialized accordingly.
The structure(s) have to be zeroed out first and then filled with the neccecary
The structure(s) have to be zeroed out first and then filled with the necessary
information about the device.
</para>
<programlisting>
@ -327,7 +327,7 @@ module_init(board_init);
<sect1 id="Exit_function">
<title>Exit function</title>
<para>
The exit function is only neccecary if the driver is
The exit function is only necessary if the driver is
compiled as a module. It releases all resources which
are held by the chip driver and unregisters the partitions
in the MTD layer.
@ -494,7 +494,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip)
in this case. See rts_from4.c and diskonchip.c for
implementation reference. In those cases we must also
use bad block tables on FLASH, because the ECC layout is
interferring with the bad block marker positions.
interfering with the bad block marker positions.
See bad block table support for details.
</para>
</sect2>
@ -542,7 +542,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip)
<para>
nand_scan() calls the function nand_default_bbt().
nand_default_bbt() selects appropriate default
bad block table desriptors depending on the chip information
bad block table descriptors depending on the chip information
which was retrieved by nand_scan().
</para>
<para>
@ -554,7 +554,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip)
<sect2 id="Flash_based_tables">
<title>Flash based tables</title>
<para>
It may be desired or neccecary to keep a bad block table in FLASH.
It may be desired or necessary to keep a bad block table in FLASH.
For AG-AND chips this is mandatory, as they have no factory marked
bad blocks. They have factory marked good blocks. The marker pattern
is erased when the block is erased to be reused. So in case of
@ -565,10 +565,10 @@ static void board_select_chip (struct mtd_info *mtd, int chip)
of the blocks.
</para>
<para>
The blocks in which the tables are stored are procteted against
The blocks in which the tables are stored are protected against
accidental access by marking them bad in the memory bad block
table. The bad block table management functions are allowed
to circumvernt this protection.
to circumvent this protection.
</para>
<para>
The simplest way to activate the FLASH based bad block table support
@ -592,7 +592,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip)
User defined tables are created by filling out a
nand_bbt_descr structure and storing the pointer in the
nand_chip structure member bbt_td before calling nand_scan().
If a mirror table is neccecary a second structure must be
If a mirror table is necessary a second structure must be
created and a pointer to this structure must be stored
in bbt_md inside the nand_chip structure. If the bbt_md
member is set to NULL then only the main table is used
@ -666,7 +666,7 @@ static void board_select_chip (struct mtd_info *mtd, int chip)
<para>
For automatic placement some blocks must be reserved for
bad block table storage. The number of reserved blocks is defined
in the maxblocks member of the babd block table description structure.
in the maxblocks member of the bad block table description structure.
Reserving 4 blocks for mirrored tables should be a reasonable number.
This also limits the number of blocks which are scanned for the bad
block table ident pattern.
@ -1068,11 +1068,11 @@ in this page</entry>
<chapter id="filesystems">
<title>Filesystem support</title>
<para>
The NAND driver provides all neccecary functions for a
The NAND driver provides all necessary functions for a
filesystem via the MTD interface.
</para>
<para>
Filesystems must be aware of the NAND pecularities and
Filesystems must be aware of the NAND peculiarities and
restrictions. One major restrictions of NAND Flash is, that you cannot
write as often as you want to a page. The consecutive writes to a page,
before erasing it again, are restricted to 1-3 writes, depending on the
@ -1222,7 +1222,7 @@ in this page</entry>
#define NAND_BBT_VERSION 0x00000100
/* Create a bbt if none axists */
#define NAND_BBT_CREATE 0x00000200
/* Write bbt if neccecary */
/* Write bbt if necessary */
#define NAND_BBT_WRITE 0x00001000
/* Read and write back block contents when writing bbt */
#define NAND_BBT_SAVECONTENT 0x00002000

2
Documentation/DocBook/regulator.tmpl
View File

@ -155,7 +155,7 @@
release regulators. Functions are
provided to <link linkend='API-regulator-enable'>enable</link>
and <link linkend='API-regulator-disable'>disable</link> the
reguator and to get and set the runtime parameters of the
regulator and to get and set the runtime parameters of the
regulator.
</para>
<para>

4
Documentation/DocBook/uio-howto.tmpl
View File

@ -766,10 +766,10 @@ framework to set up sysfs files for this region. Simply leave it alone.
<para>
The dynamic memory regions will be allocated when the UIO device file,
<varname>/dev/uioX</varname> is opened.
Simiar to static memory resources, the memory region information for
Similar to static memory resources, the memory region information for
dynamic regions is then visible via sysfs at
<varname>/sys/class/uio/uioX/maps/mapY/*</varname>.
The dynmaic memory regions will be freed when the UIO device file is
The dynamic memory regions will be freed when the UIO device file is
closed. When no processes are holding the device file open, the address
returned to userspace is ~0.
</para>

2
Documentation/DocBook/usb.tmpl
View File

@ -153,7 +153,7 @@
<listitem><para>The Linux USB API supports synchronous calls for
control and bulk messages.
It also supports asynchnous calls for all kinds of data transfer,
It also supports asynchronous calls for all kinds of data transfer,
using request structures called "URBs" (USB Request Blocks).
</para></listitem>

2
Documentation/DocBook/writing-an-alsa-driver.tmpl
View File

@ -5696,7 +5696,7 @@ struct _snd_pcm_runtime {
suspending the PCM operations via
<function>snd_pcm_suspend_all()</function> or
<function>snd_pcm_suspend()</function>. It means that the PCM
streams are already stoppped when the register snapshot is
streams are already stopped when the register snapshot is
taken. But, remember that you don't have to restart the PCM
stream in the resume callback. It'll be restarted via
trigger call with <constant>SNDRV_PCM_TRIGGER_RESUME</constant>

873
Documentation/DocBook/writing_musb_glue_layer.tmpl 100644
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>

2
Documentation/EDID/1024x768.S
View File

@ -36,7 +36,7 @@
#define DPI 72
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux XGA"
#define ESTABLISHED_TIMINGS_BITS 0x08 /* Bit 3 -> 1024x768 @60 Hz */
#define ESTABLISHED_TIMING2_BITS 0x08 /* Bit 3 -> 1024x768 @60 Hz */
#define HSYNC_POL 0
#define VSYNC_POL 0
#define CRC 0x55

2
Documentation/EDID/1280x1024.S
View File

@ -36,7 +36,7 @@
#define DPI 72
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux SXGA"
#define ESTABLISHED_TIMINGS_BITS 0x00 /* none */
/* No ESTABLISHED_TIMINGx_BITS */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0xa0

2
Documentation/EDID/1600x1200.S
View File

@ -36,7 +36,7 @@
#define DPI 72
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux UXGA"
#define ESTABLISHED_TIMINGS_BITS 0x00 /* none */
/* No ESTABLISHED_TIMINGx_BITS */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0x9d

2
Documentation/EDID/1680x1050.S
View File

@ -36,7 +36,7 @@
#define DPI 96
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux WSXGA"
#define ESTABLISHED_TIMINGS_BITS 0x00 /* none */
/* No ESTABLISHED_TIMINGx_BITS */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0x26

2
Documentation/EDID/1920x1080.S
View File

@ -36,7 +36,7 @@
#define DPI 96
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux FHD"
#define ESTABLISHED_TIMINGS_BITS 0x00 /* none */
/* No ESTABLISHED_TIMINGx_BITS */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0x05

41
Documentation/EDID/800x600.S 100644
View File

@ -0,0 +1,41 @@
/*
800x600.S: EDID data set for standard 800x600 60 Hz monitor
Copyright (C) 2011 Carsten Emde <C.Emde@osadl.org>
Copyright (C) 2014 Linaro Limited
This program 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.
This program 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.
*/
/* EDID */
#define VERSION 1
#define REVISION 3
/* Display */
#define CLOCK 40000 /* kHz */
#define XPIX 800
#define YPIX 600
#define XY_RATIO XY_RATIO_4_3
#define XBLANK 256
#define YBLANK 28
#define XOFFSET 40
#define XPULSE 128
#define YOFFSET (63+1)
#define YPULSE (63+4)
#define DPI 72
#define VFREQ 60 /* Hz */
#define TIMING_NAME "Linux SVGA"
#define ESTABLISHED_TIMING1_BITS 0x01 /* Bit 0: 800x600 @ 60Hz */
#define HSYNC_POL 1
#define VSYNC_POL 1
#define CRC 0xc2
#include "edid.S"

2
Documentation/EDID/HOWTO.txt
View File

@ -18,7 +18,7 @@ CONFIG_DRM_LOAD_EDID_FIRMWARE was introduced. It allows to provide an
individually prepared or corrected EDID data set in the /lib/firmware
directory from where it is loaded via the firmware interface. The code
(see drivers/gpu/drm/drm_edid_load.c) contains built-in data sets for
commonly used screen resolutions (1024x768, 1280x1024, 1600x1200,
commonly used screen resolutions (800x600, 1024x768, 1280x1024, 1600x1200,
1680x1050, 1920x1080) as binary blobs, but the kernel source tree does
not contain code to create these data. In order to elucidate the origin
of the built-in binary EDID blobs and to facilitate the creation of

17
Documentation/EDID/edid.S
View File

@ -33,6 +33,17 @@
#define XY_RATIO_5_4 0b10
#define XY_RATIO_16_9 0b11
/* Provide defaults for the timing bits */
#ifndef ESTABLISHED_TIMING1_BITS
#define ESTABLISHED_TIMING1_BITS 0x00
#endif
#ifndef ESTABLISHED_TIMING2_BITS
#define ESTABLISHED_TIMING2_BITS 0x00
#endif
#ifndef ESTABLISHED_TIMING3_BITS
#define ESTABLISHED_TIMING3_BITS 0x00
#endif
#define mfgname2id(v1,v2,v3) \
((((v1-'@')&0x1f)<<10)+(((v2-'@')&0x1f)<<5)+((v3-'@')&0x1f))
#define swap16(v1) ((v1>>8)+((v1&0xff)<<8))
@ -139,7 +150,7 @@ white_x_y_msb: .byte 0x50,0x54
Bit 2 640x480 @ 75 Hz
Bit 1 800x600 @ 56 Hz
Bit 0 800x600 @ 60 Hz */
estbl_timing1: .byte 0x00
estbl_timing1: .byte ESTABLISHED_TIMING1_BITS
/* Bit 7 800x600 @ 72 Hz
Bit 6 800x600 @ 75 Hz
@ -149,11 +160,11 @@ estbl_timing1: .byte 0x00
Bit 2 1024x768 @ 72 Hz
Bit 1 1024x768 @ 75 Hz
Bit 0 1280x1024 @ 75 Hz */
estbl_timing2: .byte ESTABLISHED_TIMINGS_BITS
estbl_timing2: .byte ESTABLISHED_TIMING2_BITS
/* Bit 7 1152x870 @ 75 Hz (Apple Macintosh II)
Bits 6-0 Other manufacturer-specific display mod */
estbl_timing3: .byte 0x00
estbl_timing3: .byte ESTABLISHED_TIMING3_BITS
/* Standard timing */
/* X resolution, less 31, divided by 8 (256-2288 pixels) */

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 100644
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

1
Documentation/accounting/getdelays.c
View File

@ -314,6 +314,7 @@ int main(int argc, char *argv[])
break;
case 'm':
strncpy(cpumask, optarg, sizeof(cpumask));
cpumask[sizeof(cpumask) - 1] = '\0';
maskset = 1;
printf("cpumask %s maskset %d\n", cpumask, maskset);
break;

8
Documentation/acpi/enumeration.txt
View File

@ -60,12 +60,6 @@ If the driver needs to perform more complex initialization like getting and
configuring GPIOs it can get its ACPI handle and extract this information
from ACPI tables.
Currently the kernel is not able to automatically determine from which ACPI
device it should make the corresponding platform device so we need to add
the ACPI device explicitly to acpi_platform_device_ids list defined in
drivers/acpi/acpi_platform.c. This limitation is only for the platform
devices, SPI and I2C devices are created automatically as described below.
DMA support
~~~~~~~~~~~
DMA controllers enumerated via ACPI should be registered in the system to
@ -296,7 +290,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 100644
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 100644
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

27
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
@ -453,15 +458,11 @@ About use_hierarchy, see Section 6.
5.1 force_empty
memory.force_empty interface is provided to make cgroup's memory usage empty.
You can use this interface only when the cgroup has no tasks.
When writing anything to this
# echo 0 > memory.force_empty
Almost all pages tracked by this memory cgroup will be unmapped and freed.
Some pages cannot be freed because they are locked or in-use. Such pages are
moved to parent (if use_hierarchy==1) or root (if use_hierarchy==0) and this
cgroup will be empty.
the cgroup will be reclaimed and as many pages reclaimed as possible.
The typical use case for this interface is before calling rmdir().
Because rmdir() moves all pages to parent, some out-of-use page caches can be
@ -535,16 +536,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 +752,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.

359
Documentation/cgroups/unified-hierarchy.txt 100644
View File

@ -0,0 +1,359 @@
Cgroup unified hierarchy
April, 2014 Tejun Heo <tj@kernel.org>
This document describes the changes made by unified hierarchy and
their rationales. It will eventually be merged into the main cgroup
documentation.
CONTENTS
1. Background
2. Basic Operation
2-1. Mounting
2-2. cgroup.subtree_control
2-3. cgroup.controllers
3. Structural Constraints
3-1. Top-down
3-2. No internal tasks
4. Other Changes
4-1. [Un]populated Notification
4-2. Other Core Changes
4-3. Per-Controller Changes
4-3-1. blkio
4-3-2. cpuset
4-3-3. memory
5. Planned Changes
5-1. CAP for resource control
1. Background
cgroup allows an arbitrary number of hierarchies and each hierarchy
can host any number of controllers. While this seems to provide a
high level of flexibility, it isn't quite useful in practice.
For example, as there is only one instance of each controller, utility
type controllers such as freezer which can be useful in all
hierarchies can only be used in one. The issue is exacerbated by the
fact that controllers can't be moved around once hierarchies are
populated. Another issue is that all controllers bound to a hierarchy
are forced to have exactly the same view of the hierarchy. It isn't
possible to vary the granularity depending on the specific controller.
In practice, these issues heavily limit which controllers can be put
on the same hierarchy and most configurations resort to putting each
controller on its own hierarchy. Only closely related ones, such as
the cpu and cpuacct controllers, make sense to put on the same
hierarchy. This often means that userland ends up managing multiple
similar hierarchies repeating the same steps on each hierarchy
whenever a hierarchy management operation is necessary.
Unfortunately, support for multiple hierarchies comes at a steep cost.
Internal implementation in cgroup core proper is dazzlingly
complicated but more importantly the support for multiple hierarchies
restricts how cgroup is used in general and what controllers can do.
There's no limit on how many hierarchies there may be, which means
that a task's cgroup membership can't be described in finite length.
The key may contain any varying number of entries and is unlimited in
length, which makes it highly awkward to handle and leads to addition
of controllers which exist only to identify membership, which in turn
exacerbates the original problem.
Also, as a controller can't have any expectation regarding what shape
of hierarchies other controllers would be on, each controller has to
assume that all other controllers are operating on completely
orthogonal hierarchies. This makes it impossible, or at least very
cumbersome, for controllers to cooperate with each other.
In most use cases, putting controllers on hierarchies which are
completely orthogonal to each other isn't necessary. What usually is
called for is the ability to have differing levels of granularity
depending on the specific controller. In other words, hierarchy may
be collapsed from leaf towards root when viewed from specific
controllers. For example, a given configuration might not care about
how memory is distributed beyond a certain level while still wanting
to control how CPU cycles are distributed.
Unified hierarchy is the next version of cgroup interface. It aims to
address the aforementioned issues by having more structure while
retaining enough flexibility for most use cases. Various other
general and controller-specific interface issues are also addressed in
the process.
2. Basic Operation
2-1. Mounting
Currently, unified hierarchy can be mounted with the following mount
command. Note that this is still under development and scheduled to
change soon.
mount -t cgroup -o __DEVEL__sane_behavior cgroup $MOUNT_POINT
All controllers which are not bound to other hierarchies are
automatically bound to unified hierarchy and show up at the root of
it. Controllers which are enabled only in the root of unified
hierarchy can be bound to other hierarchies at any time. This allows
mixing unified hierarchy with the traditional multiple hierarchies in
a fully backward compatible way.
2-2. cgroup.subtree_control
All cgroups on unified hierarchy have a "cgroup.subtree_control" file
which governs which controllers are enabled on the children of the
cgroup. Let's assume a hierarchy like the following.
root - A - B - C
\ D
root's "cgroup.subtree_control" file determines which controllers are
enabled on A. A's on B. B's on C and D. This coincides with the
fact that controllers on the immediate sub-level are used to
distribute the resources of the parent. In fact, it's natural to
assume that resource control knobs of a child belong to its parent.
Enabling a controller in a "cgroup.subtree_control" file declares that
distribution of the respective resources of the cgroup will be
controlled. Note that this means that controller enable states are
shared among siblings.
When read, the file contains a space-separated list of currently
enabled controllers. A write to the file should contain a
space-separated list of controllers with '+' or '-' prefixed (without
the quotes). Controllers prefixed with '+' are enabled and '-'
disabled. If a controller is listed multiple times, the last entry
wins. The specific operations are executed atomically - either all
succeed or fail.
2-3. cgroup.controllers
Read-only "cgroup.controllers" file contains a space-separated list of
controllers which can be enabled in the cgroup's
"cgroup.subtree_control" file.
In the root cgroup, this lists controllers which are not bound to
other hierarchies and the content changes as controllers are bound to
and unbound from other hierarchies.
In non-root cgroups, the content of this file equals that of the
parent's "cgroup.subtree_control" file as only controllers enabled
from the parent can be used in its children.
3. Structural Constraints
3-1. Top-down
As it doesn't make sense to nest control of an uncontrolled resource,
all non-root "cgroup.subtree_control" files can only contain
controllers which are enabled in the parent's "cgroup.subtree_control"
file. A controller can be enabled only if the parent has the
controller enabled and a controller can't be disabled if one or more
children have it enabled.
3-2. No internal tasks
One long-standing issue that cgroup faces is the competition between
tasks belonging to the parent cgroup and its children cgroups. This
is inherently nasty as two different types of entities compete and
there is no agreed-upon obvious way to handle it. Different
controllers are doing different things.
The cpu controller considers tasks and cgroups as equivalents and maps
nice levels to cgroup weights. This works for some cases but falls
flat when children should be allocated specific ratios of CPU cycles
and the number of internal tasks fluctuates - the ratios constantly
change as the number of competing entities fluctuates. There also are
other issues. The mapping from nice level to weight isn't obvious or
universal, and there are various other knobs which simply aren't
available for tasks.
The blkio controller implicitly creates a hidden leaf node for each
cgroup to host the tasks. The hidden leaf has its own copies of all
the knobs with "leaf_" prefixed. While this allows equivalent control
over internal tasks, it's with serious drawbacks. It always adds an
extra layer of nesting which may not be necessary, makes the interface
messy and significantly complicates the implementation.
The memory controller currently doesn't have a way to control what
happens between internal tasks and child cgroups and the behavior is
not clearly defined. There have been attempts to add ad-hoc behaviors
and knobs to tailor the behavior to specific workloads. Continuing
this direction will lead to problems which will be extremely difficult
to resolve in the long term.
Multiple controllers struggle with internal tasks and came up with
different ways to deal with it; unfortunately, all the approaches in
use now are severely flawed and, furthermore, the widely different
behaviors make cgroup as whole highly inconsistent.
It is clear that this is something which needs to be addressed from
cgroup core proper in a uniform way so that controllers don't need to
worry about it and cgroup as a whole shows a consistent and logical
behavior. To achieve that, unified hierarchy enforces the following
structural constraint:
Except for the root, only cgroups which don't contain any task may
have controllers enabled in their "cgroup.subtree_control" files.
Combined with other properties, this guarantees that, when a
controller is looking at the part of the hierarchy which has it
enabled, tasks are always only on the leaves. This rules out
situations where child cgroups compete against internal tasks of the
parent.
There are two things to note. Firstly, the root cgroup is exempt from
the restriction. Root contains tasks and anonymous resource
consumption which can't be associated with any other cgroup and
requires special treatment from most controllers. How resource
consumption in the root cgroup is governed is up to each controller.
Secondly, the restriction doesn't take effect if there is no enabled
controller in the cgroup's "cgroup.subtree_control" file. This is
important as otherwise it wouldn't be possible to create children of a
populated cgroup. To control resource distribution of a cgroup, the
cgroup must create children and transfer all its tasks to the children
before enabling controllers in its "cgroup.subtree_control" file.
4. Other Changes
4-1. [Un]populated Notification
cgroup users often need a way to determine when a cgroup's
subhierarchy becomes empty so that it can be cleaned up. cgroup
currently provides release_agent for it; unfortunately, this mechanism
is riddled with issues.
- It delivers events by forking and execing a userland binary
specified as the release_agent. This is a long deprecated method of
notification delivery. It's extremely heavy, slow and cumbersome to
integrate with larger infrastructure.
- There is single monitoring point at the root. There's no way to
delegate management of a subtree.
- The event isn't recursive. It triggers when a cgroup doesn't have
any tasks or child cgroups. Events for internal nodes trigger only
after all children are removed. This again makes it impossible to
delegate management of a subtree.
- Events are filtered from the kernel side. A "notify_on_release"
file is used to subscribe to or suppress release events. This is
unnecessarily complicated and probably done this way because event
delivery itself was expensive.
Unified hierarchy implements an interface file "cgroup.populated"
which can be used to monitor whether the cgroup's subhierarchy has
tasks in it or not. Its value is 0 if there is no task in the cgroup
and its descendants; otherwise, 1. poll and [id]notify events are
triggered when the value changes.
This is significantly lighter and simpler and trivially allows
delegating management of subhierarchy - subhierarchy monitoring can
block further propagation simply by putting itself or another process
in the subhierarchy and monitor events that it's interested in from
there without interfering with monitoring higher in the tree.
In unified hierarchy, the release_agent mechanism is no longer
supported and the interface files "release_agent" and
"notify_on_release" do not exist.
4-2. Other Core Changes
- None of the mount options is allowed.
- remount is disallowed.
- rename(2) is disallowed.
- The "tasks" file is removed. Everything should at process
granularity. Use the "cgroup.procs" file instead.
- The "cgroup.procs" file is not sorted. pids will be unique unless
they got recycled in-between reads.
- The "cgroup.clone_children" file is removed.
4-3. Per-Controller Changes
4-3-1. blkio
- blk-throttle becomes properly hierarchical.
4-3-2. cpuset
- Tasks are kept in empty cpusets after hotplug and take on the masks
of the nearest non-empty ancestor, instead of being moved to it.
- A task can be moved into an empty cpuset, and again it takes on the
masks of the nearest non-empty ancestor.
4-3-3. memory
- use_hierarchy is on by default and the cgroup file for the flag is
not created.
5. Planned Changes
5-1. CAP for resource control
Unified hierarchy will require one of the capabilities(7), which is
yet to be decided, for all resource control related knobs. Process
organization operations - creation of sub-cgroups and migration of
processes in sub-hierarchies may be delegated by changing the
ownership and/or permissions on the cgroup directory and
"cgroup.procs" interface file; however, all operations which affect
resource control - writes to a "cgroup.subtree_control" file or any
controller-specific knobs - will require an explicit CAP privilege.
This, in part, is to prevent the cgroup interface from being
inadvertently promoted to programmable API used by non-privileged
binaries. cgroup exposes various aspects of the system in ways which
aren't properly abstracted for direct consumption by regular programs.
This is an administration interface much closer to sysctl knobs than
system calls. Even the basic access model, being filesystem path
based, isn't suitable for direct consumption. There's no way to
access "my cgroup" in a race-free way or make multiple operations
atomic against migration to another cgroup.
Another aspect is that, for better or for worse, the cgroup interface
goes through far less scrutiny than regular interfaces for
unprivileged userland. The upside is that cgroup is able to expose
useful features which may not be suitable for general consumption in a
reasonable time frame. It provides a relatively short path between
internal details and userland-visible interface. Of course, this
shortcut comes with high risk. We go through what we go through for
general kernel APIs for good reasons. It may end up leaking internal
details in a way which can exert significant pain by locking the
kernel into a contract that can't be maintained in a reasonable
manner.
Also, due to the specific nature, cgroup and its controllers don't
tend to attract attention from a wide scope of developers. cgroup's
short history is already fraught with severely mis-designed
interfaces, unnecessary commitments to and exposing of internal
details, broken and dangerous implementations of various features.
Keeping cgroup as an administration interface is both advantageous for
its role and imperative given its nature. Some of the cgroup features
may make sense for unprivileged access. If deemed justified, those
must be further abstracted and implemented as a different interface,
be it a system call or process-private filesystem, and survive through
the scrutiny that any interface for general consumption is required to
go through.
Requiring CAP is not a complete solution but should serve as a
significant deterrent against spraying cgroup usages in non-privileged
programs.

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

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

@ -26,6 +26,7 @@ Contents:
1.4 target/target_index or setpolicy?
1.5 target/target_index
1.6 setpolicy
1.7 get_intermediate and target_intermediate
2. Frequency Table Helpers
@ -79,6 +80,10 @@ cpufreq_driver.attr - A pointer to a NULL-terminated list of
"struct freq_attr" which allow to
export values to sysfs.
cpufreq_driver.get_intermediate
and target_intermediate Used to switch to stable frequency while
changing CPU frequency.
1.2 Per-CPU Initialization
--------------------------
@ -151,7 +156,7 @@ Some cpufreq-capable processors switch the frequency between certain
limits on their own. These shall use the ->setpolicy call
1.4. target/target_index
1.5. target/target_index
-------------
The target_index call has two arguments: struct cpufreq_policy *policy,
@ -160,6 +165,9 @@ and unsigned int index (into the exposed frequency table).
The CPUfreq driver must set the new frequency when called here. The
actual frequency must be determined by freq_table[index].frequency.
It should always restore to earlier frequency (i.e. policy->restore_freq) in
case of errors, even if we switched to intermediate frequency earlier.
Deprecated:
----------
The target call has three arguments: struct cpufreq_policy *policy,
@ -179,7 +187,7 @@ Here again the frequency table helper might assist you - see section 2
for details.
1.5 setpolicy
1.6 setpolicy
---------------
The setpolicy call only takes a struct cpufreq_policy *policy as
@ -190,6 +198,23 @@ setting when policy->policy is CPUFREQ_POLICY_PERFORMANCE, and a
powersaving-oriented setting when CPUFREQ_POLICY_POWERSAVE. Also check
the reference implementation in drivers/cpufreq/longrun.c
1.7 get_intermediate and target_intermediate
--------------------------------------------
Only for drivers with target_index() and CPUFREQ_ASYNC_NOTIFICATION unset.
get_intermediate should return a stable intermediate frequency platform wants to
switch to, and target_intermediate() should set CPU to to that frequency, before
jumping to the frequency corresponding to 'index'. Core will take care of
sending notifications and driver doesn't have to handle them in
target_intermediate() or target_index().
Drivers can return '0' from get_intermediate() in case they don't wish to switch
to intermediate frequency for some target frequency. In that case core will
directly call ->target_index().
NOTE: ->target_index() should restore to policy->restore_freq in case of
failures as core would send notifications for that.
2. Frequency Table Helpers
@ -228,3 +253,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

7
Documentation/cpu-freq/intel-pstate.txt
View File

@ -15,10 +15,13 @@ New sysfs files for controlling P state selection have been added to
/sys/devices/system/cpu/intel_pstate/
max_perf_pct: limits the maximum P state that will be requested by
the driver stated as a percentage of the available performance.
the driver stated as a percentage of the available performance. The
available (P states) performance may be reduced by the no_turbo
setting described below.
min_perf_pct: limits the minimum P state that will be requested by
the driver stated as a percentage of the available performance.
the driver stated as a percentage of the max (non-turbo)
performance level.
no_turbo: limits the driver to selecting P states below the turbo
frequency range.

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-38x.txt
View File

@ -6,5 +6,15 @@ following property:
Required root node property:
- compatible: must contain either "marvell,armada380" or
"marvell,armada385" depending on the variant of the SoC being used.
- compatible: must contain "marvell,armada380"
In addition, boards using the Marvell Armada 385 SoC shall have the
following property before the previous one:
Required root node property:
compatible: must contain "marvell,armada385"
Example:
compatible = "marvell,a385-rd", "marvell,armada385", "marvell,armada380";

14
Documentation/devicetree/bindings/arm/armada-cpu-reset.txt 100644
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 100644
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"

20
Documentation/devicetree/bindings/arm/exynos/power_domain.txt
View File

@ -9,6 +9,18 @@ Required Properties:
- reg: physical base address of the controller and length of memory mapped
region.
Optional Properties:
- clocks: List of clock handles. The parent clocks of the input clocks to the
devices in this power domain are set to oscclk before power gating
and restored back after powering on a domain. This is required for
all domains which are powered on and off and not required for unused
domains.
- clock-names: The following clocks can be specified:
- oscclk: Oscillator clock.
- pclkN, clkN: Pairs of parent of input clock and input clock to the
devices in this power domain. Maximum of 4 pairs (N = 0 to 3)
are supported currently.
Node of a device using power domains must have a samsung,power-domain property
defined with a phandle to respective power domain.
@ -19,6 +31,14 @@ Example:
reg = <0x10023C00 0x10>;
};
mfc_pd: power-domain@10044060 {
compatible = "samsung,exynos4210-pd";
reg = <0x10044060 0x20>;
clocks = <&clock CLK_FIN_PLL>, <&clock CLK_MOUT_SW_ACLK333>,
<&clock CLK_MOUT_USER_ACLK333>;
clock-names = "oscclk", "pclk0", "clk0";
};
Example of the node using power domain:
node {

38
Documentation/devicetree/bindings/arm/exynos/smp-sysram.txt 100644
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

3
Documentation/devicetree/bindings/arm/l2cc.txt
View File

@ -40,6 +40,9 @@ Optional properties:
- arm,filter-ranges : <start length> Starting address and length of window to
filter. Addresses in the filter window are directed to the M1 port. Other
addresses will go to the M0 port.
- arm,io-coherent : indicates that the system is operating in an hardware
I/O coherent mode. Valid only when the arm,pl310-cache compatible
string is used.
- interrupts : 1 combined interrupt.
- cache-id-part: cache id part number to be used if it is not present
on hardware

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 100644
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";

2
Documentation/devicetree/bindings/arm/samsung/exynos-adc.txt
View File

@ -48,7 +48,7 @@ adc@12D10000 {
/* NTC thermistor is a hwmon device */
ncp15wb473@0 {
compatible = "ntc,ncp15wb473";
compatible = "murata,ncp15wb473";
pullup-uv = <1800000>;
pullup-ohm = <47000>;
pulldown-ohm = <0>;

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 100644
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";

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