summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2017-05-04 19:07:10 -0700
committerLinus Torvalds <torvalds@linux-foundation.org>2017-05-04 19:15:35 -0700
commitaf82455f7dbd9dc20244d80d033721b30d22c065 (patch)
tree3b9246456e82ae116b57834a2f0b4a307a016474 /Documentation
parent0be75179df5e20306528800fc7c6a504b12b97db (diff)
parent2a76f89fa58c769241cfc21f2614705591519ae3 (diff)
Merge tag 'char-misc-4.12-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc
Pull char/misc driver updates from Greg KH: "Here is the big set of new char/misc driver drivers and features for 4.12-rc1. There's lots of new drivers added this time around, new firmware drivers from Google, more auxdisplay drivers, extcon drivers, fpga drivers, and a bunch of other driver updates. Nothing major, except if you happen to have the hardware for these drivers, and then you will be happy :) All of these have been in linux-next for a while with no reported issues" * tag 'char-misc-4.12-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/char-misc: (136 commits) firmware: google memconsole: Fix return value check in platform_memconsole_init() firmware: Google VPD: Fix return value check in vpd_platform_init() goldfish_pipe: fix build warning about using too much stack. goldfish_pipe: An implementation of more parallel pipe fpga fr br: update supported version numbers fpga: region: release FPGA region reference in error path fpga altera-hps2fpga: disable/unprepare clock on error in alt_fpga_bridge_probe() mei: drop the TODO from samples firmware: Google VPD sysfs driver firmware: Google VPD: import lib_vpd source files misc: lkdtm: Add volatile to intentional NULL pointer reference eeprom: idt_89hpesx: Add OF device ID table misc: ds1682: Add OF device ID table misc: tsl2550: Add OF device ID table w1: Remove unneeded use of assert() and remove w1_log.h w1: Use kernel common min() implementation uio_mf624: Align memory regions to page size and set correct offsets uio_mf624: Refactor memory info initialization uio: Allow handling of non page-aligned memory regions hangcheck-timer: Fix typo in comment ...
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/DocBook/rapidio.tmpl3
-rw-r--r--Documentation/devicetree/bindings/auxdisplay/hit,hd44780.txt45
-rw-r--r--Documentation/devicetree/bindings/firmware/coreboot.txt33
-rw-r--r--Documentation/devicetree/bindings/fpga/altera-pr-ip.txt12
-rw-r--r--Documentation/devicetree/bindings/fpga/fpga-region.txt1
-rw-r--r--Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt21
-rw-r--r--Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt44
-rw-r--r--Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt6
-rw-r--r--Documentation/devicetree/bindings/nvmem/imx-iim.txt22
-rw-r--r--Documentation/devicetree/bindings/nvmem/imx-ocotp.txt5
-rw-r--r--Documentation/driver-api/vme.rst363
-rw-r--r--Documentation/extcon/porting-android-switch-class123
-rw-r--r--Documentation/w1/slaves/00-INDEX4
-rw-r--r--Documentation/w1/slaves/w1_ds241350
-rw-r--r--Documentation/w1/slaves/w1_ds243863
15 files changed, 398 insertions, 397 deletions
diff --git a/Documentation/DocBook/rapidio.tmpl b/Documentation/DocBook/rapidio.tmpl
index 50479360d845..ac3cca3399a1 100644
--- a/Documentation/DocBook/rapidio.tmpl
+++ b/Documentation/DocBook/rapidio.tmpl
@@ -129,9 +129,6 @@
<sect1 id="Device_model_support"><title>Device model support</title>
!Idrivers/rapidio/rio-driver.c
</sect1>
- <sect1 id="Sysfs_support"><title>Sysfs support</title>
-!Idrivers/rapidio/rio-sysfs.c
- </sect1>
<sect1 id="PPC32_support"><title>PPC32 support</title>
!Iarch/powerpc/sysdev/fsl_rio.c
</sect1>
diff --git a/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.txt b/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.txt
new file mode 100644
index 000000000000..2aa24b889923
--- /dev/null
+++ b/Documentation/devicetree/bindings/auxdisplay/hit,hd44780.txt
@@ -0,0 +1,45 @@
+DT bindings for the Hitachi HD44780 Character LCD Controller
+
+The Hitachi HD44780 Character LCD Controller is commonly used on character LCDs
+that can display one or more lines of text. It exposes an M6800 bus interface,
+which can be used in either 4-bit or 8-bit mode.
+
+Required properties:
+ - compatible: Must contain "hit,hd44780",
+ - data-gpios: Must contain an array of either 4 or 8 GPIO specifiers,
+ referring to the GPIO pins connected to the data signal lines DB0-DB7
+ (8-bit mode) or DB4-DB7 (4-bit mode) of the LCD Controller's bus interface,
+ - enable-gpios: Must contain a GPIO specifier, referring to the GPIO pin
+ connected to the "E" (Enable) signal line of the LCD Controller's bus
+ interface,
+ - rs-gpios: Must contain a GPIO specifier, referring to the GPIO pin
+ connected to the "RS" (Register Select) signal line of the LCD Controller's
+ bus interface,
+ - display-height-chars: Height of the display, in character cells,
+ - display-width-chars: Width of the display, in character cells.
+
+Optional properties:
+ - rw-gpios: Must contain a GPIO specifier, referring to the GPIO pin
+ connected to the "RW" (Read/Write) signal line of the LCD Controller's bus
+ interface,
+ - backlight-gpios: Must contain a GPIO specifier, referring to the GPIO pin
+ used for enabling the LCD's backlight,
+ - internal-buffer-width: Internal buffer width (default is 40 for displays
+ with 1 or 2 lines, and display-width-chars for displays with more than 2
+ lines).
+
+Example:
+
+ auxdisplay {
+ compatible = "hit,hd44780";
+
+ data-gpios = <&hc595 0 GPIO_ACTIVE_HIGH>,
+ <&hc595 1 GPIO_ACTIVE_HIGH>,
+ <&hc595 2 GPIO_ACTIVE_HIGH>,
+ <&hc595 3 GPIO_ACTIVE_HIGH>;
+ enable-gpios = <&hc595 4 GPIO_ACTIVE_HIGH>;
+ rs-gpios = <&hc595 5 GPIO_ACTIVE_HIGH>;
+
+ display-height-chars = <2>;
+ display-width-chars = <16>;
+ };
diff --git a/Documentation/devicetree/bindings/firmware/coreboot.txt b/Documentation/devicetree/bindings/firmware/coreboot.txt
new file mode 100644
index 000000000000..4c955703cea8
--- /dev/null
+++ b/Documentation/devicetree/bindings/firmware/coreboot.txt
@@ -0,0 +1,33 @@
+COREBOOT firmware information
+
+The device tree node to communicate the location of coreboot's memory-resident
+bookkeeping structures to the kernel. Since coreboot itself cannot boot a
+device-tree-based kernel (yet), this node needs to be inserted by a
+second-stage bootloader (a coreboot "payload").
+
+Required properties:
+ - compatible: Should be "coreboot"
+ - reg: Address and length of the following two memory regions, in order:
+ 1.) The coreboot table. This is a list of variable-sized descriptors
+ that contain various compile- and run-time generated firmware
+ parameters. It is identified by the magic string "LBIO" in its first
+ four bytes.
+ See coreboot's src/commonlib/include/commonlib/coreboot_tables.h for
+ details.
+ 2.) The CBMEM area. This is a downward-growing memory region used by
+ coreboot to dynamically allocate data structures that remain resident.
+ It may or may not include the coreboot table as one of its members. It
+ is identified by a root node descriptor with the magic number
+ 0xc0389481 that resides in the topmost 8 bytes of the area.
+ See coreboot's src/include/imd.h for details.
+
+Example:
+ firmware {
+ ranges;
+
+ coreboot {
+ compatible = "coreboot";
+ reg = <0xfdfea000 0x264>,
+ <0xfdfea000 0x16000>;
+ }
+ };
diff --git a/Documentation/devicetree/bindings/fpga/altera-pr-ip.txt b/Documentation/devicetree/bindings/fpga/altera-pr-ip.txt
new file mode 100644
index 000000000000..52a294cf2730
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/altera-pr-ip.txt
@@ -0,0 +1,12 @@
+Altera Arria10 Partial Reconfiguration IP
+
+Required properties:
+- compatible : should contain "altr,a10-pr-ip"
+- reg : base address and size for memory mapped io.
+
+Example:
+
+ fpga_mgr: fpga-mgr@ff20c000 {
+ compatible = "altr,a10-pr-ip";
+ reg = <0xff20c000 0x10>;
+ };
diff --git a/Documentation/devicetree/bindings/fpga/fpga-region.txt b/Documentation/devicetree/bindings/fpga/fpga-region.txt
index 3b32ba15a717..81bf3adba24b 100644
--- a/Documentation/devicetree/bindings/fpga/fpga-region.txt
+++ b/Documentation/devicetree/bindings/fpga/fpga-region.txt
@@ -186,6 +186,7 @@ Optional properties:
otherwise full reconfiguration is done.
- external-fpga-config : boolean, set if the FPGA has already been configured
prior to OS boot up.
+- encrypted-fpga-config : boolean, set if the bitstream is encrypted
- region-unfreeze-timeout-us : The maximum time in microseconds to wait for
bridges to successfully become enabled after the region has been
programmed.
diff --git a/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt b/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt
new file mode 100644
index 000000000000..4dc412437b08
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/lattice-ice40-fpga-mgr.txt
@@ -0,0 +1,21 @@
+Lattice iCE40 FPGA Manager
+
+Required properties:
+- compatible: Should contain "lattice,ice40-fpga-mgr"
+- reg: SPI chip select
+- spi-max-frequency: Maximum SPI frequency (>=1000000, <=25000000)
+- cdone-gpios: GPIO input connected to CDONE pin
+- reset-gpios: Active-low GPIO output connected to CRESET_B pin. Note
+ that unless the GPIO is held low during startup, the
+ FPGA will enter Master SPI mode and drive SCK with a
+ clock signal potentially jamming other devices on the
+ bus until the firmware is loaded.
+
+Example:
+ fpga: fpga@0 {
+ compatible = "lattice,ice40-fpga-mgr";
+ reg = <0>;
+ spi-max-frequency = <1000000>;
+ cdone-gpios = <&gpio 24 GPIO_ACTIVE_HIGH>;
+ reset-gpios = <&gpio 22 GPIO_ACTIVE_LOW>;
+ };
diff --git a/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt
new file mode 100644
index 000000000000..9766f7472f51
--- /dev/null
+++ b/Documentation/devicetree/bindings/fpga/xilinx-slave-serial.txt
@@ -0,0 +1,44 @@
+Xilinx Slave Serial SPI FPGA Manager
+
+Xilinx Spartan-6 FPGAs support a method of loading the bitstream over
+what is referred to as "slave serial" interface.
+The slave serial link is not technically SPI, and might require extra
+circuits in order to play nicely with other SPI slaves on the same bus.
+
+See https://www.xilinx.com/support/documentation/user_guides/ug380.pdf
+
+Required properties:
+- compatible: should contain "xlnx,fpga-slave-serial"
+- reg: spi chip select of the FPGA
+- prog_b-gpios: config pin (referred to as PROGRAM_B in the manual)
+- done-gpios: config status pin (referred to as DONE in the manual)
+
+Example for full FPGA configuration:
+
+ fpga-region0 {
+ compatible = "fpga-region";
+ fpga-mgr = <&fpga_mgr_spi>;
+ #address-cells = <0x1>;
+ #size-cells = <0x1>;
+ };
+
+ spi1: spi@10680 {
+ compatible = "marvell,armada-xp-spi", "marvell,orion-spi";
+ pinctrl-0 = <&spi0_pins>;
+ pinctrl-names = "default";
+ #address-cells = <1>;
+ #size-cells = <0>;
+ cell-index = <1>;
+ interrupts = <92>;
+ clocks = <&coreclk 0>;
+ status = "okay";
+
+ fpga_mgr_spi: fpga-mgr@0 {
+ compatible = "xlnx,fpga-slave-serial";
+ spi-max-frequency = <60000000>;
+ spi-cpha;
+ reg = <0>;
+ done-gpios = <&gpio0 9 GPIO_ACTIVE_HIGH>;
+ prog_b-gpios = <&gpio0 29 GPIO_ACTIVE_LOW>;
+ };
+ };
diff --git a/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt b/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt
index d543ed3f5363..ef06d061913c 100644
--- a/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt
+++ b/Documentation/devicetree/bindings/nvmem/allwinner,sunxi-sid.txt
@@ -1,7 +1,11 @@
Allwinner sunxi-sid
Required properties:
-- compatible: "allwinner,sun4i-a10-sid" or "allwinner,sun7i-a20-sid"
+- compatible: Should be one of the following:
+ "allwinner,sun4i-a10-sid"
+ "allwinner,sun7i-a20-sid"
+ "allwinner,sun8i-h3-sid"
+
- reg: Should contain registers location and length
= Data cells =
diff --git a/Documentation/devicetree/bindings/nvmem/imx-iim.txt b/Documentation/devicetree/bindings/nvmem/imx-iim.txt
new file mode 100644
index 000000000000..1978c5bcd96d
--- /dev/null
+++ b/Documentation/devicetree/bindings/nvmem/imx-iim.txt
@@ -0,0 +1,22 @@
+Freescale i.MX IC Identification Module (IIM) device tree bindings
+
+This binding represents the IC Identification Module (IIM) found on
+i.MX25, i.MX27, i.MX31, i.MX35, i.MX51 and i.MX53 SoCs.
+
+Required properties:
+- compatible: should be one of
+ "fsl,imx25-iim", "fsl,imx27-iim",
+ "fsl,imx31-iim", "fsl,imx35-iim",
+ "fsl,imx51-iim", "fsl,imx53-iim",
+- reg: Should contain the register base and length.
+- interrupts: Should contain the interrupt for the IIM
+- clocks: Should contain a phandle pointing to the gated peripheral clock.
+
+Example:
+
+ iim: iim@63f98000 {
+ compatible = "fsl,imx53-iim", "fsl,imx27-iim";
+ reg = <0x63f98000 0x4000>;
+ interrupts = <69>;
+ clocks = <&clks IMX5_CLK_IIM_GATE>;
+ };
diff --git a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt
index 966a72ecc6bd..70d791b03ea1 100644
--- a/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt
+++ b/Documentation/devicetree/bindings/nvmem/imx-ocotp.txt
@@ -9,14 +9,19 @@ Required properties:
"fsl,imx6sl-ocotp" (i.MX6SL), or
"fsl,imx6sx-ocotp" (i.MX6SX),
"fsl,imx6ul-ocotp" (i.MX6UL),
+ "fsl,imx7d-ocotp" (i.MX7D/S),
followed by "syscon".
- reg: Should contain the register base and length.
- clocks: Should contain a phandle pointing to the gated peripheral clock.
+Optional properties:
+- read-only: disable write access
+
Example:
ocotp: ocotp@021bc000 {
compatible = "fsl,imx6q-ocotp", "syscon";
reg = <0x021bc000 0x4000>;
clocks = <&clks IMX6QDL_CLK_IIM>;
+ read-only;
};
diff --git a/Documentation/driver-api/vme.rst b/Documentation/driver-api/vme.rst
index 89776fb3c8bd..def139c13410 100644
--- a/Documentation/driver-api/vme.rst
+++ b/Documentation/driver-api/vme.rst
@@ -6,36 +6,15 @@ Driver registration
As with other subsystems within the Linux kernel, VME device drivers register
with the VME subsystem, typically called from the devices init routine. This is
-achieved via a call to the following function:
+achieved via a call to :c:func:`vme_register_driver`.
-.. code-block:: c
-
- int vme_register_driver (struct vme_driver *driver, unsigned int ndevs);
+A pointer to a structure of type :c:type:`struct vme_driver <vme_driver>` must
+be provided to the registration function. Along with the maximum number of
+devices your driver is able to support.
-If driver registration is successful this function returns zero, if an error
-occurred a negative error code will be returned.
-
-A pointer to a structure of type 'vme_driver' must be provided to the
-registration function. Along with ndevs, which is the number of devices your
-driver is able to support. The structure is as follows:
-
-.. code-block:: c
-
- struct vme_driver {
- struct list_head node;
- const char *name;
- int (*match)(struct vme_dev *);
- int (*probe)(struct vme_dev *);
- int (*remove)(struct vme_dev *);
- void (*shutdown)(void);
- struct device_driver driver;
- struct list_head devices;
- unsigned int ndev;
- };
-
-At the minimum, the '.name', '.match' and '.probe' elements of this structure
-should be correctly set. The '.name' element is a pointer to a string holding
-the device driver's name.
+At the minimum, the '.name', '.match' and '.probe' elements of
+:c:type:`struct vme_driver <vme_driver>` should be correctly set. The '.name'
+element is a pointer to a string holding the device driver's name.
The '.match' function allows control over which VME devices should be registered
with the driver. The match function should return 1 if a device should be
@@ -54,29 +33,16 @@ the number of devices probed to one:
}
The '.probe' element should contain a pointer to the probe routine. The
-probe routine is passed a 'struct vme_dev' pointer as an argument. The
-'struct vme_dev' structure looks like the following:
-
-.. code-block:: c
-
- struct vme_dev {
- int num;
- struct vme_bridge *bridge;
- struct device dev;
- struct list_head drv_list;
- struct list_head bridge_list;
- };
+probe routine is passed a :c:type:`struct vme_dev <vme_dev>` pointer as an
+argument.
Here, the 'num' field refers to the sequential device ID for this specific
driver. The bridge number (or bus number) can be accessed using
dev->bridge->num.
-A function is also provided to unregister the driver from the VME core and is
-usually called from the device driver's exit routine:
-
-.. code-block:: c
-
- void vme_unregister_driver (struct vme_driver *driver);
+A function is also provided to unregister the driver from the VME core called
+:c:func:`vme_unregister_driver` and should usually be called from the device
+driver's exit routine.
Resource management
@@ -90,47 +56,29 @@ driver is called. The probe routine is passed a pointer to the devices
device structure. This pointer should be saved, it will be required for
requesting VME resources.
-The driver can request ownership of one or more master windows, slave windows
-and/or dma channels. Rather than allowing the device driver to request a
-specific window or DMA channel (which may be used by a different driver) this
-driver allows a resource to be assigned based on the required attributes of the
-driver in question:
-
-.. code-block:: c
-
- struct vme_resource * vme_master_request(struct vme_dev *dev,
- u32 aspace, u32 cycle, u32 width);
-
- struct vme_resource * vme_slave_request(struct vme_dev *dev, u32 aspace,
- u32 cycle);
-
- struct vme_resource *vme_dma_request(struct vme_dev *dev, u32 route);
-
-For slave windows these attributes are split into the VME address spaces that
-need to be accessed in 'aspace' and VME bus cycle types required in 'cycle'.
-Master windows add a further set of attributes in 'width' specifying the
-required data transfer widths. These attributes are defined as bitmasks and as
-such any combination of the attributes can be requested for a single window,
-the core will assign a window that meets the requirements, returning a pointer
-of type vme_resource that should be used to identify the allocated resource
-when it is used. For DMA controllers, the request function requires the
-potential direction of any transfers to be provided in the route attributes.
-This is typically VME-to-MEM and/or MEM-to-VME, though some hardware can
-support VME-to-VME and MEM-to-MEM transfers as well as test pattern generation.
-If an unallocated window fitting the requirements can not be found a NULL
-pointer will be returned.
+The driver can request ownership of one or more master windows
+(:c:func:`vme_master_request`), slave windows (:c:func:`vme_slave_request`)
+and/or dma channels (:c:func:`vme_dma_request`). Rather than allowing the device
+driver to request a specific window or DMA channel (which may be used by a
+different driver) the API allows a resource to be assigned based on the required
+attributes of the driver in question. For slave windows these attributes are
+split into the VME address spaces that need to be accessed in 'aspace' and VME
+bus cycle types required in 'cycle'. Master windows add a further set of
+attributes in 'width' specifying the required data transfer widths. These
+attributes are defined as bitmasks and as such any combination of the
+attributes can be requested for a single window, the core will assign a window
+that meets the requirements, returning a pointer of type vme_resource that
+should be used to identify the allocated resource when it is used. For DMA
+controllers, the request function requires the potential direction of any
+transfers to be provided in the route attributes. This is typically VME-to-MEM
+and/or MEM-to-VME, though some hardware can support VME-to-VME and MEM-to-MEM
+transfers as well as test pattern generation. If an unallocated window fitting
+the requirements can not be found a NULL pointer will be returned.
Functions are also provided to free window allocations once they are no longer
-required. These functions should be passed the pointer to the resource provided
-during resource allocation:
-
-.. code-block:: c
-
- void vme_master_free(struct vme_resource *res);
-
- void vme_slave_free(struct vme_resource *res);
-
- void vme_dma_free(struct vme_resource *res);
+required. These functions (:c:func:`vme_master_free`, :c:func:`vme_slave_free`
+and :c:func:`vme_dma_free`) should be passed the pointer to the resource
+provided during resource allocation.
Master windows
@@ -144,61 +92,22 @@ the underlying chipset. A window must be configured before it can be used.
Master window configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Once a master window has been assigned the following functions can be used to
-configure it and retrieve the current settings:
-
-.. code-block:: c
-
- int vme_master_set (struct vme_resource *res, int enabled,
- unsigned long long base, unsigned long long size, u32 aspace,
- u32 cycle, u32 width);
-
- int vme_master_get (struct vme_resource *res, int *enabled,
- unsigned long long *base, unsigned long long *size, u32 *aspace,
- u32 *cycle, u32 *width);
-
-The address spaces, transfer widths and cycle types are the same as described
+Once a master window has been assigned :c:func:`vme_master_set` can be used to
+configure it and :c:func:`vme_master_get` to retrieve the current settings. The
+address spaces, transfer widths and cycle types are the same as described
under resource management, however some of the options are mutually exclusive.
For example, only one address space may be specified.
-These functions return 0 on success or an error code should the call fail.
-
Master window access
~~~~~~~~~~~~~~~~~~~~
-The following functions can be used to read from and write to configured master
-windows. These functions return the number of bytes copied:
-
-.. code-block:: c
-
- ssize_t vme_master_read(struct vme_resource *res, void *buf,
- size_t count, loff_t offset);
-
- ssize_t vme_master_write(struct vme_resource *res, void *buf,
- size_t count, loff_t offset);
-
-In addition to simple reads and writes, a function is provided to do a
-read-modify-write transaction. This function returns the original value of the
-VME bus location :
-
-.. code-block:: c
-
- unsigned int vme_master_rmw (struct vme_resource *res,
- unsigned int mask, unsigned int compare, unsigned int swap,
- loff_t offset);
-
-This functions by reading the offset, applying the mask. If the bits selected in
-the mask match with the values of the corresponding bits in the compare field,
-the value of swap is written the specified offset.
-
-Parts of a VME window can be mapped into user space memory using the following
-function:
+The function :c:func:`vme_master_read` can be used to read from and
+:c:func:`vme_master_write` used to write to configured master windows.
-.. code-block:: c
-
- int vme_master_mmap(struct vme_resource *resource,
- struct vm_area_struct *vma)
+In addition to simple reads and writes, :c:func:`vme_master_rmw` is provided to
+do a read-modify-write transaction. Parts of a VME window can also be mapped
+into user space memory using :c:func:`vme_master_mmap`.
Slave windows
@@ -213,41 +122,23 @@ it can be used.
Slave window configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~
-Once a slave window has been assigned the following functions can be used to
-configure it and retrieve the current settings:
-
-.. code-block:: c
-
- int vme_slave_set (struct vme_resource *res, int enabled,
- unsigned long long base, unsigned long long size,
- dma_addr_t mem, u32 aspace, u32 cycle);
-
- int vme_slave_get (struct vme_resource *res, int *enabled,
- unsigned long long *base, unsigned long long *size,
- dma_addr_t *mem, u32 *aspace, u32 *cycle);
+Once a slave window has been assigned :c:func:`vme_slave_set` can be used to
+configure it and :c:func:`vme_slave_get` to retrieve the current settings.
The address spaces, transfer widths and cycle types are the same as described
under resource management, however some of the options are mutually exclusive.
For example, only one address space may be specified.
-These functions return 0 on success or an error code should the call fail.
-
Slave window buffer allocation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Functions are provided to allow the user to allocate and free a contiguous
-buffers which will be accessible by the VME bridge. These functions do not have
-to be used, other methods can be used to allocate a buffer, though care must be
-taken to ensure that they are contiguous and accessible by the VME bridge:
-
-.. code-block:: c
-
- void * vme_alloc_consistent(struct vme_resource *res, size_t size,
- dma_addr_t *mem);
-
- void vme_free_consistent(struct vme_resource *res, size_t size,
- void *virt, dma_addr_t mem);
+Functions are provided to allow the user to allocate
+(:c:func:`vme_alloc_consistent`) and free (:c:func:`vme_free_consistent`)
+contiguous buffers which will be accessible by the VME bridge. These functions
+do not have to be used, other methods can be used to allocate a buffer, though
+care must be taken to ensure that they are contiguous and accessible by the VME
+bridge.
Slave window access
@@ -269,29 +160,18 @@ executed, reused and destroyed.
List Management
~~~~~~~~~~~~~~~
-The following functions are provided to create and destroy DMA lists. Execution
-of a list will not automatically destroy the list, thus enabling a list to be
-reused for repetitive tasks:
-
-.. code-block:: c
-
- struct vme_dma_list *vme_new_dma_list(struct vme_resource *res);
-
- int vme_dma_list_free(struct vme_dma_list *list);
+The function :c:func:`vme_new_dma_list` is provided to create and
+:c:func:`vme_dma_list_free` to destroy DMA lists. Execution of a list will not
+automatically destroy the list, thus enabling a list to be reused for repetitive
+tasks.
List Population
~~~~~~~~~~~~~~~
-An item can be added to a list using the following function ( the source and
+An item can be added to a list using :c:func:`vme_dma_list_add` (the source and
destination attributes need to be created before calling this function, this is
-covered under "Transfer Attributes"):
-
-.. code-block:: c
-
- int vme_dma_list_add(struct vme_dma_list *list,
- struct vme_dma_attr *src, struct vme_dma_attr *dest,
- size_t count);
+covered under "Transfer Attributes").
.. note::
@@ -310,41 +190,19 @@ an item to a list. This is due to the diverse attributes required for each type
of source and destination. There are functions to create attributes for PCI, VME
and pattern sources and destinations (where appropriate):
-Pattern source:
-
-.. code-block:: c
-
- struct vme_dma_attr *vme_dma_pattern_attribute(u32 pattern, u32 type);
-
-PCI source or destination:
-
-.. code-block:: c
-
- struct vme_dma_attr *vme_dma_pci_attribute(dma_addr_t mem);
-
-VME source or destination:
+ - PCI source or destination: :c:func:`vme_dma_pci_attribute`
+ - VME source or destination: :c:func:`vme_dma_vme_attribute`
+ - Pattern source: :c:func:`vme_dma_pattern_attribute`
-.. code-block:: c
-
- struct vme_dma_attr *vme_dma_vme_attribute(unsigned long long base,
- u32 aspace, u32 cycle, u32 width);
-
-The following function should be used to free an attribute:
-
-.. code-block:: c
-
- void vme_dma_free_attribute(struct vme_dma_attr *attr);
+The function :c:func:`vme_dma_free_attribute` should be used to free an
+attribute.
List Execution
~~~~~~~~~~~~~~
-The following function queues a list for execution. The function will return
-once the list has been executed:
-
-.. code-block:: c
-
- int vme_dma_list_exec(struct vme_dma_list *list);
+The function :c:func:`vme_dma_list_exec` queues a list for execution and will
+return once the list has been executed.
Interrupts
@@ -358,20 +216,13 @@ specific VME level and status IDs.
Attaching Interrupt Handlers
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The following functions can be used to attach and free a specific VME level and
-status ID combination. Any given combination can only be assigned a single
-callback function. A void pointer parameter is provided, the value of which is
-passed to the callback function, the use of this pointer is user undefined:
-
-.. code-block:: c
-
- int vme_irq_request(struct vme_dev *dev, int level, int statid,
- void (*callback)(int, int, void *), void *priv);
-
- void vme_irq_free(struct vme_dev *dev, int level, int statid);
-
-The callback parameters are as follows. Care must be taken in writing a callback
-function, callback functions run in interrupt context:
+The function :c:func:`vme_irq_request` can be used to attach and
+:c:func:`vme_irq_free` to free a specific VME level and status ID combination.
+Any given combination can only be assigned a single callback function. A void
+pointer parameter is provided, the value of which is passed to the callback
+function, the use of this pointer is user undefined. The callback parameters are
+as follows. Care must be taken in writing a callback function, callback
+functions run in interrupt context:
.. code-block:: c
@@ -381,12 +232,8 @@ function, callback functions run in interrupt context:
Interrupt Generation
~~~~~~~~~~~~~~~~~~~~
-The following function can be used to generate a VME interrupt at a given VME
-level and VME status ID:
-
-.. code-block:: c
-
- int vme_irq_generate(struct vme_dev *dev, int level, int statid);
+The function :c:func:`vme_irq_generate` can be used to generate a VME interrupt
+at a given VME level and VME status ID.
Location monitors
@@ -399,54 +246,29 @@ monitor.
Location Monitor Management
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The following functions are provided to request the use of a block of location
-monitors and to free them after they are no longer required:
-
-.. code-block:: c
-
- struct vme_resource * vme_lm_request(struct vme_dev *dev);
-
- void vme_lm_free(struct vme_resource * res);
-
-Each block may provide a number of location monitors, monitoring adjacent
-locations. The following function can be used to determine how many locations
-are provided:
-
-.. code-block:: c
-
- int vme_lm_count(struct vme_resource * res);
+The function :c:func:`vme_lm_request` is provided to request the use of a block
+of location monitors and :c:func:`vme_lm_free` to free them after they are no
+longer required. Each block may provide a number of location monitors,
+monitoring adjacent locations. The function :c:func:`vme_lm_count` can be used
+to determine how many locations are provided.
Location Monitor Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Once a bank of location monitors has been allocated, the following functions
-are provided to configure the location and mode of the location monitor:
-
-.. code-block:: c
-
- int vme_lm_set(struct vme_resource *res, unsigned long long base,
- u32 aspace, u32 cycle);
-
- int vme_lm_get(struct vme_resource *res, unsigned long long *base,
- u32 *aspace, u32 *cycle);
+Once a bank of location monitors has been allocated, the function
+:c:func:`vme_lm_set` is provided to configure the location and mode of the
+location monitor. The function :c:func:`vme_lm_get` can be used to retrieve
+existing settings.
Location Monitor Use
~~~~~~~~~~~~~~~~~~~~
-The following functions allow a callback to be attached and detached from each
-location monitor location. Each location monitor can monitor a number of
-adjacent locations:
-
-.. code-block:: c
-
- int vme_lm_attach(struct vme_resource *res, int num,
- void (*callback)(void *));
-
- int vme_lm_detach(struct vme_resource *res, int num);
-
-The callback function is declared as follows.
+The function :c:func:`vme_lm_attach` enables a callback to be attached and
+:c:func:`vme_lm_detach` allows on to be detached from each location monitor
+location. Each location monitor can monitor a number of adjacent locations. The
+callback function is declared as follows.
.. code-block:: c
@@ -456,19 +278,20 @@ The callback function is declared as follows.
Slot Detection
--------------
-This function returns the slot ID of the provided bridge.
-
-.. code-block:: c
-
- int vme_slot_num(struct vme_dev *dev);
+The function :c:func:`vme_slot_num` returns the slot ID of the provided bridge.
Bus Detection
-------------
-This function returns the bus ID of the provided bridge.
+The function :c:func:`vme_bus_num` returns the bus ID of the provided bridge.
-.. code-block:: c
- int vme_bus_num(struct vme_dev *dev);
+VME API
+-------
+
+.. kernel-doc:: include/linux/vme.h
+ :internal:
+.. kernel-doc:: drivers/vme/vme.c
+ :export:
diff --git a/Documentation/extcon/porting-android-switch-class b/Documentation/extcon/porting-android-switch-class
deleted file mode 100644
index 49c81caef84d..000000000000
--- a/Documentation/extcon/porting-android-switch-class
+++ /dev/null
@@ -1,123 +0,0 @@
-
- Staging/Android Switch Class Porting Guide
- (linux/drivers/staging/android/switch)
- (c) Copyright 2012 Samsung Electronics
-
-AUTHORS
-MyungJoo Ham <myungjoo.ham@samsung.com>
-
-/*****************************************************************
- * CHAPTER 1. *
- * PORTING SWITCH CLASS DEVICE DRIVERS *
- *****************************************************************/
-
-****** STEP 1. Basic Functionality
- No extcon extended feature, but switch features only.
-
-- struct switch_dev (fed to switch_dev_register/unregister)
- @name: no change
- @dev: no change
- @index: drop (not used in switch device driver side anyway)
- @state: no change
- If you have used @state with magic numbers, keep it
- at this step.
- @print_name: no change but type change (switch_dev->extcon_dev)
- @print_state: no change but type change (switch_dev->extcon_dev)
-
-- switch_dev_register(sdev, dev)
- => extcon_dev_register(edev)
- : type change (sdev->edev)
- : remove second param('dev'). if edev has parent device, should store
- 'dev' to 'edev.dev.parent' before registering extcon device
-- switch_dev_unregister(sdev)
- => extcon_dev_unregister(edev)
- : no change but type change (sdev->edev)
-- switch_get_state(sdev)
- => extcon_get_state(edev)
- : no change but type change (sdev->edev) and (return: int->u32)
-- switch_set_state(sdev, state)
- => extcon_set_state(edev, state)
- : no change but type change (sdev->edev) and (state: int->u32)
-
-With this changes, the ex-switch extcon class device works as it once
-worked as switch class device. However, it will now have additional
-interfaces (both ABI and in-kernel API) and different ABI locations.
-However, if CONFIG_ANDROID is enabled without CONFIG_ANDROID_SWITCH,
-/sys/class/switch/* will be symbolically linked to /sys/class/extcon/
-so that they are still compatible with legacy userspace processes.
-
-****** STEP 2. Multistate (no more magic numbers in state value)
- Extcon's extended features for switch device drivers with
- complex features usually required magic numbers in state
- value of switch_dev. With extcon, such magic numbers that
- support multiple cables are no more required or supported.
-
- 1. Define cable names at edev->supported_cable.
- 2. (Recommended) remove print_state callback.
- 3. Use extcon_get_cable_state_(edev, index) or
- extcon_get_cable_state(edev, cable_name) instead of
- extcon_get_state(edev) if you intend to get a state of a specific
- cable. Same for set_state. This way, you can remove the usage of
- magic numbers in state value.
- 4. Use extcon_update_state() if you are updating specific bits of
- the state value.
-
-Example: a switch device driver w/ magic numbers for two cables.
- "0x00": no cables connected.
- "0x01": cable 1 connected
- "0x02": cable 2 connected
- "0x03": cable 1 and 2 connected
- 1. edev->supported_cable = {"1", "2", NULL};
- 2. edev->print_state = NULL;
- 3. extcon_get_cable_state_(edev, 0) shows cable 1's state.
- extcon_get_cable_state(edev, "1") shows cable 1's state.
- extcon_set_cable_state_(edev, 1) sets cable 2's state.
- extcon_set_cable_state(edev, "2") sets cable 2's state
- 4. extcon_update_state(edev, 0x01, 0) sets the least bit's 0.
-
-****** STEP 3. Notify other device drivers
-
- You can notify others of the cable attach/detach events with
-notifier chains.
-
- At the side of other device drivers (the extcon device itself
-does not need to get notified of its own events), there are two
-methods to register notifier_block for cable events:
-(a) for a specific cable or (b) for every cable.
-
- (a) extcon_register_interest(obj, extcon_name, cable_name, nb)
- Example: want to get news of "MAX8997_MUIC"'s "USB" cable
-
- obj = kzalloc(sizeof(struct extcon_specific_cable_nb),
- GFP_KERNEL);
- nb->notifier_call = the_callback_to_handle_usb;
-
- extcon_register_intereset(obj, "MAX8997_MUIC", "USB", nb);
-
- (b) extcon_register_notifier(edev, nb)
- Call nb for any changes in edev.
-
- Please note that in order to properly behave with method (a),
-the extcon device driver should support multistate feature (STEP 2).
-
-****** STEP 4. Inter-cable relation (mutually exclusive)
-
- You can provide inter-cable mutually exclusiveness information
-for an extcon device. When cables A and B are declared to be mutually
-exclusive, the two cables cannot be in ATTACHED state simulteneously.
-
-
-/*****************************************************************
- * CHAPTER 2. *
- * PORTING USERSPACE w/ SWITCH CLASS DEVICE SUPPORT *
- *****************************************************************/
-
-****** ABI Location
-
- If "CONFIG_ANDROID" is enabled, /sys/class/switch/* are created
-as symbolic links to /sys/class/extcon/*.
-
- The two files of switch class, name and state, are provided with
-extcon, too. When the multistate support (STEP 2 of CHAPTER 1.) is
-not enabled or print_state callback is supplied, the output of
-state ABI is same with switch class.
diff --git a/Documentation/w1/slaves/00-INDEX b/Documentation/w1/slaves/00-INDEX
index 6e18c70c3474..8d76718e1ea2 100644
--- a/Documentation/w1/slaves/00-INDEX
+++ b/Documentation/w1/slaves/00-INDEX
@@ -2,7 +2,11 @@
- This file
w1_therm
- The Maxim/Dallas Semiconductor ds18*20 temperature sensor.
+w1_ds2413
+ - The Maxim/Dallas Semiconductor ds2413 dual channel addressable switch.
w1_ds2423
- The Maxim/Dallas Semiconductor ds2423 counter device.
+w1_ds2438
+ - The Maxim/Dallas Semiconductor ds2438 smart battery monitor.
w1_ds28e04
- The Maxim/Dallas Semiconductor ds28e04 eeprom.
diff --git a/Documentation/w1/slaves/w1_ds2413 b/Documentation/w1/slaves/w1_ds2413
new file mode 100644
index 000000000000..936263a8ccb4
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2413
@@ -0,0 +1,50 @@
+Kernel driver w1_ds2413
+=======================
+
+Supported chips:
+ * Maxim DS2413 1-Wire Dual Channel Addressable Switch
+
+supported family codes:
+ W1_FAMILY_DS2413 0x3A
+
+Author: Mariusz Bialonczyk <manio@skyboo.net>
+
+Description
+-----------
+
+The DS2413 chip has two open-drain outputs (PIO A and PIO B).
+Support is provided through the sysfs files "output" and "state".
+
+Reading state
+-------------
+The "state" file provides one-byte value which is in the same format as for
+the chip PIO_ACCESS_READ command (refer the datasheet for details):
+
+Bit 0: PIOA Pin State
+Bit 1: PIOA Output Latch State
+Bit 2: PIOB Pin State
+Bit 3: PIOB Output Latch State
+Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+
+This file is readonly.
+
+Writing output
+--------------
+You can set the PIO pins using the "output" file.
+It is writable, you can write one-byte value to this sysfs file.
+Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
+
+Bit 0: PIOA
+Bit 1: PIOB
+Bit 2-7: No matter (driver will set it to "1"s)
+
+
+The chip has some kind of basic protection against transmission errors.
+When reading the state, there is a four complement bits.
+The driver is checking this complement, and when it is wrong then it is
+returning I/O error.
+
+When writing output, the master must repeat the PIO Output Data byte in
+its inverted form and it is waiting for a confirmation.
+If the write is unsuccessful for three times, the write also returns
+I/O error.
diff --git a/Documentation/w1/slaves/w1_ds2438 b/Documentation/w1/slaves/w1_ds2438
new file mode 100644
index 000000000000..b99f3674c5b4
--- /dev/null
+++ b/Documentation/w1/slaves/w1_ds2438
@@ -0,0 +1,63 @@
+Kernel driver w1_ds2438
+=======================
+
+Supported chips:
+ * Maxim DS2438 Smart Battery Monitor
+
+supported family codes:
+ W1_FAMILY_DS2438 0x26
+
+Author: Mariusz Bialonczyk <manio@skyboo.net>
+
+Description
+-----------
+
+The DS2438 chip provides several functions that are desirable to carry in
+a battery pack. It also has a 40 bytes of nonvolatile EEPROM.
+Because the ability of temperature, current and voltage measurement, the chip
+is also often used in weather stations and applications such as: rain gauge,
+wind speed/direction measuring, humidity sensing, etc.
+
+Current support is provided through the following sysfs files (all files
+except "iad" are readonly):
+
+"iad"
+-----
+This file controls the 'Current A/D Control Bit' (IAD) in the
+Status/Configuration Register.
+Writing a zero value will clear the IAD bit and disables the current
+measurements.
+Writing value "1" is setting the IAD bit (enables the measurements).
+The IAD bit is enabled by default in the DS2438.
+
+When writing to sysfs file bits 2-7 are ignored, so it's safe to write ASCII.
+An I/O error is returned when there is a problem setting the new value.
+
+"page0"
+-------
+This file provides full 8 bytes of the chip Page 0 (00h).
+This page contains the most frequently accessed information of the DS2438.
+Internally when this file is read, the additional CRC byte is also obtained
+from the slave device. If it is correct, the 8 bytes page data are passed
+to userspace, otherwise an I/O error is returned.
+
+"temperature"
+-------------
+Opening and reading this file initiates the CONVERT_T (temperature conversion)
+command of the chip, afterwards the temperature is read from the device
+registers and provided as an ASCII decimal value.
+
+Important: The returned value has to be divided by 256 to get a real
+temperature in degrees Celsius.
+
+"vad", "vdd"
+------------
+Opening and reading this file initiates the CONVERT_V (voltage conversion)
+command of the chip.
+
+Depending on a sysfs filename a different input for the A/D will be selected:
+vad: general purpose A/D input (VAD)
+vdd: battery input (VDD)
+
+After the voltage conversion the value is returned as decimal ASCII.
+Note: The value is in mV, so to get a volts the value has to be divided by 10.