diff options
Diffstat (limited to 'Documentation')
300 files changed, 15293 insertions, 3017 deletions
diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 49c051380daf..f54273e2ac97 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -270,8 +270,6 @@ preempt-locking.txt - info on locking under a preemptive kernel. printk-formats.txt - how to get printk format specifiers right -prio_tree.txt - - info on radix-priority-search-tree use for indexing vmas. ramoops.txt - documentation of the ramoops oops/panic logging module. rbtree.txt diff --git a/Documentation/ABI/obsolete/proc-pid-oom_adj b/Documentation/ABI/obsolete/proc-pid-oom_adj deleted file mode 100644 index 9a3cb88ade47..000000000000 --- a/Documentation/ABI/obsolete/proc-pid-oom_adj +++ /dev/null @@ -1,22 +0,0 @@ -What: /proc/<pid>/oom_adj -When: August 2012 -Why: /proc/<pid>/oom_adj allows userspace to influence the oom killer's - badness heuristic used to determine which task to kill when the kernel - is out of memory. - - The badness heuristic has since been rewritten since the introduction of - this tunable such that its meaning is deprecated. The value was - implemented as a bitshift on a score generated by the badness() - function that did not have any precise units of measure. With the - rewrite, the score is given as a proportion of available memory to the - task allocating pages, so using a bitshift which grows the score - exponentially is, thus, impossible to tune with fine granularity. - - A much more powerful interface, /proc/<pid>/oom_score_adj, was - introduced with the oom killer rewrite that allows users to increase or - decrease the badness score linearly. This interface will replace - /proc/<pid>/oom_adj. - - A warning will be emitted to the kernel log if an application uses this - deprecated interface. After it is printed once, future warnings will be - suppressed until the kernel is rebooted. diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index 6cd6daefaaed..986946613542 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -12,11 +12,14 @@ Description: then closing the file. The new policy takes effect after the file ima/policy is closed. + IMA appraisal, if configured, uses these file measurements + for local measurement appraisal. + rule format: action [condition ...] - action: measure | dont_measure + action: measure | dont_measure | appraise | dont_appraise | audit condition:= base | lsm - base: [[func=] [mask=] [fsmagic=] [uid=]] + base: [[func=] [mask=] [fsmagic=] [uid=] [fowner]] lsm: [[subj_user=] [subj_role=] [subj_type=] [obj_user=] [obj_role=] [obj_type=]] @@ -24,36 +27,50 @@ Description: mask:= [MAY_READ] [MAY_WRITE] [MAY_APPEND] [MAY_EXEC] fsmagic:= hex value uid:= decimal value + fowner:=decimal value lsm: are LSM specific default policy: # PROC_SUPER_MAGIC dont_measure fsmagic=0x9fa0 + dont_appraise fsmagic=0x9fa0 # SYSFS_MAGIC dont_measure fsmagic=0x62656572 + dont_appraise fsmagic=0x62656572 # DEBUGFS_MAGIC dont_measure fsmagic=0x64626720 + dont_appraise fsmagic=0x64626720 # TMPFS_MAGIC dont_measure fsmagic=0x01021994 + dont_appraise fsmagic=0x01021994 + # RAMFS_MAGIC + dont_measure fsmagic=0x858458f6 + dont_appraise fsmagic=0x858458f6 # SECURITYFS_MAGIC dont_measure fsmagic=0x73636673 + dont_appraise fsmagic=0x73636673 measure func=BPRM_CHECK measure func=FILE_MMAP mask=MAY_EXEC measure func=FILE_CHECK mask=MAY_READ uid=0 + appraise fowner=0 The default policy measures all executables in bprm_check, all files mmapped executable in file_mmap, and all files - open for read by root in do_filp_open. + open for read by root in do_filp_open. The default appraisal + policy appraises all files owned by root. Examples of LSM specific definitions: SELinux: # SELINUX_MAGIC - dont_measure fsmagic=0xF97CFF8C + dont_measure fsmagic=0xf97cff8c + dont_appraise fsmagic=0xf97cff8c dont_measure obj_type=var_log_t + dont_appraise obj_type=var_log_t dont_measure obj_type=auditd_log_t + dont_appraise obj_type=auditd_log_t measure subj_user=system_u func=FILE_CHECK mask=MAY_READ measure subj_role=system_r func=FILE_CHECK mask=MAY_READ diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd index 3c17b62899f6..1cf2adf46b11 100644 --- a/Documentation/ABI/testing/sysfs-bus-rbd +++ b/Documentation/ABI/testing/sysfs-bus-rbd @@ -25,6 +25,10 @@ client_id The ceph unique client id that was assigned for this specific session. +features + + A hexadecimal encoding of the feature bits for this image. + major The block device major number. @@ -33,6 +37,11 @@ name The name of the rbd image. +image_id + + The unique id for the rbd image. (For rbd image format 1 + this is empty.) + pool The name of the storage pool where this rbd image resides. @@ -57,12 +66,6 @@ current_snap The current snapshot for which the device is mapped. -create_snap - - Create a snapshot: - - $ echo <snap-name> > /sys/bus/rbd/devices/<dev-id>/snap_create - snap_* A directory per each snapshot @@ -79,4 +82,7 @@ snap_size The size of the image when this snapshot was taken. +snap_features + + A hexadecimal encoding of the feature bits for this snapshot. diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index 5f75f8f7df34..b6fbe514a869 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -220,3 +220,10 @@ Description: If the device doesn't support LTM, the file will read "no". The file will be present for all speeds of USB devices, and will always read "no" for USB 1.1 and USB 2.0 devices. + +What: /sys/bus/usb/devices/.../(hub interface)/portX +Date: August 2012 +Contact: Lan Tianyu <tianyu.lan@intel.com> +Description: + The /sys/bus/usb/devices/.../(hub interface)/portX + is usb port device's sysfs directory. diff --git a/Documentation/ABI/testing/sysfs-class-extcon b/Documentation/ABI/testing/sysfs-class-extcon index 20ab361bd8c6..57a726232912 100644 --- a/Documentation/ABI/testing/sysfs-class-extcon +++ b/Documentation/ABI/testing/sysfs-class-extcon @@ -13,7 +13,7 @@ Description: accessory cables have such capability. For example, the 30-pin port of Nuri board (/arch/arm/mach-exynos) may have both HDMI and Charger attached, or analog audio, - video, and USB cables attached simulteneously. + video, and USB cables attached simultaneously. If there are cables mutually exclusive with each other, such binary relations may be expressed with extcon_dev's @@ -35,7 +35,7 @@ Description: The /sys/class/extcon/.../state shows and stores the cable attach/detach information of the corresponding extcon object. If the extcon object has an optional callback "show_state" - defined, the showing function is overriden with the optional + defined, the showing function is overridden with the optional callback. If the default callback for showing function is used, the @@ -46,19 +46,19 @@ Description: TA=1 EAR_JACK=0 # - In this example, the extcon device have USB_OTG and TA + In this example, the extcon device has USB_OTG and TA cables attached and HDMI and EAR_JACK cables detached. In order to update the state of an extcon device, enter a hex - state number starting with 0x. - echo 0xHEX > state + state number starting with 0x: + # echo 0xHEX > state - This updates the whole state of the extcon dev. + This updates the whole state of the extcon device. Inputs of all the methods are required to meet the - mutually_exclusive contidions if they exist. + mutually_exclusive conditions if they exist. It is recommended to use this "global" state interface if - you need to enter the value atomically. The later state + you need to set the value atomically. The later state interface associated with each cable cannot update multiple cable states of an extcon device simultaneously. @@ -73,7 +73,7 @@ What: /sys/class/extcon/.../cable.x/state Date: February 2012 Contact: MyungJoo Ham <myungjoo.ham@samsung.com> Description: - The /sys/class/extcon/.../cable.x/name shows and stores the + The /sys/class/extcon/.../cable.x/state shows and stores the state of cable "x" (integer between 0 and 31) of an extcon device. The state value is either 0 (detached) or 1 (attached). @@ -83,8 +83,8 @@ Date: December 2011 Contact: MyungJoo Ham <myungjoo.ham@samsung.com> Description: Shows the relations of mutually exclusiveness. For example, - if the mutually_exclusive array of extcon_dev is - {0x3, 0x5, 0xC, 0x0}, the, the output is: + if the mutually_exclusive array of extcon device is + {0x3, 0x5, 0xC, 0x0}, then the output is: # ls mutually_exclusive/ 0x3 0x5 diff --git a/Documentation/ABI/testing/sysfs-class-regulator b/Documentation/ABI/testing/sysfs-class-regulator index e091fa873792..bc578bc60628 100644 --- a/Documentation/ABI/testing/sysfs-class-regulator +++ b/Documentation/ABI/testing/sysfs-class-regulator @@ -349,3 +349,24 @@ Description: This will be one of the same strings reported by the "state" attribute. + +What: /sys/class/regulator/.../bypass +Date: September 2012 +KernelVersion: 3.7 +Contact: Mark Brown <broonie@opensource.wolfsonmicro.com> +Description: + Some regulator directories will contain a field called + bypass. This indicates if the device is in bypass mode. + + This will be one of the following strings: + + 'enabled' + 'disabled' + 'unknown' + + 'enabled' means the regulator is in bypass mode. + + 'disabled' means that the regulator is regulating. + + 'unknown' means software cannot determine the state, or + the reported state is invalid. diff --git a/Documentation/ABI/testing/sysfs-devices-firmware_node b/Documentation/ABI/testing/sysfs-devices-firmware_node new file mode 100644 index 000000000000..46badc9ea284 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-firmware_node @@ -0,0 +1,17 @@ +What: /sys/devices/.../firmware_node/ +Date: September 2012 +Contact: <> +Description: + The /sys/devices/.../firmware_node directory contains attributes + allowing the user space to check and modify some firmware + related properties of given device. + +What: /sys/devices/.../firmware_node/description +Date: September 2012 +Contact: Lance Ortiz <lance.ortiz@hp.com> +Description: + The /sys/devices/.../firmware/description attribute contains a string + that describes the device as provided by the _STR method in the ACPI + namespace. This attribute is read-only. If the device does not have + an _STR method associated with it in the ACPI namespace, this + attribute is not present. diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index 5dab36448b44..6943133afcb8 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -176,3 +176,14 @@ Description: Disable L3 cache indices All AMD processors with L3 caches provide this functionality. For details, see BKDGs at http://developer.amd.com/documentation/guides/Pages/default.aspx + + +What: /sys/devices/system/cpu/cpufreq/boost +Date: August 2012 +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> +Description: Processor frequency boosting control + + This switch controls the boost setting for the whole system. + Boosting allows the CPU and the firmware to run at a frequency + beyound it's nominal limit. + More details can be found in Documentation/cpu-freq/boost.txt diff --git a/Documentation/ABI/testing/sysfs-driver-ppi b/Documentation/ABI/testing/sysfs-driver-ppi new file mode 100644 index 000000000000..97a003ee058b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-ppi @@ -0,0 +1,70 @@ +What: /sys/devices/pnp0/<bus-num>/ppi/ +Date: August 2012 +Kernel Version: 3.6 +Contact: xiaoyan.zhang@intel.com +Description: + This folder includes the attributes related with PPI (Physical + Presence Interface). Only if TPM is supported by BIOS, this + folder makes sence. The folder path can be got by command + 'find /sys/ -name 'pcrs''. For the detail information of PPI, + please refer to the PPI specification from + http://www.trustedcomputinggroup.org/ + +What: /sys/devices/pnp0/<bus-num>/ppi/version +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows the version of the PPI supported by the + platform. + This file is readonly. + +What: /sys/devices/pnp0/<bus-num>/ppi/request +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows the request for an operation to be + executed in the pre-OS environment. It is the only input from + the OS to the pre-OS environment. The request should be an + integer value range from 1 to 160, and 0 means no request. + This file can be read and written. + +What: /sys/devices/pnp0/00:<bus-num>/ppi/response +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows the response to the most recent operation + request it acted upon. The format is "<request> <response num> + : <response description>". + This file is readonly. + +What: /sys/devices/pnp0/<bus-num>/ppi/transition_action +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows the platform-specific action that should + take place in order to transition to the BIOS for execution of + a requested operation. The format is "<action num>: <action + description>". + This file is readonly. + +What: /sys/devices/pnp0/<bus-num>/ppi/tcg_operations +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows whether it is allowed to request an + operation to be executed in the pre-OS environment by the BIOS + for the requests defined by TCG, i.e. requests from 1 to 22. + The format is "<request> <status num>: <status description>". + This attribute is only supported by PPI version 1.2+. + This file is readonly. + +What: /sys/devices/pnp0/<bus-num>/ppi/vs_operations +Date: August 2012 +Contact: xiaoyan.zhang@intel.com +Description: + This attribute shows whether it is allowed to request an + operation to be executed in the pre-OS environment by the BIOS + for the verdor specific requests, i.e. requests from 128 to + 255. The format is same with tcg_operations. This attribute + is also only supported by PPI version 1.2+. + This file is readonly. diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom index 8d55a83d6921..7fc781048b79 100644 --- a/Documentation/ABI/testing/sysfs-driver-wacom +++ b/Documentation/ABI/testing/sysfs-driver-wacom @@ -1,3 +1,16 @@ +WWhat: /sys/class/hidraw/hidraw*/device/oled*_img +Date: June 2012 +Contact: linux-bluetooth@vger.kernel.org +Description: + The /sys/class/hidraw/hidraw*/device/oled*_img files control + OLED mocro displays on Intuos4 Wireless tablet. Accepted image + has to contain 256 bytes (64x32 px 1 bit colour). The format + is the same as PBM image 62x32px without header (64 bits per + horizontal line, 32 lines). An example of setting OLED No. 0: + dd bs=256 count=1 if=img_file of=[path to oled0_img]/oled0_img + The attribute is read only and no local copy of the image is + stored. + What: /sys/class/hidraw/hidraw*/device/speed Date: April 2010 Kernel Version: 2.6.35 diff --git a/Documentation/ABI/testing/sysfs-fs-ext4 b/Documentation/ABI/testing/sysfs-fs-ext4 index f22ac0872ae8..c631253cf85c 100644 --- a/Documentation/ABI/testing/sysfs-fs-ext4 +++ b/Documentation/ABI/testing/sysfs-fs-ext4 @@ -96,3 +96,16 @@ Contact: "Theodore Ts'o" <tytso@mit.edu> Description: The maximum number of megabytes the writeback code will try to write out before move on to another inode. + +What: /sys/fs/ext4/<disk>/extent_max_zeroout_kb +Date: August 2012 +Contact: "Theodore Ts'o" <tytso@mit.edu> +Description: + The maximum number of kilobytes which will be zeroed + out in preference to creating a new uninitialized + extent when manipulating an inode's extent tree. Note + that using a larger value will increase the + variability of time necessary to complete a random + write operation (since a 4k random write might turn + into a much larger write due to the zeroout + operation). diff --git a/Documentation/ABI/testing/sysfs-ptp b/Documentation/ABI/testing/sysfs-ptp index d40d2b550502..05aeedf17794 100644 --- a/Documentation/ABI/testing/sysfs-ptp +++ b/Documentation/ABI/testing/sysfs-ptp @@ -19,7 +19,11 @@ Date: September 2010 Contact: Richard Cochran <richardcochran@gmail.com> Description: This file contains the name of the PTP hardware clock - as a human readable string. + as a human readable string. The purpose of this + attribute is to provide the user with a "friendly + name" and to help distinguish PHY based devices from + MAC based ones. The string does not necessarily have + to be any kind of unique id. What: /sys/class/ptp/ptpN/max_adjustment Date: September 2010 diff --git a/Documentation/ABI/testing/sysfs-tty b/Documentation/ABI/testing/sysfs-tty index b138b663bf54..0c430150d929 100644 --- a/Documentation/ABI/testing/sysfs-tty +++ b/Documentation/ABI/testing/sysfs-tty @@ -17,3 +17,12 @@ Description: device, like 'tty1'. The file supports poll() to detect virtual console switches. + +What: /sys/class/tty/ttyS0/uartclk +Date: Sep 2012 +Contact: Tomas Hlavacek <tmshlvck@gmail.com> +Description: + Shows the current uartclk value associated with the + UART port in serial_core, that is bound to TTY like ttyS0. + uartclk = 16 * baud_base + diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index cb9258b8fd35..495e5ba1634c 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -454,6 +454,16 @@ The preferred style for long (multi-line) comments is: * with beginning and ending almost-blank lines. */ +For files in net/ and drivers/net/ the preferred style for long (multi-line) +comments is a little different. + + /* The preferred comment style for files in net/ and drivers/net + * looks like this. + * + * It is nearly the same as the generally preferred comment style, + * but there is no initial almost-blank line. + */ + It's also important to comment data, whether they are basic types or derived types. To this end, use just one data declaration per line (no commas for multiple data declarations). This leaves you room for a small comment on each diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 196b8b9dba11..b0300529ab13 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -6,11 +6,36 @@ <bookinfo> <title>Linux DRM Developer's Guide</title> + <authorgroup> + <author> + <firstname>Jesse</firstname> + <surname>Barnes</surname> + <contrib>Initial version</contrib> + <affiliation> + <orgname>Intel Corporation</orgname> + <address> + <email>jesse.barnes@intel.com</email> + </address> + </affiliation> + </author> + <author> + <firstname>Laurent</firstname> + <surname>Pinchart</surname> + <contrib>Driver internals</contrib> + <affiliation> + <orgname>Ideas on board SPRL</orgname> + <address> + <email>laurent.pinchart@ideasonboard.com</email> + </address> + </affiliation> + </author> + </authorgroup> + <copyright> <year>2008-2009</year> - <holder> - Intel Corporation (Jesse Barnes <jesse.barnes@intel.com>) - </holder> + <year>2012</year> + <holder>Intel Corporation</holder> + <holder>Laurent Pinchart</holder> </copyright> <legalnotice> @@ -20,6 +45,17 @@ the kernel source COPYING file. </para> </legalnotice> + + <revhistory> + <!-- Put document revisions here, newest first. --> + <revision> + <revnumber>1.0</revnumber> + <date>2012-07-13</date> + <authorinitials>LP</authorinitials> + <revremark>Added extensive documentation about driver internals. + </revremark> + </revision> + </revhistory> </bookinfo> <toc></toc> @@ -72,342 +108,361 @@ submission & fencing, suspend/resume support, and DMA services. </para> - <para> - The core of every DRM driver is struct drm_driver. Drivers - typically statically initialize a drm_driver structure, - then pass it to drm_init() at load time. - </para> <!-- Internals: driver init --> <sect1> - <title>Driver initialization</title> - <para> - Before calling the DRM initialization routines, the driver must - first create and fill out a struct drm_driver structure. - </para> - <programlisting> - static struct drm_driver driver = { - /* Don't use MTRRs here; the Xserver or userspace app should - * deal with them for Intel hardware. - */ - .driver_features = - DRIVER_USE_AGP | DRIVER_REQUIRE_AGP | - DRIVER_HAVE_IRQ | DRIVER_IRQ_SHARED | DRIVER_MODESET, - .load = i915_driver_load, - .unload = i915_driver_unload, - .firstopen = i915_driver_firstopen, - .lastclose = i915_driver_lastclose, - .preclose = i915_driver_preclose, - .save = i915_save, - .restore = i915_restore, - .device_is_agp = i915_driver_device_is_agp, - .get_vblank_counter = i915_get_vblank_counter, - .enable_vblank = i915_enable_vblank, - .disable_vblank = i915_disable_vblank, - .irq_preinstall = i915_driver_irq_preinstall, - .irq_postinstall = i915_driver_irq_postinstall, - .irq_uninstall = i915_driver_irq_uninstall, - .irq_handler = i915_driver_irq_handler, - .reclaim_buffers = drm_core_reclaim_buffers, - .get_map_ofs = drm_core_get_map_ofs, - .get_reg_ofs = drm_core_get_reg_ofs, - .fb_probe = intelfb_probe, - .fb_remove = intelfb_remove, - .fb_resize = intelfb_resize, - .master_create = i915_master_create, - .master_destroy = i915_master_destroy, -#if defined(CONFIG_DEBUG_FS) - .debugfs_init = i915_debugfs_init, - .debugfs_cleanup = i915_debugfs_cleanup, -#endif - .gem_init_object = i915_gem_init_object, - .gem_free_object = i915_gem_free_object, - .gem_vm_ops = &i915_gem_vm_ops, - .ioctls = i915_ioctls, - .fops = { - .owner = THIS_MODULE, - .open = drm_open, - .release = drm_release, - .ioctl = drm_ioctl, - .mmap = drm_mmap, - .poll = drm_poll, - .fasync = drm_fasync, -#ifdef CONFIG_COMPAT - .compat_ioctl = i915_compat_ioctl, -#endif - .llseek = noop_llseek, - }, - .pci_driver = { - .name = DRIVER_NAME, - .id_table = pciidlist, - .probe = probe, - .remove = __devexit_p(drm_cleanup_pci), - }, - .name = DRIVER_NAME, - .desc = DRIVER_DESC, - .date = DRIVER_DATE, - .major = DRIVER_MAJOR, - .minor = DRIVER_MINOR, - .patchlevel = DRIVER_PATCHLEVEL, - }; - </programlisting> - <para> - In the example above, taken from the i915 DRM driver, the driver - sets several flags indicating what core features it supports; - we go over the individual callbacks in later sections. Since - flags indicate which features your driver supports to the DRM - core, you need to set most of them prior to calling drm_init(). Some, - like DRIVER_MODESET can be set later based on user supplied parameters, - but that's the exception rather than the rule. - </para> - <variablelist> - <title>Driver flags</title> - <varlistentry> - <term>DRIVER_USE_AGP</term> - <listitem><para> - Driver uses AGP interface - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_REQUIRE_AGP</term> - <listitem><para> - Driver needs AGP interface to function. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_USE_MTRR</term> - <listitem> - <para> - Driver uses MTRR interface for mapping memory. Deprecated. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_PCI_DMA</term> - <listitem><para> - Driver is capable of PCI DMA. Deprecated. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_SG</term> - <listitem><para> - Driver can perform scatter/gather DMA. Deprecated. - </para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_HAVE_DMA</term> - <listitem><para>Driver supports DMA. Deprecated.</para></listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term> - <listitem> - <para> - DRIVER_HAVE_IRQ indicates whether the driver has an IRQ - handler. DRIVER_IRQ_SHARED indicates whether the device & - handler support shared IRQs (note that this is required of - PCI drivers). - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_DMA_QUEUE</term> - <listitem> - <para> - Should be set if the driver queues DMA requests and completes them - asynchronously. Deprecated. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_FB_DMA</term> - <listitem> - <para> - Driver supports DMA to/from the framebuffer. Deprecated. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>DRIVER_MODESET</term> - <listitem> - <para> - Driver supports mode setting interfaces. - </para> - </listitem> - </varlistentry> - </variablelist> - <para> - In this specific case, the driver requires AGP and supports - IRQs. DMA, as discussed later, is handled by device-specific ioctls - in this case. It also supports the kernel mode setting APIs, though - unlike in the actual i915 driver source, this example unconditionally - exports KMS capability. + <title>Driver Initialization</title> + <para> + At the core of every DRM driver is a <structname>drm_driver</structname> + structure. Drivers typically statically initialize a drm_driver structure, + and then pass it to one of the <function>drm_*_init()</function> functions + to register it with the DRM subsystem. </para> - </sect1> - - <!-- Internals: driver load --> - - <sect1> - <title>Driver load</title> - <para> - In the previous section, we saw what a typical drm_driver - structure might look like. One of the more important fields in - the structure is the hook for the load function. - </para> - <programlisting> - static struct drm_driver driver = { - ... - .load = i915_driver_load, - ... - }; - </programlisting> - <para> - The load function has many responsibilities: allocating a driver - private structure, specifying supported performance counters, - configuring the device (e.g. mapping registers & command - buffers), initializing the memory manager, and setting up the - initial output configuration. - </para> - <para> - If compatibility is a concern (e.g. with drivers converted over - to the new interfaces from the old ones), care must be taken to - prevent device initialization and control that is incompatible with - currently active userspace drivers. For instance, if user - level mode setting drivers are in use, it would be problematic - to perform output discovery & configuration at load time. - Likewise, if user-level drivers unaware of memory management are - in use, memory management and command buffer setup may need to - be omitted. These requirements are driver-specific, and care - needs to be taken to keep both old and new applications and - libraries working. The i915 driver supports the "modeset" - module parameter to control whether advanced features are - enabled at load time or in legacy fashion. + <para> + The <structname>drm_driver</structname> structure contains static + information that describes the driver and features it supports, and + pointers to methods that the DRM core will call to implement the DRM API. + We will first go through the <structname>drm_driver</structname> static + information fields, and will then describe individual operations in + details as they get used in later sections. </para> - <sect2> - <title>Driver private & performance counters</title> - <para> - The driver private hangs off the main drm_device structure and - can be used for tracking various device-specific bits of - information, like register offsets, command buffer status, - register state for suspend/resume, etc. At load time, a - driver may simply allocate one and set drm_device.dev_priv - appropriately; it should be freed and drm_device.dev_priv set - to NULL when the driver is unloaded. - </para> + <title>Driver Information</title> + <sect3> + <title>Driver Features</title> + <para> + Drivers inform the DRM core about their requirements and supported + features by setting appropriate flags in the + <structfield>driver_features</structfield> field. Since those flags + influence the DRM core behaviour since registration time, most of them + must be set to registering the <structname>drm_driver</structname> + instance. + </para> + <synopsis>u32 driver_features;</synopsis> + <variablelist> + <title>Driver Feature Flags</title> + <varlistentry> + <term>DRIVER_USE_AGP</term> + <listitem><para> + Driver uses AGP interface, the DRM core will manage AGP resources. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_REQUIRE_AGP</term> + <listitem><para> + Driver needs AGP interface to function. AGP initialization failure + will become a fatal error. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_USE_MTRR</term> + <listitem><para> + Driver uses MTRR interface for mapping memory, the DRM core will + manage MTRR resources. Deprecated. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_PCI_DMA</term> + <listitem><para> + Driver is capable of PCI DMA, mapping of PCI DMA buffers to + userspace will be enabled. Deprecated. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_SG</term> + <listitem><para> + Driver can perform scatter/gather DMA, allocation and mapping of + scatter/gather buffers will be enabled. Deprecated. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_HAVE_DMA</term> + <listitem><para> + Driver supports DMA, the userspace DMA API will be supported. + Deprecated. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_HAVE_IRQ</term><term>DRIVER_IRQ_SHARED</term> + <listitem><para> + DRIVER_HAVE_IRQ indicates whether the driver has an IRQ handler. The + DRM core will automatically register an interrupt handler when the + flag is set. DRIVER_IRQ_SHARED indicates whether the device & + handler support shared IRQs (note that this is required of PCI + drivers). + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_IRQ_VBL</term> + <listitem><para>Unused. Deprecated.</para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_DMA_QUEUE</term> + <listitem><para> + Should be set if the driver queues DMA requests and completes them + asynchronously. Deprecated. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_FB_DMA</term> + <listitem><para> + Driver supports DMA to/from the framebuffer, mapping of frambuffer + DMA buffers to userspace will be supported. Deprecated. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_IRQ_VBL2</term> + <listitem><para>Unused. Deprecated.</para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_GEM</term> + <listitem><para> + Driver use the GEM memory manager. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_MODESET</term> + <listitem><para> + Driver supports mode setting interfaces (KMS). + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRIVER_PRIME</term> + <listitem><para> + Driver implements DRM PRIME buffer sharing. + </para></listitem> + </varlistentry> + </variablelist> + </sect3> + <sect3> + <title>Major, Minor and Patchlevel</title> + <synopsis>int major; +int minor; +int patchlevel;</synopsis> + <para> + The DRM core identifies driver versions by a major, minor and patch + level triplet. The information is printed to the kernel log at + initialization time and passed to userspace through the + DRM_IOCTL_VERSION ioctl. + </para> + <para> + The major and minor numbers are also used to verify the requested driver + API version passed to DRM_IOCTL_SET_VERSION. When the driver API changes + between minor versions, applications can call DRM_IOCTL_SET_VERSION to + select a specific version of the API. If the requested major isn't equal + to the driver major, or the requested minor is larger than the driver + minor, the DRM_IOCTL_SET_VERSION call will return an error. Otherwise + the driver's set_version() method will be called with the requested + version. + </para> + </sect3> + <sect3> + <title>Name, Description and Date</title> + <synopsis>char *name; +char *desc; +char *date;</synopsis> + <para> + The driver name is printed to the kernel log at initialization time, + used for IRQ registration and passed to userspace through + DRM_IOCTL_VERSION. + </para> + <para> + The driver description is a purely informative string passed to + userspace through the DRM_IOCTL_VERSION ioctl and otherwise unused by + the kernel. + </para> + <para> + The driver date, formatted as YYYYMMDD, is meant to identify the date of + the latest modification to the driver. However, as most drivers fail to + update it, its value is mostly useless. The DRM core prints it to the + kernel log at initialization time and passes it to userspace through the + DRM_IOCTL_VERSION ioctl. + </para> + </sect3> + </sect2> + <sect2> + <title>Driver Load</title> <para> - The DRM supports several counters which may be used for rough - performance characterization. Note that the DRM stat counter - system is not often used by applications, and supporting - additional counters is completely optional. + The <methodname>load</methodname> method is the driver and device + initialization entry point. The method is responsible for allocating and + initializing driver private data, specifying supported performance + counters, performing resource allocation and mapping (e.g. acquiring + clocks, mapping registers or allocating command buffers), initializing + the memory manager (<xref linkend="drm-memory-management"/>), installing + the IRQ handler (<xref linkend="drm-irq-registration"/>), setting up + vertical blanking handling (<xref linkend="drm-vertical-blank"/>), mode + setting (<xref linkend="drm-mode-setting"/>) and initial output + configuration (<xref linkend="drm-kms-init"/>). </para> + <note><para> + If compatibility is a concern (e.g. with drivers converted over from + User Mode Setting to Kernel Mode Setting), care must be taken to prevent + device initialization and control that is incompatible with currently + active userspace drivers. For instance, if user level mode setting + drivers are in use, it would be problematic to perform output discovery + & configuration at load time. Likewise, if user-level drivers + unaware of memory management are in use, memory management and command + buffer setup may need to be omitted. These requirements are + driver-specific, and care needs to be taken to keep both old and new + applications and libraries working. + </para></note> + <synopsis>int (*load) (struct drm_device *, unsigned long flags);</synopsis> <para> - These interfaces are deprecated and should not be used. If performance - monitoring is desired, the developer should investigate and - potentially enhance the kernel perf and tracing infrastructure to export - GPU related performance information for consumption by performance - monitoring tools and applications. + The method takes two arguments, a pointer to the newly created + <structname>drm_device</structname> and flags. The flags are used to + pass the <structfield>driver_data</structfield> field of the device id + corresponding to the device passed to <function>drm_*_init()</function>. + Only PCI devices currently use this, USB and platform DRM drivers have + their <methodname>load</methodname> method called with flags to 0. </para> + <sect3> + <title>Driver Private & Performance Counters</title> + <para> + The driver private hangs off the main + <structname>drm_device</structname> structure and can be used for + tracking various device-specific bits of information, like register + offsets, command buffer status, register state for suspend/resume, etc. + At load time, a driver may simply allocate one and set + <structname>drm_device</structname>.<structfield>dev_priv</structfield> + appropriately; it should be freed and + <structname>drm_device</structname>.<structfield>dev_priv</structfield> + set to NULL when the driver is unloaded. + </para> + <para> + DRM supports several counters which were used for rough performance + characterization. This stat counter system is deprecated and should not + be used. If performance monitoring is desired, the developer should + investigate and potentially enhance the kernel perf and tracing + infrastructure to export GPU related performance information for + consumption by performance monitoring tools and applications. + </para> + </sect3> + <sect3 id="drm-irq-registration"> + <title>IRQ Registration</title> + <para> + The DRM core tries to facilitate IRQ handler registration and + unregistration by providing <function>drm_irq_install</function> and + <function>drm_irq_uninstall</function> functions. Those functions only + support a single interrupt per device. + </para> + <!--!Fdrivers/char/drm/drm_irq.c drm_irq_install--> + <para> + Both functions get the device IRQ by calling + <function>drm_dev_to_irq</function>. This inline function will call a + bus-specific operation to retrieve the IRQ number. For platform devices, + <function>platform_get_irq</function>(..., 0) is used to retrieve the + IRQ number. + </para> + <para> + <function>drm_irq_install</function> starts by calling the + <methodname>irq_preinstall</methodname> driver operation. The operation + is optional and must make sure that the interrupt will not get fired by + clearing all pending interrupt flags or disabling the interrupt. + </para> + <para> + The IRQ will then be requested by a call to + <function>request_irq</function>. If the DRIVER_IRQ_SHARED driver + feature flag is set, a shared (IRQF_SHARED) IRQ handler will be + requested. + </para> + <para> + The IRQ handler function must be provided as the mandatory irq_handler + driver operation. It will get passed directly to + <function>request_irq</function> and thus has the same prototype as all + IRQ handlers. It will get called with a pointer to the DRM device as the + second argument. + </para> + <para> + Finally the function calls the optional + <methodname>irq_postinstall</methodname> driver operation. The operation + usually enables interrupts (excluding the vblank interrupt, which is + enabled separately), but drivers may choose to enable/disable interrupts + at a different time. + </para> + <para> + <function>drm_irq_uninstall</function> is similarly used to uninstall an + IRQ handler. It starts by waking up all processes waiting on a vblank + interrupt to make sure they don't hang, and then calls the optional + <methodname>irq_uninstall</methodname> driver operation. The operation + must disable all hardware interrupts. Finally the function frees the IRQ + by calling <function>free_irq</function>. + </para> + </sect3> + <sect3> + <title>Memory Manager Initialization</title> + <para> + Every DRM driver requires a memory manager which must be initialized at + load time. DRM currently contains two memory managers, the Translation + Table Manager (TTM) and the Graphics Execution Manager (GEM). + This document describes the use of the GEM memory manager only. See + <xref linkend="drm-memory-management"/> for details. + </para> + </sect3> + <sect3> + <title>Miscellaneous Device Configuration</title> + <para> + Another task that may be necessary for PCI devices during configuration + is mapping the video BIOS. On many devices, the VBIOS describes device + configuration, LCD panel timings (if any), and contains flags indicating + device state. Mapping the BIOS can be done using the pci_map_rom() call, + a convenience function that takes care of mapping the actual ROM, + whether it has been shadowed into memory (typically at address 0xc0000) + or exists on the PCI device in the ROM BAR. Note that after the ROM has + been mapped and any necessary information has been extracted, it should + be unmapped; on many devices, the ROM address decoder is shared with + other BARs, so leaving it mapped could cause undesired behaviour like + hangs or memory corruption. + <!--!Fdrivers/pci/rom.c pci_map_rom--> + </para> + </sect3> </sect2> + </sect1> - <sect2> - <title>Configuring the device</title> - <para> - Obviously, device configuration is device-specific. - However, there are several common operations: finding a - device's PCI resources, mapping them, and potentially setting - up an IRQ handler. - </para> - <para> - Finding & mapping resources is fairly straightforward. The - DRM wrapper functions, drm_get_resource_start() and - drm_get_resource_len(), may be used to find BARs on the given - drm_device struct. Once those values have been retrieved, the - driver load function can call drm_addmap() to create a new - mapping for the BAR in question. Note that you probably want a - drm_local_map_t in your driver private structure to track any - mappings you create. -<!-- !Fdrivers/gpu/drm/drm_bufs.c drm_get_resource_* --> -<!-- !Finclude/drm/drmP.h drm_local_map_t --> - </para> - <para> - if compatibility with other operating systems isn't a concern - (DRM drivers can run under various BSD variants and OpenSolaris), - native Linux calls may be used for the above, e.g. pci_resource_* - and iomap*/iounmap. See the Linux device driver book for more - info. - </para> - <para> - Once you have a register map, you may use the DRM_READn() and - DRM_WRITEn() macros to access the registers on your device, or - use driver-specific versions to offset into your MMIO space - relative to a driver-specific base pointer (see I915_READ for - an example). - </para> - <para> - If your device supports interrupt generation, you may want to - set up an interrupt handler when the driver is loaded. This - is done using the drm_irq_install() function. If your device - supports vertical blank interrupts, it should call - drm_vblank_init() to initialize the core vblank handling code before - enabling interrupts on your device. This ensures the vblank related - structures are allocated and allows the core to handle vblank events. - </para> -<!--!Fdrivers/char/drm/drm_irq.c drm_irq_install--> - <para> - Once your interrupt handler is registered (it uses your - drm_driver.irq_handler as the actual interrupt handling - function), you can safely enable interrupts on your device, - assuming any other state your interrupt handler uses is also - initialized. - </para> - <para> - Another task that may be necessary during configuration is - mapping the video BIOS. On many devices, the VBIOS describes - device configuration, LCD panel timings (if any), and contains - flags indicating device state. Mapping the BIOS can be done - using the pci_map_rom() call, a convenience function that - takes care of mapping the actual ROM, whether it has been - shadowed into memory (typically at address 0xc0000) or exists - on the PCI device in the ROM BAR. Note that after the ROM - has been mapped and any necessary information has been extracted, - it should be unmapped; on many devices, the ROM address decoder is - shared with other BARs, so leaving it mapped could cause - undesired behavior like hangs or memory corruption. -<!--!Fdrivers/pci/rom.c pci_map_rom--> - </para> - </sect2> + <!-- Internals: memory management --> + <sect1 id="drm-memory-management"> + <title>Memory management</title> + <para> + Modern Linux systems require large amount of graphics memory to store + frame buffers, textures, vertices and other graphics-related data. Given + the very dynamic nature of many of that data, managing graphics memory + efficiently is thus crucial for the graphics stack and plays a central + role in the DRM infrastructure. + </para> + <para> + The DRM core includes two memory managers, namely Translation Table Maps + (TTM) and Graphics Execution Manager (GEM). TTM was the first DRM memory + manager to be developed and tried to be a one-size-fits-them all + solution. It provides a single userspace API to accomodate the need of + all hardware, supporting both Unified Memory Architecture (UMA) devices + and devices with dedicated video RAM (i.e. most discrete video cards). + This resulted in a large, complex piece of code that turned out to be + hard to use for driver development. + </para> + <para> + GEM started as an Intel-sponsored project in reaction to TTM's + complexity. Its design philosophy is completely different: instead of + providing a solution to every graphics memory-related problems, GEM + identified common code between drivers and created a support library to + share it. GEM has simpler initialization and execution requirements than + TTM, but has no video RAM management capabitilies and is thus limited to + UMA devices. + </para> <sect2> - <title>Memory manager initialization</title> - <para> - In order to allocate command buffers, cursor memory, scanout - buffers, etc., as well as support the latest features provided - by packages like Mesa and the X.Org X server, your driver - should support a memory manager. - </para> + <title>The Translation Table Manager (TTM)</title> <para> - If your driver supports memory management (it should!), you - need to set that up at load time as well. How you initialize - it depends on which memory manager you're using: TTM or GEM. + TTM design background and information belongs here. </para> <sect3> <title>TTM initialization</title> - <para> - TTM (for Translation Table Manager) manages video memory and - aperture space for graphics devices. TTM supports both UMA devices - and devices with dedicated video RAM (VRAM), i.e. most discrete - graphics devices. If your device has dedicated RAM, supporting - TTM is desirable. TTM also integrates tightly with your - driver-specific buffer execution function. See the radeon - driver for examples. - </para> - <para> - The core TTM structure is the ttm_bo_driver struct. It contains - several fields with function pointers for initializing the TTM, - allocating and freeing memory, waiting for command completion - and fence synchronization, and memory migration. See the - radeon_ttm.c file for an example of usage. + <warning><para>This section is outdated.</para></warning> + <para> + Drivers wishing to support TTM must fill out a drm_bo_driver + structure. The structure contains several fields with function + pointers for initializing the TTM, allocating and freeing memory, + waiting for command completion and fence synchronization, and memory + migration. See the radeon_ttm.c file for an example of usage. </para> <para> The ttm_global_reference structure is made up of several fields: @@ -445,82 +500,1081 @@ count for the TTM, which will call your initialization function. </para> </sect3> + </sect2> + <sect2 id="drm-gem"> + <title>The Graphics Execution Manager (GEM)</title> + <para> + The GEM design approach has resulted in a memory manager that doesn't + provide full coverage of all (or even all common) use cases in its + userspace or kernel API. GEM exposes a set of standard memory-related + operations to userspace and a set of helper functions to drivers, and let + drivers implement hardware-specific operations with their own private API. + </para> + <para> + The GEM userspace API is described in the + <ulink url="http://lwn.net/Articles/283798/"><citetitle>GEM - the Graphics + Execution Manager</citetitle></ulink> article on LWN. While slightly + outdated, the document provides a good overview of the GEM API principles. + Buffer allocation and read and write operations, described as part of the + common GEM API, are currently implemented using driver-specific ioctls. + </para> + <para> + GEM is data-agnostic. It manages abstract buffer objects without knowing + what individual buffers contain. APIs that require knowledge of buffer + contents or purpose, such as buffer allocation or synchronization + primitives, are thus outside of the scope of GEM and must be implemented + using driver-specific ioctls. + </para> + <para> + On a fundamental level, GEM involves several operations: + <itemizedlist> + <listitem>Memory allocation and freeing</listitem> + <listitem>Command execution</listitem> + <listitem>Aperture management at command execution time</listitem> + </itemizedlist> + Buffer object allocation is relatively straightforward and largely + provided by Linux's shmem layer, which provides memory to back each + object. + </para> + <para> + Device-specific operations, such as command execution, pinning, buffer + read & write, mapping, and domain ownership transfers are left to + driver-specific ioctls. + </para> + <sect3> + <title>GEM Initialization</title> + <para> + Drivers that use GEM must set the DRIVER_GEM bit in the struct + <structname>drm_driver</structname> + <structfield>driver_features</structfield> field. The DRM core will + then automatically initialize the GEM core before calling the + <methodname>load</methodname> operation. Behind the scene, this will + create a DRM Memory Manager object which provides an address space + pool for object allocation. + </para> + <para> + In a KMS configuration, drivers need to allocate and initialize a + command ring buffer following core GEM initialization if required by + the hardware. UMA devices usually have what is called a "stolen" + memory region, which provides space for the initial framebuffer and + large, contiguous memory regions required by the device. This space is + typically not managed by GEM, and must be initialized separately into + its own DRM MM object. + </para> + </sect3> <sect3> - <title>GEM initialization</title> - <para> - GEM is an alternative to TTM, designed specifically for UMA - devices. It has simpler initialization and execution requirements - than TTM, but has no VRAM management capability. Core GEM - is initialized by calling drm_mm_init() to create - a GTT DRM MM object, which provides an address space pool for - object allocation. In a KMS configuration, the driver - needs to allocate and initialize a command ring buffer following - core GEM initialization. A UMA device usually has what is called a - "stolen" memory region, which provides space for the initial - framebuffer and large, contiguous memory regions required by the - device. This space is not typically managed by GEM, and it must - be initialized separately into its own DRM MM object. - </para> - <para> - Initialization is driver-specific. In the case of Intel - integrated graphics chips like 965GM, GEM initialization can - be done by calling the internal GEM init function, - i915_gem_do_init(). Since the 965GM is a UMA device - (i.e. it doesn't have dedicated VRAM), GEM manages - making regular RAM available for GPU operations. Memory set - aside by the BIOS (called "stolen" memory by the i915 - driver) is managed by the DRM memrange allocator; the - rest of the aperture is managed by GEM. - <programlisting> - /* Basic memrange allocator for stolen space (aka vram) */ - drm_memrange_init(&dev_priv->vram, 0, prealloc_size); - /* Let GEM Manage from end of prealloc space to end of aperture */ - i915_gem_do_init(dev, prealloc_size, agp_size); - </programlisting> -<!--!Edrivers/char/drm/drm_memrange.c--> - </para> - <para> - Once the memory manager has been set up, we may allocate the - command buffer. In the i915 case, this is also done with a - GEM function, i915_gem_init_ringbuffer(). - </para> + <title>GEM Objects Creation</title> + <para> + GEM splits creation of GEM objects and allocation of the memory that + backs them in two distinct operations. + </para> + <para> + GEM objects are represented by an instance of struct + <structname>drm_gem_object</structname>. Drivers usually need to extend + GEM objects with private information and thus create a driver-specific + GEM object structure type that embeds an instance of struct + <structname>drm_gem_object</structname>. + </para> + <para> + To create a GEM object, a driver allocates memory for an instance of its + specific GEM object type and initializes the embedded struct + <structname>drm_gem_object</structname> with a call to + <function>drm_gem_object_init</function>. The function takes a pointer to + the DRM device, a pointer to the GEM object and the buffer object size + in bytes. + </para> + <para> + GEM uses shmem to allocate anonymous pageable memory. + <function>drm_gem_object_init</function> will create an shmfs file of + the requested size and store it into the struct + <structname>drm_gem_object</structname> <structfield>filp</structfield> + field. The memory is used as either main storage for the object when the + graphics hardware uses system memory directly or as a backing store + otherwise. + </para> + <para> + Drivers are responsible for the actual physical pages allocation by + calling <function>shmem_read_mapping_page_gfp</function> for each page. + Note that they can decide to allocate pages when initializing the GEM + object, or to delay allocation until the memory is needed (for instance + when a page fault occurs as a result of a userspace memory access or + when the driver needs to start a DMA transfer involving the memory). + </para> + <para> + Anonymous pageable memory allocation is not always desired, for instance + when the hardware requires physically contiguous system memory as is + often the case in embedded devices. Drivers can create GEM objects with + no shmfs backing (called private GEM objects) by initializing them with + a call to <function>drm_gem_private_object_init</function> instead of + <function>drm_gem_object_init</function>. Storage for private GEM + objects must be managed by drivers. + </para> + <para> + Drivers that do not need to extend GEM objects with private information + can call the <function>drm_gem_object_alloc</function> function to + allocate and initialize a struct <structname>drm_gem_object</structname> + instance. The GEM core will call the optional driver + <methodname>gem_init_object</methodname> operation after initializing + the GEM object with <function>drm_gem_object_init</function>. + <synopsis>int (*gem_init_object) (struct drm_gem_object *obj);</synopsis> + </para> + <para> + No alloc-and-init function exists for private GEM objects. + </para> + </sect3> + <sect3> + <title>GEM Objects Lifetime</title> + <para> + All GEM objects are reference-counted by the GEM core. References can be + acquired and release by <function>calling drm_gem_object_reference</function> + and <function>drm_gem_object_unreference</function> respectively. The + caller must hold the <structname>drm_device</structname> + <structfield>struct_mutex</structfield> lock. As a convenience, GEM + provides the <function>drm_gem_object_reference_unlocked</function> and + <function>drm_gem_object_unreference_unlocked</function> functions that + can be called without holding the lock. + </para> + <para> + When the last reference to a GEM object is released the GEM core calls + the <structname>drm_driver</structname> + <methodname>gem_free_object</methodname> operation. That operation is + mandatory for GEM-enabled drivers and must free the GEM object and all + associated resources. + </para> + <para> + <synopsis>void (*gem_free_object) (struct drm_gem_object *obj);</synopsis> + Drivers are responsible for freeing all GEM object resources, including + the resources created by the GEM core. If an mmap offset has been + created for the object (in which case + <structname>drm_gem_object</structname>::<structfield>map_list</structfield>::<structfield>map</structfield> + is not NULL) it must be freed by a call to + <function>drm_gem_free_mmap_offset</function>. The shmfs backing store + must be released by calling <function>drm_gem_object_release</function> + (that function can safely be called if no shmfs backing store has been + created). + </para> + </sect3> + <sect3> + <title>GEM Objects Naming</title> + <para> + Communication between userspace and the kernel refers to GEM objects + using local handles, global names or, more recently, file descriptors. + All of those are 32-bit integer values; the usual Linux kernel limits + apply to the file descriptors. + </para> + <para> + GEM handles are local to a DRM file. Applications get a handle to a GEM + object through a driver-specific ioctl, and can use that handle to refer + to the GEM object in other standard or driver-specific ioctls. Closing a + DRM file handle frees all its GEM handles and dereferences the + associated GEM objects. + </para> + <para> + To create a handle for a GEM object drivers call + <function>drm_gem_handle_create</function>. The function takes a pointer + to the DRM file and the GEM object and returns a locally unique handle. + When the handle is no longer needed drivers delete it with a call to + <function>drm_gem_handle_delete</function>. Finally the GEM object + associated with a handle can be retrieved by a call to + <function>drm_gem_object_lookup</function>. + </para> + <para> + Handles don't take ownership of GEM objects, they only take a reference + to the object that will be dropped when the handle is destroyed. To + avoid leaking GEM objects, drivers must make sure they drop the + reference(s) they own (such as the initial reference taken at object + creation time) as appropriate, without any special consideration for the + handle. For example, in the particular case of combined GEM object and + handle creation in the implementation of the + <methodname>dumb_create</methodname> operation, drivers must drop the + initial reference to the GEM object before returning the handle. + </para> + <para> + GEM names are similar in purpose to handles but are not local to DRM + files. They can be passed between processes to reference a GEM object + globally. Names can't be used directly to refer to objects in the DRM + API, applications must convert handles to names and names to handles + using the DRM_IOCTL_GEM_FLINK and DRM_IOCTL_GEM_OPEN ioctls + respectively. The conversion is handled by the DRM core without any + driver-specific support. + </para> + <para> + Similar to global names, GEM file descriptors are also used to share GEM + objects across processes. They offer additional security: as file + descriptors must be explictly sent over UNIX domain sockets to be shared + between applications, they can't be guessed like the globally unique GEM + names. + </para> + <para> + Drivers that support GEM file descriptors, also known as the DRM PRIME + API, must set the DRIVER_PRIME bit in the struct + <structname>drm_driver</structname> + <structfield>driver_features</structfield> field, and implement the + <methodname>prime_handle_to_fd</methodname> and + <methodname>prime_fd_to_handle</methodname> operations. + </para> + <para> + <synopsis>int (*prime_handle_to_fd)(struct drm_device *dev, + struct drm_file *file_priv, uint32_t handle, + uint32_t flags, int *prime_fd); + int (*prime_fd_to_handle)(struct drm_device *dev, + struct drm_file *file_priv, int prime_fd, + uint32_t *handle);</synopsis> + Those two operations convert a handle to a PRIME file descriptor and + vice versa. Drivers must use the kernel dma-buf buffer sharing framework + to manage the PRIME file descriptors. + </para> + <para> + While non-GEM drivers must implement the operations themselves, GEM + drivers must use the <function>drm_gem_prime_handle_to_fd</function> + and <function>drm_gem_prime_fd_to_handle</function> helper functions. + Those helpers rely on the driver + <methodname>gem_prime_export</methodname> and + <methodname>gem_prime_import</methodname> operations to create a dma-buf + instance from a GEM object (dma-buf exporter role) and to create a GEM + object from a dma-buf instance (dma-buf importer role). + </para> + <para> + <synopsis>struct dma_buf * (*gem_prime_export)(struct drm_device *dev, + struct drm_gem_object *obj, + int flags); + struct drm_gem_object * (*gem_prime_import)(struct drm_device *dev, + struct dma_buf *dma_buf);</synopsis> + These two operations are mandatory for GEM drivers that support DRM + PRIME. + </para> + </sect3> + <sect3 id="drm-gem-objects-mapping"> + <title>GEM Objects Mapping</title> + <para> + Because mapping operations are fairly heavyweight GEM favours + read/write-like access to buffers, implemented through driver-specific + ioctls, over mapping buffers to userspace. However, when random access + to the buffer is needed (to perform software rendering for instance), + direct access to the object can be more efficient. + </para> + <para> + The mmap system call can't be used directly to map GEM objects, as they + don't have their own file handle. Two alternative methods currently + co-exist to map GEM objects to userspace. The first method uses a + driver-specific ioctl to perform the mapping operation, calling + <function>do_mmap</function> under the hood. This is often considered + dubious, seems to be discouraged for new GEM-enabled drivers, and will + thus not be described here. + </para> + <para> + The second method uses the mmap system call on the DRM file handle. + <synopsis>void *mmap(void *addr, size_t length, int prot, int flags, int fd, + off_t offset);</synopsis> + DRM identifies the GEM object to be mapped by a fake offset passed + through the mmap offset argument. Prior to being mapped, a GEM object + must thus be associated with a fake offset. To do so, drivers must call + <function>drm_gem_create_mmap_offset</function> on the object. The + function allocates a fake offset range from a pool and stores the + offset divided by PAGE_SIZE in + <literal>obj->map_list.hash.key</literal>. Care must be taken not to + call <function>drm_gem_create_mmap_offset</function> if a fake offset + has already been allocated for the object. This can be tested by + <literal>obj->map_list.map</literal> being non-NULL. + </para> + <para> + Once allocated, the fake offset value + (<literal>obj->map_list.hash.key << PAGE_SHIFT</literal>) + must be passed to the application in a driver-specific way and can then + be used as the mmap offset argument. + </para> + <para> + The GEM core provides a helper method <function>drm_gem_mmap</function> + to handle object mapping. The method can be set directly as the mmap + file operation handler. It will look up the GEM object based on the + offset value and set the VMA operations to the + <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield> + field. Note that <function>drm_gem_mmap</function> doesn't map memory to + userspace, but relies on the driver-provided fault handler to map pages + individually. + </para> + <para> + To use <function>drm_gem_mmap</function>, drivers must fill the struct + <structname>drm_driver</structname> <structfield>gem_vm_ops</structfield> + field with a pointer to VM operations. + </para> + <para> + <synopsis>struct vm_operations_struct *gem_vm_ops + + struct vm_operations_struct { + void (*open)(struct vm_area_struct * area); + void (*close)(struct vm_area_struct * area); + int (*fault)(struct vm_area_struct *vma, struct vm_fault *vmf); + };</synopsis> + </para> + <para> + The <methodname>open</methodname> and <methodname>close</methodname> + operations must update the GEM object reference count. Drivers can use + the <function>drm_gem_vm_open</function> and + <function>drm_gem_vm_close</function> helper functions directly as open + and close handlers. + </para> + <para> + The fault operation handler is responsible for mapping individual pages + to userspace when a page fault occurs. Depending on the memory + allocation scheme, drivers can allocate pages at fault time, or can + decide to allocate memory for the GEM object at the time the object is + created. + </para> + <para> + Drivers that want to map the GEM object upfront instead of handling page + faults can implement their own mmap file operation handler. + </para> + </sect3> + <sect3> + <title>Dumb GEM Objects</title> + <para> + The GEM API doesn't standardize GEM objects creation and leaves it to + driver-specific ioctls. While not an issue for full-fledged graphics + stacks that include device-specific userspace components (in libdrm for + instance), this limit makes DRM-based early boot graphics unnecessarily + complex. + </para> + <para> + Dumb GEM objects partly alleviate the problem by providing a standard + API to create dumb buffers suitable for scanout, which can then be used + to create KMS frame buffers. + </para> + <para> + To support dumb GEM objects drivers must implement the + <methodname>dumb_create</methodname>, + <methodname>dumb_destroy</methodname> and + <methodname>dumb_map_offset</methodname> operations. + </para> + <itemizedlist> + <listitem> + <synopsis>int (*dumb_create)(struct drm_file *file_priv, struct drm_device *dev, + struct drm_mode_create_dumb *args);</synopsis> + <para> + The <methodname>dumb_create</methodname> operation creates a GEM + object suitable for scanout based on the width, height and depth + from the struct <structname>drm_mode_create_dumb</structname> + argument. It fills the argument's <structfield>handle</structfield>, + <structfield>pitch</structfield> and <structfield>size</structfield> + fields with a handle for the newly created GEM object and its line + pitch and size in bytes. + </para> + </listitem> + <listitem> + <synopsis>int (*dumb_destroy)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle);</synopsis> + <para> + The <methodname>dumb_destroy</methodname> operation destroys a dumb + GEM object created by <methodname>dumb_create</methodname>. + </para> + </listitem> + <listitem> + <synopsis>int (*dumb_map_offset)(struct drm_file *file_priv, struct drm_device *dev, + uint32_t handle, uint64_t *offset);</synopsis> + <para> + The <methodname>dumb_map_offset</methodname> operation associates an + mmap fake offset with the GEM object given by the handle and returns + it. Drivers must use the + <function>drm_gem_create_mmap_offset</function> function to + associate the fake offset as described in + <xref linkend="drm-gem-objects-mapping"/>. + </para> + </listitem> + </itemizedlist> + </sect3> + <sect3> + <title>Memory Coherency</title> + <para> + When mapped to the device or used in a command buffer, backing pages + for an object are flushed to memory and marked write combined so as to + be coherent with the GPU. Likewise, if the CPU accesses an object + after the GPU has finished rendering to the object, then the object + must be made coherent with the CPU's view of memory, usually involving + GPU cache flushing of various kinds. This core CPU<->GPU + coherency management is provided by a device-specific ioctl, which + evaluates an object's current domain and performs any necessary + flushing or synchronization to put the object into the desired + coherency domain (note that the object may be busy, i.e. an active + render target; in that case, setting the domain blocks the client and + waits for rendering to complete before performing any necessary + flushing operations). + </para> + </sect3> + <sect3> + <title>Command Execution</title> + <para> + Perhaps the most important GEM function for GPU devices is providing a + command execution interface to clients. Client programs construct + command buffers containing references to previously allocated memory + objects, and then submit them to GEM. At that point, GEM takes care to + bind all the objects into the GTT, execute the buffer, and provide + necessary synchronization between clients accessing the same buffers. + This often involves evicting some objects from the GTT and re-binding + others (a fairly expensive operation), and providing relocation + support which hides fixed GTT offsets from clients. Clients must take + care not to submit command buffers that reference more objects than + can fit in the GTT; otherwise, GEM will reject them and no rendering + will occur. Similarly, if several objects in the buffer require fence + registers to be allocated for correct rendering (e.g. 2D blits on + pre-965 chips), care must be taken not to require more fence registers + than are available to the client. Such resource management should be + abstracted from the client in libdrm. + </para> </sect3> </sect2> + </sect1> + + <!-- Internals: mode setting --> + <sect1 id="drm-mode-setting"> + <title>Mode Setting</title> + <para> + Drivers must initialize the mode setting core by calling + <function>drm_mode_config_init</function> on the DRM device. The function + initializes the <structname>drm_device</structname> + <structfield>mode_config</structfield> field and never fails. Once done, + mode configuration must be setup by initializing the following fields. + </para> + <itemizedlist> + <listitem> + <synopsis>int min_width, min_height; +int max_width, max_height;</synopsis> + <para> + Minimum and maximum width and height of the frame buffers in pixel + units. + </para> + </listitem> + <listitem> + <synopsis>struct drm_mode_config_funcs *funcs;</synopsis> + <para>Mode setting functions.</para> + </listitem> + </itemizedlist> <sect2> - <title>Output configuration</title> + <title>Frame Buffer Creation</title> + <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, + struct drm_file *file_priv, + struct drm_mode_fb_cmd2 *mode_cmd);</synopsis> <para> - The final initialization task is output configuration. This involves: - <itemizedlist> - <listitem> - Finding and initializing the CRTCs, encoders, and connectors - for the device. - </listitem> - <listitem> - Creating an initial configuration. - </listitem> - <listitem> - Registering a framebuffer console driver. - </listitem> - </itemizedlist> + Frame buffers are abstract memory objects that provide a source of + pixels to scanout to a CRTC. Applications explicitly request the + creation of frame buffers through the DRM_IOCTL_MODE_ADDFB(2) ioctls and + receive an opaque handle that can be passed to the KMS CRTC control, + plane configuration and page flip functions. + </para> + <para> + Frame buffers rely on the underneath memory manager for low-level memory + operations. When creating a frame buffer applications pass a memory + handle (or a list of memory handles for multi-planar formats) through + the <parameter>drm_mode_fb_cmd2</parameter> argument. This document + assumes that the driver uses GEM, those handles thus reference GEM + objects. + </para> + <para> + Drivers must first validate the requested frame buffer parameters passed + through the mode_cmd argument. In particular this is where invalid + sizes, pixel formats or pitches can be caught. + </para> + <para> + If the parameters are deemed valid, drivers then create, initialize and + return an instance of struct <structname>drm_framebuffer</structname>. + If desired the instance can be embedded in a larger driver-specific + structure. The new instance is initialized with a call to + <function>drm_framebuffer_init</function> which takes a pointer to DRM + frame buffer operations (struct + <structname>drm_framebuffer_funcs</structname>). Frame buffer operations are + <itemizedlist> + <listitem> + <synopsis>int (*create_handle)(struct drm_framebuffer *fb, + struct drm_file *file_priv, unsigned int *handle);</synopsis> + <para> + Create a handle to the frame buffer underlying memory object. If + the frame buffer uses a multi-plane format, the handle will + reference the memory object associated with the first plane. + </para> + <para> + Drivers call <function>drm_gem_handle_create</function> to create + the handle. + </para> + </listitem> + <listitem> + <synopsis>void (*destroy)(struct drm_framebuffer *framebuffer);</synopsis> + <para> + Destroy the frame buffer object and frees all associated + resources. Drivers must call + <function>drm_framebuffer_cleanup</function> to free resources + allocated by the DRM core for the frame buffer object, and must + make sure to unreference all memory objects associated with the + frame buffer. Handles created by the + <methodname>create_handle</methodname> operation are released by + the DRM core. + </para> + </listitem> + <listitem> + <synopsis>int (*dirty)(struct drm_framebuffer *framebuffer, + struct drm_file *file_priv, unsigned flags, unsigned color, + struct drm_clip_rect *clips, unsigned num_clips);</synopsis> + <para> + This optional operation notifies the driver that a region of the + frame buffer has changed in response to a DRM_IOCTL_MODE_DIRTYFB + ioctl call. + </para> + </listitem> + </itemizedlist> + </para> + <para> + After initializing the <structname>drm_framebuffer</structname> + instance drivers must fill its <structfield>width</structfield>, + <structfield>height</structfield>, <structfield>pitches</structfield>, + <structfield>offsets</structfield>, <structfield>depth</structfield>, + <structfield>bits_per_pixel</structfield> and + <structfield>pixel_format</structfield> fields from the values passed + through the <parameter>drm_mode_fb_cmd2</parameter> argument. They + should call the <function>drm_helper_mode_fill_fb_struct</function> + helper function to do so. + </para> + </sect2> + <sect2> + <title>Output Polling</title> + <synopsis>void (*output_poll_changed)(struct drm_device *dev);</synopsis> + <para> + This operation notifies the driver that the status of one or more + connectors has changed. Drivers that use the fb helper can just call the + <function>drm_fb_helper_hotplug_event</function> function to handle this + operation. + </para> + </sect2> + </sect1> + + <!-- Internals: kms initialization and cleanup --> + + <sect1 id="drm-kms-init"> + <title>KMS Initialization and Cleanup</title> + <para> + A KMS device is abstracted and exposed as a set of planes, CRTCs, encoders + and connectors. KMS drivers must thus create and initialize all those + objects at load time after initializing mode setting. + </para> + <sect2> + <title>CRTCs (struct <structname>drm_crtc</structname>)</title> + <para> + A CRTC is an abstraction representing a part of the chip that contains a + pointer to a scanout buffer. Therefore, the number of CRTCs available + determines how many independent scanout buffers can be active at any + given time. The CRTC structure contains several fields to support this: + a pointer to some video memory (abstracted as a frame buffer object), a + display mode, and an (x, y) offset into the video memory to support + panning or configurations where one piece of video memory spans multiple + CRTCs. </para> <sect3> - <title>Output discovery and initialization</title> - <para> - Several core functions exist to create CRTCs, encoders, and - connectors, namely: drm_crtc_init(), drm_connector_init(), and - drm_encoder_init(), along with several "helper" functions to - perform common tasks. - </para> - <para> - Connectors should be registered with sysfs once they've been - detected and initialized, using the - drm_sysfs_connector_add() function. Likewise, when they're - removed from the system, they should be destroyed with - drm_sysfs_connector_remove(). - </para> - <programlisting> -<![CDATA[ + <title>CRTC Initialization</title> + <para> + A KMS device must create and register at least one struct + <structname>drm_crtc</structname> instance. The instance is allocated + and zeroed by the driver, possibly as part of a larger structure, and + registered with a call to <function>drm_crtc_init</function> with a + pointer to CRTC functions. + </para> + </sect3> + <sect3> + <title>CRTC Operations</title> + <sect4> + <title>Set Configuration</title> + <synopsis>int (*set_config)(struct drm_mode_set *set);</synopsis> + <para> + Apply a new CRTC configuration to the device. The configuration + specifies a CRTC, a frame buffer to scan out from, a (x,y) position in + the frame buffer, a display mode and an array of connectors to drive + with the CRTC if possible. + </para> + <para> + If the frame buffer specified in the configuration is NULL, the driver + must detach all encoders connected to the CRTC and all connectors + attached to those encoders and disable them. + </para> + <para> + This operation is called with the mode config lock held. + </para> + <note><para> + FIXME: How should set_config interact with DPMS? If the CRTC is + suspended, should it be resumed? + </para></note> + </sect4> + <sect4> + <title>Page Flipping</title> + <synopsis>int (*page_flip)(struct drm_crtc *crtc, struct drm_framebuffer *fb, + struct drm_pending_vblank_event *event);</synopsis> + <para> + Schedule a page flip to the given frame buffer for the CRTC. This + operation is called with the mode config mutex held. + </para> + <para> + Page flipping is a synchronization mechanism that replaces the frame + buffer being scanned out by the CRTC with a new frame buffer during + vertical blanking, avoiding tearing. When an application requests a page + flip the DRM core verifies that the new frame buffer is large enough to + be scanned out by the CRTC in the currently configured mode and then + calls the CRTC <methodname>page_flip</methodname> operation with a + pointer to the new frame buffer. + </para> + <para> + The <methodname>page_flip</methodname> operation schedules a page flip. + Once any pending rendering targetting the new frame buffer has + completed, the CRTC will be reprogrammed to display that frame buffer + after the next vertical refresh. The operation must return immediately + without waiting for rendering or page flip to complete and must block + any new rendering to the frame buffer until the page flip completes. + </para> + <para> + If a page flip is already pending, the + <methodname>page_flip</methodname> operation must return + -<errorname>EBUSY</errorname>. + </para> + <para> + To synchronize page flip to vertical blanking the driver will likely + need to enable vertical blanking interrupts. It should call + <function>drm_vblank_get</function> for that purpose, and call + <function>drm_vblank_put</function> after the page flip completes. + </para> + <para> + If the application has requested to be notified when page flip completes + the <methodname>page_flip</methodname> operation will be called with a + non-NULL <parameter>event</parameter> argument pointing to a + <structname>drm_pending_vblank_event</structname> instance. Upon page + flip completion the driver must fill the + <parameter>event</parameter>::<structfield>event</structfield> + <structfield>sequence</structfield>, <structfield>tv_sec</structfield> + and <structfield>tv_usec</structfield> fields with the associated + vertical blanking count and timestamp, add the event to the + <parameter>drm_file</parameter> list of events to be signaled, and wake + up any waiting process. This can be performed with + <programlisting><![CDATA[ + struct timeval now; + + event->event.sequence = drm_vblank_count_and_time(..., &now); + event->event.tv_sec = now.tv_sec; + event->event.tv_usec = now.tv_usec; + + spin_lock_irqsave(&dev->event_lock, flags); + list_add_tail(&event->base.link, &event->base.file_priv->event_list); + wake_up_interruptible(&event->base.file_priv->event_wait); + spin_unlock_irqrestore(&dev->event_lock, flags); + ]]></programlisting> + </para> + <note><para> + FIXME: Could drivers that don't need to wait for rendering to complete + just add the event to <literal>dev->vblank_event_list</literal> and + let the DRM core handle everything, as for "normal" vertical blanking + events? + </para></note> + <para> + While waiting for the page flip to complete, the + <literal>event->base.link</literal> list head can be used freely by + the driver to store the pending event in a driver-specific list. + </para> + <para> + If the file handle is closed before the event is signaled, drivers must + take care to destroy the event in their + <methodname>preclose</methodname> operation (and, if needed, call + <function>drm_vblank_put</function>). + </para> + </sect4> + <sect4> + <title>Miscellaneous</title> + <itemizedlist> + <listitem> + <synopsis>void (*gamma_set)(struct drm_crtc *crtc, u16 *r, u16 *g, u16 *b, + uint32_t start, uint32_t size);</synopsis> + <para> + Apply a gamma table to the device. The operation is optional. + </para> + </listitem> + <listitem> + <synopsis>void (*destroy)(struct drm_crtc *crtc);</synopsis> + <para> + Destroy the CRTC when not needed anymore. See + <xref linkend="drm-kms-init"/>. + </para> + </listitem> + </itemizedlist> + </sect4> + </sect3> + </sect2> + <sect2> + <title>Planes (struct <structname>drm_plane</structname>)</title> + <para> + A plane represents an image source that can be blended with or overlayed + on top of a CRTC during the scanout process. Planes are associated with + a frame buffer to crop a portion of the image memory (source) and + optionally scale it to a destination size. The result is then blended + with or overlayed on top of a CRTC. + </para> + <sect3> + <title>Plane Initialization</title> + <para> + Planes are optional. To create a plane, a KMS drivers allocates and + zeroes an instances of struct <structname>drm_plane</structname> + (possibly as part of a larger structure) and registers it with a call + to <function>drm_plane_init</function>. The function takes a bitmask + of the CRTCs that can be associated with the plane, a pointer to the + plane functions and a list of format supported formats. + </para> + </sect3> + <sect3> + <title>Plane Operations</title> + <itemizedlist> + <listitem> + <synopsis>int (*update_plane)(struct drm_plane *plane, struct drm_crtc *crtc, + struct drm_framebuffer *fb, int crtc_x, int crtc_y, + unsigned int crtc_w, unsigned int crtc_h, + uint32_t src_x, uint32_t src_y, + uint32_t src_w, uint32_t src_h);</synopsis> + <para> + Enable and configure the plane to use the given CRTC and frame buffer. + </para> + <para> + The source rectangle in frame buffer memory coordinates is given by + the <parameter>src_x</parameter>, <parameter>src_y</parameter>, + <parameter>src_w</parameter> and <parameter>src_h</parameter> + parameters (as 16.16 fixed point values). Devices that don't support + subpixel plane coordinates can ignore the fractional part. + </para> + <para> + The destination rectangle in CRTC coordinates is given by the + <parameter>crtc_x</parameter>, <parameter>crtc_y</parameter>, + <parameter>crtc_w</parameter> and <parameter>crtc_h</parameter> + parameters (as integer values). Devices scale the source rectangle to + the destination rectangle. If scaling is not supported, and the source + rectangle size doesn't match the destination rectangle size, the + driver must return a -<errorname>EINVAL</errorname> error. + </para> + </listitem> + <listitem> + <synopsis>int (*disable_plane)(struct drm_plane *plane);</synopsis> + <para> + Disable the plane. The DRM core calls this method in response to a + DRM_IOCTL_MODE_SETPLANE ioctl call with the frame buffer ID set to 0. + Disabled planes must not be processed by the CRTC. + </para> + </listitem> + <listitem> + <synopsis>void (*destroy)(struct drm_plane *plane);</synopsis> + <para> + Destroy the plane when not needed anymore. See + <xref linkend="drm-kms-init"/>. + </para> + </listitem> + </itemizedlist> + </sect3> + </sect2> + <sect2> + <title>Encoders (struct <structname>drm_encoder</structname>)</title> + <para> + An encoder takes pixel data from a CRTC and converts it to a format + suitable for any attached connectors. On some devices, it may be + possible to have a CRTC send data to more than one encoder. In that + case, both encoders would receive data from the same scanout buffer, + resulting in a "cloned" display configuration across the connectors + attached to each encoder. + </para> + <sect3> + <title>Encoder Initialization</title> + <para> + As for CRTCs, a KMS driver must create, initialize and register at + least one struct <structname>drm_encoder</structname> instance. The + instance is allocated and zeroed by the driver, possibly as part of a + larger structure. + </para> + <para> + Drivers must initialize the struct <structname>drm_encoder</structname> + <structfield>possible_crtcs</structfield> and + <structfield>possible_clones</structfield> fields before registering the + encoder. Both fields are bitmasks of respectively the CRTCs that the + encoder can be connected to, and sibling encoders candidate for cloning. + </para> + <para> + After being initialized, the encoder must be registered with a call to + <function>drm_encoder_init</function>. The function takes a pointer to + the encoder functions and an encoder type. Supported types are + <itemizedlist> + <listitem> + DRM_MODE_ENCODER_DAC for VGA and analog on DVI-I/DVI-A + </listitem> + <listitem> + DRM_MODE_ENCODER_TMDS for DVI, HDMI and (embedded) DisplayPort + </listitem> + <listitem> + DRM_MODE_ENCODER_LVDS for display panels + </listitem> + <listitem> + DRM_MODE_ENCODER_TVDAC for TV output (Composite, S-Video, Component, + SCART) + </listitem> + <listitem> + DRM_MODE_ENCODER_VIRTUAL for virtual machine displays + </listitem> + </itemizedlist> + </para> + <para> + Encoders must be attached to a CRTC to be used. DRM drivers leave + encoders unattached at initialization time. Applications (or the fbdev + compatibility layer when implemented) are responsible for attaching the + encoders they want to use to a CRTC. + </para> + </sect3> + <sect3> + <title>Encoder Operations</title> + <itemizedlist> + <listitem> + <synopsis>void (*destroy)(struct drm_encoder *encoder);</synopsis> + <para> + Called to destroy the encoder when not needed anymore. See + <xref linkend="drm-kms-init"/>. + </para> + </listitem> + </itemizedlist> + </sect3> + </sect2> + <sect2> + <title>Connectors (struct <structname>drm_connector</structname>)</title> + <para> + A connector is the final destination for pixel data on a device, and + usually connects directly to an external display device like a monitor + or laptop panel. A connector can only be attached to one encoder at a + time. The connector is also the structure where information about the + attached display is kept, so it contains fields for display data, EDID + data, DPMS & connection status, and information about modes + supported on the attached displays. + </para> + <sect3> + <title>Connector Initialization</title> + <para> + Finally a KMS driver must create, initialize, register and attach at + least one struct <structname>drm_connector</structname> instance. The + instance is created as other KMS objects and initialized by setting the + following fields. + </para> + <variablelist> + <varlistentry> + <term><structfield>interlace_allowed</structfield></term> + <listitem><para> + Whether the connector can handle interlaced modes. + </para></listitem> + </varlistentry> + <varlistentry> + <term><structfield>doublescan_allowed</structfield></term> + <listitem><para> + Whether the connector can handle doublescan. + </para></listitem> + </varlistentry> + <varlistentry> + <term><structfield>display_info + </structfield></term> + <listitem><para> + Display information is filled from EDID information when a display + is detected. For non hot-pluggable displays such as flat panels in + embedded systems, the driver should initialize the + <structfield>display_info</structfield>.<structfield>width_mm</structfield> + and + <structfield>display_info</structfield>.<structfield>height_mm</structfield> + fields with the physical size of the display. + </para></listitem> + </varlistentry> + <varlistentry> + <term id="drm-kms-connector-polled"><structfield>polled</structfield></term> + <listitem><para> + Connector polling mode, a combination of + <variablelist> + <varlistentry> + <term>DRM_CONNECTOR_POLL_HPD</term> + <listitem><para> + The connector generates hotplug events and doesn't need to be + periodically polled. The CONNECT and DISCONNECT flags must not + be set together with the HPD flag. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_CONNECTOR_POLL_CONNECT</term> + <listitem><para> + Periodically poll the connector for connection. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_CONNECTOR_POLL_DISCONNECT</term> + <listitem><para> + Periodically poll the connector for disconnection. + </para></listitem> + </varlistentry> + </variablelist> + Set to 0 for connectors that don't support connection status + discovery. + </para></listitem> + </varlistentry> + </variablelist> + <para> + The connector is then registered with a call to + <function>drm_connector_init</function> with a pointer to the connector + functions and a connector type, and exposed through sysfs with a call to + <function>drm_sysfs_connector_add</function>. + </para> + <para> + Supported connector types are + <itemizedlist> + <listitem>DRM_MODE_CONNECTOR_VGA</listitem> + <listitem>DRM_MODE_CONNECTOR_DVII</listitem> + <listitem>DRM_MODE_CONNECTOR_DVID</listitem> + <listitem>DRM_MODE_CONNECTOR_DVIA</listitem> + <listitem>DRM_MODE_CONNECTOR_Composite</listitem> + <listitem>DRM_MODE_CONNECTOR_SVIDEO</listitem> + <listitem>DRM_MODE_CONNECTOR_LVDS</listitem> + <listitem>DRM_MODE_CONNECTOR_Component</listitem> + <listitem>DRM_MODE_CONNECTOR_9PinDIN</listitem> + <listitem>DRM_MODE_CONNECTOR_DisplayPort</listitem> + <listitem>DRM_MODE_CONNECTOR_HDMIA</listitem> + <listitem>DRM_MODE_CONNECTOR_HDMIB</listitem> + <listitem>DRM_MODE_CONNECTOR_TV</listitem> + <listitem>DRM_MODE_CONNECTOR_eDP</listitem> + <listitem>DRM_MODE_CONNECTOR_VIRTUAL</listitem> + </itemizedlist> + </para> + <para> + Connectors must be attached to an encoder to be used. For devices that + map connectors to encoders 1:1, the connector should be attached at + initialization time with a call to + <function>drm_mode_connector_attach_encoder</function>. The driver must + also set the <structname>drm_connector</structname> + <structfield>encoder</structfield> field to point to the attached + encoder. + </para> + <para> + Finally, drivers must initialize the connectors state change detection + with a call to <function>drm_kms_helper_poll_init</function>. If at + least one connector is pollable but can't generate hotplug interrupts + (indicated by the DRM_CONNECTOR_POLL_CONNECT and + DRM_CONNECTOR_POLL_DISCONNECT connector flags), a delayed work will + automatically be queued to periodically poll for changes. Connectors + that can generate hotplug interrupts must be marked with the + DRM_CONNECTOR_POLL_HPD flag instead, and their interrupt handler must + call <function>drm_helper_hpd_irq_event</function>. The function will + queue a delayed work to check the state of all connectors, but no + periodic polling will be done. + </para> + </sect3> + <sect3> + <title>Connector Operations</title> + <note><para> + Unless otherwise state, all operations are mandatory. + </para></note> + <sect4> + <title>DPMS</title> + <synopsis>void (*dpms)(struct drm_connector *connector, int mode);</synopsis> + <para> + The DPMS operation sets the power state of a connector. The mode + argument is one of + <itemizedlist> + <listitem><para>DRM_MODE_DPMS_ON</para></listitem> + <listitem><para>DRM_MODE_DPMS_STANDBY</para></listitem> + <listitem><para>DRM_MODE_DPMS_SUSPEND</para></listitem> + <listitem><para>DRM_MODE_DPMS_OFF</para></listitem> + </itemizedlist> + </para> + <para> + In all but DPMS_ON mode the encoder to which the connector is attached + should put the display in low-power mode by driving its signals + appropriately. If more than one connector is attached to the encoder + care should be taken not to change the power state of other displays as + a side effect. Low-power mode should be propagated to the encoders and + CRTCs when all related connectors are put in low-power mode. + </para> + </sect4> + <sect4> + <title>Modes</title> + <synopsis>int (*fill_modes)(struct drm_connector *connector, uint32_t max_width, + uint32_t max_height);</synopsis> + <para> + Fill the mode list with all supported modes for the connector. If the + <parameter>max_width</parameter> and <parameter>max_height</parameter> + arguments are non-zero, the implementation must ignore all modes wider + than <parameter>max_width</parameter> or higher than + <parameter>max_height</parameter>. + </para> + <para> + The connector must also fill in this operation its + <structfield>display_info</structfield> + <structfield>width_mm</structfield> and + <structfield>height_mm</structfield> fields with the connected display + physical size in millimeters. The fields should be set to 0 if the value + isn't known or is not applicable (for instance for projector devices). + </para> + </sect4> + <sect4> + <title>Connection Status</title> + <para> + The connection status is updated through polling or hotplug events when + supported (see <xref linkend="drm-kms-connector-polled"/>). The status + value is reported to userspace through ioctls and must not be used + inside the driver, as it only gets initialized by a call to + <function>drm_mode_getconnector</function> from userspace. + </para> + <synopsis>enum drm_connector_status (*detect)(struct drm_connector *connector, + bool force);</synopsis> + <para> + Check to see if anything is attached to the connector. The + <parameter>force</parameter> parameter is set to false whilst polling or + to true when checking the connector due to user request. + <parameter>force</parameter> can be used by the driver to avoid + expensive, destructive operations during automated probing. + </para> + <para> + Return connector_status_connected if something is connected to the + connector, connector_status_disconnected if nothing is connected and + connector_status_unknown if the connection state isn't known. + </para> + <para> + Drivers should only return connector_status_connected if the connection + status has really been probed as connected. Connectors that can't detect + the connection status, or failed connection status probes, should return + connector_status_unknown. + </para> + </sect4> + <sect4> + <title>Miscellaneous</title> + <itemizedlist> + <listitem> + <synopsis>void (*destroy)(struct drm_connector *connector);</synopsis> + <para> + Destroy the connector when not needed anymore. See + <xref linkend="drm-kms-init"/>. + </para> + </listitem> + </itemizedlist> + </sect4> + </sect3> + </sect2> + <sect2> + <title>Cleanup</title> + <para> + The DRM core manages its objects' lifetime. When an object is not needed + anymore the core calls its destroy function, which must clean up and + free every resource allocated for the object. Every + <function>drm_*_init</function> call must be matched with a + corresponding <function>drm_*_cleanup</function> call to cleanup CRTCs + (<function>drm_crtc_cleanup</function>), planes + (<function>drm_plane_cleanup</function>), encoders + (<function>drm_encoder_cleanup</function>) and connectors + (<function>drm_connector_cleanup</function>). Furthermore, connectors + that have been added to sysfs must be removed by a call to + <function>drm_sysfs_connector_remove</function> before calling + <function>drm_connector_cleanup</function>. + </para> + <para> + Connectors state change detection must be cleanup up with a call to + <function>drm_kms_helper_poll_fini</function>. + </para> + </sect2> + <sect2> + <title>Output discovery and initialization example</title> + <programlisting><![CDATA[ void intel_crt_init(struct drm_device *dev) { struct drm_connector *connector; @@ -556,252 +1610,741 @@ void intel_crt_init(struct drm_device *dev) drm_connector_helper_add(connector, &intel_crt_connector_helper_funcs); drm_sysfs_connector_add(connector); -} -]]> - </programlisting> - <para> - In the example above (again, taken from the i915 driver), a - CRT connector and encoder combination is created. A device-specific - i2c bus is also created for fetching EDID data and - performing monitor detection. Once the process is complete, - the new connector is registered with sysfs to make its - properties available to applications. - </para> - <sect4> - <title>Helper functions and core functions</title> - <para> - Since many PC-class graphics devices have similar display output - designs, the DRM provides a set of helper functions to make - output management easier. The core helper routines handle - encoder re-routing and the disabling of unused functions following - mode setting. Using the helpers is optional, but recommended for - devices with PC-style architectures (i.e. a set of display planes - for feeding pixels to encoders which are in turn routed to - connectors). Devices with more complex requirements needing - finer grained management may opt to use the core callbacks - directly. - </para> - <para> - [Insert typical diagram here.] [Insert OMAP style config here.] - </para> - </sect4> - <para> - Each encoder object needs to provide: - <itemizedlist> - <listitem> - A DPMS (basically on/off) function. - </listitem> - <listitem> - A mode-fixup function (for converting requested modes into - native hardware timings). - </listitem> - <listitem> - Functions (prepare, set, and commit) for use by the core DRM - helper functions. - </listitem> - </itemizedlist> - Connector helpers need to provide functions (mode-fetch, validity, - and encoder-matching) for returning an ideal encoder for a given - connector. The core connector functions include a DPMS callback, - save/restore routines (deprecated), detection, mode probing, - property handling, and cleanup functions. - </para> -<!--!Edrivers/char/drm/drm_crtc.h--> -<!--!Edrivers/char/drm/drm_crtc.c--> -<!--!Edrivers/char/drm/drm_crtc_helper.c--> - </sect3> +}]]></programlisting> + <para> + In the example above (taken from the i915 driver), a CRTC, connector and + encoder combination is created. A device-specific i2c bus is also + created for fetching EDID data and performing monitor detection. Once + the process is complete, the new connector is registered with sysfs to + make its properties available to applications. + </para> </sect2> </sect1> - <!-- Internals: vblank handling --> + <!-- Internals: mid-layer helper functions --> <sect1> - <title>VBlank event handling</title> + <title>Mid-layer Helper Functions</title> <para> - The DRM core exposes two vertical blank related ioctls: - <variablelist> - <varlistentry> - <term>DRM_IOCTL_WAIT_VBLANK</term> - <listitem> - <para> - This takes a struct drm_wait_vblank structure as its argument, - and it is used to block or request a signal when a specified - vblank event occurs. - </para> - </listitem> - </varlistentry> - <varlistentry> - <term>DRM_IOCTL_MODESET_CTL</term> - <listitem> - <para> - This should be called by application level drivers before and - after mode setting, since on many devices the vertical blank - counter is reset at that time. Internally, the DRM snapshots - the last vblank count when the ioctl is called with the - _DRM_PRE_MODESET command, so that the counter won't go backwards - (which is dealt with when _DRM_POST_MODESET is used). - </para> - </listitem> - </varlistentry> - </variablelist> -<!--!Edrivers/char/drm/drm_irq.c--> + The CRTC, encoder and connector functions provided by the drivers + implement the DRM API. They're called by the DRM core and ioctl handlers + to handle device state changes and configuration request. As implementing + those functions often requires logic not specific to drivers, mid-layer + helper functions are available to avoid duplicating boilerplate code. + </para> + <para> + The DRM core contains one mid-layer implementation. The mid-layer provides + implementations of several CRTC, encoder and connector functions (called + from the top of the mid-layer) that pre-process requests and call + lower-level functions provided by the driver (at the bottom of the + mid-layer). For instance, the + <function>drm_crtc_helper_set_config</function> function can be used to + fill the struct <structname>drm_crtc_funcs</structname> + <structfield>set_config</structfield> field. When called, it will split + the <methodname>set_config</methodname> operation in smaller, simpler + operations and call the driver to handle them. </para> <para> - To support the functions above, the DRM core provides several - helper functions for tracking vertical blank counters, and - requires drivers to provide several callbacks: - get_vblank_counter(), enable_vblank() and disable_vblank(). The - core uses get_vblank_counter() to keep the counter accurate - across interrupt disable periods. It should return the current - vertical blank event count, which is often tracked in a device - register. The enable and disable vblank callbacks should enable - and disable vertical blank interrupts, respectively. In the - absence of DRM clients waiting on vblank events, the core DRM - code uses the disable_vblank() function to disable - interrupts, which saves power. They are re-enabled again when - a client calls the vblank wait ioctl above. + To use the mid-layer, drivers call <function>drm_crtc_helper_add</function>, + <function>drm_encoder_helper_add</function> and + <function>drm_connector_helper_add</function> functions to install their + mid-layer bottom operations handlers, and fill the + <structname>drm_crtc_funcs</structname>, + <structname>drm_encoder_funcs</structname> and + <structname>drm_connector_funcs</structname> structures with pointers to + the mid-layer top API functions. Installing the mid-layer bottom operation + handlers is best done right after registering the corresponding KMS object. </para> <para> - A device that doesn't provide a count register may simply use an - internal atomic counter incremented on every vertical blank - interrupt (and then treat the enable_vblank() and disable_vblank() - callbacks as no-ops). + The mid-layer is not split between CRTC, encoder and connector operations. + To use it, a driver must provide bottom functions for all of the three KMS + entities. </para> + <sect2> + <title>Helper Functions</title> + <itemizedlist> + <listitem> + <synopsis>int drm_crtc_helper_set_config(struct drm_mode_set *set);</synopsis> + <para> + The <function>drm_crtc_helper_set_config</function> helper function + is a CRTC <methodname>set_config</methodname> implementation. It + first tries to locate the best encoder for each connector by calling + the connector <methodname>best_encoder</methodname> helper + operation. + </para> + <para> + After locating the appropriate encoders, the helper function will + call the <methodname>mode_fixup</methodname> encoder and CRTC helper + operations to adjust the requested mode, or reject it completely in + which case an error will be returned to the application. If the new + configuration after mode adjustment is identical to the current + configuration the helper function will return without performing any + other operation. + </para> + <para> + If the adjusted mode is identical to the current mode but changes to + the frame buffer need to be applied, the + <function>drm_crtc_helper_set_config</function> function will call + the CRTC <methodname>mode_set_base</methodname> helper operation. If + the adjusted mode differs from the current mode, or if the + <methodname>mode_set_base</methodname> helper operation is not + provided, the helper function performs a full mode set sequence by + calling the <methodname>prepare</methodname>, + <methodname>mode_set</methodname> and + <methodname>commit</methodname> CRTC and encoder helper operations, + in that order. + </para> + </listitem> + <listitem> + <synopsis>void drm_helper_connector_dpms(struct drm_connector *connector, int mode);</synopsis> + <para> + The <function>drm_helper_connector_dpms</function> helper function + is a connector <methodname>dpms</methodname> implementation that + tracks power state of connectors. To use the function, drivers must + provide <methodname>dpms</methodname> helper operations for CRTCs + and encoders to apply the DPMS state to the device. + </para> + <para> + The mid-layer doesn't track the power state of CRTCs and encoders. + The <methodname>dpms</methodname> helper operations can thus be + called with a mode identical to the currently active mode. + </para> + </listitem> + <listitem> + <synopsis>int drm_helper_probe_single_connector_modes(struct drm_connector *connector, + uint32_t maxX, uint32_t maxY);</synopsis> + <para> + The <function>drm_helper_probe_single_connector_modes</function> helper + function is a connector <methodname>fill_modes</methodname> + implementation that updates the connection status for the connector + and then retrieves a list of modes by calling the connector + <methodname>get_modes</methodname> helper operation. + </para> + <para> + The function filters out modes larger than + <parameter>max_width</parameter> and <parameter>max_height</parameter> + if specified. It then calls the connector + <methodname>mode_valid</methodname> helper operation for each mode in + the probed list to check whether the mode is valid for the connector. + </para> + </listitem> + </itemizedlist> + </sect2> + <sect2> + <title>CRTC Helper Operations</title> + <itemizedlist> + <listitem id="drm-helper-crtc-mode-fixup"> + <synopsis>bool (*mode_fixup)(struct drm_crtc *crtc, + const struct drm_display_mode *mode, + struct drm_display_mode *adjusted_mode);</synopsis> + <para> + Let CRTCs adjust the requested mode or reject it completely. This + operation returns true if the mode is accepted (possibly after being + adjusted) or false if it is rejected. + </para> + <para> + The <methodname>mode_fixup</methodname> operation should reject the + mode if it can't reasonably use it. The definition of "reasonable" + is currently fuzzy in this context. One possible behaviour would be + to set the adjusted mode to the panel timings when a fixed-mode + panel is used with hardware capable of scaling. Another behaviour + would be to accept any input mode and adjust it to the closest mode + supported by the hardware (FIXME: This needs to be clarified). + </para> + </listitem> + <listitem> + <synopsis>int (*mode_set_base)(struct drm_crtc *crtc, int x, int y, + struct drm_framebuffer *old_fb)</synopsis> + <para> + Move the CRTC on the current frame buffer (stored in + <literal>crtc->fb</literal>) to position (x,y). Any of the frame + buffer, x position or y position may have been modified. + </para> + <para> + This helper operation is optional. If not provided, the + <function>drm_crtc_helper_set_config</function> function will fall + back to the <methodname>mode_set</methodname> helper operation. + </para> + <note><para> + FIXME: Why are x and y passed as arguments, as they can be accessed + through <literal>crtc->x</literal> and + <literal>crtc->y</literal>? + </para></note> + </listitem> + <listitem> + <synopsis>void (*prepare)(struct drm_crtc *crtc);</synopsis> + <para> + Prepare the CRTC for mode setting. This operation is called after + validating the requested mode. Drivers use it to perform + device-specific operations required before setting the new mode. + </para> + </listitem> + <listitem> + <synopsis>int (*mode_set)(struct drm_crtc *crtc, struct drm_display_mode *mode, + struct drm_display_mode *adjusted_mode, int x, int y, + struct drm_framebuffer *old_fb);</synopsis> + <para> + Set a new mode, position and frame buffer. Depending on the device + requirements, the mode can be stored internally by the driver and + applied in the <methodname>commit</methodname> operation, or + programmed to the hardware immediately. + </para> + <para> + The <methodname>mode_set</methodname> operation returns 0 on success + or a negative error code if an error occurs. + </para> + </listitem> + <listitem> + <synopsis>void (*commit)(struct drm_crtc *crtc);</synopsis> + <para> + Commit a mode. This operation is called after setting the new mode. + Upon return the device must use the new mode and be fully + operational. + </para> + </listitem> + </itemizedlist> + </sect2> + <sect2> + <title>Encoder Helper Operations</title> + <itemizedlist> + <listitem> + <synopsis>bool (*mode_fixup)(struct drm_encoder *encoder, + const struct drm_display_mode *mode, + struct drm_display_mode *adjusted_mode);</synopsis> + <note><para> + FIXME: The mode argument be const, but the i915 driver modifies + mode->clock in <function>intel_dp_mode_fixup</function>. + </para></note> + <para> + Let encoders adjust the requested mode or reject it completely. This + operation returns true if the mode is accepted (possibly after being + adjusted) or false if it is rejected. See the + <link linkend="drm-helper-crtc-mode-fixup">mode_fixup CRTC helper + operation</link> for an explanation of the allowed adjustments. + </para> + </listitem> + <listitem> + <synopsis>void (*prepare)(struct drm_encoder *encoder);</synopsis> + <para> + Prepare the encoder for mode setting. This operation is called after + validating the requested mode. Drivers use it to perform + device-specific operations required before setting the new mode. + </para> + </listitem> + <listitem> + <synopsis>void (*mode_set)(struct drm_encoder *encoder, + struct drm_display_mode *mode, + struct drm_display_mode *adjusted_mode);</synopsis> + <para> + Set a new mode. Depending on the device requirements, the mode can + be stored internally by the driver and applied in the + <methodname>commit</methodname> operation, or programmed to the + hardware immediately. + </para> + </listitem> + <listitem> + <synopsis>void (*commit)(struct drm_encoder *encoder);</synopsis> + <para> + Commit a mode. This operation is called after setting the new mode. + Upon return the device must use the new mode and be fully + operational. + </para> + </listitem> + </itemizedlist> + </sect2> + <sect2> + <title>Connector Helper Operations</title> + <itemizedlist> + <listitem> + <synopsis>struct drm_encoder *(*best_encoder)(struct drm_connector *connector);</synopsis> + <para> + Return a pointer to the best encoder for the connecter. Device that + map connectors to encoders 1:1 simply return the pointer to the + associated encoder. This operation is mandatory. + </para> + </listitem> + <listitem> + <synopsis>int (*get_modes)(struct drm_connector *connector);</synopsis> + <para> + Fill the connector's <structfield>probed_modes</structfield> list + by parsing EDID data with <function>drm_add_edid_modes</function> or + calling <function>drm_mode_probed_add</function> directly for every + supported mode and return the number of modes it has detected. This + operation is mandatory. + </para> + <para> + When adding modes manually the driver creates each mode with a call to + <function>drm_mode_create</function> and must fill the following fields. + <itemizedlist> + <listitem> + <synopsis>__u32 type;</synopsis> + <para> + Mode type bitmask, a combination of + <variablelist> + <varlistentry> + <term>DRM_MODE_TYPE_BUILTIN</term> + <listitem><para>not used?</para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_TYPE_CLOCK_C</term> + <listitem><para>not used?</para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_TYPE_CRTC_C</term> + <listitem><para>not used?</para></listitem> + </varlistentry> + <varlistentry> + <term> + DRM_MODE_TYPE_PREFERRED - The preferred mode for the connector + </term> + <listitem> + <para>not used?</para> + </listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_TYPE_DEFAULT</term> + <listitem><para>not used?</para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_TYPE_USERDEF</term> + <listitem><para>not used?</para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_TYPE_DRIVER</term> + <listitem> + <para> + The mode has been created by the driver (as opposed to + to user-created modes). + </para> + </listitem> + </varlistentry> + </variablelist> + Drivers must set the DRM_MODE_TYPE_DRIVER bit for all modes they + create, and set the DRM_MODE_TYPE_PREFERRED bit for the preferred + mode. + </para> + </listitem> + <listitem> + <synopsis>__u32 clock;</synopsis> + <para>Pixel clock frequency in kHz unit</para> + </listitem> + <listitem> + <synopsis>__u16 hdisplay, hsync_start, hsync_end, htotal; + __u16 vdisplay, vsync_start, vsync_end, vtotal;</synopsis> + <para>Horizontal and vertical timing information</para> + <screen><![CDATA[ + Active Front Sync Back + Region Porch Porch + <-----------------------><----------------><-------------><--------------> + + //////////////////////| + ////////////////////// | + ////////////////////// |.................. ................ + _______________ + + <----- [hv]display -----> + <------------- [hv]sync_start ------------> + <--------------------- [hv]sync_end ---------------------> + <-------------------------------- [hv]total -----------------------------> +]]></screen> + </listitem> + <listitem> + <synopsis>__u16 hskew; + __u16 vscan;</synopsis> + <para>Unknown</para> + </listitem> + <listitem> + <synopsis>__u32 flags;</synopsis> + <para> + Mode flags, a combination of + <variablelist> + <varlistentry> + <term>DRM_MODE_FLAG_PHSYNC</term> + <listitem><para> + Horizontal sync is active high + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_NHSYNC</term> + <listitem><para> + Horizontal sync is active low + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_PVSYNC</term> + <listitem><para> + Vertical sync is active high + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_NVSYNC</term> + <listitem><para> + Vertical sync is active low + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_INTERLACE</term> + <listitem><para> + Mode is interlaced + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_DBLSCAN</term> + <listitem><para> + Mode uses doublescan + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_CSYNC</term> + <listitem><para> + Mode uses composite sync + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_PCSYNC</term> + <listitem><para> + Composite sync is active high + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_NCSYNC</term> + <listitem><para> + Composite sync is active low + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_HSKEW</term> + <listitem><para> + hskew provided (not used?) + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_BCAST</term> + <listitem><para> + not used? + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_PIXMUX</term> + <listitem><para> + not used? + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_DBLCLK</term> + <listitem><para> + not used? + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_FLAG_CLKDIV2</term> + <listitem><para> + ? + </para></listitem> + </varlistentry> + </variablelist> + </para> + <para> + Note that modes marked with the INTERLACE or DBLSCAN flags will be + filtered out by + <function>drm_helper_probe_single_connector_modes</function> if + the connector's <structfield>interlace_allowed</structfield> or + <structfield>doublescan_allowed</structfield> field is set to 0. + </para> + </listitem> + <listitem> + <synopsis>char name[DRM_DISPLAY_MODE_LEN];</synopsis> + <para> + Mode name. The driver must call + <function>drm_mode_set_name</function> to fill the mode name from + <structfield>hdisplay</structfield>, + <structfield>vdisplay</structfield> and interlace flag after + filling the corresponding fields. + </para> + </listitem> + </itemizedlist> + </para> + <para> + The <structfield>vrefresh</structfield> value is computed by + <function>drm_helper_probe_single_connector_modes</function>. + </para> + <para> + When parsing EDID data, <function>drm_add_edid_modes</function> fill the + connector <structfield>display_info</structfield> + <structfield>width_mm</structfield> and + <structfield>height_mm</structfield> fields. When creating modes + manually the <methodname>get_modes</methodname> helper operation must + set the <structfield>display_info</structfield> + <structfield>width_mm</structfield> and + <structfield>height_mm</structfield> fields if they haven't been set + already (for instance at initilization time when a fixed-size panel is + attached to the connector). The mode <structfield>width_mm</structfield> + and <structfield>height_mm</structfield> fields are only used internally + during EDID parsing and should not be set when creating modes manually. + </para> + </listitem> + <listitem> + <synopsis>int (*mode_valid)(struct drm_connector *connector, + struct drm_display_mode *mode);</synopsis> + <para> + Verify whether a mode is valid for the connector. Return MODE_OK for + supported modes and one of the enum drm_mode_status values (MODE_*) + for unsupported modes. This operation is mandatory. + </para> + <para> + As the mode rejection reason is currently not used beside for + immediately removing the unsupported mode, an implementation can + return MODE_BAD regardless of the exact reason why the mode is not + valid. + </para> + <note><para> + Note that the <methodname>mode_valid</methodname> helper operation is + only called for modes detected by the device, and + <emphasis>not</emphasis> for modes set by the user through the CRTC + <methodname>set_config</methodname> operation. + </para></note> + </listitem> + </itemizedlist> + </sect2> </sect1> - <sect1> - <title>Memory management</title> + <!-- Internals: vertical blanking --> + + <sect1 id="drm-vertical-blank"> + <title>Vertical Blanking</title> + <para> + Vertical blanking plays a major role in graphics rendering. To achieve + tear-free display, users must synchronize page flips and/or rendering to + vertical blanking. The DRM API offers ioctls to perform page flips + synchronized to vertical blanking and wait for vertical blanking. + </para> + <para> + The DRM core handles most of the vertical blanking management logic, which + involves filtering out spurious interrupts, keeping race-free blanking + counters, coping with counter wrap-around and resets and keeping use + counts. It relies on the driver to generate vertical blanking interrupts + and optionally provide a hardware vertical blanking counter. Drivers must + implement the following operations. + </para> + <itemizedlist> + <listitem> + <synopsis>int (*enable_vblank) (struct drm_device *dev, int crtc); +void (*disable_vblank) (struct drm_device *dev, int crtc);</synopsis> + <para> + Enable or disable vertical blanking interrupts for the given CRTC. + </para> + </listitem> + <listitem> + <synopsis>u32 (*get_vblank_counter) (struct drm_device *dev, int crtc);</synopsis> + <para> + Retrieve the value of the vertical blanking counter for the given + CRTC. If the hardware maintains a vertical blanking counter its value + should be returned. Otherwise drivers can use the + <function>drm_vblank_count</function> helper function to handle this + operation. + </para> + </listitem> + </itemizedlist> <para> - The memory manager lies at the heart of many DRM operations; it - is required to support advanced client features like OpenGL - pbuffers. The DRM currently contains two memory managers: TTM - and GEM. + Drivers must initialize the vertical blanking handling core with a call to + <function>drm_vblank_init</function> in their + <methodname>load</methodname> operation. The function will set the struct + <structname>drm_device</structname> + <structfield>vblank_disable_allowed</structfield> field to 0. This will + keep vertical blanking interrupts enabled permanently until the first mode + set operation, where <structfield>vblank_disable_allowed</structfield> is + set to 1. The reason behind this is not clear. Drivers can set the field + to 1 after <function>calling drm_vblank_init</function> to make vertical + blanking interrupts dynamically managed from the beginning. </para> + <para> + Vertical blanking interrupts can be enabled by the DRM core or by drivers + themselves (for instance to handle page flipping operations). The DRM core + maintains a vertical blanking use count to ensure that the interrupts are + not disabled while a user still needs them. To increment the use count, + drivers call <function>drm_vblank_get</function>. Upon return vertical + blanking interrupts are guaranteed to be enabled. + </para> + <para> + To decrement the use count drivers call + <function>drm_vblank_put</function>. Only when the use count drops to zero + will the DRM core disable the vertical blanking interrupts after a delay + by scheduling a timer. The delay is accessible through the vblankoffdelay + module parameter or the <varname>drm_vblank_offdelay</varname> global + variable and expressed in milliseconds. Its default value is 5000 ms. + </para> + <para> + When a vertical blanking interrupt occurs drivers only need to call the + <function>drm_handle_vblank</function> function to account for the + interrupt. + </para> + <para> + Resources allocated by <function>drm_vblank_init</function> must be freed + with a call to <function>drm_vblank_cleanup</function> in the driver + <methodname>unload</methodname> operation handler. + </para> + </sect1> + + <!-- Internals: open/close, file operations and ioctls --> + <sect1> + <title>Open/Close, File Operations and IOCTLs</title> <sect2> - <title>The Translation Table Manager (TTM)</title> + <title>Open and Close</title> + <synopsis>int (*firstopen) (struct drm_device *); +void (*lastclose) (struct drm_device *); +int (*open) (struct drm_device *, struct drm_file *); +void (*preclose) (struct drm_device *, struct drm_file *); +void (*postclose) (struct drm_device *, struct drm_file *);</synopsis> + <abstract>Open and close handlers. None of those methods are mandatory. + </abstract> <para> - TTM was developed by Tungsten Graphics, primarily by Thomas - Hellström, and is intended to be a flexible, high performance - graphics memory manager. + The <methodname>firstopen</methodname> method is called by the DRM core + when an application opens a device that has no other opened file handle. + Similarly the <methodname>lastclose</methodname> method is called when + the last application holding a file handle opened on the device closes + it. Both methods are mostly used for UMS (User Mode Setting) drivers to + acquire and release device resources which should be done in the + <methodname>load</methodname> and <methodname>unload</methodname> + methods for KMS drivers. </para> <para> - Drivers wishing to support TTM must fill out a drm_bo_driver - structure. + Note that the <methodname>lastclose</methodname> method is also called + at module unload time or, for hot-pluggable devices, when the device is + unplugged. The <methodname>firstopen</methodname> and + <methodname>lastclose</methodname> calls can thus be unbalanced. </para> <para> - TTM design background and information belongs here. + The <methodname>open</methodname> method is called every time the device + is opened by an application. Drivers can allocate per-file private data + in this method and store them in the struct + <structname>drm_file</structname> <structfield>driver_priv</structfield> + field. Note that the <methodname>open</methodname> method is called + before <methodname>firstopen</methodname>. + </para> + <para> + The close operation is split into <methodname>preclose</methodname> and + <methodname>postclose</methodname> methods. Drivers must stop and + cleanup all per-file operations in the <methodname>preclose</methodname> + method. For instance pending vertical blanking and page flip events must + be cancelled. No per-file operation is allowed on the file handle after + returning from the <methodname>preclose</methodname> method. + </para> + <para> + Finally the <methodname>postclose</methodname> method is called as the + last step of the close operation, right before calling the + <methodname>lastclose</methodname> method if no other open file handle + exists for the device. Drivers that have allocated per-file private data + in the <methodname>open</methodname> method should free it here. + </para> + <para> + The <methodname>lastclose</methodname> method should restore CRTC and + plane properties to default value, so that a subsequent open of the + device will not inherit state from the previous user. </para> </sect2> - <sect2> - <title>The Graphics Execution Manager (GEM)</title> + <title>File Operations</title> + <synopsis>const struct file_operations *fops</synopsis> + <abstract>File operations for the DRM device node.</abstract> <para> - GEM is an Intel project, authored by Eric Anholt and Keith - Packard. It provides simpler interfaces than TTM, and is well - suited for UMA devices. + Drivers must define the file operations structure that forms the DRM + userspace API entry point, even though most of those operations are + implemented in the DRM core. The <methodname>open</methodname>, + <methodname>release</methodname> and <methodname>ioctl</methodname> + operations are handled by + <programlisting> + .owner = THIS_MODULE, + .open = drm_open, + .release = drm_release, + .unlocked_ioctl = drm_ioctl, + #ifdef CONFIG_COMPAT + .compat_ioctl = drm_compat_ioctl, + #endif + </programlisting> </para> <para> - GEM-enabled drivers must provide gem_init_object() and - gem_free_object() callbacks to support the core memory - allocation routines. They should also provide several driver-specific - ioctls to support command execution, pinning, buffer - read & write, mapping, and domain ownership transfers. + Drivers that implement private ioctls that requires 32/64bit + compatibility support must provide their own + <methodname>compat_ioctl</methodname> handler that processes private + ioctls and calls <function>drm_compat_ioctl</function> for core ioctls. </para> <para> - On a fundamental level, GEM involves several operations: - <itemizedlist> - <listitem>Memory allocation and freeing</listitem> - <listitem>Command execution</listitem> - <listitem>Aperture management at command execution time</listitem> - </itemizedlist> - Buffer object allocation is relatively - straightforward and largely provided by Linux's shmem layer, which - provides memory to back each object. When mapped into the GTT - or used in a command buffer, the backing pages for an object are - flushed to memory and marked write combined so as to be coherent - with the GPU. Likewise, if the CPU accesses an object after the GPU - has finished rendering to the object, then the object must be made - coherent with the CPU's view - of memory, usually involving GPU cache flushing of various kinds. - This core CPU<->GPU coherency management is provided by a - device-specific ioctl, which evaluates an object's current domain and - performs any necessary flushing or synchronization to put the object - into the desired coherency domain (note that the object may be busy, - i.e. an active render target; in that case, setting the domain - blocks the client and waits for rendering to complete before - performing any necessary flushing operations). - </para> - <para> - Perhaps the most important GEM function is providing a command - execution interface to clients. Client programs construct command - buffers containing references to previously allocated memory objects, - and then submit them to GEM. At that point, GEM takes care to bind - all the objects into the GTT, execute the buffer, and provide - necessary synchronization between clients accessing the same buffers. - This often involves evicting some objects from the GTT and re-binding - others (a fairly expensive operation), and providing relocation - support which hides fixed GTT offsets from clients. Clients must - take care not to submit command buffers that reference more objects - than can fit in the GTT; otherwise, GEM will reject them and no rendering - will occur. Similarly, if several objects in the buffer require - fence registers to be allocated for correct rendering (e.g. 2D blits - on pre-965 chips), care must be taken not to require more fence - registers than are available to the client. Such resource management - should be abstracted from the client in libdrm. + The <methodname>read</methodname> and <methodname>poll</methodname> + operations provide support for reading DRM events and polling them. They + are implemented by + <programlisting> + .poll = drm_poll, + .read = drm_read, + .fasync = drm_fasync, + .llseek = no_llseek, + </programlisting> + </para> + <para> + The memory mapping implementation varies depending on how the driver + manages memory. Pre-GEM drivers will use <function>drm_mmap</function>, + while GEM-aware drivers will use <function>drm_gem_mmap</function>. See + <xref linkend="drm-gem"/>. + <programlisting> + .mmap = drm_gem_mmap, + </programlisting> + </para> + <para> + No other file operation is supported by the DRM API. + </para> + </sect2> + <sect2> + <title>IOCTLs</title> + <synopsis>struct drm_ioctl_desc *ioctls; +int num_ioctls;</synopsis> + <abstract>Driver-specific ioctls descriptors table.</abstract> + <para> + Driver-specific ioctls numbers start at DRM_COMMAND_BASE. The ioctls + descriptors table is indexed by the ioctl number offset from the base + value. Drivers can use the DRM_IOCTL_DEF_DRV() macro to initialize the + table entries. + </para> + <para> + <programlisting>DRM_IOCTL_DEF_DRV(ioctl, func, flags)</programlisting> + <para> + <parameter>ioctl</parameter> is the ioctl name. Drivers must define + the DRM_##ioctl and DRM_IOCTL_##ioctl macros to the ioctl number + offset from DRM_COMMAND_BASE and the ioctl number respectively. The + first macro is private to the device while the second must be exposed + to userspace in a public header. + </para> + <para> + <parameter>func</parameter> is a pointer to the ioctl handler function + compatible with the <type>drm_ioctl_t</type> type. + <programlisting>typedef int drm_ioctl_t(struct drm_device *dev, void *data, + struct drm_file *file_priv);</programlisting> + </para> + <para> + <parameter>flags</parameter> is a bitmask combination of the following + values. It restricts how the ioctl is allowed to be called. + <itemizedlist> + <listitem><para> + DRM_AUTH - Only authenticated callers allowed + </para></listitem> + <listitem><para> + DRM_MASTER - The ioctl can only be called on the master file + handle + </para></listitem> + <listitem><para> + DRM_ROOT_ONLY - Only callers with the SYSADMIN capability allowed + </para></listitem> + <listitem><para> + DRM_CONTROL_ALLOW - The ioctl can only be called on a control + device + </para></listitem> + <listitem><para> + DRM_UNLOCKED - The ioctl handler will be called without locking + the DRM global mutex + </para></listitem> + </itemizedlist> + </para> </para> </sect2> - - </sect1> - - <!-- Output management --> - <sect1> - <title>Output management</title> - <para> - At the core of the DRM output management code is a set of - structures representing CRTCs, encoders, and connectors. - </para> - <para> - A CRTC is an abstraction representing a part of the chip that - contains a pointer to a scanout buffer. Therefore, the number - of CRTCs available determines how many independent scanout - buffers can be active at any given time. The CRTC structure - contains several fields to support this: a pointer to some video - memory, a display mode, and an (x, y) offset into the video - memory to support panning or configurations where one piece of - video memory spans multiple CRTCs. - </para> - <para> - An encoder takes pixel data from a CRTC and converts it to a - format suitable for any attached connectors. On some devices, - it may be possible to have a CRTC send data to more than one - encoder. In that case, both encoders would receive data from - the same scanout buffer, resulting in a "cloned" display - configuration across the connectors attached to each encoder. - </para> - <para> - A connector is the final destination for pixel data on a device, - and usually connects directly to an external display device like - a monitor or laptop panel. A connector can only be attached to - one encoder at a time. The connector is also the structure - where information about the attached display is kept, so it - contains fields for display data, EDID data, DPMS & - connection status, and information about modes supported on the - attached displays. - </para> -<!--!Edrivers/char/drm/drm_crtc.c--> - </sect1> - - <sect1> - <title>Framebuffer management</title> - <para> - Clients need to provide a framebuffer object which provides a source - of pixels for a CRTC to deliver to the encoder(s) and ultimately the - connector(s). A framebuffer is fundamentally a driver-specific memory - object, made into an opaque handle by the DRM's addfb() function. - Once a framebuffer has been created this way, it may be passed to the - KMS mode setting routines for use in a completed configuration. - </para> </sect1> <sect1> @@ -812,15 +2355,24 @@ void intel_crt_init(struct drm_device *dev) </para> </sect1> + <!-- Internals: suspend/resume --> + <sect1> - <title>Suspend/resume</title> + <title>Suspend/Resume</title> + <para> + The DRM core provides some suspend/resume code, but drivers wanting full + suspend/resume support should provide save() and restore() functions. + These are called at suspend, hibernate, or resume time, and should perform + any state save or restore required by your device across suspend or + hibernate states. + </para> + <synopsis>int (*suspend) (struct drm_device *, pm_message_t state); +int (*resume) (struct drm_device *);</synopsis> <para> - The DRM core provides some suspend/resume code, but drivers - wanting full suspend/resume support should provide save() and - restore() functions. These are called at suspend, - hibernate, or resume time, and should perform any state save or - restore required by your device across suspend or hibernate - states. + Those are legacy suspend and resume methods. New driver should use the + power management interface provided by their bus type (usually through + the struct <structname>device_driver</structname> dev_pm_ops) and set + these methods to NULL. </para> </sect1> @@ -833,6 +2385,35 @@ void intel_crt_init(struct drm_device *dev) </sect1> </chapter> +<!-- TODO + +- Add a glossary +- Document the struct_mutex catch-all lock +- Document connector properties + +- Why is the load method optional? +- What are drivers supposed to set the initial display state to, and how? + Connector's DPMS states are not initialized and are thus equal to + DRM_MODE_DPMS_ON. The fbcon compatibility layer calls + drm_helper_disable_unused_functions(), which disables unused encoders and + CRTCs, but doesn't touch the connectors' DPMS state, and + drm_helper_connector_dpms() in reaction to fbdev blanking events. Do drivers + that don't implement (or just don't use) fbcon compatibility need to call + those functions themselves? +- KMS drivers must call drm_vblank_pre_modeset() and drm_vblank_post_modeset() + around mode setting. Should this be done in the DRM core? +- vblank_disable_allowed is set to 1 in the first drm_vblank_post_modeset() + call and never set back to 0. It seems to be safe to permanently set it to 1 + in drm_vblank_init() for KMS driver, and it might be safe for UMS drivers as + well. This should be investigated. +- crtc and connector .save and .restore operations are only used internally in + drivers, should they be removed from the core? +- encoder mid-layer .save and .restore operations are only used internally in + drivers, should they be removed from the core? +- encoder mid-layer .detect operation is only used internally in drivers, + should it be removed from the core? +--> + <!-- External interfaces --> <chapter id="drmExternals"> @@ -853,6 +2434,42 @@ void intel_crt_init(struct drm_device *dev) Cover generic ioctls and sysfs layout here. We only need high-level info, since man pages should cover the rest. </para> + + <!-- External: vblank handling --> + + <sect1> + <title>VBlank event handling</title> + <para> + The DRM core exposes two vertical blank related ioctls: + <variablelist> + <varlistentry> + <term>DRM_IOCTL_WAIT_VBLANK</term> + <listitem> + <para> + This takes a struct drm_wait_vblank structure as its argument, + and it is used to block or request a signal when a specified + vblank event occurs. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>DRM_IOCTL_MODESET_CTL</term> + <listitem> + <para> + This should be called by application level drivers before and + after mode setting, since on many devices the vertical blank + counter is reset at that time. Internally, the DRM snapshots + the last vblank count when the ioctl is called with the + _DRM_PRE_MODESET command, so that the counter won't go backwards + (which is dealt with when _DRM_POST_MODESET is used). + </para> + </listitem> + </varlistentry> + </variablelist> +<!--!Edrivers/char/drm/drm_irq.c--> + </para> + </sect1> + </chapter> <!-- API reference --> diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 362520992ced..9b7e4c557928 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -300,7 +300,7 @@ $(MEDIA_OBJ_DIR)/media-entities.tmpl: $(MEDIA_OBJ_DIR)/v4l2.xml @( \ for ident in $(IOCTLS) ; do \ entity=`echo $$ident | tr _ -` ; \ - id=`grep "<refname>$$ident" $(MEDIA_OBJ_DIR)/vidioc-*.xml | sed -r s,"^.*/(.*).xml.*","\1",` ; \ + id=`grep "<refname>$$ident" $(MEDIA_OBJ_DIR)/vidioc-*.xml $(MEDIA_OBJ_DIR)/media-ioc-*.xml | sed -r s,"^.*/(.*).xml.*","\1",` ; \ echo "<!ENTITY $$entity \"<link" \ "linkend='$$id'><constant>$$ident</constant></link>\">" \ >>$@ ; \ diff --git a/Documentation/DocBook/media/dvb/audio.xml b/Documentation/DocBook/media/dvb/audio.xml index d64386237207..a7ea56c71a27 100644 --- a/Documentation/DocBook/media/dvb/audio.xml +++ b/Documentation/DocBook/media/dvb/audio.xml @@ -1,12 +1,16 @@ <title>DVB Audio Device</title> <para>The DVB audio device controls the MPEG2 audio decoder of the DVB hardware. It can be accessed through <emphasis role="tt">/dev/dvb/adapter0/audio0</emphasis>. Data types and and -ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/video.h</emphasis> in your +ioctl definitions can be accessed by including <emphasis role="tt">linux/dvb/audio.h</emphasis> in your application. </para> <para>Please note that some DVB cards don’t have their own MPEG decoder, which results in the omission of the audio and video device. </para> +<para> +These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use +of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls +have been created to replace that functionality.</para> <section id="audio_data_types"> <title>Audio Data Types</title> @@ -558,6 +562,8 @@ role="subsection"><title>AUDIO_SELECT_SOURCE</title> role="subsection"><title>AUDIO_SET_MUTE</title> <para>DESCRIPTION </para> +<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 +&VIDIOC-DECODER-CMD; with the <constant>V4L2_DEC_CMD_START_MUTE_AUDIO</constant> flag instead.</para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call asks the audio device to mute the stream that is currently being @@ -730,6 +736,8 @@ role="subsection"><title>AUDIO_SET_BYPASS_MODE</title> role="subsection"><title>AUDIO_CHANNEL_SELECT</title> <para>DESCRIPTION </para> +<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 +<constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> control instead.</para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call asks the Audio Device to select the requested channel if possible.</para> @@ -772,6 +780,109 @@ role="subsection"><title>AUDIO_CHANNEL_SELECT</title> </row></tbody></tgroup></informaltable> &return-value-dvb; +</section><section id="AUDIO_BILINGUAL_CHANNEL_SELECT" +role="subsection"><title>AUDIO_BILINGUAL_CHANNEL_SELECT</title> +<para>DESCRIPTION +</para> +<para>This ioctl is obsolete. Do not use in new drivers. It has been replaced by +the V4L2 <constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> control +for MPEG decoders controlled through V4L2.</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to select the requested channel for bilingual streams if possible.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + AUDIO_BILINGUAL_CHANNEL_SELECT, audio_channel_select_t);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_BILINGUAL_CHANNEL_SELECT for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>audio_channel_select_t +ch</para> +</entry><entry + align="char"> +<para>Select the output format of the audio (mono left/right, + stereo).</para> +</entry> + </row> +</tbody></tgroup></informaltable> +&return-value-dvb; + +</section><section id="AUDIO_GET_PTS" +role="subsection"><title>AUDIO_GET_PTS</title> +<para>DESCRIPTION +</para> +<para>This ioctl is obsolete. Do not use in new drivers. If you need this functionality, +then please contact the linux-media mailing list (&v4l-ml;).</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Audio Device to return the current PTS timestamp.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + AUDIO_GET_PTS, __u64 *pts);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals AUDIO_GET_PTS for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>__u64 *pts +</para> +</entry><entry + align="char"> +<para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1. +</para> +<para> +The PTS should belong to the currently played +frame if possible, but may also be a value close to it +like the PTS of the last decoded frame or the last PTS +extracted by the PES parser.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; + </section><section id="AUDIO_GET_STATUS" role="subsection"><title>AUDIO_GET_STATUS</title> <para>DESCRIPTION diff --git a/Documentation/DocBook/media/dvb/ca.xml b/Documentation/DocBook/media/dvb/ca.xml index 5c4adb44b1c1..85eaf4fe2931 100644 --- a/Documentation/DocBook/media/dvb/ca.xml +++ b/Documentation/DocBook/media/dvb/ca.xml @@ -226,4 +226,357 @@ typedef struct ca_pid { </entry> </row></tbody></tgroup></informaltable> </section> + +<section id="CA_RESET" +role="subsection"><title>CA_RESET</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = CA_RESET); +</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals CA_RESET for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="CA_GET_CAP" +role="subsection"><title>CA_GET_CAP</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = CA_GET_CAP, + ca_caps_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals CA_GET_CAP for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>ca_caps_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="CA_GET_SLOT_INFO" +role="subsection"><title>CA_GET_SLOT_INFO</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = CA_GET_SLOT_INFO, + ca_slot_info_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals CA_GET_SLOT_INFO for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>ca_slot_info_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="CA_GET_DESCR_INFO" +role="subsection"><title>CA_GET_DESCR_INFO</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = CA_GET_DESCR_INFO, + ca_descr_info_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals CA_GET_DESCR_INFO for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>ca_descr_info_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="CA_GET_MSG" +role="subsection"><title>CA_GET_MSG</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = CA_GET_MSG, + ca_msg_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals CA_GET_MSG for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>ca_msg_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="CA_SEND_MSG" +role="subsection"><title>CA_SEND_MSG</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = CA_SEND_MSG, + ca_msg_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals CA_SEND_MSG for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>ca_msg_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="CA_SET_DESCR" +role="subsection"><title>CA_SET_DESCR</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = CA_SET_DESCR, + ca_descr_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals CA_SET_DESCR for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>ca_descr_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="CA_SET_PID" +role="subsection"><title>CA_SET_PID</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = CA_SET_PID, + ca_pid_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals CA_SET_PID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>ca_pid_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + </section> diff --git a/Documentation/DocBook/media/dvb/demux.xml b/Documentation/DocBook/media/dvb/demux.xml index 37c17908aa40..86de89cfbd67 100644 --- a/Documentation/DocBook/media/dvb/demux.xml +++ b/Documentation/DocBook/media/dvb/demux.xml @@ -899,4 +899,232 @@ typedef enum { <para>Invalid stc number.</para> </entry> </row></tbody></tgroup></informaltable> - </section></section> + </section> + +<section id="DMX_GET_PES_PIDS" +role="subsection"><title>DMX_GET_PES_PIDS</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = DMX_GET_PES_PIDS, + __u16[5]);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_GET_PES_PIDS for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16[5] +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="DMX_GET_CAPS" +role="subsection"><title>DMX_GET_CAPS</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = DMX_GET_CAPS, + dmx_caps_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_GET_CAPS for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_caps_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="DMX_SET_SOURCE" +role="subsection"><title>DMX_SET_SOURCE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = DMX_SET_SOURCE, + dmx_source_t *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_SET_SOURCE for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>dmx_source_t * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="DMX_ADD_PID" +role="subsection"><title>DMX_ADD_PID</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = DMX_ADD_PID, + __u16 *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_ADD_PID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="DMX_REMOVE_PID" +role="subsection"><title>DMX_REMOVE_PID</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = DMX_REMOVE_PID, + __u16 *);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals DMX_REMOVE_PID for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>__u16 * +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + + +</section> diff --git a/Documentation/DocBook/media/dvb/dvbapi.xml b/Documentation/DocBook/media/dvb/dvbapi.xml index 2ab6ddcfc4e0..757488b24f4f 100644 --- a/Documentation/DocBook/media/dvb/dvbapi.xml +++ b/Documentation/DocBook/media/dvb/dvbapi.xml @@ -28,7 +28,7 @@ <holder>Convergence GmbH</holder> </copyright> <copyright> - <year>2009-2011</year> + <year>2009-2012</year> <holder>Mauro Carvalho Chehab</holder> </copyright> @@ -84,7 +84,7 @@ Added ISDB-T test originally written by Patrick Boettcher <title>LINUX DVB API</title> -<subtitle>Version 5.2</subtitle> +<subtitle>Version 5.8</subtitle> <!-- ADD THE CHAPTERS HERE --> <chapter id="dvb_introdution"> &sub-intro; diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index e633c097a8d1..957e3acaae8e 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -194,6 +194,7 @@ get/set up to 64 properties. The actual meaning of each property is described on APSK_16, APSK_32, DQPSK, + QAM_4_NR, } fe_modulation_t; </programlisting> </section> @@ -265,6 +266,7 @@ typedef enum fe_code_rate { FEC_AUTO, FEC_3_5, FEC_9_10, + FEC_2_5, } fe_code_rate_t; </programlisting> <para>which correspond to error correction rates of 1/2, 2/3, etc., @@ -351,7 +353,7 @@ typedef enum fe_delivery_system { SYS_ISDBC, SYS_ATSC, SYS_ATSCMH, - SYS_DMBTH, + SYS_DTMB, SYS_CMMB, SYS_DAB, SYS_DVBT2, @@ -567,28 +569,33 @@ typedef enum fe_delivery_system { <title><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></title> <para>RS frame mode.</para> <para>Possible values are:</para> + <para id="atscmh-rs-frame-mode"> <programlisting> typedef enum atscmh_rs_frame_mode { ATSCMH_RSFRAME_PRI_ONLY = 0, ATSCMH_RSFRAME_PRI_SEC = 1, } atscmh_rs_frame_mode_t; </programlisting> + </para> </section> <section id="DTV-ATSCMH-RS-FRAME-ENSEMBLE"> <title><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></title> <para>RS frame ensemble.</para> <para>Possible values are:</para> + <para id="atscmh-rs-frame-ensemble"> <programlisting> typedef enum atscmh_rs_frame_ensemble { ATSCMH_RSFRAME_ENS_PRI = 0, ATSCMH_RSFRAME_ENS_SEC = 1, } atscmh_rs_frame_ensemble_t; </programlisting> + </para> </section> <section id="DTV-ATSCMH-RS-CODE-MODE-PRI"> <title><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></title> <para>RS code mode (primary).</para> <para>Possible values are:</para> + <para id="atscmh-rs-code-mode"> <programlisting> typedef enum atscmh_rs_code_mode { ATSCMH_RSCODE_211_187 = 0, @@ -596,6 +603,7 @@ typedef enum atscmh_rs_code_mode { ATSCMH_RSCODE_235_187 = 2, } atscmh_rs_code_mode_t; </programlisting> + </para> </section> <section id="DTV-ATSCMH-RS-CODE-MODE-SEC"> <title><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></title> @@ -613,23 +621,27 @@ typedef enum atscmh_rs_code_mode { <title><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></title> <para>Series Concatenated Convolutional Code Block Mode.</para> <para>Possible values are:</para> + <para id="atscmh-sccc-block-mode"> <programlisting> typedef enum atscmh_sccc_block_mode { ATSCMH_SCCC_BLK_SEP = 0, ATSCMH_SCCC_BLK_COMB = 1, } atscmh_sccc_block_mode_t; </programlisting> + </para> </section> <section id="DTV-ATSCMH-SCCC-CODE-MODE-A"> <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></title> <para>Series Concatenated Convolutional Code Rate.</para> <para>Possible values are:</para> + <para id="atscmh-sccc-code-mode"> <programlisting> typedef enum atscmh_sccc_code_mode { ATSCMH_SCCC_CODE_HLF = 0, ATSCMH_SCCC_CODE_QTR = 1, } atscmh_sccc_code_mode_t; </programlisting> + </para> </section> <section id="DTV-ATSCMH-SCCC-CODE-MODE-B"> <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></title> @@ -725,6 +737,9 @@ typedef enum fe_guard_interval { GUARD_INTERVAL_1_128, GUARD_INTERVAL_19_128, GUARD_INTERVAL_19_256, + GUARD_INTERVAL_PN420, + GUARD_INTERVAL_PN595, + GUARD_INTERVAL_PN945, } fe_guard_interval_t; </programlisting> @@ -733,6 +748,7 @@ typedef enum fe_guard_interval { try to find the correct guard interval (if capable) and will use TMCC to fill in the missing parameters.</para> <para>2) Intervals 1/128, 19/128 and 19/256 are used only for DVB-T2 at present</para> + <para>3) DTMB specifies PN420, PN595 and PN945.</para> </section> <section id="DTV-TRANSMISSION-MODE"> <title><constant>DTV_TRANSMISSION_MODE</constant></title> @@ -749,6 +765,8 @@ typedef enum fe_transmit_mode { TRANSMISSION_MODE_1K, TRANSMISSION_MODE_16K, TRANSMISSION_MODE_32K, + TRANSMISSION_MODE_C1, + TRANSMISSION_MODE_C3780, } fe_transmit_mode_t; </programlisting> <para>Notes:</para> @@ -760,6 +778,7 @@ typedef enum fe_transmit_mode { use TMCC to fill in the missing parameters.</para> <para>3) DVB-T specifies 2K and 8K as valid sizes.</para> <para>4) DVB-T2 specifies 1K, 2K, 4K, 8K, 16K and 32K.</para> + <para>5) DTMB specifies C1 and C3780.</para> </section> <section id="DTV-HIERARCHY"> <title><constant>DTV_HIERARCHY</constant></title> @@ -774,17 +793,28 @@ typedef enum fe_hierarchy { } fe_hierarchy_t; </programlisting> </section> - <section id="DTV-ISDBS-TS-ID"> - <title><constant>DTV_ISDBS_TS_ID</constant></title> - <para>Currently unused.</para> + <section id="DTV-STREAM-ID"> + <title><constant>DTV_STREAM_ID</constant></title> + <para>DVB-S2, DVB-T2 and ISDB-S support the transmission of several + streams on a single transport stream. + This property enables the DVB driver to handle substream filtering, + when supported by the hardware. + By default, substream filtering is disabled. + </para><para> + For DVB-S2 and DVB-T2, the valid substream id range is from 0 to 255. + </para><para> + For ISDB, the valid substream id range is from 1 to 65535. + </para><para> + To disable it, you should use the special macro NO_STREAM_ID_FILTER. + </para><para> + Note: any value outside the id range also disables filtering. + </para> </section> - <section id="DTV-DVBT2-PLP-ID"> - <title><constant>DTV_DVBT2_PLP_ID</constant></title> - <para>DVB-T2 supports Physical Layer Pipes (PLP) to allow transmission of - many data types via a single multiplex. The API will soon support this - at which point this section will be expanded.</para> + <section id="DTV-DVBT2-PLP-ID-LEGACY"> + <title><constant>DTV_DVBT2_PLP_ID_LEGACY</constant></title> + <para>Obsolete, replaced with DTV_STREAM_ID.</para> </section> - <section id="DTV_ENUM_DELSYS"> + <section id="DTV-ENUM-DELSYS"> <title><constant>DTV_ENUM_DELSYS</constant></title> <para>A Multi standard frontend needs to advertise the delivery systems provided. Applications need to enumerate the provided delivery systems, before using @@ -796,6 +826,29 @@ typedef enum fe_hierarchy { FE_GET_INFO. In the case of a legacy frontend, the result is just the same as with FE_GET_INFO, but in a more structured format </para> </section> + <section id="DTV-INTERLEAVING"> + <title><constant>DTV_INTERLEAVING</constant></title> + <para id="fe-interleaving">Interleaving mode</para> + <programlisting> +enum fe_interleaving { + INTERLEAVING_NONE, + INTERLEAVING_AUTO, + INTERLEAVING_240, + INTERLEAVING_720, +}; + </programlisting> + </section> + <section id="DTV-LNA"> + <title><constant>DTV_LNA</constant></title> + <para>Low-noise amplifier.</para> + <para>Hardware might offer controllable LNA which can be set manually + using that parameter. Usually LNA could be found only from + terrestrial devices if at all.</para> + <para>Possible values: 0, 1, LNA_AUTO</para> + <para>0, LNA off</para> + <para>1, LNA on</para> + <para>use the special macro LNA_AUTO to set LNA auto</para> + </section> </section> <section id="frontend-property-terrestrial-systems"> <title>Properties used on terrestrial delivery systems</title> @@ -816,6 +869,7 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem> <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem> <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem> + <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> </itemizedlist> </section> <section id="dvbt2-params"> @@ -838,7 +892,8 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem> <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem> <listitem><para><link linkend="DTV-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem> - <listitem><para><link linkend="DTV-DVBT2-PLP-ID"><constant>DTV_DVBT2_PLP_ID</constant></link></para></listitem> + <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem> + <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> </itemizedlist> </section> <section id="isdbt"> @@ -925,13 +980,32 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-ATSCMH-PRC"><constant>DTV_ATSCMH_PRC</constant></link></para></listitem> <listitem><para><link linkend="DTV-ATSCMH-RS-FRAME-MODE"><constant>DTV_ATSCMH_RS_FRAME_MODE</constant></link></para></listitem> <listitem><para><link linkend="DTV-ATSCMH-RS-FRAME-ENSEMBLE"><constant>DTV_ATSCMH_RS_FRAME_ENSEMBLE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-CODE-MODE-PRI"><constant>DTV_ATSCMH_CODE_MODE_PRI</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-CODE-MODE-SEC"><constant>DTV_ATSCMH_CODE_MODE_SEC</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-RS-CODE-MODE-PRI"><constant>DTV_ATSCMH_RS_CODE_MODE_PRI</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-RS-CODE-MODE-SEC"><constant>DTV_ATSCMH_RS_CODE_MODE_SEC</constant></link></para></listitem> <listitem><para><link linkend="DTV-ATSCMH-SCCC-BLOCK-MODE"><constant>DTV_ATSCMH_SCCC_BLOCK_MODE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE_MODE-A"><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE_MODE-B"><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE_MODE-C"><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE_MODE-D"><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-A"><constant>DTV_ATSCMH_SCCC_CODE_MODE_A</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-B"><constant>DTV_ATSCMH_SCCC_CODE_MODE_B</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-C"><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-SCCC-CODE-MODE-D"><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></link></para></listitem> + </itemizedlist> + </section> + <section id="dtmb-params"> + <title>DTMB delivery system</title> + <para>The following parameters are valid for DTMB:</para> + <itemizedlist mark='opencircle'> + <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> + <listitem><para><link linkend="DTV-DELIVERY-SYSTEM"><constant>DTV_DELIVERY_SYSTEM</constant></link></para></listitem> + <listitem><para><link linkend="DTV-TUNE"><constant>DTV_TUNE</constant></link></para></listitem> + <listitem><para><link linkend="DTV-CLEAR"><constant>DTV_CLEAR</constant></link></para></listitem> + <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> + <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> + <listitem><para><link linkend="DTV-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem> + <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> + <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem> + <listitem><para><link linkend="DTV-GUARD-INTERVAL"><constant>DTV_GUARD_INTERVAL</constant></link></para></listitem> + <listitem><para><link linkend="DTV-TRANSMISSION-MODE"><constant>DTV_TRANSMISSION_MODE</constant></link></para></listitem> + <listitem><para><link linkend="DTV-INTERLEAVING"><constant>DTV_INTERLEAVING</constant></link></para></listitem> + <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> </itemizedlist> </section> </section> @@ -952,6 +1026,7 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem> <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem> + <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> </itemizedlist> </section> <section id="dvbc-annex-b-params"> @@ -966,6 +1041,7 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-FREQUENCY"><constant>DTV_FREQUENCY</constant></link></para></listitem> <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> <listitem><para><link linkend="DTV-INVERSION"><constant>DTV_INVERSION</constant></link></para></listitem> + <listitem><para><link linkend="DTV-LNA"><constant>DTV_LNA</constant></link></para></listitem> </itemizedlist> </section> </section> @@ -999,6 +1075,7 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-MODULATION"><constant>DTV_MODULATION</constant></link></para></listitem> <listitem><para><link linkend="DTV-PILOT"><constant>DTV_PILOT</constant></link></para></listitem> <listitem><para><link linkend="DTV-ROLLOFF"><constant>DTV_ROLLOFF</constant></link></para></listitem> + <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem> </itemizedlist> </section> <section id="turbo-params"> @@ -1021,7 +1098,7 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-SYMBOL-RATE"><constant>DTV_SYMBOL_RATE</constant></link></para></listitem> <listitem><para><link linkend="DTV-INNER-FEC"><constant>DTV_INNER_FEC</constant></link></para></listitem> <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem> - <listitem><para><link linkend="DTV-ISDBS-TS-ID"><constant>DTV_ISDBS_TS_ID</constant></link></para></listitem> + <listitem><para><link linkend="DTV-STREAM-ID"><constant>DTV_STREAM_ID</constant></link></para></listitem> </itemizedlist> </section> </section> diff --git a/Documentation/DocBook/media/dvb/frontend.xml b/Documentation/DocBook/media/dvb/frontend.xml index aeaed59d0f1f..426c2526a454 100644 --- a/Documentation/DocBook/media/dvb/frontend.xml +++ b/Documentation/DocBook/media/dvb/frontend.xml @@ -66,7 +66,7 @@ supported via the new <link linkend="FE_GET_SET_PROPERTY">FE_GET_PROPERTY/FE_GET <para>The usage of this field is deprecated, as it doesn't report all supported standards, and will provide an incomplete information for frontends that support multiple delivery systems. -Please use <link linkend="DTV_ENUM_DELSYS">DTV_ENUM_DELSYS</link> instead.</para> +Please use <link linkend="DTV-ENUM-DELSYS">DTV_ENUM_DELSYS</link> instead.</para> </section> <section id="fe-caps-t"> @@ -101,6 +101,7 @@ a specific frontend type.</para> FE_CAN_8VSB = 0x200000, FE_CAN_16VSB = 0x400000, FE_HAS_EXTENDED_CAPS = 0x800000, + FE_CAN_MULTISTREAM = 0x4000000, FE_CAN_TURBO_FEC = 0x8000000, FE_CAN_2G_MODULATION = 0x10000000, FE_NEEDS_BENDING = 0x20000000, @@ -207,18 +208,44 @@ spec.</para> <para>Several functions of the frontend device use the fe_status data type defined by</para> <programlisting> - typedef enum fe_status { - FE_HAS_SIGNAL = 0x01, /⋆ found something above the noise level ⋆/ - FE_HAS_CARRIER = 0x02, /⋆ found a DVB signal ⋆/ - FE_HAS_VITERBI = 0x04, /⋆ FEC is stable ⋆/ - FE_HAS_SYNC = 0x08, /⋆ found sync bytes ⋆/ - FE_HAS_LOCK = 0x10, /⋆ everything's working... ⋆/ - FE_TIMEDOUT = 0x20, /⋆ no lock within the last ~2 seconds ⋆/ - FE_REINIT = 0x40 /⋆ frontend was reinitialized, ⋆/ - } fe_status_t; /⋆ application is recommned to reset ⋆/ +typedef enum fe_status { + FE_HAS_SIGNAL = 0x01, + FE_HAS_CARRIER = 0x02, + FE_HAS_VITERBI = 0x04, + FE_HAS_SYNC = 0x08, + FE_HAS_LOCK = 0x10, + FE_TIMEDOUT = 0x20, + FE_REINIT = 0x40, +} fe_status_t; </programlisting> -<para>to indicate the current state and/or state changes of the frontend hardware. -</para> +<para>to indicate the current state and/or state changes of the frontend hardware: +</para> + +<informaltable><tgroup cols="2"><tbody> +<row> +<entry align="char">FE_HAS_SIGNAL</entry> +<entry align="char">The frontend has found something above the noise level</entry> +</row><row> +<entry align="char">FE_HAS_CARRIER</entry> +<entry align="char">The frontend has found a DVB signal</entry> +</row><row> +<entry align="char">FE_HAS_VITERBI</entry> +<entry align="char">The frontend FEC code is stable</entry> +</row><row> +<entry align="char">FE_HAS_SYNC</entry> +<entry align="char">Syncronization bytes was found</entry> +</row><row> +<entry align="char">FE_HAS_LOCK</entry> +<entry align="char">The DVB were locked and everything is working</entry> +</row><row> +<entry align="char">FE_TIMEDOUT</entry> +<entry align="char">no lock within the last about 2 seconds</entry> +</row><row> +<entry align="char">FE_REINIT</entry> +<entry align="char">The frontend was reinitialized, application is +recommended to reset DiSEqC, tone and parameters</entry> +</row> +</tbody></tgroup></informaltable> </section> @@ -238,7 +265,7 @@ and to add newer delivery systems.</para> <constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></link> instead, in order to be able to support the newer System Delivery like DVB-S2, DVB-T2, DVB-C2, ISDB, etc.</para> -<para>All kinds of parameters are combined as an union in the FrontendParameters structure:</para> +<para>All kinds of parameters are combined as an union in the FrontendParameters structure: <programlisting> struct dvb_frontend_parameters { uint32_t frequency; /⋆ (absolute) frequency in Hz for QAM/OFDM ⋆/ @@ -251,12 +278,13 @@ struct dvb_frontend_parameters { struct dvb_vsb_parameters vsb; } u; }; -</programlisting> +</programlisting></para> <para>In the case of QPSK frontends the <constant>frequency</constant> field specifies the intermediate frequency, i.e. the offset which is effectively added to the local oscillator frequency (LOF) of the LNB. The intermediate frequency has to be specified in units of kHz. For QAM and OFDM frontends the <constant>frequency</constant> specifies the absolute frequency and is given in Hz. </para> + <section id="dvb-qpsk-parameters"> <title>QPSK parameters</title> <para>For satellite QPSK frontends you have to use the <constant>dvb_qpsk_parameters</constant> structure:</para> @@ -321,8 +349,8 @@ itself. <section id="fe-code-rate-t"> <title>frontend code rate</title> <para>The possible values for the <constant>fec_inner</constant> field used on -<link refend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and -<link refend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> are: +<link linkend="dvb-qpsk-parameters"><constant>struct dvb_qpsk_parameters</constant></link> and +<link linkend="dvb-qam-parameters"><constant>struct dvb_qam_parameters</constant></link> are: </para> <programlisting> typedef enum fe_code_rate { @@ -347,9 +375,9 @@ detection. <section id="fe-modulation-t"> <title>frontend modulation type for QAM, OFDM and VSB</title> <para>For cable and terrestrial frontends, e. g. for -<link refend="dvb-qam-parameters"><constant>struct dvb_qpsk_parameters</constant></link>, -<link refend="dvb-ofdm-parameters"><constant>struct dvb_qam_parameters</constant></link> and -<link refend="dvb-vsb-parameters"><constant>struct dvb_qam_parameters</constant></link>, +<link linkend="dvb-qam-parameters"><constant>struct dvb_qpsk_parameters</constant></link>, +<link linkend="dvb-ofdm-parameters"><constant>struct dvb_qam_parameters</constant></link> and +<link linkend="dvb-vsb-parameters"><constant>struct dvb_qam_parameters</constant></link>, it needs to specify the quadrature modulation mode which can be one of the following: </para> <programlisting> @@ -370,8 +398,8 @@ it needs to specify the quadrature modulation mode which can be one of the follo } fe_modulation_t; </programlisting> </section> -<para>Finally, there are several more parameters for OFDM: -</para> +<section> +<title>More OFDM parameters</title> <section id="fe-transmit-mode-t"> <title>Number of carriers per channel</title> <programlisting> @@ -427,6 +455,7 @@ typedef enum fe_hierarchy { } fe_hierarchy_t; </programlisting> </section> +</section> </section> diff --git a/Documentation/DocBook/media/dvb/intro.xml b/Documentation/DocBook/media/dvb/intro.xml index 170064a3dc8f..2048b53d19b9 100644 --- a/Documentation/DocBook/media/dvb/intro.xml +++ b/Documentation/DocBook/media/dvb/intro.xml @@ -205,7 +205,7 @@ a partial path like:</para> additional include file <emphasis role="tt">linux/dvb/version.h</emphasis> exists, which defines the constant <emphasis role="tt">DVB_API_VERSION</emphasis>. This document -describes <emphasis role="tt">DVB_API_VERSION 5.4</emphasis>. +describes <emphasis role="tt">DVB_API_VERSION 5.8</emphasis>. </para> </section> diff --git a/Documentation/DocBook/media/dvb/kdapi.xml b/Documentation/DocBook/media/dvb/kdapi.xml index 6c67481eaa4b..6c11ec52cbee 100644 --- a/Documentation/DocBook/media/dvb/kdapi.xml +++ b/Documentation/DocBook/media/dvb/kdapi.xml @@ -2,7 +2,7 @@ <para>The kernel demux API defines a driver-internal interface for registering low-level, hardware specific driver to a hardware independent demux layer. It is only of interest for DVB device driver writers. The header file for this API is named <emphasis role="tt">demux.h</emphasis> and located in -<emphasis role="tt">drivers/media/dvb/dvb-core</emphasis>. +<emphasis role="tt">drivers/media/dvb-core</emphasis>. </para> <para>Maintainer note: This section must be reviewed. It is probably out of date. </para> diff --git a/Documentation/DocBook/media/dvb/net.xml b/Documentation/DocBook/media/dvb/net.xml index 67d37e5ce597..a193e86941b5 100644 --- a/Documentation/DocBook/media/dvb/net.xml +++ b/Documentation/DocBook/media/dvb/net.xml @@ -26,4 +26,131 @@ struct dvb_net_if { <title>DVB net Function Calls</title> <para>To be written… </para> + +<section id="NET_ADD_IF" +role="subsection"><title>NET_ADD_IF</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = NET_ADD_IF, + struct dvb_net_if *if);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals NET_ADD_IF for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct dvb_net_if *if +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="NET_REMOVE_IF" +role="subsection"><title>NET_REMOVE_IF</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = NET_REMOVE_IF); +</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals NET_REMOVE_IF for this command.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> + +<section id="NET_GET_IF" +role="subsection"><title>NET_GET_IF</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl is undocumented. Documentation is welcome.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(fd, int request = NET_GET_IF, + struct dvb_net_if *if);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals NET_GET_IF for this command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct dvb_net_if *if +</para> +</entry><entry + align="char"> +<para>Undocumented.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; +</section> </section> diff --git a/Documentation/DocBook/media/dvb/video.xml b/Documentation/DocBook/media/dvb/video.xml index 25fb823226b4..3ea1ca7e785e 100644 --- a/Documentation/DocBook/media/dvb/video.xml +++ b/Documentation/DocBook/media/dvb/video.xml @@ -15,6 +15,10 @@ the audio and video device as well as the video4linux device. <para>The ioctls that deal with SPUs (sub picture units) and navigation packets are only supported on some MPEG decoders made for DVD playback. </para> +<para> +These ioctls were also used by V4L2 to control MPEG decoders implemented in V4L2. The use +of these ioctls for that purpose has been made obsolete and proper V4L2 ioctls or controls +have been created to replace that functionality.</para> <section id="video_types"> <title>Video Data Types</title> @@ -55,7 +59,7 @@ typedef enum { </section> <section id="video-stream-source-t"> -<title>video stream source</title> +<title>video_stream_source_t</title> <para>The video stream source is set through the VIDEO_SELECT_SOURCE call and can take the following values, depending on whether we are replaying from an internal (demuxer) or external (user write) source. @@ -76,7 +80,7 @@ call. </section> <section id="video-play-state-t"> -<title>video play state</title> +<title>video_play_state_t</title> <para>The following values can be returned by the VIDEO_GET_STATUS call representing the state of video playback. </para> @@ -90,9 +94,9 @@ typedef enum { </section> <section id="video-command"> +<title>struct video_command</title> <para>The structure must be zeroed before use by the application This ensures it can be extended safely in the future.</para> -<title>struct video-command</title> <programlisting> struct video_command { __u32 cmd; @@ -121,7 +125,7 @@ struct video_command { </section> <section id="video-size-t"> -<title>struct video_size-t</title> +<title>video_size_t</title> <programlisting> typedef struct { int w; @@ -217,7 +221,7 @@ bits set according to the hardwares capabilities. </section> <section id="video-system"> -<title>video system</title> +<title>video_system_t</title> <para>A call to VIDEO_SET_SYSTEM sets the desired video system for TV output. The following system types can be set: </para> @@ -263,7 +267,7 @@ call expects the following format for that information: </section> <section id="video-spu"> -<title>video SPU</title> +<title>struct video_spu</title> <para>Calling VIDEO_SET_SPU deactivates or activates SPU decoding, according to the following format: </para> @@ -277,12 +281,12 @@ following format: </section> <section id="video-spu-palette"> -<title>video SPU palette</title> +<title>struct video_spu_palette</title> <para>The following structure is used to set the SPU palette by calling VIDEO_SPU_PALETTE: </para> <programlisting> typedef - struct video_spu_palette{ + struct video_spu_palette { int length; uint8_t ⋆palette; } video_spu_palette_t; @@ -290,13 +294,13 @@ following format: </section> <section id="video-navi-pack"> -<title>video NAVI pack</title> +<title>struct video_navi_pack</title> <para>In order to get the navigational data the following structure has to be passed to the ioctl VIDEO_GET_NAVI: </para> <programlisting> typedef - struct video_navi_pack{ + struct video_navi_pack { int length; /⋆ 0 ... 1024 ⋆/ uint8_t data[1024]; } video_navi_pack_t; @@ -305,7 +309,7 @@ VIDEO_GET_NAVI: <section id="video-attributes-t"> -<title>video attributes</title> +<title>video_attributes_t</title> <para>The following attributes can be set by a call to VIDEO_SET_ATTRIBUTES: </para> <programlisting> @@ -541,6 +545,8 @@ VIDEO_GET_NAVI: role="subsection"><title>VIDEO_STOP</title> <para>DESCRIPTION </para> +<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 +&VIDIOC-DECODER-CMD; instead.</para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call asks the Video Device to stop playing the current stream. @@ -598,6 +604,8 @@ role="subsection"><title>VIDEO_STOP</title> role="subsection"><title>VIDEO_PLAY</title> <para>DESCRIPTION </para> +<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 +&VIDIOC-DECODER-CMD; instead.</para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call asks the Video Device to start playing a video stream from the @@ -634,6 +642,8 @@ role="subsection"><title>VIDEO_PLAY</title> role="subsection"><title>VIDEO_FREEZE</title> <para>DESCRIPTION </para> +<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 +&VIDIOC-DECODER-CMD; instead.</para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call suspends the live video stream being played. Decoding @@ -674,6 +684,8 @@ role="subsection"><title>VIDEO_FREEZE</title> role="subsection"><title>VIDEO_CONTINUE</title> <para>DESCRIPTION </para> +<para>This ioctl is for DVB devices only. To control a V4L2 decoder use the V4L2 +&VIDIOC-DECODER-CMD; instead.</para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call restarts decoding and playing processes of the video stream @@ -710,6 +722,9 @@ role="subsection"><title>VIDEO_CONTINUE</title> role="subsection"><title>VIDEO_SELECT_SOURCE</title> <para>DESCRIPTION </para> +<para>This ioctl is for DVB devices only. This ioctl was also supported by the +V4L2 ivtv driver, but that has been replaced by the ivtv-specific +<constant>IVTV_IOC_PASSTHROUGH_MODE</constant> ioctl.</para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call informs the video device which source shall be used for the input @@ -845,10 +860,160 @@ role="subsection"><title>VIDEO_GET_STATUS</title> </row></tbody></tgroup></informaltable> &return-value-dvb; +</section><section id="VIDEO_GET_FRAME_COUNT" +role="subsection"><title>VIDEO_GET_FRAME_COUNT</title> +<para>DESCRIPTION +</para> +<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this +ioctl has been replaced by the <constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant> control.</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to return the number of displayed frames +since the decoder was started.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + VIDEO_GET_FRAME_COUNT, __u64 *pts);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_FRAME_COUNT for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>__u64 *pts +</para> +</entry><entry + align="char"> +<para>Returns the number of frames displayed since the decoder was started. +</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; + +</section><section id="VIDEO_GET_PTS" +role="subsection"><title>VIDEO_GET_PTS</title> +<para>DESCRIPTION +</para> +<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this +ioctl has been replaced by the <constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant> control.</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to return the current PTS timestamp.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + VIDEO_GET_PTS, __u64 *pts);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_PTS for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>__u64 *pts +</para> +</entry><entry + align="char"> +<para>Returns the 33-bit timestamp as defined in ITU T-REC-H.222.0 / ISO/IEC 13818-1. +</para> +<para> +The PTS should belong to the currently played +frame if possible, but may also be a value close to it +like the PTS of the last decoded frame or the last PTS +extracted by the PES parser.</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; + +</section><section id="VIDEO_GET_FRAME_RATE" +role="subsection"><title>VIDEO_GET_FRAME_RATE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl call asks the Video Device to return the current framerate.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + VIDEO_GET_FRAME_RATE, unsigned int *rate);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_FRAME_RATE for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>unsigned int *rate +</para> +</entry><entry + align="char"> +<para>Returns the framerate in number of frames per 1000 seconds. +</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; + </section><section id="VIDEO_GET_EVENT" role="subsection"><title>VIDEO_GET_EVENT</title> <para>DESCRIPTION </para> +<para>This ioctl is for DVB devices only. To get events from a V4L2 decoder use the V4L2 +&VIDIOC-DQEVENT; ioctl instead.</para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> <para>This ioctl call returns an event of type video_event if available. If an event is @@ -914,6 +1079,152 @@ role="subsection"><title>VIDEO_GET_EVENT</title> </entry> </row></tbody></tgroup></informaltable> +</section><section id="VIDEO_COMMAND" +role="subsection"><title>VIDEO_COMMAND</title> +<para>DESCRIPTION +</para> +<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this +ioctl has been replaced by the &VIDIOC-DECODER-CMD; ioctl.</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl commands the decoder. The <constant>video_command</constant> struct +is a subset of the <constant>v4l2_decoder_cmd</constant> struct, so refer to the +&VIDIOC-DECODER-CMD; documentation for more information.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + VIDEO_COMMAND, struct video_command *cmd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_COMMAND for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct video_command *cmd +</para> +</entry><entry + align="char"> +<para>Commands the decoder. +</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; + +</section><section id="VIDEO_TRY_COMMAND" +role="subsection"><title>VIDEO_TRY_COMMAND</title> +<para>DESCRIPTION +</para> +<para>This ioctl is obsolete. Do not use in new drivers. For V4L2 decoders this +ioctl has been replaced by the &VIDIOC-TRY-DECODER-CMD; ioctl.</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl tries a decoder command. The <constant>video_command</constant> struct +is a subset of the <constant>v4l2_decoder_cmd</constant> struct, so refer to the +&VIDIOC-TRY-DECODER-CMD; documentation for more information.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + VIDEO_TRY_COMMAND, struct video_command *cmd);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_TRY_COMMAND for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>struct video_command *cmd +</para> +</entry><entry + align="char"> +<para>Try a decoder command. +</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; + +</section><section id="VIDEO_GET_SIZE" +role="subsection"><title>VIDEO_GET_SIZE</title> +<para>DESCRIPTION +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>This ioctl returns the size and aspect ratio.</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>SYNOPSIS +</para> +<informaltable><tgroup cols="1"><tbody><row><entry + align="char"> +<para>int ioctl(int fd, int request = + VIDEO_GET_SIZE, video_size_t *size);</para> +</entry> + </row></tbody></tgroup></informaltable> +<para>PARAMETERS +</para> +<informaltable><tgroup cols="2"><tbody><row><entry + align="char"> +<para>int fd</para> +</entry><entry + align="char"> +<para>File descriptor returned by a previous call to open().</para> +</entry> + </row><row><entry + align="char"> +<para>int request</para> +</entry><entry + align="char"> +<para>Equals VIDEO_GET_SIZE for this + command.</para> +</entry> + </row><row><entry + align="char"> +<para>video_size_t *size +</para> +</entry><entry + align="char"> +<para>Returns the size and aspect ratio. +</para> +</entry> + </row></tbody></tgroup></informaltable> +&return-value-dvb; + </section><section id="VIDEO_SET_DISPLAY_FORMAT" role="subsection"><title>VIDEO_SET_DISPLAY_FORMAT</title> <para>DESCRIPTION diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index 1078e45f189f..d2eb79e41a01 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -178,23 +178,23 @@ Signal - NTSC for Studio Applications"</title> 1125-Line High-Definition Production"</title> </biblioentry> - <biblioentry id="en50067"> - <abbrev>EN 50067</abbrev> + <biblioentry id="iec62106"> + <abbrev>IEC 62106</abbrev> <authorgroup> - <corpauthor>European Committee for Electrotechnical Standardization -(<ulink url="http://www.cenelec.eu">http://www.cenelec.eu</ulink>)</corpauthor> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> </authorgroup> <title>Specification of the radio data system (RDS) for VHF/FM sound broadcasting in the frequency range from 87,5 to 108,0 MHz</title> </biblioentry> <biblioentry id="nrsc4"> - <abbrev>NRSC-4</abbrev> + <abbrev>NRSC-4-B</abbrev> <authorgroup> <corpauthor>National Radio Systems Committee (<ulink url="http://www.nrscstandards.org">http://www.nrscstandards.org</ulink>)</corpauthor> </authorgroup> - <title>NRSC-4: United States RBDS Standard</title> + <title>NRSC-4-B: United States RBDS Standard</title> </biblioentry> <biblioentry id="iso12232"> @@ -226,4 +226,44 @@ in the frequency range from 87,5 to 108,0 MHz</title> <title>VESA and Industry Standards and Guidelines for Computer Display Monitor Timing (DMT)</title> </biblioentry> + <biblioentry id="vesaedid"> + <abbrev>EDID</abbrev> + <authorgroup> + <corpauthor>Video Electronics Standards Association +(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor> + </authorgroup> + <title>VESA Enhanced Extended Display Identification Data Standard</title> + <subtitle>Release A, Revision 2</subtitle> + </biblioentry> + + <biblioentry id="hdcp"> + <abbrev>HDCP</abbrev> + <authorgroup> + <corpauthor>Digital Content Protection LLC +(<ulink url="http://www.digital-cp.com">http://www.digital-cp.com</ulink>)</corpauthor> + </authorgroup> + <title>High-bandwidth Digital Content Protection System</title> + <subtitle>Revision 1.3</subtitle> + </biblioentry> + + <biblioentry id="hdmi"> + <abbrev>HDMI</abbrev> + <authorgroup> + <corpauthor>HDMI Licensing LLC +(<ulink url="http://www.hdmi.org">http://www.hdmi.org</ulink>)</corpauthor> + </authorgroup> + <title>High-Definition Multimedia Interface</title> + <subtitle>Specification Version 1.4a</subtitle> + </biblioentry> + + <biblioentry id="dp"> + <abbrev>DP</abbrev> + <authorgroup> + <corpauthor>Video Electronics Standards Association +(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor> + </authorgroup> + <title>VESA DisplayPort Standard</title> + <subtitle>Version 1, Revision 2</subtitle> + </biblioentry> + </bibliography> diff --git a/Documentation/DocBook/media/v4l/common.xml b/Documentation/DocBook/media/v4l/common.xml index b91d25313b63..73c6847436c9 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -564,7 +564,7 @@ automatically.</para> <para>To query and select the standard used by the current video input or output applications call the &VIDIOC-G-STD; and &VIDIOC-S-STD; ioctl, respectively. The <emphasis>received</emphasis> -standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote> +standard can be sensed with the &VIDIOC-QUERYSTD; ioctl. Note that the parameter of all these ioctls is a pointer to a &v4l2-std-id; type (a standard set), <emphasis>not</emphasis> an index into the standard enumeration.<footnote> <para>An alternative to the current scheme is to use pointers to indices as arguments of <constant>VIDIOC_G_STD</constant> and <constant>VIDIOC_S_STD</constant>, the &v4l2-input; and @@ -588,30 +588,28 @@ switch to a standard by &v4l2-std-id;.</para> </footnote> Drivers must implement all video standard ioctls when the device has one or more video inputs or outputs.</para> - <para>Special rules apply to USB cameras where the notion of video -standards makes little sense. More generally any capture device, -output devices accordingly, which is <itemizedlist> + <para>Special rules apply to devices such as USB cameras where the notion of video +standards makes little sense. More generally for any capture or output device +which is: <itemizedlist> <listitem> <para>incapable of capturing fields or frames at the nominal rate of the video standard, or</para> </listitem> <listitem> - <para>where <link linkend="buffer">timestamps</link> refer -to the instant the field or frame was received by the driver, not the -capture time, or</para> - </listitem> - <listitem> - <para>where <link linkend="buffer">sequence numbers</link> -refer to the frames received by the driver, not the captured -frames.</para> + <para>that does not support the video standard formats at all.</para> </listitem> </itemizedlist> Here the driver shall set the <structfield>std</structfield> field of &v4l2-input; and &v4l2-output; -to zero, the <constant>VIDIOC_G_STD</constant>, +to zero and the <constant>VIDIOC_G_STD</constant>, <constant>VIDIOC_S_STD</constant>, <constant>VIDIOC_QUERYSTD</constant> and <constant>VIDIOC_ENUMSTD</constant> ioctls shall return the -&EINVAL;.<footnote> +&ENOTTY;.<footnote> + <para>See <xref linkend="buffer" /> for a rationale.</para> + <para>Applications can make use of the <xref linkend="input-capabilities" /> and +<xref linkend="output-capabilities"/> flags to determine whether the video standard ioctls +are available for the device.</para> +&ENOTTY;. <para>See <xref linkend="buffer" /> for a rationale. Probably even USB cameras follow some well known video standard. It might have been better to explicitly indicate elsewhere if a device cannot live @@ -626,9 +624,9 @@ up to normal expectations, instead of this exception.</para> &v4l2-standard; standard; if (-1 == ioctl (fd, &VIDIOC-G-STD;, &std_id)) { - /* Note when VIDIOC_ENUMSTD always returns EINVAL this + /* Note when VIDIOC_ENUMSTD always returns ENOTTY this is no video device or it falls under the USB exception, - and VIDIOC_G_STD returning EINVAL is no error. */ + and VIDIOC_G_STD returning ENOTTY is no error. */ perror ("VIDIOC_G_STD"); exit (EXIT_FAILURE); diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index faa0fd14666a..c6ae4c9d0e0c 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -1476,7 +1476,7 @@ follows.<informaltable> </row> <row> <entry><constant>V4L2_BUF_TYPE_PRIVATE_BASE</constant></entry> - <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry> + <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant> (but this is deprecated)</entry> </row> </tbody> </tgroup> @@ -2468,21 +2468,9 @@ that used it. It was originally scheduled for removal in 2.6.35. <structfield>reserved2</structfield> and removed <constant>V4L2_BUF_FLAG_INPUT</constant>.</para> </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.6</title> - <orderedlist> <listitem> <para>Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE capabilities.</para> </listitem> - </orderedlist> - </section> - - <section> - <title>V4L2 in Linux 3.6</title> - <orderedlist> <listitem> <para>Added support for frequency band enumerations: &VIDIOC-ENUM-FREQ-BANDS;.</para> </listitem> @@ -2567,29 +2555,6 @@ and may change in the future.</para> <para>Video Output Overlay (OSD) Interface, <xref linkend="osd" />.</para> </listitem> - <listitem> - <para><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant>, - &v4l2-buf-type;, <xref linkend="v4l2-buf-type" />.</para> - </listitem> - <listitem> - <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>, -&VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para> - </listitem> - <listitem> - <para>&VIDIOC-ENUM-FRAMESIZES; and -&VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para> - </listitem> - <listitem> - <para>&VIDIOC-G-ENC-INDEX; ioctl.</para> - </listitem> - <listitem> - <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; -ioctls.</para> - </listitem> - <listitem> - <para>&VIDIOC-DECODER-CMD; and &VIDIOC-TRY-DECODER-CMD; -ioctls.</para> - </listitem> <listitem> <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; ioctls.</para> @@ -2615,10 +2580,6 @@ ioctls.</para> and &VIDIOC-SUBDEV-S-SELECTION; ioctls.</para> </listitem> <listitem> - <para><link linkend="v4l2-auto-focus-area"><constant> - V4L2_CID_AUTO_FOCUS_AREA</constant></link> control.</para> - </listitem> - <listitem> <para>Support for frequency band enumeration: &VIDIOC-ENUM-FREQ-BANDS; ioctl.</para> </listitem> </itemizedlist> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index b0964fb4e834..272a5f718509 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -3505,7 +3505,7 @@ This encodes up to 31 pre-defined programme types.</entry> </row> <row><entry spanname="descr">Sets the Programme Service name (PS_NAME) for transmission. It is intended for static display on a receiver. It is the primary aid to listeners in programme service -identification and selection. In Annex E of <xref linkend="en50067" />, the RDS specification, +identification and selection. In Annex E of <xref linkend="iec62106" />, the RDS specification, there is a full description of the correct character encoding for Programme Service name strings. Also from RDS specification, PS is usually a single eight character text. However, it is also possible to find receivers which can scroll strings sized as 8 x N characters. So, this control must be configured @@ -3519,7 +3519,7 @@ with steps of 8 characters. The result is it must always contain a string with s what is being broadcasted. RDS Radio Text can be applied when broadcaster wishes to transmit longer PS names, programme-related information or any other text. In these cases, RadioText should be used in addition to <constant>V4L2_CID_RDS_TX_PS_NAME</constant>. The encoding for Radio Text strings is also fully described -in Annex E of <xref linkend="en50067" />. The length of Radio Text strings depends on which RDS Block is being +in Annex E of <xref linkend="iec62106" />. The length of Radio Text strings depends on which RDS Block is being used to transmit it, either 32 (2A block) or 64 (2B block). However, it is also possible to find receivers which can scroll strings sized as 32 x N or 64 x N characters. So, this control must be configured with steps of 32 or 64 characters. The result is it must always contain a string with size multiple of 32 or 64. </entry> @@ -3650,7 +3650,7 @@ manually or automatically if set to zero. Unit, range and step are driver-specif </table> <para>For more details about RDS specification, refer to -<xref linkend="en50067" /> document, from CENELEC.</para> +<xref linkend="iec62106" /> document, from CENELEC.</para> </section> <section id="flash-controls"> @@ -3717,232 +3717,231 @@ interface and may change in the future.</para> use case involving camera or individually. </para> - </section> + <table pgwide="1" frame="none" id="flash-control-id"> + <title>Flash Control IDs</title> + + <tgroup cols="4"> + <colspec colname="c1" colwidth="1*" /> + <colspec colname="c2" colwidth="6*" /> + <colspec colname="c3" colwidth="2*" /> + <colspec colname="c4" colwidth="6*" /> + <spanspec namest="c1" nameend="c2" spanname="id" /> + <spanspec namest="c2" nameend="c4" spanname="descr" /> + <thead> + <row> + <entry spanname="id" align="left">ID</entry> + <entry align="left">Type</entry> + </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> + </row> + </thead> + <tbody valign="top"> + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry> + <entry>class</entry> + </row> + <row> + <entry spanname="descr">The FLASH class descriptor.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_LED_MODE</constant></entry> + <entry>menu</entry> + </row> + <row id="v4l2-flash-led-mode"> + <entry spanname="descr">Defines the mode of the flash LED, + the high-power white LED attached to the flash controller. + Setting this control may not be possible in presence of + some faults. See V4L2_CID_FLASH_FAULT.</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry> + <entry>Off.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry> + <entry>Flash mode.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry> + <entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry> + <entry>menu</entry> + </row> + <row id="v4l2-flash-strobe-source"><entry + spanname="descr">Defines the source of the flash LED + strobe.</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_FLASH_STROBE_SOURCE_SOFTWARE</constant></entry> + <entry>The flash strobe is triggered by using + the V4L2_CID_FLASH_STROBE control.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_STROBE_SOURCE_EXTERNAL</constant></entry> + <entry>The flash strobe is triggered by an + external source. Typically this is a sensor, + which makes it possible to synchronises the + flash strobe start to exposure start.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE</constant></entry> + <entry>button</entry> + </row> + <row> + <entry spanname="descr">Strobe flash. Valid when + V4L2_CID_FLASH_LED_MODE is set to + V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE + is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this + control may not be possible in presence of some faults. + See V4L2_CID_FLASH_FAULT.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STOP</constant></entry> + <entry>button</entry> + </row> + <row><entry spanname="descr">Stop flash strobe immediately.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Strobe status: whether the flash + is strobing at the moment or not. This is a read-only + control.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Hardware timeout for flash. The + flash strobe is stopped after this period of time has + passed from the start of the strobe.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Intensity of the flash strobe when + the flash LED is in flash mode + (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps + (mA) if possible.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Intensity of the flash LED in + torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be + milliamps (mA) if possible. Setting this control may not + be possible in presence of some faults. See + V4L2_CID_FLASH_FAULT.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr">Intensity of the indicator LED. + The indicator LED may be fully independent of the flash + LED. The unit should be microamps (uA) if possible.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry> + <entry>bitmask</entry> + </row> + <row> + <entry spanname="descr">Faults related to the flash. The + faults tell about specific problems in the flash chip + itself or the LEDs attached to it. Faults may prevent + further use of some of the flash controls. In particular, + V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE + if the fault affects the flash LED. Exactly which faults + have such an effect is chip dependent. Reading the faults + resets the control and returns the chip to a usable state + if possible.</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_FLASH_FAULT_OVER_VOLTAGE</constant></entry> + <entry>Flash controller voltage to the flash LED + has exceeded the limit specific to the flash + controller.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_TIMEOUT</constant></entry> + <entry>The flash strobe was still on when + the timeout set by the user --- + V4L2_CID_FLASH_TIMEOUT control --- has expired. + Not all flash controllers may set this in all + such conditions.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_OVER_TEMPERATURE</constant></entry> + <entry>The flash controller has overheated.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_SHORT_CIRCUIT</constant></entry> + <entry>The short circuit protection of the flash + controller has been triggered.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_OVER_CURRENT</constant></entry> + <entry>Current in the LED power supply has exceeded the limit + specific to the flash controller.</entry> + </row> + <row> + <entry><constant>V4L2_FLASH_FAULT_INDICATOR</constant></entry> + <entry>The flash controller has detected a short or open + circuit condition on the indicator LED.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Enable or disable charging of the xenon + flash capacitor.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Is the flash ready to strobe? + Xenon flashes require their capacitors charged before + strobing. LED flashes often require a cooldown period + after strobe during which another strobe will not be + possible. This is a read-only control.</entry> + </row> + <row><entry></entry></row> + </tbody> + </tgroup> + </table> + </section> </section> - - <table pgwide="1" frame="none" id="flash-control-id"> - <title>Flash Control IDs</title> - - <tgroup cols="4"> - <colspec colname="c1" colwidth="1*" /> - <colspec colname="c2" colwidth="6*" /> - <colspec colname="c3" colwidth="2*" /> - <colspec colname="c4" colwidth="6*" /> - <spanspec namest="c1" nameend="c2" spanname="id" /> - <spanspec namest="c2" nameend="c4" spanname="descr" /> - <thead> - <row> - <entry spanname="id" align="left">ID</entry> - <entry align="left">Type</entry> - </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> - </row> - </thead> - <tbody valign="top"> - <row><entry></entry></row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry> - <entry>class</entry> - </row> - <row> - <entry spanname="descr">The FLASH class descriptor.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_LED_MODE</constant></entry> - <entry>menu</entry> - </row> - <row id="v4l2-flash-led-mode"> - <entry spanname="descr">Defines the mode of the flash LED, - the high-power white LED attached to the flash controller. - Setting this control may not be possible in presence of - some faults. See V4L2_CID_FLASH_FAULT.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry> - <entry>Off.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry> - <entry>Flash mode.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry> - <entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry> - <entry>menu</entry> - </row> - <row id="v4l2-flash-strobe-source"><entry - spanname="descr">Defines the source of the flash LED - strobe.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_FLASH_STROBE_SOURCE_SOFTWARE</constant></entry> - <entry>The flash strobe is triggered by using - the V4L2_CID_FLASH_STROBE control.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_STROBE_SOURCE_EXTERNAL</constant></entry> - <entry>The flash strobe is triggered by an - external source. Typically this is a sensor, - which makes it possible to synchronises the - flash strobe start to exposure start.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE</constant></entry> - <entry>button</entry> - </row> - <row> - <entry spanname="descr">Strobe flash. Valid when - V4L2_CID_FLASH_LED_MODE is set to - V4L2_FLASH_LED_MODE_FLASH and V4L2_CID_FLASH_STROBE_SOURCE - is set to V4L2_FLASH_STROBE_SOURCE_SOFTWARE. Setting this - control may not be possible in presence of some faults. - See V4L2_CID_FLASH_FAULT.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STOP</constant></entry> - <entry>button</entry> - </row> - <row><entry spanname="descr">Stop flash strobe immediately.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Strobe status: whether the flash - is strobing at the moment or not. This is a read-only - control.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Hardware timeout for flash. The - flash strobe is stopped after this period of time has - passed from the start of the strobe.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Intensity of the flash strobe when - the flash LED is in flash mode - (V4L2_FLASH_LED_MODE_FLASH). The unit should be milliamps - (mA) if possible.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Intensity of the flash LED in - torch mode (V4L2_FLASH_LED_MODE_TORCH). The unit should be - milliamps (mA) if possible. Setting this control may not - be possible in presence of some faults. See - V4L2_CID_FLASH_FAULT.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry> - <entry>integer</entry> - </row> - <row> - <entry spanname="descr">Intensity of the indicator LED. - The indicator LED may be fully independent of the flash - LED. The unit should be microamps (uA) if possible.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry> - <entry>bitmask</entry> - </row> - <row> - <entry spanname="descr">Faults related to the flash. The - faults tell about specific problems in the flash chip - itself or the LEDs attached to it. Faults may prevent - further use of some of the flash controls. In particular, - V4L2_CID_FLASH_LED_MODE is set to V4L2_FLASH_LED_MODE_NONE - if the fault affects the flash LED. Exactly which faults - have such an effect is chip dependent. Reading the faults - resets the control and returns the chip to a usable state - if possible.</entry> - </row> - <row> - <entrytbl spanname="descr" cols="2"> - <tbody valign="top"> - <row> - <entry><constant>V4L2_FLASH_FAULT_OVER_VOLTAGE</constant></entry> - <entry>Flash controller voltage to the flash LED - has exceeded the limit specific to the flash - controller.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_TIMEOUT</constant></entry> - <entry>The flash strobe was still on when - the timeout set by the user --- - V4L2_CID_FLASH_TIMEOUT control --- has expired. - Not all flash controllers may set this in all - such conditions.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_OVER_TEMPERATURE</constant></entry> - <entry>The flash controller has overheated.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_SHORT_CIRCUIT</constant></entry> - <entry>The short circuit protection of the flash - controller has been triggered.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_OVER_CURRENT</constant></entry> - <entry>Current in the LED power supply has exceeded the limit - specific to the flash controller.</entry> - </row> - <row> - <entry><constant>V4L2_FLASH_FAULT_INDICATOR</constant></entry> - <entry>The flash controller has detected a short or open - circuit condition on the indicator LED.</entry> - </row> - </tbody> - </entrytbl> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry> - <entry>boolean</entry> - </row> - <row><entry spanname="descr">Enable or disable charging of the xenon - flash capacitor.</entry> - </row> - <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry> - <entry>boolean</entry> - </row> - <row> - <entry spanname="descr">Is the flash ready to strobe? - Xenon flashes require their capacitors charged before - strobing. LED flashes often require a cooldown period - after strobe during which another strobe will not be - possible. This is a read-only control.</entry> - </row> - <row><entry></entry></row> - </tbody> - </tgroup> - </table> </section> <section id="jpeg-controls"> @@ -4274,4 +4273,165 @@ interface and may change in the future.</para> </table> </section> + + <section id="dv-controls"> + <title>Digital Video Control Reference</title> + + <note> + <title>Experimental</title> + + <para>This is an <link + linkend="experimental">experimental</link> interface and may + change in the future.</para> + </note> + + <para> + The Digital Video control class is intended to control receivers + and transmitters for <ulink url="http://en.wikipedia.org/wiki/Vga">VGA</ulink>, + <ulink url="http://en.wikipedia.org/wiki/Digital_Visual_Interface">DVI</ulink> + (Digital Visual Interface), HDMI (<xref linkend="hdmi" />) and DisplayPort (<xref linkend="dp" />). + These controls are generally expected to be private to the receiver or transmitter + subdevice that implements them, so they are only exposed on the + <filename>/dev/v4l-subdev*</filename> device node. + </para> + + <para>Note that these devices can have multiple input or output pads which are + hooked up to e.g. HDMI connectors. Even though the subdevice will receive or + transmit video from/to only one of those pads, the other pads can still be + active when it comes to EDID (Extended Display Identification Data, + <xref linkend="vesaedid" />) and HDCP (High-bandwidth Digital Content + Protection System, <xref linkend="hdcp" />) processing, allowing the device + to do the fairly slow EDID/HDCP handling in advance. This allows for quick + switching between connectors.</para> + + <para>These pads appear in several of the controls in this section as + bitmasks, one bit for each pad. Bit 0 corresponds to pad 0, bit 1 to pad 1, + etc. The maximum value of the control is the set of valid pads.</para> + + <table pgwide="1" frame="none" id="dv-control-id"> + <title>Digital Video Control IDs</title> + + <tgroup cols="4"> + <colspec colname="c1" colwidth="1*" /> + <colspec colname="c2" colwidth="6*" /> + <colspec colname="c3" colwidth="2*" /> + <colspec colname="c4" colwidth="6*" /> + <spanspec namest="c1" nameend="c2" spanname="id" /> + <spanspec namest="c2" nameend="c4" spanname="descr" /> + <thead> + <row> + <entry spanname="id" align="left">ID</entry> + <entry align="left">Type</entry> + </row><row rowsep="1"><entry spanname="descr" align="left">Description</entry> + </row> + </thead> + <tbody valign="top"> + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_CLASS</constant></entry> + <entry>class</entry> + </row> + <row> + <entry spanname="descr">The Digital Video class descriptor.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_TX_HOTPLUG</constant></entry> + <entry>bitmask</entry> + </row> + <row> + <entry spanname="descr">Many connectors have a hotplug pin which is high + if EDID information is available from the source. This control shows the + state of the hotplug pin as seen by the transmitter. + Each bit corresponds to an output pad on the transmitter. If an output pad + does not have an associated hotplug pin, then the bit for that pad will be 0. + This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_TX_RXSENSE</constant></entry> + <entry>bitmask</entry> + </row> + <row> + <entry spanname="descr">Rx Sense is the detection of pull-ups on the TMDS + clock lines. This normally means that the sink has left/entered standby (i.e. + the transmitter can sense that the receiver is ready to receive video). + Each bit corresponds to an output pad on the transmitter. If an output pad + does not have an associated Rx Sense, then the bit for that pad will be 0. + This read-only control is applicable to DVI-D and HDMI devices. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_TX_EDID_PRESENT</constant></entry> + <entry>bitmask</entry> + </row> + <row> + <entry spanname="descr">When the transmitter sees the hotplug signal from the + receiver it will attempt to read the EDID. If set, then the transmitter has read + at least the first block (= 128 bytes). + Each bit corresponds to an output pad on the transmitter. If an output pad + does not support EDIDs, then the bit for that pad will be 0. + This read-only control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_TX_MODE</constant></entry> + <entry id="v4l2-dv-tx-mode">enum v4l2_dv_tx_mode</entry> + </row> + <row> + <entry spanname="descr">HDMI transmitters can transmit in DVI-D mode (just video) + or in HDMI mode (video + audio + auxiliary data). This control selects which mode + to use: V4L2_DV_TX_MODE_DVI_D or V4L2_DV_TX_MODE_HDMI. + This control is applicable to HDMI connectors. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_TX_RGB_RANGE</constant></entry> + <entry id="v4l2-dv-rgb-range">enum v4l2_dv_rgb_range</entry> + </row> + <row> + <entry spanname="descr">Select the quantization range for RGB output. V4L2_DV_RANGE_AUTO + follows the RGB quantization range specified in the standard for the video interface + (ie. <xref linkend="cea861" /> for HDMI). V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the standard + to be compatible with sinks that have not implemented the standard correctly + (unfortunately quite common for HDMI and DVI-D). Full range allows all possible values to be + used whereas limited range sets the range to (16 << (N-8)) - (235 << (N-8)) + where N is the number of bits per component. + This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_RX_POWER_PRESENT</constant></entry> + <entry>bitmask</entry> + </row> + <row> + <entry spanname="descr">Detects whether the receiver receives power from the source + (e.g. HDMI carries 5V on one of the pins). This is often used to power an eeprom + which contains EDID information, such that the source can read the EDID even if + the sink is in standby/power off. + Each bit corresponds to an input pad on the transmitter. If an input pad + cannot detect whether power is present, then the bit for that pad will be 0. + This read-only control is applicable to DVI-D, HDMI and DisplayPort connectors. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_RX_RGB_RANGE</constant></entry> + <entry>enum v4l2_dv_rgb_range</entry> + </row> + <row> + <entry spanname="descr">Select the quantization range for RGB input. V4L2_DV_RANGE_AUTO + follows the RGB quantization range specified in the standard for the video interface + (ie. <xref linkend="cea861" /> for HDMI). V4L2_DV_RANGE_LIMITED and V4L2_DV_RANGE_FULL override the standard + to be compatible with sources that have not implemented the standard correctly + (unfortunately quite common for HDMI and DVI-D). Full range allows all possible values to be + used whereas limited range sets the range to (16 << (N-8)) - (235 << (N-8)) + where N is the number of bits per component. + This control is applicable to VGA, DVI-A/D, HDMI and DisplayPort connectors. + </entry> + </row> + <row><entry></entry></row> + </tbody> + </tgroup> + </table> + + </section> </section> diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml index 479d9433869a..dd91d6134e8c 100644 --- a/Documentation/DocBook/media/v4l/dev-osd.xml +++ b/Documentation/DocBook/media/v4l/dev-osd.xml @@ -1,13 +1,6 @@ <title>Video Output Overlay Interface</title> <subtitle>Also known as On-Screen Display (OSD)</subtitle> - <note> - <title>Experimental</title> - - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - <para>Some video output devices can overlay a framebuffer image onto the outgoing video signal. Applications can set up such an overlay using this interface, which borrows structures and ioctls of the <link diff --git a/Documentation/DocBook/media/v4l/dev-rds.xml b/Documentation/DocBook/media/v4l/dev-rds.xml index 38883a419e65..be2f33737323 100644 --- a/Documentation/DocBook/media/v4l/dev-rds.xml +++ b/Documentation/DocBook/media/v4l/dev-rds.xml @@ -6,7 +6,7 @@ information, on an inaudible audio subcarrier of a radio program. This interface is aimed at devices capable of receiving and/or transmitting RDS information.</para> - <para>For more information see the core RDS standard <xref linkend="en50067" /> + <para>For more information see the core RDS standard <xref linkend="iec62106" /> and the RBDS standard <xref linkend="nrsc4" />.</para> <para>Note that the RBDS standard as is used in the USA is almost identical diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index a3d9dd093268..d15aaf83f56f 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -374,29 +374,29 @@ rectangle --- if it is supported by the hardware.</para> <orderedlist> - <listitem>Sink pad format. The user configures the sink pad + <listitem><para>Sink pad format. The user configures the sink pad format. This format defines the parameters of the image the - entity receives through the pad for further processing.</listitem> + entity receives through the pad for further processing.</para></listitem> - <listitem>Sink pad actual crop selection. The sink pad crop - defines the crop performed to the sink pad format.</listitem> + <listitem><para>Sink pad actual crop selection. The sink pad crop + defines the crop performed to the sink pad format.</para></listitem> - <listitem>Sink pad actual compose selection. The size of the + <listitem><para>Sink pad actual compose selection. The size of the sink pad compose rectangle defines the scaling ratio compared to the size of the sink pad crop rectangle. The location of the compose rectangle specifies the location of the actual sink compose rectangle in the sink compose bounds - rectangle.</listitem> + rectangle.</para></listitem> - <listitem>Source pad actual crop selection. Crop on the source + <listitem><para>Source pad actual crop selection. Crop on the source pad defines crop performed to the image in the sink compose - bounds rectangle.</listitem> + bounds rectangle.</para></listitem> - <listitem>Source pad format. The source pad format defines the + <listitem><para>Source pad format. The source pad format defines the output pixel format of the subdev, as well as the other parameters with the exception of the image width and height. Width and height are defined by the size of the source pad - actual crop selection.</listitem> + actual crop selection.</para></listitem> </orderedlist> <para>Accessing any of the above rectangles not supported by the diff --git a/Documentation/DocBook/media/v4l/gen-errors.xml b/Documentation/DocBook/media/v4l/gen-errors.xml index 5bbf3ce1973a..7e29a4e1f696 100644 --- a/Documentation/DocBook/media/v4l/gen-errors.xml +++ b/Documentation/DocBook/media/v4l/gen-errors.xml @@ -7,6 +7,15 @@ <tbody valign="top"> <!-- Keep it ordered alphabetically --> <row> + <entry>EAGAIN (aka EWOULDBLOCK)</entry> + <entry>The ioctl can't be handled because the device is in state where + it can't perform it. This could happen for example in case where + device is sleeping and ioctl is performed to query statistics. + It is also returned when the ioctl would need to wait + for an event, but the device was opened in non-blocking mode. + </entry> + </row> + <row> <entry>EBADF</entry> <entry>The file descriptor is not a valid.</entry> </row> @@ -51,21 +60,11 @@ for periodic transfers (up to 80% of the USB bandwidth).</entry> </row> <row> - <entry>ENOSYS or EOPNOTSUPP</entry> - <entry>Function not available for this device (dvb API only. Will likely - be replaced anytime soon by ENOTTY).</entry> - </row> - <row> <entry>EPERM</entry> <entry>Permission denied. Can be returned if the device needs write permission, or some special capabilities is needed (e. g. root)</entry> </row> - <row> - <entry>EWOULDBLOCK</entry> - <entry>Operation would block. Used when the ioctl would need to wait - for an event, but the device was opened in non-blocking mode.</entry> - </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index 1885cc0755cb..97f785add841 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -613,8 +613,8 @@ field is independent of the <structfield>timestamp</structfield> and <entry>__u32</entry> <entry><structfield>sequence</structfield></entry> <entry></entry> - <entry>Set by the driver, counting the frames in the -sequence.</entry> + <entry>Set by the driver, counting the frames (not fields!) in +sequence. This field is set for both input and output devices.</entry> </row> <row> <entry spanname="hspan"><para>In <link @@ -685,18 +685,14 @@ memory, set by the application. See <xref linkend="userp" /> for details. <entry>__u32</entry> <entry><structfield>reserved2</structfield></entry> <entry></entry> - <entry>A place holder for future extensions and custom -(driver defined) buffer types -<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications + <entry>A place holder for future extensions. Applications should set this to 0.</entry> </row> <row> <entry>__u32</entry> <entry><structfield>reserved</structfield></entry> <entry></entry> - <entry>A place holder for future extensions and custom -(driver defined) buffer types -<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher. Applications + <entry>A place holder for future extensions. Applications should set this to 0.</entry> </row> </tbody> @@ -827,14 +823,7 @@ should set this to 0.</entry> <entry><constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_OVERLAY</constant></entry> <entry>8</entry> <entry>Buffer for video output overlay (OSD), see <xref - linkend="osd" />. Status: <link -linkend="experimental">Experimental</link>.</entry> - </row> - <row> - <entry><constant>V4L2_BUF_TYPE_PRIVATE</constant></entry> - <entry>0x80</entry> - <entry>This and higher values are reserved for custom -(driver defined) buffer types.</entry> + linkend="osd" />.</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml b/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml index 8eace3e2e7d4..2d3f0b1aefe0 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-srggb10dpcm8.xml @@ -22,8 +22,7 @@ with 10 bits per colour compressed to 8 bits each, using DPCM compression. DPCM, differential pulse-code modulation, is lossy. Each colour component consumes 8 bits of memory. In other respects - this format is similar to <xref - linkend="pixfmt-srggb10">.</xref></para> + this format is similar to <xref linkend="pixfmt-srggb10" />.</para> </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml b/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml new file mode 100644 index 000000000000..2330667907c7 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-yvu420m.xml @@ -0,0 +1,154 @@ + <refentry id="V4L2-PIX-FMT-YVU420M"> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_YVU420M ('YM21')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname> <constant>V4L2_PIX_FMT_YVU420M</constant></refname> + <refpurpose>Variation of <constant>V4L2_PIX_FMT_YVU420</constant> + with planes non contiguous in memory. </refpurpose> + </refnamediv> + + <refsect1> + <title>Description</title> + + <para>This is a multi-planar format, as opposed to a packed format. +The three components are separated into three sub-images or planes. + +The Y plane is first. The Y plane has one byte per pixel. The Cr data +constitutes the second plane which is half the width and half +the height of the Y plane (and of the image). Each Cr belongs to four +pixels, a two-by-two square of the image. For example, +Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, +Y'<subscript>01</subscript>, Y'<subscript>10</subscript>, and +Y'<subscript>11</subscript>. The Cb data, just like the Cr plane, constitutes +the third plane. </para> + + <para>If the Y plane has pad bytes after each row, then the Cr +and Cb planes have half as many pad bytes after their rows. In other +words, two Cx rows (including padding) is exactly as long as one Y row +(including padding).</para> + + <para><constant>V4L2_PIX_FMT_YVU420M</constant> is intended to be +used only in drivers and applications that support the multi-planar API, +described in <xref linkend="planar-apis"/>. </para> + + <example> + <title><constant>V4L2_PIX_FMT_YVU420M</constant> 4 × 4 +pixel image</title> + + <formalpara> + <title>Byte Order.</title> + <para>Each cell is one byte. + <informaltable frame="none"> + <tgroup cols="5" align="center"> + <colspec align="left" colwidth="2*" /> + <tbody valign="top"> + <row> + <entry>start0 + 0:</entry> + <entry>Y'<subscript>00</subscript></entry> + <entry>Y'<subscript>01</subscript></entry> + <entry>Y'<subscript>02</subscript></entry> + <entry>Y'<subscript>03</subscript></entry> + </row> + <row> + <entry>start0 + 4:</entry> + <entry>Y'<subscript>10</subscript></entry> + <entry>Y'<subscript>11</subscript></entry> + <entry>Y'<subscript>12</subscript></entry> + <entry>Y'<subscript>13</subscript></entry> + </row> + <row> + <entry>start0 + 8:</entry> + <entry>Y'<subscript>20</subscript></entry> + <entry>Y'<subscript>21</subscript></entry> + <entry>Y'<subscript>22</subscript></entry> + <entry>Y'<subscript>23</subscript></entry> + </row> + <row> + <entry>start0 + 12:</entry> + <entry>Y'<subscript>30</subscript></entry> + <entry>Y'<subscript>31</subscript></entry> + <entry>Y'<subscript>32</subscript></entry> + <entry>Y'<subscript>33</subscript></entry> + </row> + <row><entry></entry></row> + <row> + <entry>start1 + 0:</entry> + <entry>Cr<subscript>00</subscript></entry> + <entry>Cr<subscript>01</subscript></entry> + </row> + <row> + <entry>start1 + 2:</entry> + <entry>Cr<subscript>10</subscript></entry> + <entry>Cr<subscript>11</subscript></entry> + </row> + <row><entry></entry></row> + <row> + <entry>start2 + 0:</entry> + <entry>Cb<subscript>00</subscript></entry> + <entry>Cb<subscript>01</subscript></entry> + </row> + <row> + <entry>start2 + 2:</entry> + <entry>Cb<subscript>10</subscript></entry> + <entry>Cb<subscript>11</subscript></entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + + <formalpara> + <title>Color Sample Location.</title> + <para> + <informaltable frame="none"> + <tgroup cols="7" align="center"> + <tbody valign="top"> + <row> + <entry></entry> + <entry>0</entry><entry></entry><entry>1</entry><entry></entry> + <entry>2</entry><entry></entry><entry>3</entry> + </row> + <row> + <entry>0</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + <entry></entry><entry>C</entry><entry></entry><entry></entry> + <entry></entry><entry>C</entry><entry></entry> + </row> + <row> + <entry>1</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + </row> + <row> + <entry>2</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + <row> + <entry></entry> + <entry></entry><entry>C</entry><entry></entry><entry></entry> + <entry></entry><entry>C</entry><entry></entry> + </row> + <row> + <entry>3</entry> + <entry>Y</entry><entry></entry><entry>Y</entry><entry></entry> + <entry>Y</entry><entry></entry><entry>Y</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </para> + </formalpara> + </example> + </refsect1> + </refentry> diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index e58934c92895..1ddbfabe3195 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -708,6 +708,7 @@ information.</para> &sub-y41p; &sub-yuv420; &sub-yuv420m; + &sub-yvu420m; &sub-yuv410; &sub-yuv422p; &sub-yuv411p; diff --git a/Documentation/DocBook/media/v4l/selection-api.xml b/Documentation/DocBook/media/v4l/selection-api.xml index e7ed5077834d..4c238ce068b0 100644 --- a/Documentation/DocBook/media/v4l/selection-api.xml +++ b/Documentation/DocBook/media/v4l/selection-api.xml @@ -40,6 +40,7 @@ cropping and composing rectangles have the same size.</para> <section> <title>Selection targets</title> + <para> <figure id="sel-targets-capture"> <title>Cropping and composing targets</title> <mediaobject> @@ -52,12 +53,12 @@ cropping and composing rectangles have the same size.</para> </textobject> </mediaobject> </figure> + </para> + <para>See <xref linkend="v4l2-selection-targets" /> for more + information.</para> </section> - See <xref linkend="v4l2-selection-targets" /> for more - information. - <section> <title>Configuration</title> @@ -216,18 +217,17 @@ composing and cropping operations by setting the appropriate targets. The V4L2 API lacks any support for composing to and cropping from an image inside a memory buffer. The application could configure a capture device to fill only a part of an image by abusing V4L2 API. Cropping a smaller image from a larger -one is achieved by setting the field <structfield> -&v4l2-pix-format;::bytesperline </structfield>. Introducing an image offsets -could be done by modifying field <structfield> &v4l2-buffer;::m:userptr -</structfield> before calling <constant> VIDIOC_QBUF </constant>. Those +one is achieved by setting the field +&v4l2-pix-format;<structfield>::bytesperline</structfield>. Introducing an image offsets +could be done by modifying field &v4l2-buffer;<structfield>::m_userptr</structfield> +before calling <constant> VIDIOC_QBUF </constant>. Those operations should be avoided because they are not portable (endianness), and do not work for macroblock and Bayer formats and mmap buffers. The selection API deals with configuration of buffer cropping/composing in a clear, intuitive and portable way. Next, with the selection API the concepts of the padded target -and constraints flags are introduced. Finally, <structname> &v4l2-crop; -</structname> and <structname> &v4l2-cropcap; </structname> have no reserved -fields. Therefore there is no way to extend their functionality. The new -<structname> &v4l2-selection; </structname> provides a lot of place for future +and constraints flags are introduced. Finally, &v4l2-crop; and &v4l2-cropcap; +have no reserved fields. Therefore there is no way to extend their functionality. +The new &v4l2-selection; provides a lot of place for future extensions. Driver developers are encouraged to implement only selection API. The former cropping API would be simulated using the new one. </para> diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index eee6908c749f..10ccde9d16d0 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -145,9 +145,12 @@ applications. --> <authorinitials>hv</authorinitials> <revremark>Added VIDIOC_ENUM_FREQ_BANDS. </revremark> + </revision> + + <revision> <revnumber>3.5</revnumber> <date>2012-05-07</date> - <authorinitials>sa, sn</authorinitials> + <authorinitials>sa, sn, hv</authorinitials> <revremark>Added V4L2_CTRL_TYPE_INTEGER_MENU and V4L2 subdev selections API. Improved the description of V4L2_CID_COLORFX control, added V4L2_CID_COLORFX_CBCR control. @@ -158,11 +161,8 @@ applications. --> V4L2_CID_3A_LOCK, V4L2_CID_AUTO_FOCUS_START, V4L2_CID_AUTO_FOCUS_STOP, V4L2_CID_AUTO_FOCUS_STATUS and V4L2_CID_AUTO_FOCUS_RANGE. - </revremark> - <date>2012-05-01</date> - <authorinitials>hv</authorinitials> - <revremark>Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and - VIDIOC_DV_TIMINGS_CAP. + Added VIDIOC_ENUM_DV_TIMINGS, VIDIOC_QUERY_DV_TIMINGS and + VIDIOC_DV_TIMINGS_CAP. </revremark> </revision> @@ -472,7 +472,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 3.5</subtitle> + <subtitle>Revision 3.6</subtitle> <chapter id="common"> &sub-common; @@ -581,6 +581,7 @@ and discussions on the V4L mailing list.</revremark> &sub-subdev-enum-frame-size; &sub-subdev-enum-mbus-code; &sub-subdev-g-crop; + &sub-subdev-g-edid; &sub-subdev-g-fmt; &sub-subdev-g-frame-interval; &sub-subdev-g-selection; diff --git a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml index f1bac2c6e978..bf7cc979fdfa 100644 --- a/Documentation/DocBook/media/v4l/vidioc-cropcap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-cropcap.xml @@ -59,6 +59,9 @@ constant except when switching the video standard. Remember this switch can occur implicit when switching the video input or output.</para> + <para>This ioctl must be implemented for video capture or output devices that +support cropping and/or scaling and/or have non-square pixels, and for overlay devices.</para> + <table pgwide="1" frame="none" id="v4l2-cropcap"> <title>struct <structname>v4l2_cropcap</structname></title> <tgroup cols="3"> @@ -70,10 +73,10 @@ output.</para> <entry>Type of the data stream, set by the application. Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, +<constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>, <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver -defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> -and higher. See <xref linkend="v4l2-buf-type" />.</entry> +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and +<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry> </row> <row> <entry>struct <link linkend="v4l2-rect-crop">v4l2_rect</link></entry> @@ -156,8 +159,7 @@ on 22 Oct 2002 subject "Re:[V4L][patches!] Re:v4l2/kernel-2.5" --> <term><errorcode>EINVAL</errorcode></term> <listitem> <para>The &v4l2-cropcap; <structfield>type</structfield> is -invalid. This is not permitted for video capture, output and overlay devices, -which must support <constant>VIDIOC_CROPCAP</constant>.</para> +invalid.</para> </listitem> </varlistentry> </variablelist> diff --git a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml index 74b87f6e480a..9215627b04c7 100644 --- a/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-decoder-cmd.xml @@ -49,13 +49,6 @@ <refsect1> <title>Description</title> - <note> - <title>Experimental</title> - - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - <para>These ioctls control an audio/video (usually MPEG-) decoder. <constant>VIDIOC_DECODER_CMD</constant> sends a command to the decoder, <constant>VIDIOC_TRY_DECODER_CMD</constant> can be used to diff --git a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml index f431b3ba79bd..0619ca5d2d36 100644 --- a/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-encoder-cmd.xml @@ -49,13 +49,6 @@ <refsect1> <title>Description</title> - <note> - <title>Experimental</title> - - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - <para>These ioctls control an audio/video (usually MPEG-) encoder. <constant>VIDIOC_ENCODER_CMD</constant> sends a command to the encoder, <constant>VIDIOC_TRY_ENCODER_CMD</constant> can be used to diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml index 509f0012d2a6..fced5fb0dbf0 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-presets.xml @@ -229,6 +229,12 @@ intended for the user.</entry> is out of bounds.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Digital video presets are not supported for this input or output.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml index 24c3bf4fd29a..b3e17c1dfaf5 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-dv-timings.xml @@ -106,6 +106,12 @@ application.</entry> is out of bounds.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Digital video presets are not supported for this input or output.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml index 81ebe48317fe..f8dfeed34fca 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-fmt.xml @@ -58,6 +58,9 @@ structure. Drivers fill the rest of the structure or return an incrementing by one until <errorcode>EINVAL</errorcode> is returned.</para> + <para>Note that after switching input or output the list of enumerated image +formats may be different.</para> + <table pgwide="1" frame="none" id="v4l2-fmtdesc"> <title>struct <structname>v4l2_fmtdesc</structname></title> <tgroup cols="3"> @@ -78,10 +81,8 @@ Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE</constant>, <constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver -defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> -and higher. See <xref linkend="v4l2-buf-type" />.</entry> +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT_MPLANE</constant> and +<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml index f77a13f486d7..a78454b5abcd 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enum-framesizes.xml @@ -50,13 +50,6 @@ and pixel format and receives a frame width and height.</para> <refsect1> <title>Description</title> - <note> - <title>Experimental</title> - - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - <para>This ioctl allows applications to enumerate all frame sizes (&ie; width and height in pixels) that the device supports for the given pixel format.</para> diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml index 46d5a044a537..3c9a81305ad4 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml @@ -283,7 +283,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>This input supports setting DV presets by using VIDIOC_S_DV_PRESET.</entry> </row> <row> - <entry><constant>V4L2_IN_CAP_CUSTOM_TIMINGS</constant></entry> + <entry><constant>V4L2_IN_CAP_DV_TIMINGS</constant></entry> <entry>0x00000002</entry> <entry>This input supports setting video timings by using VIDIOC_S_DV_TIMINGS.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml index 428020000ef0..f4ab0798545d 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml @@ -168,7 +168,7 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>This output supports setting DV presets by using VIDIOC_S_DV_PRESET.</entry> </row> <row> - <entry><constant>V4L2_OUT_CAP_CUSTOM_TIMINGS</constant></entry> + <entry><constant>V4L2_OUT_CAP_DV_TIMINGS</constant></entry> <entry>0x00000002</entry> <entry>This output supports setting video timings by using VIDIOC_S_DV_TIMINGS.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml index 3a5fc5405f96..8065099401d1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumstd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumstd.xml @@ -378,6 +378,12 @@ system)</para></footnote></para></entry> is out of bounds.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Standard video timings are not supported for this input or output.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml b/Documentation/DocBook/media/v4l/vidioc-g-crop.xml index c4ff3b1887fb..75c6a93de3c1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-crop.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-crop.xml @@ -104,10 +104,8 @@ changed and <constant>VIDIOC_S_CROP</constant> returns the <entry><structfield>type</structfield></entry> <entry>Type of the data stream, set by the application. Only these types are valid here: <constant>V4L2_BUF_TYPE_VIDEO_CAPTURE</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant>, -<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>, and custom (driver -defined) types with code <constant>V4L2_BUF_TYPE_PRIVATE</constant> -and higher. See <xref linkend="v4l2-buf-type" />.</entry> +<constant>V4L2_BUF_TYPE_VIDEO_OUTPUT</constant> and +<constant>V4L2_BUF_TYPE_VIDEO_OVERLAY</constant>. See <xref linkend="v4l2-buf-type" />.</entry> </row> <row> <entry>&v4l2-rect;</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml index 61be9fa3803a..b9ea37634f6c 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-preset.xml @@ -78,6 +78,12 @@ If the preset is not supported, it returns an &EINVAL; </para> </listitem> </varlistentry> <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Digital video presets are not supported for this input or output.</para> + </listitem> + </varlistentry> + <varlistentry> <term><errorcode>EBUSY</errorcode></term> <listitem> <para>The device is busy and therefore can not change the preset.</para> @@ -104,7 +110,4 @@ If the preset is not supported, it returns an &EINVAL; </para> </tgroup> </table> </refsect1> - <refsect1> - &return-value; - </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml index eda1a2991bbe..72369707bd77 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-dv-timings.xml @@ -56,7 +56,9 @@ a pointer to the &v4l2-dv-timings; structure as argument. If the ioctl is not su or the timing values are not correct, the driver returns &EINVAL;.</para> <para>The <filename>linux/v4l2-dv-timings.h</filename> header can be used to get the timings of the formats in the <xref linkend="cea861" /> and <xref linkend="vesadmt" /> -standards.</para> +standards. If the current input or output does not support DV timings (e.g. if +&VIDIOC-ENUMINPUT; does not set the <constant>V4L2_IN_CAP_DV_TIMINGS</constant> flag), then +&ENODATA; is returned.</para> </refsect1> <refsect1> @@ -71,6 +73,12 @@ standards.</para> </listitem> </varlistentry> <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Digital video timings are not supported for this input or output.</para> + </listitem> + </varlistentry> + <varlistentry> <term><errorcode>EBUSY</errorcode></term> <listitem> <para>The device is busy and therefore can not change the timings.</para> @@ -320,7 +328,4 @@ detected or used depends on the hardware. </tgroup> </table> </refsect1> - <refsect1> - &return-value; - </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml b/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml index 2aef02c9044e..be25029a16f1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-enc-index.xml @@ -48,13 +48,6 @@ <refsect1> <title>Description</title> - <note> - <title>Experimental</title> - - <para>This is an <link linkend="experimental">experimental</link> -interface and may change in the future.</para> - </note> - <para>The <constant>VIDIOC_G_ENC_INDEX</constant> ioctl provides meta data about a compressed video stream the same or another application currently reads from the driver, which is useful for diff --git a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml index 52acff193a6f..ee8f56e1bac0 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-fmt.xml @@ -81,7 +81,7 @@ the application calls the <constant>VIDIOC_S_FMT</constant> ioctl with a pointer to a <structname>v4l2_format</structname> structure the driver checks and adjusts the parameters against hardware abilities. Drivers -should not return an error code unless the input is ambiguous, this is +should not return an error code unless the <structfield>type</structfield> field is invalid, this is a mechanism to fathom device capabilities and to approach parameters acceptable for both the application and driver. On success the driver may program the hardware, allocate resources and generally prepare for @@ -107,6 +107,10 @@ disabling I/O or possibly time consuming hardware preparations. Although strongly recommended drivers are not required to implement this ioctl.</para> + <para>The format as returned by <constant>VIDIOC_TRY_FMT</constant> +must be identical to what <constant>VIDIOC_S_FMT</constant> returns for +the same input or output.</para> + <table pgwide="1" frame="none" id="v4l2-format"> <title>struct <structname>v4l2_format</structname></title> <tgroup cols="4"> @@ -170,9 +174,7 @@ capture and output devices.</entry> <entry></entry> <entry>__u8</entry> <entry><structfield>raw_data</structfield>[200]</entry> - <entry>Place holder for future extensions and custom -(driver defined) formats with <structfield>type</structfield> -<constant>V4L2_BUF_TYPE_PRIVATE</constant> and higher.</entry> + <entry>Place holder for future extensions.</entry> </row> </tbody> </tgroup> @@ -187,8 +189,7 @@ capture and output devices.</entry> <term><errorcode>EINVAL</errorcode></term> <listitem> <para>The &v4l2-format; <structfield>type</structfield> -field is invalid, the requested buffer type not supported, or the -format is not supported with this buffer type.</para> +field is invalid or the requested buffer type not supported.</para> </listitem> </varlistentry> </variablelist> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml index f83d2cdd1185..9058224d1bbf 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-parm.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-parm.xml @@ -108,9 +108,7 @@ devices.</para> <entry></entry> <entry>__u8</entry> <entry><structfield>raw_data</structfield>[200]</entry> - <entry>A place holder for future extensions and custom -(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and -higher.</entry> + <entry>A place holder for future extensions.</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml index f76d8a6d9b92..b11ec75e21a1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-selection.xml @@ -152,12 +152,10 @@ satisfactory parameters have been negotiated. If constraints flags have to be violated at then ERANGE is returned. The error indicates that <emphasis> there exist no rectangle </emphasis> that satisfies the constraints.</para> - </refsect1> - <para>Selection targets and flags are documented in <xref linkend="v4l2-selections-common"/>.</para> - <section> + <para> <figure id="sel-const-adjust"> <title>Size adjustments with constraint flags.</title> <mediaobject> @@ -170,9 +168,9 @@ exist no rectangle </emphasis> that satisfies the constraints.</para> </textobject> </mediaobject> </figure> - </section> + </para> - <refsect1> + <para> <table pgwide="1" frame="none" id="v4l2-selection"> <title>struct <structname>v4l2_selection</structname></title> <tgroup cols="3"> @@ -208,6 +206,7 @@ exist no rectangle </emphasis> that satisfies the constraints.</para> </tbody> </tgroup> </table> + </para> </refsect1> <refsect1> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-std.xml b/Documentation/DocBook/media/v4l/vidioc-g-std.xml index 99ff1a016220..4a898417de28 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-std.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-std.xml @@ -72,7 +72,9 @@ flags, being a write-only ioctl it does not return the actual new standard as the current input does not support the requested standard the driver returns an &EINVAL;. When the standard set is ambiguous drivers may return <errorcode>EINVAL</errorcode> or choose any of the requested -standards.</para> +standards. If the current input or output does not support standard video timings (e.g. if +&VIDIOC-ENUMINPUT; does not set the <constant>V4L2_IN_CAP_STD</constant> flag), then +&ENODATA; is returned.</para> </refsect1> <refsect1> @@ -85,6 +87,12 @@ standards.</para> <para>The <constant>VIDIOC_S_STD</constant> parameter was unsuitable.</para> </listitem> </varlistentry> + <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Standard video timings are not supported for this input or output.</para> + </listitem> + </varlistentry> </variablelist> </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml index 701138f1209d..6cc82010c736 100644 --- a/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml +++ b/Documentation/DocBook/media/v4l/vidioc-g-tuner.xml @@ -354,6 +354,12 @@ radio tuners.</entry> <entry>The &VIDIOC-ENUM-FREQ-BANDS; ioctl can be used to enumerate the available frequency bands.</entry> </row> + <row> + <entry><constant>V4L2_TUNER_CAP_HWSEEK_PROG_LIM</constant></entry> + <entry>0x0800</entry> + <entry>The range to search when using the hardware seek functionality + is programmable, see &VIDIOC-S-HW-FREQ-SEEK; for details.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml index 77ff5be0809d..6a821a65a5ae 100644 --- a/Documentation/DocBook/media/v4l/vidioc-qbuf.xml +++ b/Documentation/DocBook/media/v4l/vidioc-qbuf.xml @@ -155,6 +155,8 @@ or no buffers have been allocated yet, or the <structfield>userptr</structfield> or <structfield>length</structfield> are invalid.</para> </listitem> + </varlistentry> + <varlistentry> <term><errorcode>EIO</errorcode></term> <listitem> <para><constant>VIDIOC_DQBUF</constant> failed due to an diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml index 1bc8aeb3ff1f..68b49d09e245 100644 --- a/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml +++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-preset.xml @@ -65,5 +65,14 @@ returned.</para> <refsect1> &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Digital video presets are not supported for this input or output.</para> + </listitem> + </varlistentry> + </variablelist> </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml index 44935a0ffcf0..e185f149e0a1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml +++ b/Documentation/DocBook/media/v4l/vidioc-query-dv-timings.xml @@ -78,6 +78,12 @@ capabilities in order to give more precise feedback to the user. <variablelist> <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Digital video timings are not supported for this input or output.</para> + </listitem> + </varlistentry> + <varlistentry> <term><errorcode>ENOLINK</errorcode></term> <listitem> <para>No timings could be detected because no signal was found. diff --git a/Documentation/DocBook/media/v4l/vidioc-querycap.xml b/Documentation/DocBook/media/v4l/vidioc-querycap.xml index f33dd746b66b..4c70215ae03f 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querycap.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querycap.xml @@ -90,11 +90,13 @@ ambiguities.</entry> <entry>__u8</entry> <entry><structfield>bus_info</structfield>[32]</entry> <entry>Location of the device in the system, a -NUL-terminated ASCII string. For example: "PCI Slot 4". This +NUL-terminated ASCII string. For example: "PCI:0000:05:06.0". This information is intended for users, to distinguish multiple -identical devices. If no such information is available the field may -simply count the devices controlled by the driver, or contain the -empty string (<structfield>bus_info</structfield>[0] = 0).<!-- XXX pci_dev->slot_name example --></entry> +identical devices. If no such information is available the field must +simply count the devices controlled by the driver ("platform:vivi-000"). +The bus_info must start with "PCI:" for PCI boards, "PCIe:" for PCI Express boards, +"usb-" for USB devices, "I2C:" for i2c devices, "ISA:" for ISA devices, +"parport" for parallel port devices and "platform:" for platform devices.</entry> </row> <row> <entry>__u32</entry> diff --git a/Documentation/DocBook/media/v4l/vidioc-querystd.xml b/Documentation/DocBook/media/v4l/vidioc-querystd.xml index 4b79c7c04ed6..fe80a183d957 100644 --- a/Documentation/DocBook/media/v4l/vidioc-querystd.xml +++ b/Documentation/DocBook/media/v4l/vidioc-querystd.xml @@ -62,5 +62,13 @@ current video input or output.</para> <refsect1> &return-value; + <variablelist> + <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>Standard video timings are not supported for this input or output.</para> + </listitem> + </varlistentry> + </variablelist> </refsect1> </refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml index d7c95057bc51..2b50ef2007f3 100644 --- a/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml +++ b/Documentation/DocBook/media/v4l/vidioc-reqbufs.xml @@ -109,9 +109,8 @@ as the &v4l2-format; <structfield>type</structfield> field. See <xref <row> <entry>__u32</entry> <entry><structfield>reserved</structfield>[2]</entry> - <entry>A place holder for future extensions and custom -(driver defined) buffer types <constant>V4L2_BUF_TYPE_PRIVATE</constant> and -higher. This array should be zeroed by applications.</entry> + <entry>A place holder for future extensions. This array should +be zeroed by applications.</entry> </row> </tbody> </tgroup> diff --git a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml index 3dd1bec6d3c7..5b379e752194 100644 --- a/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml +++ b/Documentation/DocBook/media/v4l/vidioc-s-hw-freq-seek.xml @@ -75,6 +75,9 @@ seek is started.</para> <para>This ioctl is supported if the <constant>V4L2_CAP_HW_FREQ_SEEK</constant> capability is set.</para> + <para>If this ioctl is called from a non-blocking filehandle, then &EAGAIN; is + returned and no seek takes place.</para> + <table pgwide="1" frame="none" id="v4l2-hw-freq-seek"> <title>struct <structname>v4l2_hw_freq_seek</structname></title> <tgroup cols="3"> @@ -158,6 +161,13 @@ fields is wrong.</para> </listitem> </varlistentry> <varlistentry> + <term><errorcode>EAGAIN</errorcode></term> + <listitem> + <para>Attempted to call <constant>VIDIOC_S_HW_FREQ_SEEK</constant> + with the filehandle in non-blocking mode.</para> + </listitem> + </varlistentry> + <varlistentry> <term><errorcode>ENODATA</errorcode></term> <listitem> <para>The hardware seek found no channels.</para> diff --git a/Documentation/DocBook/media/v4l/vidioc-streamon.xml b/Documentation/DocBook/media/v4l/vidioc-streamon.xml index 81cca4569050..716ea15e54a1 100644 --- a/Documentation/DocBook/media/v4l/vidioc-streamon.xml +++ b/Documentation/DocBook/media/v4l/vidioc-streamon.xml @@ -74,7 +74,12 @@ not transmitted yet. I/O returns to the same state as after calling stream type. This is the same as &v4l2-requestbuffers; <structfield>type</structfield>.</para> - <para>Note applications can be preempted for unknown periods right + <para>If <constant>VIDIOC_STREAMON</constant> is called when streaming +is already in progress, or if <constant>VIDIOC_STREAMOFF</constant> is called +when streaming is already stopped, then the ioctl does nothing and 0 is +returned.</para> + + <para>Note that applications can be preempted for unknown periods right before or after the <constant>VIDIOC_STREAMON</constant> or <constant>VIDIOC_STREAMOFF</constant> calls, there is no notion of starting or stopping "now". Buffer timestamps can be used to diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml new file mode 100644 index 000000000000..bbd18f0e6ede --- /dev/null +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-edid.xml @@ -0,0 +1,152 @@ +<refentry id="vidioc-subdev-g-edid"> + <refmeta> + <refentrytitle>ioctl VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</refentrytitle> + &manvol; + </refmeta> + + <refnamediv> + <refname>VIDIOC_SUBDEV_G_EDID</refname> + <refname>VIDIOC_SUBDEV_S_EDID</refname> + <refpurpose>Get or set the EDID of a video receiver/transmitter</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>struct v4l2_subdev_edid *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>ioctl</function></funcdef> + <paramdef>int <parameter>fd</parameter></paramdef> + <paramdef>int <parameter>request</parameter></paramdef> + <paramdef>const struct v4l2_subdev_edid *<parameter>argp</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Arguments</title> + + <variablelist> + <varlistentry> + <term><parameter>fd</parameter></term> + <listitem> + <para>&fd;</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>request</parameter></term> + <listitem> + <para>VIDIOC_SUBDEV_G_EDID, VIDIOC_SUBDEV_S_EDID</para> + </listitem> + </varlistentry> + <varlistentry> + <term><parameter>argp</parameter></term> + <listitem> + <para></para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Description</title> + <para>These ioctls can be used to get or set an EDID associated with an input pad + from a receiver or an output pad of a transmitter subdevice.</para> + + <para>To get the EDID data the application has to fill in the <structfield>pad</structfield>, + <structfield>start_block</structfield>, <structfield>blocks</structfield> and <structfield>edid</structfield> + fields and call <constant>VIDIOC_SUBDEV_G_EDID</constant>. The current EDID from block + <structfield>start_block</structfield> and of size <structfield>blocks</structfield> + will be placed in the memory <structfield>edid</structfield> points to. The <structfield>edid</structfield> + pointer must point to memory at least <structfield>blocks</structfield> * 128 bytes + large (the size of one block is 128 bytes).</para> + + <para>If there are fewer blocks than specified, then the driver will set <structfield>blocks</structfield> + to the actual number of blocks. If there are no EDID blocks available at all, then the error code + ENODATA is set.</para> + + <para>If blocks have to be retrieved from the sink, then this call will block until they + have been read.</para> + + <para>To set the EDID blocks of a receiver the application has to fill in the <structfield>pad</structfield>, + <structfield>blocks</structfield> and <structfield>edid</structfield> fields and set + <structfield>start_block</structfield> to 0. It is not possible to set part of an EDID, + it is always all or nothing. Setting the EDID data is only valid for receivers as it makes + no sense for a transmitter.</para> + + <para>The driver assumes that the full EDID is passed in. If there are more EDID blocks than + the hardware can handle then the EDID is not written, but instead the error code E2BIG is set + and <structfield>blocks</structfield> is set to the maximum that the hardware supports. + If <structfield>start_block</structfield> is any + value other than 0 then the error code EINVAL is set.</para> + + <para>To disable an EDID you set <structfield>blocks</structfield> to 0. Depending on the + hardware this will drive the hotplug pin low and/or block the source from reading the EDID + data in some way. In any case, the end result is the same: the EDID is no longer available. + </para> + + <table pgwide="1" frame="none" id="v4l2-subdev-edid"> + <title>struct <structname>v4l2_subdev_edid</structname></title> + <tgroup cols="3"> + &cs-str; + <tbody valign="top"> + <row> + <entry>__u32</entry> + <entry><structfield>pad</structfield></entry> + <entry>Pad for which to get/set the EDID blocks.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>start_block</structfield></entry> + <entry>Read the EDID from starting with this block. Must be 0 when setting + the EDID.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>blocks</structfield></entry> + <entry>The number of blocks to get or set. Must be less or equal to 256 (the + maximum number of blocks as defined by the standard). When you set the EDID and + <structfield>blocks</structfield> is 0, then the EDID is disabled or erased.</entry> + </row> + <row> + <entry>__u8 *</entry> + <entry><structfield>edid</structfield></entry> + <entry>Pointer to memory that contains the EDID. The minimum size is + <structfield>blocks</structfield> * 128.</entry> + </row> + <row> + <entry>__u32</entry> + <entry><structfield>reserved</structfield>[5]</entry> + <entry>Reserved for future extensions. Applications and drivers must + set the array to zero.</entry> + </row> + </tbody> + </tgroup> + </table> + </refsect1> + + <refsect1> + &return-value; + + <variablelist> + <varlistentry> + <term><errorcode>ENODATA</errorcode></term> + <listitem> + <para>The EDID data is not available.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorcode>E2BIG</errorcode></term> + <listitem> + <para>The EDID data you provided is more than the hardware can handle.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> +</refentry> diff --git a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml index f33cc814a01d..1ba9e999af3f 100644 --- a/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml +++ b/Documentation/DocBook/media/v4l/vidioc-subdev-g-selection.xml @@ -69,23 +69,22 @@ more information on how each selection target affects the image processing pipeline inside the subdevice.</para> - <section> + <refsect2> <title>Types of selection targets</title> <para>There are two types of selection targets: actual and bounds. The actual targets are the targets which configure the hardware. The BOUNDS target will return a rectangle that contain all possible actual rectangles.</para> - </section> + </refsect2> - <section> + <refsect2> <title>Discovering supported features</title> <para>To discover which targets are supported, the user can perform <constant>VIDIOC_SUBDEV_G_SELECTION</constant> on them. Any unsupported target will return <constant>EINVAL</constant>.</para> - </section> <para>Selection targets and flags are documented in <xref linkend="v4l2-selections-common"/>.</para> @@ -132,6 +131,7 @@ </tbody> </tgroup> </table> + </refsect2> </refsect1> diff --git a/Documentation/DocBook/media_api.tmpl b/Documentation/DocBook/media_api.tmpl index 4e8e8985cc17..f2413acfe241 100644 --- a/Documentation/DocBook/media_api.tmpl +++ b/Documentation/DocBook/media_api.tmpl @@ -29,7 +29,7 @@ <title>LINUX MEDIA INFRASTRUCTURE API</title> <copyright> - <year>2009-2011</year> + <year>2009-2012</year> <holder>LinuxTV Developers</holder> </copyright> @@ -53,7 +53,7 @@ Foundation. A copy of the license is included in the chapter entitled video and radio straming devices, including video cameras, analog and digital TV receiver cards, AM/FM receiver cards, streaming capture devices.</para> - <para>It is divided into three parts.</para> + <para>It is divided into four parts.</para> <para>The first part covers radio, capture, cameras and analog TV devices.</para> <para>The second part covers the @@ -62,7 +62,8 @@ Foundation. A copy of the license is included in the chapter entitled 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> - <para>The third part covers Remote Controller API</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, see: <ulink url="http://linuxtv.org">http://linuxtv.org</ulink>.</para> <para>For discussing improvements, reporting troubles, sending new drivers, etc, please mail to: <ulink url="http://vger.kernel.org/vger-lists.html#linux-media">Linux Media Mailing List (LMML).</ulink>.</para> @@ -87,7 +88,7 @@ Foundation. A copy of the license is included in the chapter entitled </author> </authorgroup> <copyright> - <year>2009-2011</year> + <year>2009-2012</year> <holder>Mauro Carvalho Chehab</holder> </copyright> diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl index e0aedb7a7827..fe122d6e686f 100644 --- a/Documentation/DocBook/mtdnand.tmpl +++ b/Documentation/DocBook/mtdnand.tmpl @@ -1216,8 +1216,6 @@ in this page</entry> #define NAND_BBT_LASTBLOCK 0x00000010 /* The bbt is at the given page, else we must scan for the bbt */ #define NAND_BBT_ABSPAGE 0x00000020 -/* The bbt is at the given page, else we must scan for the bbt */ -#define NAND_BBT_SEARCH 0x00000040 /* bbt is stored per chip on multichip devices */ #define NAND_BBT_PERCHIP 0x00000080 /* bbt has a version counter at offset veroffs */ diff --git a/Documentation/RCU/checklist.txt b/Documentation/RCU/checklist.txt index fc103d7a0474..cdb20d41a44a 100644 --- a/Documentation/RCU/checklist.txt +++ b/Documentation/RCU/checklist.txt @@ -310,6 +310,12 @@ over a rather long period of time, but improvements are always welcome! code under the influence of preempt_disable(), you instead need to use synchronize_irq() or synchronize_sched(). + This same limitation also applies to synchronize_rcu_bh() + and synchronize_srcu(), as well as to the asynchronous and + expedited forms of the three primitives, namely call_rcu(), + call_rcu_bh(), call_srcu(), synchronize_rcu_expedited(), + synchronize_rcu_bh_expedited(), and synchronize_srcu_expedited(). + 12. Any lock acquired by an RCU callback must be acquired elsewhere with softirq disabled, e.g., via spin_lock_irqsave(), spin_lock_bh(), etc. Failing to disable irq on a given diff --git a/Documentation/RCU/stallwarn.txt b/Documentation/RCU/stallwarn.txt index 523364e4e1f1..1927151b386b 100644 --- a/Documentation/RCU/stallwarn.txt +++ b/Documentation/RCU/stallwarn.txt @@ -99,7 +99,7 @@ In kernels with CONFIG_RCU_FAST_NO_HZ, even more information is printed: INFO: rcu_preempt detected stall on CPU - 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 drain=0 . timer=-1 + 0: (64628 ticks this GP) idle=dd5/3fffffffffffffff/0 drain=0 . timer not pending (t=65000 jiffies) The "(64628 ticks this GP)" indicates that this CPU has taken more @@ -116,13 +116,13 @@ number between the two "/"s is the value of the nesting, which will be a small positive number if in the idle loop and a very large positive number (as shown above) otherwise. -For CONFIG_RCU_FAST_NO_HZ kernels, the "drain=0" indicates that the -CPU is not in the process of trying to force itself into dyntick-idle -state, the "." indicates that the CPU has not given up forcing RCU -into dyntick-idle mode (it would be "H" otherwise), and the "timer=-1" -indicates that the CPU has not recented forced RCU into dyntick-idle -mode (it would otherwise indicate the number of microseconds remaining -in this forced state). +For CONFIG_RCU_FAST_NO_HZ kernels, the "drain=0" indicates that the CPU is +not in the process of trying to force itself into dyntick-idle state, the +"." indicates that the CPU has not given up forcing RCU into dyntick-idle +mode (it would be "H" otherwise), and the "timer not pending" indicates +that the CPU has not recently forced RCU into dyntick-idle mode (it +would otherwise indicate the number of microseconds remaining in this +forced state). Multiple Warnings From One Stall diff --git a/Documentation/RCU/trace.txt b/Documentation/RCU/trace.txt index f6f15ce39903..672d19083252 100644 --- a/Documentation/RCU/trace.txt +++ b/Documentation/RCU/trace.txt @@ -333,23 +333,23 @@ o Each element of the form "1/1 0:127 ^0" represents one struct The output of "cat rcu/rcu_pending" looks as follows: rcu_sched: - 0 np=255892 qsp=53936 rpq=85 cbr=0 cng=14417 gpc=10033 gps=24320 nf=6445 nn=146741 - 1 np=261224 qsp=54638 rpq=33 cbr=0 cng=25723 gpc=16310 gps=2849 nf=5912 nn=155792 - 2 np=237496 qsp=49664 rpq=23 cbr=0 cng=2762 gpc=45478 gps=1762 nf=1201 nn=136629 - 3 np=236249 qsp=48766 rpq=98 cbr=0 cng=286 gpc=48049 gps=1218 nf=207 nn=137723 - 4 np=221310 qsp=46850 rpq=7 cbr=0 cng=26 gpc=43161 gps=4634 nf=3529 nn=123110 - 5 np=237332 qsp=48449 rpq=9 cbr=0 cng=54 gpc=47920 gps=3252 nf=201 nn=137456 - 6 np=219995 qsp=46718 rpq=12 cbr=0 cng=50 gpc=42098 gps=6093 nf=4202 nn=120834 - 7 np=249893 qsp=49390 rpq=42 cbr=0 cng=72 gpc=38400 gps=17102 nf=41 nn=144888 + 0 np=255892 qsp=53936 rpq=85 cbr=0 cng=14417 gpc=10033 gps=24320 nn=146741 + 1 np=261224 qsp=54638 rpq=33 cbr=0 cng=25723 gpc=16310 gps=2849 nn=155792 + 2 np=237496 qsp=49664 rpq=23 cbr=0 cng=2762 gpc=45478 gps=1762 nn=136629 + 3 np=236249 qsp=48766 rpq=98 cbr=0 cng=286 gpc=48049 gps=1218 nn=137723 + 4 np=221310 qsp=46850 rpq=7 cbr=0 cng=26 gpc=43161 gps=4634 nn=123110 + 5 np=237332 qsp=48449 rpq=9 cbr=0 cng=54 gpc=47920 gps=3252 nn=137456 + 6 np=219995 qsp=46718 rpq=12 cbr=0 cng=50 gpc=42098 gps=6093 nn=120834 + 7 np=249893 qsp=49390 rpq=42 cbr=0 cng=72 gpc=38400 gps=17102 nn=144888 rcu_bh: - 0 np=146741 qsp=1419 rpq=6 cbr=0 cng=6 gpc=0 gps=0 nf=2 nn=145314 - 1 np=155792 qsp=12597 rpq=3 cbr=0 cng=0 gpc=4 gps=8 nf=3 nn=143180 - 2 np=136629 qsp=18680 rpq=1 cbr=0 cng=0 gpc=7 gps=6 nf=0 nn=117936 - 3 np=137723 qsp=2843 rpq=0 cbr=0 cng=0 gpc=10 gps=7 nf=0 nn=134863 - 4 np=123110 qsp=12433 rpq=0 cbr=0 cng=0 gpc=4 gps=2 nf=0 nn=110671 - 5 np=137456 qsp=4210 rpq=1 cbr=0 cng=0 gpc=6 gps=5 nf=0 nn=133235 - 6 np=120834 qsp=9902 rpq=2 cbr=0 cng=0 gpc=6 gps=3 nf=2 nn=110921 - 7 np=144888 qsp=26336 rpq=0 cbr=0 cng=0 gpc=8 gps=2 nf=0 nn=118542 + 0 np=146741 qsp=1419 rpq=6 cbr=0 cng=6 gpc=0 gps=0 nn=145314 + 1 np=155792 qsp=12597 rpq=3 cbr=0 cng=0 gpc=4 gps=8 nn=143180 + 2 np=136629 qsp=18680 rpq=1 cbr=0 cng=0 gpc=7 gps=6 nn=117936 + 3 np=137723 qsp=2843 rpq=0 cbr=0 cng=0 gpc=10 gps=7 nn=134863 + 4 np=123110 qsp=12433 rpq=0 cbr=0 cng=0 gpc=4 gps=2 nn=110671 + 5 np=137456 qsp=4210 rpq=1 cbr=0 cng=0 gpc=6 gps=5 nn=133235 + 6 np=120834 qsp=9902 rpq=2 cbr=0 cng=0 gpc=6 gps=3 nn=110921 + 7 np=144888 qsp=26336 rpq=0 cbr=0 cng=0 gpc=8 gps=2 nn=118542 As always, this is once again split into "rcu_sched" and "rcu_bh" portions, with CONFIG_TREE_PREEMPT_RCU kernels having an additional @@ -377,17 +377,6 @@ o "gpc" is the number of times that an old grace period had o "gps" is the number of times that a new grace period had started, but this CPU was not yet aware of it. -o "nf" is the number of times that this CPU suspected that the - current grace period had run for too long, and thus needed to - be forced. - - Please note that "forcing" consists of sending resched IPIs - to holdout CPUs. If that CPU really still is in an old RCU - read-side critical section, then we really do have to wait for it. - The assumption behing "forcing" is that the CPU is not still in - an old RCU read-side critical section, but has not yet responded - for some other reason. - o "nn" is the number of times that this CPU needed nothing. Alert readers will note that the rcu "nn" number for a given CPU very closely matches the rcu_bh "np" number for that same CPU. This diff --git a/Documentation/RCU/whatisRCU.txt b/Documentation/RCU/whatisRCU.txt index 69ee188515e7..bf0f6de2aa00 100644 --- a/Documentation/RCU/whatisRCU.txt +++ b/Documentation/RCU/whatisRCU.txt @@ -873,7 +873,7 @@ d. Do you need to treat NMI handlers, hardirq handlers, and code segments with preemption disabled (whether via preempt_disable(), local_irq_save(), local_bh_disable(), or some other mechanism) as if they were explicit RCU readers? - If so, you need RCU-sched. + If so, RCU-sched is the only choice that will work for you. e. Do you need RCU grace periods to complete even in the face of softirq monopolization of one or more of the CPUs? For @@ -884,7 +884,12 @@ f. Is your workload too update-intensive for normal use of RCU, but inappropriate for other synchronization mechanisms? If so, consider SLAB_DESTROY_BY_RCU. But please be careful! -g. Otherwise, use RCU. +g. Do you need read-side critical sections that are respected + even though they are in the middle of the idle loop, during + user-mode execution, or on an offlined CPU? If so, SRCU is the + only choice that will work for you. + +h. Otherwise, use RCU. Of course, this all assumes that you have determined that RCU is in fact the right tool for your job. diff --git a/Documentation/accounting/getdelays.c b/Documentation/accounting/getdelays.c index f6318f6d7baf..6f706aca2049 100644 --- a/Documentation/accounting/getdelays.c +++ b/Documentation/accounting/getdelays.c @@ -98,10 +98,9 @@ static int create_nl_socket(int protocol) if (rcvbufsz) if (setsockopt(fd, SOL_SOCKET, SO_RCVBUF, &rcvbufsz, sizeof(rcvbufsz)) < 0) { - fprintf(stderr, "Unable to set socket rcv buf size " - "to %d\n", + fprintf(stderr, "Unable to set socket rcv buf size to %d\n", rcvbufsz); - return -1; + goto error; } memset(&local, 0, sizeof(local)); diff --git a/Documentation/aoe/aoe.txt b/Documentation/aoe/aoe.txt index 5f5aa16047ff..bfc9cb19abcd 100644 --- a/Documentation/aoe/aoe.txt +++ b/Documentation/aoe/aoe.txt @@ -1,8 +1,16 @@ -The EtherDrive (R) HOWTO for users of 2.6 kernels is found at ... +ATA over Ethernet is a network protocol that provides simple access to +block storage on the LAN. - http://www.coraid.com/SUPPORT/EtherDrive-HBA + http://support.coraid.com/documents/AoEr11.txt - It has many tips and hints! +The EtherDrive (R) HOWTO for 2.6 and 3.x kernels is found at ... + + http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO.html + +It has many tips and hints! Please see, especially, recommended +tunings for virtual memory: + + http://support.coraid.com/support/linux/EtherDrive-2.6-HOWTO-5.html#ss5.19 The aoetools are userland programs that are designed to work with this driver. The aoetools are on sourceforge. @@ -23,20 +31,12 @@ CREATING DEVICE NODES There is a udev-install.sh script that shows how to install these rules on your system. - If you are not using udev, two scripts are provided in - Documentation/aoe as examples of static device node creation for - using the aoe driver. - - rm -rf /dev/etherd - sh Documentation/aoe/mkdevs.sh /dev/etherd - - ... or to make just one shelf's worth of block device nodes ... - - sh Documentation/aoe/mkshelf.sh /dev/etherd 0 - There is also an autoload script that shows how to edit /etc/modprobe.d/aoe.conf to ensure that the aoe module is loaded when - necessary. + necessary. Preloading the aoe module is preferable to autoloading, + however, because AoE discovery takes a few seconds. It can be + confusing when an AoE device is not present the first time the a + command is run but appears a second later. USING DEVICE NODES @@ -51,9 +51,9 @@ USING DEVICE NODES "echo > /dev/etherd/discover" tells the driver to find out what AoE devices are available. - These character devices may disappear and be replaced by sysfs - counterparts. Using the commands in aoetools insulates users from - these implementation details. + In the future these character devices may disappear and be replaced + by sysfs counterparts. Using the commands in aoetools insulates + users from these implementation details. The block devices are named like this: @@ -76,8 +76,8 @@ USING SYSFS The netif attribute is the network interface on the localhost through which we are communicating with the remote AoE device. - There is a script in this directory that formats this information - in a convenient way. Users with aoetools can use the aoe-stat + There is a script in this directory that formats this information in + a convenient way. Users with aoetools should use the aoe-stat command. root@makki root# sh Documentation/aoe/status.sh @@ -121,3 +121,21 @@ DRIVER OPTIONS usage example for the module parameter. modprobe aoe_iflist="eth1 eth3" + + The aoe_deadsecs module parameter determines the maximum number of + seconds that the driver will wait for an AoE device to provide a + response to an AoE command. After aoe_deadsecs seconds have + elapsed, the AoE device will be marked as "down". + + The aoe_maxout module parameter has a default of 128. This is the + maximum number of unresponded packets that will be sent to an AoE + target at one time. + + The aoe_dyndevs module parameter defaults to 1, meaning that the + driver will assign a block device minor number to a discovered AoE + target based on the order of its discovery. With dynamic minor + device numbers in use, a greater range of AoE shelf and slot + addresses can be supported. Users with udev will never have to + think about minor numbers. Using aoe_dyndevs=0 allows device nodes + to be pre-created using a static minor-number scheme with the + aoe-mkshelf script in the aoetools. diff --git a/Documentation/aoe/mkdevs.sh b/Documentation/aoe/mkdevs.sh deleted file mode 100644 index 44c0ab702432..000000000000 --- a/Documentation/aoe/mkdevs.sh +++ /dev/null @@ -1,41 +0,0 @@ -#!/bin/sh - -n_shelves=${n_shelves:-10} -n_partitions=${n_partitions:-16} - -if test "$#" != "1"; then - echo "Usage: sh `basename $0` {dir}" 1>&2 - echo " n_partitions=16 sh `basename $0` {dir}" 1>&2 - exit 1 -fi -dir=$1 - -MAJOR=152 - -echo "Creating AoE devnode files in $dir ..." - -set -e - -mkdir -p $dir - -# (Status info is in sysfs. See status.sh.) -# rm -f $dir/stat -# mknod -m 0400 $dir/stat c $MAJOR 1 -rm -f $dir/err -mknod -m 0400 $dir/err c $MAJOR 2 -rm -f $dir/discover -mknod -m 0200 $dir/discover c $MAJOR 3 -rm -f $dir/interfaces -mknod -m 0200 $dir/interfaces c $MAJOR 4 -rm -f $dir/revalidate -mknod -m 0200 $dir/revalidate c $MAJOR 5 -rm -f $dir/flush -mknod -m 0200 $dir/flush c $MAJOR 6 - -export n_partitions -mkshelf=`echo $0 | sed 's!mkdevs!mkshelf!'` -i=0 -while test $i -lt $n_shelves; do - sh -xc "sh $mkshelf $dir $i" - i=`expr $i + 1` -done diff --git a/Documentation/aoe/mkshelf.sh b/Documentation/aoe/mkshelf.sh deleted file mode 100644 index 32615814271c..000000000000 --- a/Documentation/aoe/mkshelf.sh +++ /dev/null @@ -1,28 +0,0 @@ -#! /bin/sh - -if test "$#" != "2"; then - echo "Usage: sh `basename $0` {dir} {shelfaddress}" 1>&2 - echo " n_partitions=16 sh `basename $0` {dir} {shelfaddress}" 1>&2 - exit 1 -fi -n_partitions=${n_partitions:-16} -dir=$1 -shelf=$2 -nslots=16 -maxslot=`echo $nslots 1 - p | dc` -MAJOR=152 - -set -e - -minor=`echo $nslots \* $shelf \* $n_partitions | bc` -endp=`echo $n_partitions - 1 | bc` -for slot in `seq 0 $maxslot`; do - for part in `seq 0 $endp`; do - name=e$shelf.$slot - test "$part" != "0" && name=${name}p$part - rm -f $dir/$name - mknod -m 0660 $dir/$name b $MAJOR $minor - - minor=`expr $minor + 1` - done -done diff --git a/Documentation/aoe/status.sh b/Documentation/aoe/status.sh index 751f3be514b8..eeec7baae57a 100644 --- a/Documentation/aoe/status.sh +++ b/Documentation/aoe/status.sh @@ -1,5 +1,8 @@ #! /bin/sh # collate and present sysfs information about AoE storage +# +# A more complete version of this script is aoe-stat, in the +# aoetools. set -e format="%8s\t%8s\t%8s\n" diff --git a/Documentation/arm/Marvell/README b/Documentation/arm/Marvell/README new file mode 100644 index 000000000000..8f08a86e03b7 --- /dev/null +++ b/Documentation/arm/Marvell/README @@ -0,0 +1,232 @@ +ARM Marvell SoCs +================ + +This document lists all the ARM Marvell SoCs that are currently +supported in mainline by the Linux kernel. As the Marvell families of +SoCs are large and complex, it is hard to understand where the support +for a particular SoC is available in the Linux kernel. This document +tries to help in understanding where those SoCs are supported, and to +match them with their corresponding public datasheet, when available. + +Orion family +------------ + + Flavors: + 88F5082 + 88F5181 + 88F5181L + 88F5182 + Datasheet : http://www.embeddedarm.com/documentation/third-party/MV88F5182-datasheet.pdf + Programmer's User Guide : http://www.embeddedarm.com/documentation/third-party/MV88F5182-opensource-manual.pdf + User Manual : http://www.embeddedarm.com/documentation/third-party/MV88F5182-usermanual.pdf + 88F5281 + Datasheet : http://www.ocmodshop.com/images/reviews/networking/qnap_ts409u/marvel_88f5281_data_sheet.pdf + 88F6183 + Core: Feroceon ARMv5 compatible + Linux kernel mach directory: arch/arm/mach-orion5x + Linux kernel plat directory: arch/arm/plat-orion + +Kirkwood family +--------------- + + Flavors: + 88F6282 a.k.a Armada 300 + Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + 88F6283 a.k.a Armada 310 + Product Brief : http://www.marvell.com/embedded-processors/armada-300/assets/armada_310.pdf + 88F6190 + Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6190-003_WEB.pdf + Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + 88F6192 + Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6192-003_ver1.pdf + Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F619x_OpenSource.pdf + Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + 88F6182 + 88F6180 + Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6180-003_ver1.pdf + Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6180_OpenSource.pdf + Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + 88F6281 + Product Brief : http://www.marvell.com/embedded-processors/kirkwood/assets/88F6281-004_ver1.pdf + Hardware Spec : http://www.marvell.com/embedded-processors/kirkwood/assets/HW_88F6281_OpenSource.pdf + Functional Spec: http://www.marvell.com/embedded-processors/kirkwood/assets/FS_88F6180_9x_6281_OpenSource.pdf + Homepage: http://www.marvell.com/embedded-processors/kirkwood/ + Core: Feroceon ARMv5 compatible + Linux kernel mach directory: arch/arm/mach-kirkwood + Linux kernel plat directory: arch/arm/plat-orion + +Discovery family +---------------- + + Flavors: + MV78100 + Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78100-003_WEB.pdf + Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78100_OpenSource.pdf + Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + MV78200 + Product Brief : http://www.marvell.com/embedded-processors/discovery-innovation/assets/MV78200-002_WEB.pdf + Hardware Spec : http://www.marvell.com/embedded-processors/discovery-innovation/assets/HW_MV78200_OpenSource.pdf + Functional Spec: http://www.marvell.com/embedded-processors/discovery-innovation/assets/FS_MV76100_78100_78200_OpenSource.pdf + MV76100 + Not supported by the Linux kernel. + + Core: Feroceon ARMv5 compatible + + Linux kernel mach directory: arch/arm/mach-mv78xx0 + Linux kernel plat directory: arch/arm/plat-orion + +EBU Armada family +----------------- + + Armada 370 Flavors: + 88F6710 + 88F6707 + 88F6W11 + + Armada XP Flavors: + MV78230 + MV78260 + MV78460 + + Product Brief: http://www.marvell.com/embedded-processors/armada-xp/assets/Marvell-ArmadaXP-SoC-product%20brief.pdf + No public datasheet available. + + Core: Sheeva ARMv7 compatible + + Linux kernel mach directory: arch/arm/mach-mvebu + Linux kernel plat directory: none + +Avanta family +------------- + + Flavors: + 88F6510 + 88F6530P + 88F6550 + 88F6560 + Homepage : http://www.marvell.com/broadband/ + Product Brief: http://www.marvell.com/broadband/assets/Marvell_Avanta_88F6510_305_060-001_product_brief.pdf + No public datasheet available. + + Core: ARMv5 compatible + + Linux kernel mach directory: no code in mainline yet, planned for the future + Linux kernel plat directory: no code in mainline yet, planned for the future + +Dove family (application processor) +----------------------------------- + + Flavors: + 88AP510 a.k.a Armada 510 + Product Brief : http://www.marvell.com/application-processors/armada-500/assets/Marvell_Armada510_SoC.pdf + Hardware Spec : http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Hardware-Spec.pdf + Functional Spec : http://www.marvell.com/application-processors/armada-500/assets/Armada-510-Functional-Spec.pdf + Homepage: http://www.marvell.com/application-processors/armada-500/ + Core: ARMv7 compatible + Directory: arch/arm/mach-dove + +PXA 2xx/3xx/93x/95x family +-------------------------- + + Flavors: + PXA21x, PXA25x, PXA26x + Application processor only + Core: ARMv5 XScale core + PXA270, PXA271, PXA272 + Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_pb.pdf + Design guide : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_design_guide.pdf + Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_dev_man.pdf + Specification : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_emts.pdf + Specification update : http://www.marvell.com/application-processors/pxa-family/assets/pxa_27x_spec_update.pdf + Application processor only + Core: ARMv5 XScale core + PXA300, PXA310, PXA320 + PXA 300 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA300_PB_R4.pdf + PXA 310 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA310_PB_R4.pdf + PXA 320 Product Brief : http://www.marvell.com/application-processors/pxa-family/assets/PXA320_PB_R4.pdf + Design guide : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Design_Guide.pdf + Developers manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Developers_Manual.zip + Specifications : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_EMTS.pdf + Specification Update : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_Spec_Update.zip + Reference Manual : http://www.marvell.com/application-processors/pxa-family/assets/PXA3xx_TavorP_BootROM_Ref_Manual.pdf + Application processor only + Core: ARMv5 XScale core + PXA930, PXA935 + Application processor with Communication processor + Core: ARMv5 XScale core + PXA955 + Application processor with Communication processor + Core: ARMv7 compatible Sheeva PJ4 core + + Comments: + + * This line of SoCs originates from the XScale family developed by + Intel and acquired by Marvell in ~2006. The PXA21x, PXA25x, + PXA26x, PXA27x, PXA3xx and PXA93x were developed by Intel, while + the later PXA95x were developed by Marvell. + + * Due to their XScale origin, these SoCs have virtually nothing in + common with the other (Kirkwood, Dove, etc.) families of Marvell + SoCs, except with the MMP/MMP2 family of SoCs. + + Linux kernel mach directory: arch/arm/mach-pxa + Linux kernel plat directory: arch/arm/plat-pxa + +MMP/MMP2 family (communication processor) +----------------------------------------- + + Flavors: + PXA168, a.k.a Armada 168 + Homepage : http://www.marvell.com/application-processors/armada-100/armada-168.jsp + Product brief : http://www.marvell.com/application-processors/armada-100/assets/pxa_168_pb.pdf + Hardware manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_datasheet.pdf + Software manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_software_manual.pdf + Specification update : http://www.marvell.com/application-processors/armada-100/assets/ARMADA16x_Spec_update.pdf + Boot ROM manual : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_ref_manual.pdf + App node package : http://www.marvell.com/application-processors/armada-100/assets/armada_16x_app_note_package.pdf + Application processor only + Core: ARMv5 compatible Marvell PJ1 (Mohawk) + PXA910 + Homepage : http://www.marvell.com/communication-processors/pxa910/ + Product Brief : http://www.marvell.com/communication-processors/pxa910/assets/Marvell_PXA910_Platform-001_PB_final.pdf + Application processor with Communication processor + Core: ARMv5 compatible Marvell PJ1 (Mohawk) + MMP2, a.k.a Armada 610 + Product Brief : http://www.marvell.com/application-processors/armada-600/assets/armada610_pb.pdf + Application processor only + Core: ARMv7 compatible Sheeva PJ4 core + + Comments: + + * This line of SoCs originates from the XScale family developed by + Intel and acquired by Marvell in ~2006. All the processors of + this MMP/MMP2 family were developed by Marvell. + + * Due to their XScale origin, these SoCs have virtually nothing in + common with the other (Kirkwood, Dove, etc.) families of Marvell + SoCs, except with the PXA family of SoCs listed above. + + Linux kernel mach directory: arch/arm/mach-mmp + Linux kernel plat directory: arch/arm/plat-pxa + +Long-term plans +--------------- + + * Unify the mach-dove/, mach-mv78xx0/, mach-orion5x/ and + mach-kirkwood/ into the mach-mvebu/ to support all SoCs from the + Marvell EBU (Engineering Business Unit) in a single mach-<foo> + directory. The plat-orion/ would therefore disappear. + + * Unify the mach-mmp/ and mach-pxa/ into the same mach-pxa + directory. The plat-pxa/ would therefore disappear. + +Credits +------- + + Maen Suleiman <maen@marvell.com> + Lior Amsalem <alior@marvell.com> + Thomas Petazzoni <thomas.petazzoni@free-electrons.com> + Andrew Lunn <andrew@lunn.ch> + Nicolas Pitre <nico@fluxnic.net> + Eric Miao <eric.y.miao@gmail.com> diff --git a/Documentation/arm/Samsung-S3C24XX/GPIO.txt b/Documentation/arm/Samsung-S3C24XX/GPIO.txt index 816d6071669e..8b46c79679c4 100644 --- a/Documentation/arm/Samsung-S3C24XX/GPIO.txt +++ b/Documentation/arm/Samsung-S3C24XX/GPIO.txt @@ -1,4 +1,4 @@ - S3C2410 GPIO Control + S3C24XX GPIO Control ==================== Introduction @@ -12,7 +12,7 @@ Introduction of the s3c2410 GPIO system, please read the Samsung provided data-sheet/users manual to find out the complete list. - See Documentation/arm/Samsung/GPIO.txt for the core implemetation. + See Documentation/arm/Samsung/GPIO.txt for the core implementation. GPIOLIB @@ -41,8 +41,8 @@ GPIOLIB GPIOLIB conversion ------------------ -If you need to convert your board or driver to use gpiolib from the exiting -s3c2410 api, then here are some notes on the process. +If you need to convert your board or driver to use gpiolib from the phased +out s3c2410 API, then here are some notes on the process. 1) If your board is exclusively using an GPIO, say to control peripheral power, then it will require to claim the gpio with gpio_request() before @@ -55,7 +55,7 @@ s3c2410 api, then here are some notes on the process. as they have the same arguments, and can either take the pin specific values, or the more generic special-function-number arguments. -3) s3c2410_gpio_pullup() changs have the problem that whilst the +3) s3c2410_gpio_pullup() changes have the problem that whilst the s3c2410_gpio_pullup(x, 1) can be easily translated to the s3c_gpio_setpull(x, S3C_GPIO_PULL_NONE), the s3c2410_gpio_pullup(x, 0) are not so easy. @@ -74,7 +74,7 @@ s3c2410 api, then here are some notes on the process. when using gpio_get_value() on an output pin (s3c2410_gpio_getpin would return the value the pin is supposed to be outputting). -6) s3c2410_gpio_getirq() should be directly replacable with the +6) s3c2410_gpio_getirq() should be directly replaceable with the gpio_to_irq() call. The s3c2410_gpio and gpio_ calls have always operated on the same gpio @@ -105,7 +105,7 @@ PIN Numbers ----------- Each pin has an unique number associated with it in regs-gpio.h, - eg S3C2410_GPA(0) or S3C2410_GPF(1). These defines are used to tell + e.g. S3C2410_GPA(0) or S3C2410_GPF(1). These defines are used to tell the GPIO functions which pin is to be used. With the conversion to gpiolib, there is no longer a direct conversion @@ -120,31 +120,27 @@ Configuring a pin The following function allows the configuration of a given pin to be changed. - void s3c2410_gpio_cfgpin(unsigned int pin, unsigned int function); + void s3c_gpio_cfgpin(unsigned int pin, unsigned int function); - Eg: + e.g.: - s3c2410_gpio_cfgpin(S3C2410_GPA(0), S3C2410_GPA0_ADDR0); - s3c2410_gpio_cfgpin(S3C2410_GPE(8), S3C2410_GPE8_SDDAT1); + s3c_gpio_cfgpin(S3C2410_GPA(0), S3C_GPIO_SFN(1)); + s3c_gpio_cfgpin(S3C2410_GPE(8), S3C_GPIO_SFN(2)); which would turn GPA(0) into the lowest Address line A0, and set GPE(8) to be connected to the SDIO/MMC controller's SDDAT1 line. - The s3c_gpio_cfgpin() call is a functional replacement for this call. - Reading the current configuration --------------------------------- - The current configuration of a pin can be read by using: + The current configuration of a pin can be read by using standard + gpiolib function: - s3c2410_gpio_getcfg(unsigned int pin); + s3c_gpio_getcfg(unsigned int pin); The return value will be from the same set of values which can be - passed to s3c2410_gpio_cfgpin(). - - The s3c_gpio_getcfg() call should be a functional replacement for - this call. + passed to s3c_gpio_cfgpin(). Configuring a pull-up resistor @@ -154,61 +150,33 @@ Configuring a pull-up resistor pull-up resistors enabled. This can be configured by the following function: - void s3c2410_gpio_pullup(unsigned int pin, unsigned int to); - - Where the to value is zero to set the pull-up off, and 1 to enable - the specified pull-up. Any other values are currently undefined. - - The s3c_gpio_setpull() offers similar functionality, but with the - ability to encode whether the pull is up or down. Currently there - is no 'just on' state, so up or down must be selected. - - -Getting the state of a PIN --------------------------- - - The state of a pin can be read by using the function: - - unsigned int s3c2410_gpio_getpin(unsigned int pin); + void s3c_gpio_setpull(unsigned int pin, unsigned int to); - This will return either zero or non-zero. Do not count on this - function returning 1 if the pin is set. + Where the to value is S3C_GPIO_PULL_NONE to set the pull-up off, + and S3C_GPIO_PULL_UP to enable the specified pull-up. Any other + values are currently undefined. - This call is now implemented by the relevant gpiolib calls, convert - your board or driver to use gpiolib. - - -Setting the state of a PIN --------------------------- - - The value an pin is outputing can be modified by using the following: - void s3c2410_gpio_setpin(unsigned int pin, unsigned int to); +Getting and setting the state of a PIN +-------------------------------------- - Which sets the given pin to the value. Use 0 to write 0, and 1 to - set the output to 1. - - This call is now implemented by the relevant gpiolib calls, convert + These calls are now implemented by the relevant gpiolib calls, convert your board or driver to use gpiolib. Getting the IRQ number associated with a PIN -------------------------------------------- - The following function can map the given pin number to an IRQ + A standard gpiolib function can map the given pin number to an IRQ number to pass to the IRQ system. - int s3c2410_gpio_getirq(unsigned int pin); + int gpio_to_irq(unsigned int pin); Note, not all pins have an IRQ. - This call is now implemented by the relevant gpiolib calls, convert - your board or driver to use gpiolib. - -Authour +Author ------- - Ben Dooks, 03 October 2004 Copyright 2004 Ben Dooks, Simtec Electronics diff --git a/Documentation/arm/Samsung/GPIO.txt b/Documentation/arm/Samsung/GPIO.txt index 513f2562c1a3..795adfd88081 100644 --- a/Documentation/arm/Samsung/GPIO.txt +++ b/Documentation/arm/Samsung/GPIO.txt @@ -5,14 +5,14 @@ Introduction ------------ This outlines the Samsung GPIO implementation and the architecture -specific calls provided alongisde the drivers/gpio core. +specific calls provided alongside the drivers/gpio core. S3C24XX (Legacy) ---------------- See Documentation/arm/Samsung-S3C24XX/GPIO.txt for more information -about these devices. Their implementation is being brought into line +about these devices. Their implementation has been brought into line with the core samsung implementation described in this document. @@ -29,7 +29,7 @@ GPIO numbering is synchronised between the Samsung and gpiolib system. PIN configuration ----------------- -Pin configuration is specific to the Samsung architecutre, with each SoC +Pin configuration is specific to the Samsung architecture, with each SoC registering the necessary information for the core gpio configuration implementation to configure pins as necessary. @@ -38,5 +38,3 @@ driver or machine to change gpio configuration. See arch/arm/plat-samsung/include/plat/gpio-cfg.h for more information on these functions. - - diff --git a/Documentation/arm/memory.txt b/Documentation/arm/memory.txt index 208a2d465b92..4bfb9ffbdbc1 100644 --- a/Documentation/arm/memory.txt +++ b/Documentation/arm/memory.txt @@ -51,6 +51,9 @@ ffc00000 ffefffff DMA memory mapping region. Memory returned 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. + VMALLOC_START VMALLOC_END-1 vmalloc() / ioremap() space. Memory returned by vmalloc/ioremap will be dynamically placed in this region. diff --git a/Documentation/arm64/booting.txt b/Documentation/arm64/booting.txt new file mode 100644 index 000000000000..9c4d388daddc --- /dev/null +++ b/Documentation/arm64/booting.txt @@ -0,0 +1,152 @@ + Booting AArch64 Linux + ===================== + +Author: Will Deacon <will.deacon@arm.com> +Date : 07 September 2012 + +This document is based on the ARM booting document by Russell King and +is relevant to all public releases of the AArch64 Linux kernel. + +The AArch64 exception model is made up of a number of exception levels +(EL0 - EL3), with EL0 and EL1 having a secure and a non-secure +counterpart. EL2 is the hypervisor level and exists only in non-secure +mode. EL3 is the highest priority level and exists only in secure mode. + +For the purposes of this document, we will use the term `boot loader' +simply to define all software that executes on the CPU(s) before control +is passed to the Linux kernel. This may include secure monitor and +hypervisor code, or it may just be a handful of instructions for +preparing a minimal boot environment. + +Essentially, the boot loader should provide (as a minimum) the +following: + +1. Setup and initialise the RAM +2. Setup the device tree +3. Decompress the kernel image +4. Call the kernel image + + +1. Setup and initialise RAM +--------------------------- + +Requirement: MANDATORY + +The boot loader is expected to find and initialise all RAM that the +kernel will use for volatile data storage in the system. It performs +this in a machine dependent manner. (It may use internal algorithms +to automatically locate and size all RAM, or it may use knowledge of +the RAM in the machine, or any other method the boot loader designer +sees fit.) + + +2. Setup the device tree +------------------------- + +Requirement: MANDATORY + +The device tree blob (dtb) must be no bigger than 2 megabytes in size +and placed at a 2-megabyte boundary within the first 512 megabytes from +the start of the kernel image. This is to allow the kernel to map the +blob using a single section mapping in the initial page tables. + + +3. Decompress the kernel image +------------------------------ + +Requirement: OPTIONAL + +The AArch64 kernel does not currently provide a decompressor and +therefore requires decompression (gzip etc.) to be performed by the boot +loader if a compressed Image target (e.g. Image.gz) is used. For +bootloaders that do not implement this requirement, the uncompressed +Image target is available instead. + + +4. Call the kernel image +------------------------ + +Requirement: MANDATORY + +The decompressed kernel image contains a 32-byte header as follows: + + u32 magic = 0x14000008; /* branch to stext, little-endian */ + u32 res0 = 0; /* reserved */ + u64 text_offset; /* Image load offset */ + u64 res1 = 0; /* reserved */ + u64 res2 = 0; /* reserved */ + +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 +system RAM must be aligned to 2MB. + +Before jumping into the kernel, the following conditions must be met: + +- Quiesce all DMA capable devices so that memory does not get + corrupted by bogus network packets or disk data. This will save + you many hours of debug. + +- Primary CPU general-purpose register settings + x0 = physical address of device tree blob (dtb) in system RAM. + x1 = 0 (reserved for future use) + x2 = 0 (reserved for future use) + x3 = 0 (reserved for future use) + +- CPU mode + All forms of interrupts must be masked in PSTATE.DAIF (Debug, SError, + IRQ and FIQ). + The CPU must be in either EL2 (RECOMMENDED in order to have access to + the virtualisation extensions) or non-secure EL1. + +- Caches, MMUs + The MMU must be off. + Instruction cache may be on or off. + Data cache must be off and invalidated. + External caches (if present) must be configured and disabled. + +- Architected timers + CNTFRQ must be programmed with the timer frequency. + If entering the kernel at EL1, CNTHCTL_EL2 must have EL1PCTEN (bit 0) + set where available. + +- Coherency + All CPUs to be booted by the kernel must be part of the same coherency + domain on entry to the kernel. This may require IMPLEMENTATION DEFINED + initialisation to enable the receiving of maintenance operations on + each CPU. + +- System registers + All writable architected system registers at the exception level where + the kernel image will be entered must be initialised by software at a + higher exception level to prevent execution in an UNKNOWN state. + +The boot loader is expected to enter the kernel on each CPU in the +following manner: + +- The primary CPU must jump directly to the first instruction of the + kernel image. The device tree blob passed by this CPU must contain + for each CPU node: + + 1. An 'enable-method' property. Currently, the only supported value + for this field is the string "spin-table". + + 2. A 'cpu-release-addr' property identifying a 64-bit, + zero-initialised memory location. + + It is expected that the bootloader will generate these device tree + properties and insert them into the blob prior to kernel entry. + +- Any secondary CPUs must spin outside of the kernel in a reserved area + of memory (communicated to the kernel by a /memreserve/ region in the + device tree) polling their cpu-release-addr location, which must be + contained in the reserved region. A wfe instruction may be inserted + to reduce the overhead of the busy-loop and a sev will be issued by + the primary CPU. When a read of the location pointed to by the + cpu-release-addr returns a non-zero value, the CPU must jump directly + to this value. + +- Secondary CPU general-purpose register settings + x0 = 0 (reserved for future use) + x1 = 0 (reserved for future use) + x2 = 0 (reserved for future use) + x3 = 0 (reserved for future use) diff --git a/Documentation/arm64/memory.txt b/Documentation/arm64/memory.txt new file mode 100644 index 000000000000..dbbdcbba75a3 --- /dev/null +++ b/Documentation/arm64/memory.txt @@ -0,0 +1,73 @@ + Memory Layout on AArch64 Linux + ============================== + +Author: Catalin Marinas <catalin.marinas@arm.com> +Date : 20 February 2012 + +This document describes the virtual memory layout used by the AArch64 +Linux kernel. The architecture allows up to 4 levels of translation +tables with a 4KB page size and up to 3 levels with a 64KB page size. + +AArch64 Linux uses 3 levels of translation tables with the 4KB page +configuration, allowing 39-bit (512GB) virtual addresses for both user +and kernel. With 64KB pages, only 2 levels of translation tables are +used but the memory layout is the same. + +User addresses have bits 63:39 set to 0 while the kernel addresses have +the same bits set to 1. TTBRx selection is given by bit 63 of the +virtual address. The swapper_pg_dir contains only kernel (global) +mappings while the user pgd contains only user (non-global) mappings. +The swapper_pgd_dir address is written to TTBR1 and never written to +TTBR0. + + +AArch64 Linux memory layout: + +Start End Size Use +----------------------------------------------------------------------- +0000000000000000 0000007fffffffff 512GB user + +ffffff8000000000 ffffffbbfffcffff ~240GB vmalloc + +ffffffbbfffd0000 ffffffbcfffdffff 64KB [guard page] + +ffffffbbfffe0000 ffffffbcfffeffff 64KB PCI I/O space + +ffffffbbffff0000 ffffffbcffffffff 64KB [guard page] + +ffffffbc00000000 ffffffbdffffffff 8GB vmemmap + +ffffffbe00000000 ffffffbffbffffff ~8GB [guard, future vmmemap] + +ffffffbffc000000 ffffffbfffffffff 64MB modules + +ffffffc000000000 ffffffffffffffff 256GB memory + + +Translation table lookup with 4KB pages: + ++--------+--------+--------+--------+--------+--------+--------+--------+ +|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| ++--------+--------+--------+--------+--------+--------+--------+--------+ + | | | | | | + | | | | | v + | | | | | [11:0] in-page offset + | | | | +-> [20:12] L3 index + | | | +-----------> [29:21] L2 index + | | +---------------------> [38:30] L1 index + | +-------------------------------> [47:39] L0 index (not used) + +-------------------------------------------------> [63] TTBR0/1 + + +Translation table lookup with 64KB pages: + ++--------+--------+--------+--------+--------+--------+--------+--------+ +|63 56|55 48|47 40|39 32|31 24|23 16|15 8|7 0| ++--------+--------+--------+--------+--------+--------+--------+--------+ + | | | | | + | | | | v + | | | | [15:0] in-page offset + | | | +----------> [28:16] L3 index + | | +--------------------------> [41:29] L2 index (only 38:29 used) + | +-------------------------------> [47:42] L1 index (not used) + +-------------------------------------------------> [63] TTBR0/1 diff --git a/Documentation/cgroups/cgroups.txt b/Documentation/cgroups/cgroups.txt index 4a0b64c605fc..9e04196c4d78 100644 --- a/Documentation/cgroups/cgroups.txt +++ b/Documentation/cgroups/cgroups.txt @@ -29,7 +29,8 @@ CONTENTS: 3.1 Overview 3.2 Synchronization 3.3 Subsystem API -4. Questions +4. Extended attributes usage +5. Questions 1. Control Groups ================= @@ -62,9 +63,9 @@ an instance of the cgroup virtual filesystem associated with it. At any one time there may be multiple active hierarchies of task cgroups. Each hierarchy is a partition of all tasks in the system. -User level code may create and destroy cgroups by name in an +User-level code may create and destroy cgroups by name in an instance of the cgroup virtual file system, specify and query to -which cgroup a task is assigned, and list the task pids assigned to +which cgroup a task is assigned, and list the task PIDs assigned to a cgroup. Those creations and assignments only affect the hierarchy associated with that instance of the cgroup file system. @@ -72,7 +73,7 @@ On their own, the only use for cgroups is for simple job tracking. The intention is that other subsystems hook into the generic cgroup support to provide new attributes for cgroups, such as accounting/limiting the resources which processes in a cgroup can -access. For example, cpusets (see Documentation/cgroups/cpusets.txt) allows +access. For example, cpusets (see Documentation/cgroups/cpusets.txt) allow you to associate a set of CPUs and a set of memory nodes with the tasks in each cgroup. @@ -80,11 +81,11 @@ tasks in each cgroup. ---------------------------- There are multiple efforts to provide process aggregations in the -Linux kernel, mainly for resource tracking purposes. Such efforts +Linux kernel, mainly for resource-tracking purposes. Such efforts include cpusets, CKRM/ResGroups, UserBeanCounters, and virtual server namespaces. These all require the basic notion of a grouping/partitioning of processes, with newly forked processes ending -in the same group (cgroup) as their parent process. +up in the same group (cgroup) as their parent process. The kernel cgroup patch provides the minimum essential kernel mechanisms required to efficiently implement such groups. It has @@ -127,14 +128,14 @@ following lines: / \ Professors (15%) students (5%) -Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd go -into NFS network class. +Browsers like Firefox/Lynx go into the WWW network class, while (k)nfsd goes +into the NFS network class. At the same time Firefox/Lynx will share an appropriate CPU/Memory class depending on who launched it (prof/student). With the ability to classify tasks differently for different resources -(by putting those resource subsystems in different hierarchies) then +(by putting those resource subsystems in different hierarchies), the admin can easily set up a script which receives exec notifications and depending on who is launching the browser he can @@ -145,19 +146,19 @@ a separate cgroup for every browser launched and associate it with appropriate network and other resource class. This may lead to proliferation of such cgroups. -Also lets say that the administrator would like to give enhanced network +Also let's say that the administrator would like to give enhanced network access temporarily to a student's browser (since it is night and the user -wants to do online gaming :)) OR give one of the students simulation -apps enhanced CPU power, +wants to do online gaming :)) OR give one of the student's simulation +apps enhanced CPU power. -With ability to write pids directly to resource classes, it's just a -matter of : +With ability to write PIDs directly to resource classes, it's just a +matter of: # echo pid > /sys/fs/cgroup/network/<new_class>/tasks (after some time) # echo pid > /sys/fs/cgroup/network/<orig_class>/tasks -Without this ability, he would have to split the cgroup into +Without this ability, the administrator would have to split the cgroup into multiple separate ones and then associate the new cgroups with the new resource classes. @@ -184,20 +185,20 @@ Control Groups extends the kernel as follows: field of each task_struct using the css_set, anchored at css_set->tasks. - - A cgroup hierarchy filesystem can be mounted for browsing and + - A cgroup hierarchy filesystem can be mounted for browsing and manipulation from user space. - - You can list all the tasks (by pid) attached to any cgroup. + - You can list all the tasks (by PID) attached to any cgroup. The implementation of cgroups requires a few, simple hooks -into the rest of the kernel, none in performance critical paths: +into the rest of the kernel, none in performance-critical paths: - in init/main.c, to initialize the root cgroups and initial css_set at system boot. - in fork and exit, to attach and detach a task from its css_set. -In addition a new file system, of type "cgroup" may be mounted, to +In addition, a new file system of type "cgroup" may be mounted, to enable browsing and modifying the cgroups presently known to the kernel. When mounting a cgroup hierarchy, you may specify a comma-separated list of subsystems to mount as the filesystem mount @@ -230,13 +231,13 @@ as the path relative to the root of the cgroup file system. Each cgroup is represented by a directory in the cgroup file system containing the following files describing that cgroup: - - tasks: list of tasks (by pid) attached to that cgroup. This list - is not guaranteed to be sorted. Writing a thread id into this file + - tasks: list of tasks (by PID) attached to that cgroup. This list + is not guaranteed to be sorted. Writing a thread ID into this file moves the thread into this cgroup. - - cgroup.procs: list of tgids in the cgroup. This list is not - guaranteed to be sorted or free of duplicate tgids, and userspace + - cgroup.procs: list of thread group IDs in the cgroup. This list is + not guaranteed to be sorted or free of duplicate TGIDs, and userspace should sort/uniquify the list if this property is required. - Writing a thread group id into this file moves all threads in that + Writing a thread group ID into this file moves all threads in that group into this cgroup. - notify_on_release flag: run the release agent on exit? - release_agent: the path to use for release notifications (this file @@ -261,7 +262,7 @@ cgroup file system directories. When a task is moved from one cgroup to another, it gets a new css_set pointer - if there's an already existing css_set with the -desired collection of cgroups then that group is reused, else a new +desired collection of cgroups then that group is reused, otherwise a new css_set is allocated. The appropriate existing css_set is located by looking into a hash table. @@ -292,7 +293,7 @@ file system) of the abandoned cgroup. This enables automatic removal of abandoned cgroups. The default value of notify_on_release in the root cgroup at system boot is disabled (0). The default value of other cgroups at creation is the current -value of their parents notify_on_release setting. The default value of +value of their parents' notify_on_release settings. The default value of a cgroup hierarchy's release_agent path is empty. 1.5 What does clone_children do ? @@ -316,7 +317,7 @@ the "cpuset" cgroup subsystem, the steps are something like: 4) Create the new cgroup by doing mkdir's and write's (or echo's) in the /sys/fs/cgroup virtual file system. 5) Start a task that will be the "founding father" of the new job. - 6) Attach that task to the new cgroup by writing its pid to the + 6) Attach that task to the new cgroup by writing its PID to the /sys/fs/cgroup/cpuset/tasks file for that cgroup. 7) fork, exec or clone the job tasks from this founding father task. @@ -344,7 +345,7 @@ and then start a subshell 'sh' in that cgroup: 2.1 Basic Usage --------------- -Creating, modifying, using the cgroups can be done through the cgroup +Creating, modifying, using cgroups can be done through the cgroup virtual filesystem. To mount a cgroup hierarchy with all available subsystems, type: @@ -441,7 +442,7 @@ You can attach the current shell task by echoing 0: # echo 0 > tasks You can use the cgroup.procs file instead of the tasks file to move all -threads in a threadgroup at once. Echoing the pid of any task in a +threads in a threadgroup at once. Echoing the PID of any task in a threadgroup to cgroup.procs causes all tasks in that threadgroup to be be attached to the cgroup. Writing 0 to cgroup.procs moves all tasks in the writing task's threadgroup. @@ -479,7 +480,7 @@ in /proc/mounts and /proc/<pid>/cgroups. There is mechanism which allows to get notifications about changing status of a cgroup. -To register new notification handler you need: +To register a new notification handler you need to: - create a file descriptor for event notification using eventfd(2); - open a control file to be monitored (e.g. memory.usage_in_bytes); - write "<event_fd> <control_fd> <args>" to cgroup.event_control. @@ -488,7 +489,7 @@ To register new notification handler you need: eventfd will be woken up by control file implementation or when the cgroup is removed. -To unregister notification handler just close eventfd. +To unregister a notification handler just close eventfd. NOTE: Support of notifications should be implemented for the control file. See documentation for the subsystem. @@ -502,7 +503,7 @@ file. See documentation for the subsystem. Each kernel subsystem that wants to hook into the generic cgroup system needs to create a cgroup_subsys object. This contains various methods, which are callbacks from the cgroup system, along -with a subsystem id which will be assigned by the cgroup system. +with a subsystem ID which will be assigned by the cgroup system. Other fields in the cgroup_subsys object include: @@ -516,7 +517,7 @@ Other fields in the cgroup_subsys object include: at system boot. Each cgroup object created by the system has an array of pointers, -indexed by subsystem id; this pointer is entirely managed by the +indexed by subsystem ID; this pointer is entirely managed by the subsystem; the generic cgroup code will never touch this pointer. 3.2 Synchronization @@ -639,7 +640,7 @@ void post_clone(struct cgroup *cgrp) Called during cgroup_create() to do any parameter initialization which might be required before a task could attach. For -example in cpusets, no task may attach before 'cpus' and 'mems' are set +example, in cpusets, no task may attach before 'cpus' and 'mems' are set up. void bind(struct cgroup *root) @@ -650,7 +651,26 @@ and root cgroup. Currently this will only involve movement between the default hierarchy (which never has sub-cgroups) and a hierarchy that is being created/destroyed (and hence has no sub-cgroups). -4. Questions +4. Extended attribute usage +=========================== + +cgroup filesystem supports certain types of extended attributes in its +directories and files. The current supported types are: + - Trusted (XATTR_TRUSTED) + - Security (XATTR_SECURITY) + +Both require CAP_SYS_ADMIN capability to set. + +Like in tmpfs, the extended attributes in cgroup filesystem are stored +using kernel memory and it's advised to keep the usage at minimum. This +is the reason why user defined extended attributes are not supported, since +any user can do it and there's no limit in the value size. + +The current known users for this feature are SELinux to limit cgroup usage +in containers and systemd for assorted meta data like main PID in a cgroup +(systemd creates a cgroup per service). + +5. Questions ============ Q: what's up with this '/bin/echo' ? @@ -660,5 +680,5 @@ A: bash's builtin 'echo' command does not check calls to write() against Q: When I attach processes, only the first of the line gets really attached ! A: We can only return one error code per call to write(). So you should also - put only ONE pid. + put only ONE PID. diff --git a/Documentation/cgroups/memory.txt b/Documentation/cgroups/memory.txt index 4372e6b8a353..c07f7b4fb88d 100644 --- a/Documentation/cgroups/memory.txt +++ b/Documentation/cgroups/memory.txt @@ -18,16 +18,16 @@ from the rest of the system. The article on LWN [12] mentions some probable uses of the memory controller. The memory controller can be used to a. Isolate an application or a group of applications - Memory hungry applications can be isolated and limited to a smaller + Memory-hungry applications can be isolated and limited to a smaller amount of memory. -b. Create a cgroup with limited amount of memory, this can be used +b. Create a cgroup with a limited amount of memory; this can be used as a good alternative to booting with mem=XXXX. c. Virtualization solutions can control the amount of memory they want to assign to a virtual machine instance. d. A CD/DVD burner could control the amount of memory used by the rest of the system to ensure that burning does not fail due to lack of available memory. -e. There are several other use cases, find one or use the controller just +e. There are several other use cases; find one or use the controller just for fun (to learn and hack on the VM subsystem). Current Status: linux-2.6.34-mmotm(development version of 2010/April) @@ -38,12 +38,12 @@ Features: - optionally, memory+swap usage can be accounted and limited. - hierarchical accounting - soft limit - - moving(recharging) account at moving a task is selectable. + - moving (recharging) account at moving a task is selectable. - usage threshold notifier - oom-killer disable knob and oom-notifier - Root cgroup has no limit controls. - Kernel memory support is work in progress, and the current version provides + Kernel memory support is a work in progress, and the current version provides basically functionality. (See Section 2.7) Brief summary of control files. @@ -144,9 +144,9 @@ Figure 1 shows the important aspects of the controller 3. Each page has a pointer to the page_cgroup, which in turn knows the cgroup it belongs to -The accounting is done as follows: mem_cgroup_charge() is invoked to setup +The accounting is done as follows: mem_cgroup_charge() is invoked to set up the necessary data structures and check if the cgroup that is being charged -is over its limit. If it is then reclaim is invoked on the cgroup. +is over its limit. If it is, then reclaim is invoked on the cgroup. More details can be found in the reclaim section of this document. If everything goes well, a page meta-data-structure called page_cgroup is updated. page_cgroup has its own LRU on cgroup. @@ -163,13 +163,13 @@ for earlier. A file page will be accounted for as Page Cache when it's inserted into inode (radix-tree). While it's mapped into the page tables of processes, duplicate accounting is carefully avoided. -A RSS page is unaccounted when it's fully unmapped. A PageCache page is +An RSS page is unaccounted when it's fully unmapped. A PageCache page is unaccounted when it's removed from radix-tree. Even if RSS pages are fully unmapped (by kswapd), they may exist as SwapCache in the system until they -are really freed. Such SwapCaches also also accounted. +are really freed. Such SwapCaches are also accounted. A swapped-in page is not accounted until it's mapped. -Note: The kernel does swapin-readahead and read multiple swaps at once. +Note: The kernel does swapin-readahead and reads multiple swaps at once. This means swapped-in pages may contain pages for other tasks than a task causing page fault. So, we avoid accounting at swap-in I/O. @@ -209,7 +209,7 @@ memsw.limit_in_bytes. Example: Assume a system with 4G of swap. A task which allocates 6G of memory (by mistake) under 2G memory limitation will use all swap. In this case, setting memsw.limit_in_bytes=3G will prevent bad use of swap. -By using memsw limit, you can avoid system OOM which can be caused by swap +By using the memsw limit, you can avoid system OOM which can be caused by swap shortage. * why 'memory+swap' rather than swap. @@ -217,7 +217,7 @@ The global LRU(kswapd) can swap out arbitrary pages. Swap-out means to move account from memory to swap...there is no change in usage of memory+swap. In other words, when we want to limit the usage of swap without affecting global LRU, memory+swap limit is better than just limiting swap from -OS point of view. +an OS point of view. * What happens when a cgroup hits memory.memsw.limit_in_bytes When a cgroup hits memory.memsw.limit_in_bytes, it's useless to do swap-out @@ -236,7 +236,7 @@ an OOM routine is invoked to select and kill the bulkiest task in the cgroup. (See 10. OOM Control below.) The reclaim algorithm has not been modified for cgroups, except that -pages that are selected for reclaiming come from the per cgroup LRU +pages that are selected for reclaiming come from the per-cgroup LRU list. NOTE: Reclaim does not work for the root cgroup, since we cannot set any @@ -316,7 +316,7 @@ We can check the usage: # cat /sys/fs/cgroup/memory/0/memory.usage_in_bytes 1216512 -A successful write to this file does not guarantee a successful set of +A successful write to this file does not guarantee a successful setting of this limit to the value written into the file. This can be due to a number of factors, such as rounding up to page boundaries or the total availability of memory on the system. The user is required to re-read @@ -350,7 +350,7 @@ Trying usual test under memory controller is always helpful. 4.1 Troubleshooting Sometimes a user might find that the application under a cgroup is -terminated by OOM killer. There are several causes for this: +terminated by the OOM killer. There are several causes for this: 1. The cgroup limit is too low (just too low to do anything useful) 2. The user is using anonymous memory and swap is turned off or too low @@ -358,7 +358,7 @@ terminated by OOM killer. There are several causes for this: A sync followed by echo 1 > /proc/sys/vm/drop_caches will help get rid of some of the pages cached in the cgroup (page cache pages). -To know what happens, disable OOM_Kill by 10. OOM Control(see below) and +To know what happens, disabling OOM_Kill as per "10. OOM Control" (below) and seeing what happens will be helpful. 4.2 Task migration @@ -399,10 +399,10 @@ About use_hierarchy, see Section 6. 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 + moved to parent (if use_hierarchy==1) or root (if use_hierarchy==0) and this cgroup will be empty. - Typical use case of this interface is that calling this before rmdir(). + 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 moved to the parent. If you want to avoid that, force_empty will be useful. @@ -486,7 +486,7 @@ You can reset failcnt by writing 0 to failcnt file. For efficiency, as other kernel components, memory cgroup uses some optimization to avoid unnecessary cacheline false sharing. usage_in_bytes is affected by the -method and doesn't show 'exact' value of memory(and swap) usage, it's an fuzz +method and doesn't show 'exact' value of memory (and swap) usage, it's a fuzz value for efficient access. (Of course, when necessary, it's synchronized.) If you want to know more exact memory usage, you should use RSS+CACHE(+SWAP) value in memory.stat(see 5.2). @@ -496,8 +496,8 @@ value in memory.stat(see 5.2). This is similar to numa_maps but operates on a per-memcg basis. This is useful for providing visibility into the numa locality information within an memcg since the pages are allowed to be allocated from any physical -node. One of the usecases is evaluating application performance by -combining this information with the application's cpu allocation. +node. One of the use cases is evaluating application performance by +combining this information with the application's CPU allocation. We export "total", "file", "anon" and "unevictable" pages per-node for each memcg. The ouput format of memory.numa_stat is: @@ -561,10 +561,10 @@ are pushed back to their soft limits. If the soft limit of each control group is very high, they are pushed back as much as possible to make sure that one control group does not starve the others of memory. -Please note that soft limits is a best effort feature, it comes with +Please note that soft limits is a best-effort feature; it comes with no guarantees, but it does its best to make sure that when memory is heavily contended for, memory is allocated based on the soft limit -hints/setup. Currently soft limit based reclaim is setup such that +hints/setup. Currently soft limit based reclaim is set up such that it gets invoked from balance_pgdat (kswapd). 7.1 Interface @@ -592,7 +592,7 @@ page tables. 8.1 Interface -This feature is disabled by default. It can be enabled(and disabled again) by +This feature is disabled by default. It can be enabledi (and disabled again) by writing to memory.move_charge_at_immigrate of the destination cgroup. If you want to enable it: @@ -601,8 +601,8 @@ If you want to enable it: Note: Each bits of move_charge_at_immigrate has its own meaning about what type of charges should be moved. See 8.2 for details. -Note: Charges are moved only when you move mm->owner, IOW, a leader of a thread - group. +Note: Charges are moved only when you move mm->owner, in other words, + a leader of a thread group. Note: If we cannot find enough space for the task in the destination cgroup, we try to make space by reclaiming memory. Task migration may fail if we cannot make enough space. @@ -612,25 +612,25 @@ And if you want disable it again: # echo 0 > memory.move_charge_at_immigrate -8.2 Type of charges which can be move +8.2 Type of charges which can be moved -Each bits of move_charge_at_immigrate has its own meaning about what type of -charges should be moved. But in any cases, it must be noted that an account of -a page or a swap can be moved only when it is charged to the task's current(old) -memory cgroup. +Each bit in move_charge_at_immigrate has its own meaning about what type of +charges should be moved. But in any case, it must be noted that an account of +a page or a swap can be moved only when it is charged to the task's current +(old) memory cgroup. bit | what type of charges would be moved ? -----+------------------------------------------------------------------------ - 0 | A charge of an anonymous page(or swap of it) used by the target task. - | You must enable Swap Extension(see 2.4) to enable move of swap charges. + 0 | A charge of an anonymous page (or swap of it) used by the target task. + | You must enable Swap Extension (see 2.4) to enable move of swap charges. -----+------------------------------------------------------------------------ - 1 | A charge of file pages(normal file, tmpfs file(e.g. ipc shared memory) + 1 | A charge of file pages (normal file, tmpfs file (e.g. ipc shared memory) | and swaps of tmpfs file) mmapped by the target task. Unlike the case of - | anonymous pages, file pages(and swaps) in the range mmapped by the task + | anonymous pages, file pages (and swaps) in the range mmapped by the task | will be moved even if the task hasn't done page fault, i.e. they might | not be the task's "RSS", but other task's "RSS" that maps the same file. - | And mapcount of the page is ignored(the page can be moved even if - | page_mapcount(page) > 1). You must enable Swap Extension(see 2.4) to + | And mapcount of the page is ignored (the page can be moved even if + | page_mapcount(page) > 1). You must enable Swap Extension (see 2.4) to | enable move of swap charges. 8.3 TODO @@ -640,11 +640,11 @@ memory cgroup. 9. Memory thresholds -Memory cgroup implements memory thresholds using cgroups notification +Memory cgroup implements memory thresholds using the cgroups notification API (see cgroups.txt). It allows to register multiple memory and memsw thresholds and gets notifications when it crosses. -To register a threshold application need: +To register a threshold, an application must: - create an eventfd using eventfd(2); - open memory.usage_in_bytes or memory.memsw.usage_in_bytes; - write string like "<event_fd> <fd of memory.usage_in_bytes> <threshold>" to @@ -659,24 +659,24 @@ It's applicable for root and non-root cgroup. memory.oom_control file is for OOM notification and other controls. -Memory cgroup implements OOM notifier using cgroup notification +Memory cgroup implements OOM notifier using the cgroup notification API (See cgroups.txt). It allows to register multiple OOM notification delivery and gets notification when OOM happens. -To register a notifier, application need: +To register a notifier, an application must: - create an eventfd using eventfd(2) - open memory.oom_control file - write string like "<event_fd> <fd of memory.oom_control>" to cgroup.event_control -Application will be notified through eventfd when OOM happens. -OOM notification doesn't work for root cgroup. +The application will be notified through eventfd when OOM happens. +OOM notification doesn't work for the root cgroup. -You can disable OOM-killer by writing "1" to memory.oom_control file, as: +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 sub-hierarchy. +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. diff --git a/Documentation/cpu-freq/boost.txt b/Documentation/cpu-freq/boost.txt new file mode 100644 index 000000000000..9b4edfcf486f --- /dev/null +++ b/Documentation/cpu-freq/boost.txt @@ -0,0 +1,93 @@ +Processor boosting control + + - information for users - + +Quick guide for the impatient: +-------------------- +/sys/devices/system/cpu/cpufreq/boost +controls the boost setting for the whole system. You can read and write +that file with either "0" (boosting disabled) or "1" (boosting allowed). +Reading or writing 1 does not mean that the system is boosting at this +very moment, but only that the CPU _may_ raise the frequency at it's +discretion. +-------------------- + +Introduction +------------- +Some CPUs support a functionality to raise the operating frequency of +some cores in a multi-core package if certain conditions apply, mostly +if the whole chip is not fully utilized and below it's intended thermal +budget. This is done without operating system control by a combination +of hardware and firmware. +On Intel CPUs this is called "Turbo Boost", AMD calls it "Turbo-Core", +in technical documentation "Core performance boost". In Linux we use +the term "boost" for convenience. + +Rationale for disable switch +---------------------------- + +Though the idea is to just give better performance without any user +intervention, sometimes the need arises to disable this functionality. +Most systems offer a switch in the (BIOS) firmware to disable the +functionality at all, but a more fine-grained and dynamic control would +be desirable: +1. While running benchmarks, reproducible results are important. Since + the boosting functionality depends on the load of the whole package, + single thread performance can vary. By explicitly disabling the boost + functionality at least for the benchmark's run-time the system will run + at a fixed frequency and results are reproducible again. +2. To examine the impact of the boosting functionality it is helpful + to do tests with and without boosting. +3. Boosting means overclocking the processor, though under controlled + conditions. By raising the frequency and the voltage the processor + will consume more power than without the boosting, which may be + undesirable for instance for mobile users. Disabling boosting may + save power here, though this depends on the workload. + + +User controlled switch +---------------------- + +To allow the user to toggle the boosting functionality, the acpi-cpufreq +driver exports a sysfs knob to disable it. There is a file: +/sys/devices/system/cpu/cpufreq/boost +which can either read "0" (boosting disabled) or "1" (boosting enabled). +Reading the file is always supported, even if the processor does not +support boosting. In this case the file will be read-only and always +reads as "0". Explicitly changing the permissions and writing to that +file anyway will return EINVAL. + +On supported CPUs one can write either a "0" or a "1" into this file. +This will either disable the boost functionality on all cores in the +whole system (0) or will allow the hardware to boost at will (1). + +Writing a "1" does not explicitly boost the system, but just allows the +CPU (and the firmware) to boost at their discretion. Some implementations +take external factors like the chip's temperature into account, so +boosting once does not necessarily mean that it will occur every time +even using the exact same software setup. + + +AMD legacy cpb switch +--------------------- +The AMD powernow-k8 driver used to support a very similar switch to +disable or enable the "Core Performance Boost" feature of some AMD CPUs. +This switch was instantiated in each CPU's cpufreq directory +(/sys/devices/system/cpu[0-9]*/cpufreq) and was called "cpb". +Though the per CPU existence hints at a more fine grained control, the +actual implementation only supported a system-global switch semantics, +which was simply reflected into each CPU's file. Writing a 0 or 1 into it +would pull the other CPUs to the same state. +For compatibility reasons this file and its behavior is still supported +on AMD CPUs, though it is now protected by a config switch +(X86_ACPI_CPUFREQ_CPB). On Intel CPUs this file will never be created, +even with the config option set. +This functionality is considered legacy and will be removed in some future +kernel version. + +More fine grained boosting control +---------------------------------- + +Technically it is possible to switch the boosting functionality at least +on a per package basis, for some CPUs even per core. Currently the driver +does not support it, but this may be implemented in the future. diff --git a/Documentation/cpuidle/sysfs.txt b/Documentation/cpuidle/sysfs.txt index 9d28a3406e74..b6f44f490ed7 100644 --- a/Documentation/cpuidle/sysfs.txt +++ b/Documentation/cpuidle/sysfs.txt @@ -76,9 +76,17 @@ total 0 * desc : Small description about the idle state (string) -* disable : Option to disable this idle state (bool) +* disable : Option to disable this idle state (bool) -> see note below * latency : Latency to exit out of this idle state (in microseconds) * name : Name of the idle state (string) * power : Power consumed while in this idle state (in milliwatts) * time : Total time spent in this idle state (in microseconds) * usage : Number of times this state was entered (count) + +Note: +The behavior and the effect of the disable variable depends on the +implementation of a particular governor. In the ladder governor, for +example, it is not coherent, i.e. if one is disabling a light state, +then all deeper states are disabled as well, but the disable variable +does not reflect it. Likewise, if one enables a deep state but a lighter +state still is disabled, then this has no effect. diff --git a/Documentation/devicetree/bindings/arm/arm-boards b/Documentation/devicetree/bindings/arm/arm-boards index 91f26148af79..fc81a7d6b0f1 100644 --- a/Documentation/devicetree/bindings/arm/arm-boards +++ b/Documentation/devicetree/bindings/arm/arm-boards @@ -1,3 +1,15 @@ +ARM Integrator/AP (Application Platform) and Integrator/CP (Compact Platform) +----------------------------------------------------------------------------- +ARM's oldest Linux-supported platform with connectors for different core +tiles of ARMv4, ARMv5 and ARMv6 type. + +Required properties (in root node): + compatible = "arm,integrator-ap"; /* Application Platform */ + compatible = "arm,integrator-cp"; /* Compact Platform */ + +FPGA type interrupt controllers, see the versatile-fpga-irq binding doc. + + ARM Versatile Application and Platform Baseboards ------------------------------------------------- ARM's development hardware platform with connectors for customizable diff --git a/Documentation/devicetree/bindings/arm/bcm2835.txt b/Documentation/devicetree/bindings/arm/bcm2835.txt new file mode 100644 index 000000000000..ac683480c486 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/bcm2835.txt @@ -0,0 +1,8 @@ +Broadcom BCM2835 device tree bindings +------------------------------------------- + +Boards with the BCM2835 SoC shall have the following properties: + +Required root node property: + +compatible = "brcm,bcm2835"; diff --git a/Documentation/devicetree/bindings/arm/calxeda/combophy.txt b/Documentation/devicetree/bindings/arm/calxeda/combophy.txt new file mode 100644 index 000000000000..6622bdb2e8bc --- /dev/null +++ b/Documentation/devicetree/bindings/arm/calxeda/combophy.txt @@ -0,0 +1,17 @@ +Calxeda Highbank Combination Phys for SATA + +Properties: +- compatible : Should be "calxeda,hb-combophy" +- #phy-cells: Should be 1. +- reg : Address and size for Combination Phy registers. +- phydev: device ID for programming the combophy. + +Example: + + combophy5: combo-phy@fff5d000 { + compatible = "calxeda,hb-combophy"; + #phy-cells = <1>; + reg = <0xfff5d000 0x1000>; + phydev = <31>; + }; + diff --git a/Documentation/devicetree/bindings/arm/davinci/nand.txt b/Documentation/devicetree/bindings/arm/davinci/nand.txt new file mode 100644 index 000000000000..e37241f1fdd8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/davinci/nand.txt @@ -0,0 +1,51 @@ +* Texas Instruments Davinci NAND + +This file provides information, what the device node for the +davinci nand interface contain. + +Required properties: +- compatible: "ti,davinci-nand"; +- reg : contain 2 offset/length values: + - offset and length for the access window + - offset and length for accessing the aemif control registers +- ti,davinci-chipselect: Indicates on the davinci_nand driver which + chipselect is used for accessing the nand. + +Recommended properties : +- ti,davinci-mask-ale: mask for ale +- ti,davinci-mask-cle: mask for cle +- ti,davinci-mask-chipsel: mask for chipselect +- ti,davinci-ecc-mode: ECC mode valid values for davinci driver: + - "none" + - "soft" + - "hw" +- ti,davinci-ecc-bits: used ECC bits, currently supported 1 or 4. +- ti,davinci-nand-buswidth: buswidth 8 or 16 +- ti,davinci-nand-use-bbt: use flash based bad block table support. + +Example (enbw_cmc board): +aemif@60000000 { + compatible = "ti,davinci-aemif"; + #address-cells = <2>; + #size-cells = <1>; + reg = <0x68000000 0x80000>; + ranges = <2 0 0x60000000 0x02000000 + 3 0 0x62000000 0x02000000 + 4 0 0x64000000 0x02000000 + 5 0 0x66000000 0x02000000 + 6 0 0x68000000 0x02000000>; + nand@3,0 { + compatible = "ti,davinci-nand"; + reg = <3 0x0 0x807ff + 6 0x0 0x8000>; + #address-cells = <1>; + #size-cells = <1>; + ti,davinci-chipselect = <1>; + ti,davinci-mask-ale = <0>; + ti,davinci-mask-cle = <0>; + ti,davinci-mask-chipsel = <0>; + ti,davinci-ecc-mode = "hw"; + ti,davinci-ecc-bits = <4>; + ti,davinci-nand-use-bbt; + }; +}; diff --git a/Documentation/devicetree/bindings/arm/mrvl/tauros2.txt b/Documentation/devicetree/bindings/arm/mrvl/tauros2.txt new file mode 100644 index 000000000000..31af1cbb60bd --- /dev/null +++ b/Documentation/devicetree/bindings/arm/mrvl/tauros2.txt @@ -0,0 +1,17 @@ +* Marvell Tauros2 Cache + +Required properties: +- compatible : Should be "marvell,tauros2-cache". +- marvell,tauros2-cache-features : Specify the features supported for the + tauros2 cache. + The features including + CACHE_TAUROS2_PREFETCH_ON (1 << 0) + CACHE_TAUROS2_LINEFILL_BURST8 (1 << 1) + The definition can be found at + arch/arm/include/asm/hardware/cache-tauros2.h + +Example: + L2: l2-cache { + compatible = "marvell,tauros2-cache"; + marvell,tauros2-cache-features = <0x3>; + }; diff --git a/Documentation/devicetree/bindings/arm/msm/timer.txt b/Documentation/devicetree/bindings/arm/msm/timer.txt new file mode 100644 index 000000000000..8c5907b9cae8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/msm/timer.txt @@ -0,0 +1,38 @@ +* MSM Timer + +Properties: + +- compatible : Should at least contain "qcom,msm-timer". More specific + properties such as "qcom,msm-gpt" and "qcom,msm-dgt" specify a general + purpose timer and a debug timer respectively. + +- interrupts : Interrupt indicating a match event. + +- reg : Specifies the base address of the timer registers. The second region + specifies an optional register used to configure the clock divider. + +- clock-frequency : The frequency of the timer in Hz. + +Optional: + +- cpu-offset : per-cpu offset used when the timer is accessed without the + CPU remapping facilities. The offset is cpu-offset * cpu-nr. + +Example: + + timer@200a004 { + compatible = "qcom,msm-gpt", "qcom,msm-timer"; + interrupts = <1 2 0x301>; + reg = <0x0200a004 0x10>; + clock-frequency = <32768>; + cpu-offset = <0x40000>; + }; + + timer@200a024 { + compatible = "qcom,msm-dgt", "qcom,msm-timer"; + interrupts = <1 3 0x301>; + reg = <0x0200a024 0x10>, + <0x0200a034 0x4>; + clock-frequency = <6750000>; + cpu-offset = <0x40000>; + }; diff --git a/Documentation/devicetree/bindings/arm/omap/omap.txt b/Documentation/devicetree/bindings/arm/omap/omap.txt index ccdd0e53451f..d0051a750587 100644 --- a/Documentation/devicetree/bindings/arm/omap/omap.txt +++ b/Documentation/devicetree/bindings/arm/omap/omap.txt @@ -36,6 +36,9 @@ Boards: - OMAP3 BeagleBoard : Low cost community board compatible = "ti,omap3-beagle", "ti,omap3" +- OMAP3 Tobi with Overo : Commercial expansion board with daughter board + compatible = "ti,omap3-tobi", "ti,omap3-overo", "ti,omap3" + - OMAP4 SDP : Software Developement Board compatible = "ti,omap4-sdp", "ti,omap4430" diff --git a/Documentation/devicetree/bindings/arm/pmu.txt b/Documentation/devicetree/bindings/arm/pmu.txt index 1c044eb320cc..343781b9f246 100644 --- a/Documentation/devicetree/bindings/arm/pmu.txt +++ b/Documentation/devicetree/bindings/arm/pmu.txt @@ -7,8 +7,12 @@ representation in the device tree should be done as under:- Required properties: - compatible : should be one of + "arm,cortex-a15-pmu" "arm,cortex-a9-pmu" "arm,cortex-a8-pmu" + "arm,cortex-a7-pmu" + "arm,cortex-a5-pmu" + "arm,arm11mpcore-pmu" "arm,arm1176-pmu" "arm,arm1136-pmu" - interrupts : 1 combined interrupt or 1 per core. diff --git a/Documentation/devicetree/bindings/arm/versatile-fpga-irq.txt b/Documentation/devicetree/bindings/arm/versatile-fpga-irq.txt new file mode 100644 index 000000000000..9989eda755d9 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/versatile-fpga-irq.txt @@ -0,0 +1,31 @@ +* ARM Versatile FPGA interrupt controller + +One or more FPGA IRQ controllers can be synthesized in an ARM reference board +such as the Integrator or Versatile family. The output of these different +controllers are OR:ed together and fed to the CPU tile's IRQ input. Each +instance can handle up to 32 interrupts. + +Required properties: +- compatible: "arm,versatile-fpga-irq" +- interrupt-controller: Identifies the node as an interrupt controller +- #interrupt-cells: The number of cells to define the interrupts. Must be 1 + as the FPGA IRQ controller has no configuration options for interrupt + sources. The cell is a u32 and defines the interrupt number. +- reg: The register bank for the FPGA interrupt controller. +- clear-mask: a u32 number representing the mask written to clear all IRQs + on the controller at boot for example. +- valid-mask: a u32 number representing a bit mask determining which of + the interrupts are valid. Unconnected/unused lines are set to 0, and + the system till not make it possible for devices to request these + interrupts. + +Example: + +pic: pic@14000000 { + compatible = "arm,versatile-fpga-irq"; + #interrupt-cells = <1>; + interrupt-controller; + reg = <0x14000000 0x100>; + clear-mask = <0xffffffff>; + valid-mask = <0x003fffff>; +}; diff --git a/Documentation/devicetree/bindings/arm/vt8500.txt b/Documentation/devicetree/bindings/arm/vt8500.txt new file mode 100644 index 000000000000..d657832c6819 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/vt8500.txt @@ -0,0 +1,14 @@ +VIA/Wondermedia VT8500 Platforms Device Tree Bindings +--------------------------------------- + +Boards with the VIA VT8500 SoC shall have the following properties: +Required root node property: +compatible = "via,vt8500"; + +Boards with the Wondermedia WM8505 SoC shall have the following properties: +Required root node property: +compatible = "wm,wm8505"; + +Boards with the Wondermedia WM8650 SoC shall have the following properties: +Required root node property: +compatible = "wm,wm8650"; diff --git a/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-intc.txt b/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-intc.txt new file mode 100644 index 000000000000..0a4ce1051b02 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-intc.txt @@ -0,0 +1,16 @@ +VIA/Wondermedia VT8500 Interrupt Controller +----------------------------------------------------- + +Required properties: +- compatible : "via,vt8500-intc" +- reg : Should contain 1 register ranges(address and length) +- #interrupt-cells : should be <1> + +Example: + + intc: interrupt-controller@d8140000 { + compatible = "via,vt8500-intc"; + interrupt-controller; + reg = <0xd8140000 0x10000>; + #interrupt-cells = <1>; + }; diff --git a/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-pmc.txt b/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-pmc.txt new file mode 100644 index 000000000000..521b9c7de933 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-pmc.txt @@ -0,0 +1,13 @@ +VIA/Wondermedia VT8500 Power Management Controller +----------------------------------------------------- + +Required properties: +- compatible : "via,vt8500-pmc" +- reg : Should contain 1 register ranges(address and length) + +Example: + + pmc@d8130000 { + compatible = "via,vt8500-pmc"; + reg = <0xd8130000 0x1000>; + }; diff --git a/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-timer.txt b/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-timer.txt new file mode 100644 index 000000000000..901c73f0d8ef --- /dev/null +++ b/Documentation/devicetree/bindings/arm/vt8500/via,vt8500-timer.txt @@ -0,0 +1,15 @@ +VIA/Wondermedia VT8500 Timer +----------------------------------------------------- + +Required properties: +- compatible : "via,vt8500-timer" +- reg : Should contain 1 register ranges(address and length) +- interrupts : interrupt for the timer + +Example: + + timer@d8130100 { + compatible = "via,vt8500-timer"; + reg = <0xd8130100 0x28>; + interrupts = <36>; + }; diff --git a/Documentation/devicetree/bindings/arm/xen.txt b/Documentation/devicetree/bindings/arm/xen.txt new file mode 100644 index 000000000000..0f7b9c2109f8 --- /dev/null +++ b/Documentation/devicetree/bindings/arm/xen.txt @@ -0,0 +1,25 @@ +* Xen hypervisor device tree bindings + +Xen ARM virtual platforms shall have a top-level "hypervisor" node with +the following properties: + +- compatible: + compatible = "xen,xen-<version>", "xen,xen"; + where <version> is the version of the Xen ABI of the platform. + +- reg: specifies the base physical address and size of a region in + memory where the grant table should be mapped to, using an + HYPERVISOR_memory_op hypercall. The memory region is large enough to map + the whole grant table (it is larger or equal to gnttab_max_grant_frames()). + +- interrupts: the interrupt used by Xen to inject event notifications. + A GIC node is also required. + + +Example (assuming #address-cells = <2> and #size-cells = <2>): + +hypervisor { + compatible = "xen,xen-4.3", "xen,xen"; + reg = <0 0xb0000000 0 0x20000>; + interrupts = <1 15 0xf08>; +}; diff --git a/Documentation/devicetree/bindings/ata/ahci-platform.txt b/Documentation/devicetree/bindings/ata/ahci-platform.txt index 8bb8a76d42e8..b519f9b699c3 100644 --- a/Documentation/devicetree/bindings/ata/ahci-platform.txt +++ b/Documentation/devicetree/bindings/ata/ahci-platform.txt @@ -8,9 +8,18 @@ Required properties: - interrupts : <interrupt mapping for SATA IRQ> - reg : <registers mapping> +Optional properties: +- calxeda,port-phys: phandle-combophy and lane assignment, which maps each + SATA port to a combophy and a lane within that + combophy +- dma-coherent : Present if dma operations are coherent + Example: sata@ffe08000 { compatible = "calxeda,hb-ahci"; reg = <0xffe08000 0x1000>; interrupts = <115>; + calxeda,port-phys = <&combophy5 0 &combophy0 0 &combophy0 1 + &combophy0 2 &combophy0 3>; + }; diff --git a/Documentation/devicetree/bindings/ata/pata-arasan.txt b/Documentation/devicetree/bindings/ata/pata-arasan.txt new file mode 100644 index 000000000000..95ec7f825ede --- /dev/null +++ b/Documentation/devicetree/bindings/ata/pata-arasan.txt @@ -0,0 +1,17 @@ +* ARASAN PATA COMPACT FLASH CONTROLLER + +Required properties: +- compatible: "arasan,cf-spear1340" +- reg: Address range of the CF registers +- interrupt-parent: Should be the phandle for the interrupt controller + that services interrupts for this device +- interrupt: Should contain the CF interrupt number + +Example: + + cf@fc000000 { + compatible = "arasan,cf-spear1340"; + reg = <0xfc000000 0x1000>; + interrupt-parent = <&vic1>; + interrupts = <12>; + }; diff --git a/Documentation/devicetree/bindings/bus/omap-ocp2scp.txt b/Documentation/devicetree/bindings/bus/omap-ocp2scp.txt new file mode 100644 index 000000000000..d2fe064a828b --- /dev/null +++ b/Documentation/devicetree/bindings/bus/omap-ocp2scp.txt @@ -0,0 +1,10 @@ +* OMAP OCP2SCP - ocp interface to scp interface + +properties: +- compatible : Should be "ti,omap-ocp2scp" +- #address-cells, #size-cells : Must be present if the device has sub-nodes +- ranges : the child address space are mapped 1:1 onto the parent address space +- ti,hwmods : must be "ocp2scp_usb_phy" + +Sub-nodes: +All the devices connected to ocp2scp are described using sub-node to ocp2scp diff --git a/Documentation/devicetree/bindings/clock/imx23-clock.txt b/Documentation/devicetree/bindings/clock/imx23-clock.txt new file mode 100644 index 000000000000..a0b867ef8d96 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx23-clock.txt @@ -0,0 +1,76 @@ +* Clock bindings for Freescale i.MX23 + +Required properties: +- compatible: Should be "fsl,imx23-clkctrl" +- reg: Address and length of the register set +- #clock-cells: Should be <1> + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. The following is a full list of i.MX23 +clocks and IDs. + + Clock ID + ------------------ + ref_xtal 0 + pll 1 + ref_cpu 2 + ref_emi 3 + ref_pix 4 + ref_io 5 + saif_sel 6 + lcdif_sel 7 + gpmi_sel 8 + ssp_sel 9 + emi_sel 10 + cpu 11 + etm_sel 12 + cpu_pll 13 + cpu_xtal 14 + hbus 15 + xbus 16 + lcdif_div 17 + ssp_div 18 + gpmi_div 19 + emi_pll 20 + emi_xtal 21 + etm_div 22 + saif_div 23 + clk32k_div 24 + rtc 25 + adc 26 + spdif_div 27 + clk32k 28 + dri 29 + pwm 30 + filt 31 + uart 32 + ssp 33 + gpmi 34 + spdif 35 + emi 36 + saif 37 + lcdif 38 + etm 39 + usb 40 + usb_pwr 41 + +Examples: + +clks: clkctrl@80040000 { + compatible = "fsl,imx23-clkctrl"; + reg = <0x80040000 0x2000>; + #clock-cells = <1>; + clock-output-names = + ... + "uart", /* 32 */ + ... + "end_of_list"; +}; + +auart0: serial@8006c000 { + compatible = "fsl,imx23-auart"; + reg = <0x8006c000 0x2000>; + interrupts = <24 25 23>; + clocks = <&clks 32>; + status = "disabled"; +}; diff --git a/Documentation/devicetree/bindings/clock/imx28-clock.txt b/Documentation/devicetree/bindings/clock/imx28-clock.txt new file mode 100644 index 000000000000..aa2af2866fe8 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx28-clock.txt @@ -0,0 +1,99 @@ +* Clock bindings for Freescale i.MX28 + +Required properties: +- compatible: Should be "fsl,imx28-clkctrl" +- reg: Address and length of the register set +- #clock-cells: Should be <1> + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. The following is a full list of i.MX28 +clocks and IDs. + + Clock ID + ------------------ + ref_xtal 0 + pll0 1 + pll1 2 + pll2 3 + ref_cpu 4 + ref_emi 5 + ref_io0 6 + ref_io1 7 + ref_pix 8 + ref_hsadc 9 + ref_gpmi 10 + saif0_sel 11 + saif1_sel 12 + gpmi_sel 13 + ssp0_sel 14 + ssp1_sel 15 + ssp2_sel 16 + ssp3_sel 17 + emi_sel 18 + etm_sel 19 + lcdif_sel 20 + cpu 21 + ptp_sel 22 + cpu_pll 23 + cpu_xtal 24 + hbus 25 + xbus 26 + ssp0_div 27 + ssp1_div 28 + ssp2_div 29 + ssp3_div 30 + gpmi_div 31 + emi_pll 32 + emi_xtal 33 + lcdif_div 34 + etm_div 35 + ptp 36 + saif0_div 37 + saif1_div 38 + clk32k_div 39 + rtc 40 + lradc 41 + spdif_div 42 + clk32k 43 + pwm 44 + uart 45 + ssp0 46 + ssp1 47 + ssp2 48 + ssp3 49 + gpmi 50 + spdif 51 + emi 52 + saif0 53 + saif1 54 + lcdif 55 + etm 56 + fec 57 + can0 58 + can1 59 + usb0 60 + usb1 61 + usb0_pwr 62 + usb1_pwr 63 + enet_out 64 + +Examples: + +clks: clkctrl@80040000 { + compatible = "fsl,imx28-clkctrl"; + reg = <0x80040000 0x2000>; + #clock-cells = <1>; + clock-output-names = + ... + "uart", /* 45 */ + ... + "end_of_list"; +}; + +auart0: serial@8006a000 { + compatible = "fsl,imx28-auart", "fsl,imx23-auart"; + reg = <0x8006a000 0x2000>; + interrupts = <112 70 71>; + clocks = <&clks 45>; + status = "disabled"; +}; diff --git a/Documentation/devicetree/bindings/clock/imx6q-clock.txt b/Documentation/devicetree/bindings/clock/imx6q-clock.txt new file mode 100644 index 000000000000..492bd991d52a --- /dev/null +++ b/Documentation/devicetree/bindings/clock/imx6q-clock.txt @@ -0,0 +1,222 @@ +* Clock bindings for Freescale i.MX6 Quad + +Required properties: +- compatible: Should be "fsl,imx6q-ccm" +- reg: Address and length of the register set +- interrupts: Should contain CCM interrupt +- #clock-cells: Should be <1> + +The clock consumer should specify the desired clock by having the clock +ID in its "clocks" phandle cell. The following is a full list of i.MX6Q +clocks and IDs. + + Clock ID + --------------------------- + dummy 0 + ckil 1 + ckih 2 + osc 3 + pll2_pfd0_352m 4 + pll2_pfd1_594m 5 + pll2_pfd2_396m 6 + pll3_pfd0_720m 7 + pll3_pfd1_540m 8 + pll3_pfd2_508m 9 + pll3_pfd3_454m 10 + pll2_198m 11 + pll3_120m 12 + pll3_80m 13 + pll3_60m 14 + twd 15 + step 16 + pll1_sw 17 + periph_pre 18 + periph2_pre 19 + periph_clk2_sel 20 + periph2_clk2_sel 21 + axi_sel 22 + esai_sel 23 + asrc_sel 24 + spdif_sel 25 + gpu2d_axi 26 + gpu3d_axi 27 + gpu2d_core_sel 28 + gpu3d_core_sel 29 + gpu3d_shader_sel 30 + ipu1_sel 31 + ipu2_sel 32 + ldb_di0_sel 33 + ldb_di1_sel 34 + ipu1_di0_pre_sel 35 + ipu1_di1_pre_sel 36 + ipu2_di0_pre_sel 37 + ipu2_di1_pre_sel 38 + ipu1_di0_sel 39 + ipu1_di1_sel 40 + ipu2_di0_sel 41 + ipu2_di1_sel 42 + hsi_tx_sel 43 + pcie_axi_sel 44 + ssi1_sel 45 + ssi2_sel 46 + ssi3_sel 47 + usdhc1_sel 48 + usdhc2_sel 49 + usdhc3_sel 50 + usdhc4_sel 51 + enfc_sel 52 + emi_sel 53 + emi_slow_sel 54 + vdo_axi_sel 55 + vpu_axi_sel 56 + cko1_sel 57 + periph 58 + periph2 59 + periph_clk2 60 + periph2_clk2 61 + ipg 62 + ipg_per 63 + esai_pred 64 + esai_podf 65 + asrc_pred 66 + asrc_podf 67 + spdif_pred 68 + spdif_podf 69 + can_root 70 + ecspi_root 71 + gpu2d_core_podf 72 + gpu3d_core_podf 73 + gpu3d_shader 74 + ipu1_podf 75 + ipu2_podf 76 + ldb_di0_podf 77 + ldb_di1_podf 78 + ipu1_di0_pre 79 + ipu1_di1_pre 80 + ipu2_di0_pre 81 + ipu2_di1_pre 82 + hsi_tx_podf 83 + ssi1_pred 84 + ssi1_podf 85 + ssi2_pred 86 + ssi2_podf 87 + ssi3_pred 88 + ssi3_podf 89 + uart_serial_podf 90 + usdhc1_podf 91 + usdhc2_podf 92 + usdhc3_podf 93 + usdhc4_podf 94 + enfc_pred 95 + enfc_podf 96 + emi_podf 97 + emi_slow_podf 98 + vpu_axi_podf 99 + cko1_podf 100 + axi 101 + mmdc_ch0_axi_podf 102 + mmdc_ch1_axi_podf 103 + arm 104 + ahb 105 + apbh_dma 106 + asrc 107 + can1_ipg 108 + can1_serial 109 + can2_ipg 110 + can2_serial 111 + ecspi1 112 + ecspi2 113 + ecspi3 114 + ecspi4 115 + ecspi5 116 + enet 117 + esai 118 + gpt_ipg 119 + gpt_ipg_per 120 + gpu2d_core 121 + gpu3d_core 122 + hdmi_iahb 123 + hdmi_isfr 124 + i2c1 125 + i2c2 126 + i2c3 127 + iim 128 + enfc 129 + ipu1 130 + ipu1_di0 131 + ipu1_di1 132 + ipu2 133 + ipu2_di0 134 + ldb_di0 135 + ldb_di1 136 + ipu2_di1 137 + hsi_tx 138 + mlb 139 + mmdc_ch0_axi 140 + mmdc_ch1_axi 141 + ocram 142 + openvg_axi 143 + pcie_axi 144 + pwm1 145 + pwm2 146 + pwm3 147 + pwm4 148 + per1_bch 149 + gpmi_bch_apb 150 + gpmi_bch 151 + gpmi_io 152 + gpmi_apb 153 + sata 154 + sdma 155 + spba 156 + ssi1 157 + ssi2 158 + ssi3 159 + uart_ipg 160 + uart_serial 161 + usboh3 162 + usdhc1 163 + usdhc2 164 + usdhc3 165 + usdhc4 166 + vdo_axi 167 + vpu_axi 168 + cko1 169 + pll1_sys 170 + pll2_bus 171 + pll3_usb_otg 172 + pll4_audio 173 + pll5_video 174 + pll6_mlb 175 + pll7_usb_host 176 + pll8_enet 177 + ssi1_ipg 178 + ssi2_ipg 179 + ssi3_ipg 180 + rom 181 + usbphy1 182 + usbphy2 183 + ldb_di0_div_3_5 184 + ldb_di1_div_3_5 185 + +Examples: + +clks: ccm@020c4000 { + compatible = "fsl,imx6q-ccm"; + reg = <0x020c4000 0x4000>; + interrupts = <0 87 0x04 0 88 0x04>; + #clock-cells = <1>; + clock-output-names = ... + "uart_ipg", + "uart_serial", + ...; +}; + +uart1: serial@02020000 { + compatible = "fsl,imx6q-uart", "fsl,imx21-uart"; + reg = <0x02020000 0x4000>; + interrupts = <0 26 0x04>; + clocks = <&clks 160>, <&clks 161>; + clock-names = "ipg", "per"; + status = "disabled"; +}; diff --git a/Documentation/devicetree/bindings/clock/vt8500.txt b/Documentation/devicetree/bindings/clock/vt8500.txt new file mode 100644 index 000000000000..a880c70d0047 --- /dev/null +++ b/Documentation/devicetree/bindings/clock/vt8500.txt @@ -0,0 +1,72 @@ +Device Tree Clock bindings for arch-vt8500 + +This binding uses the common clock binding[1]. + +[1] Documentation/devicetree/bindings/clock/clock-bindings.txt + +Required properties: +- compatible : shall be one of the following: + "via,vt8500-pll-clock" - for a VT8500/WM8505 PLL clock + "wm,wm8650-pll-clock" - for a WM8650 PLL clock + "via,vt8500-device-clock" - for a VT/WM device clock + +Required properties for PLL clocks: +- reg : shall be the control register offset from PMC base for the pll clock. +- clocks : shall be the input parent clock phandle for the clock. This should + be the reference clock. +- #clock-cells : from common clock binding; shall be set to 0. + +Required properties for device clocks: +- clocks : shall be the input parent clock phandle for the clock. This should + be a pll output. +- #clock-cells : from common clock binding; shall be set to 0. + + +Device Clocks + +Device clocks are required to have one or both of the following sets of +properties: + + +Gated device clocks: + +Required properties: +- enable-reg : shall be the register offset from PMC base for the enable + register. +- enable-bit : shall be the bit within enable-reg to enable/disable the clock. + + +Divisor device clocks: + +Required property: +- divisor-reg : shall be the register offset from PMC base for the divisor + register. +Optional property: +- divisor-mask : shall be the mask for the divisor register. Defaults to 0x1f + if not specified. + + +For example: + +ref25: ref25M { + #clock-cells = <0>; + compatible = "fixed-clock"; + clock-frequency = <25000000>; +}; + +plla: plla { + #clock-cells = <0>; + compatible = "wm,wm8650-pll-clock"; + clocks = <&ref25>; + reg = <0x200>; +}; + +sdhc: sdhc { + #clock-cells = <0>; + compatible = "via,vt8500-device-clock"; + clocks = <&pllb>; + divisor-reg = <0x328>; + divisor-mask = <0x3f>; + enable-reg = <0x254>; + enable-bit = <18>; +}; diff --git a/Documentation/devicetree/bindings/cpufreq/cpufreq-cpu0.txt b/Documentation/devicetree/bindings/cpufreq/cpufreq-cpu0.txt new file mode 100644 index 000000000000..4416ccc33472 --- /dev/null +++ b/Documentation/devicetree/bindings/cpufreq/cpufreq-cpu0.txt @@ -0,0 +1,55 @@ +Generic CPU0 cpufreq driver + +It is a generic cpufreq driver for CPU0 frequency management. It +supports both uniprocessor (UP) and symmetric multiprocessor (SMP) +systems which share clock and voltage across all CPUs. + +Both required and optional properties listed below must be defined +under node /cpus/cpu@0. + +Required properties: +- operating-points: Refer to Documentation/devicetree/bindings/power/opp.txt + for details + +Optional properties: +- clock-latency: Specify the possible maximum transition latency for clock, + in unit of nanoseconds. +- voltage-tolerance: Specify the CPU voltage tolerance in percentage. + +Examples: + +cpus { + #address-cells = <1>; + #size-cells = <0>; + + cpu@0 { + compatible = "arm,cortex-a9"; + reg = <0>; + next-level-cache = <&L2>; + operating-points = < + /* kHz uV */ + 792000 1100000 + 396000 950000 + 198000 850000 + >; + transition-latency = <61036>; /* two CLK32 periods */ + }; + + cpu@1 { + compatible = "arm,cortex-a9"; + reg = <1>; + next-level-cache = <&L2>; + }; + + cpu@2 { + compatible = "arm,cortex-a9"; + reg = <2>; + next-level-cache = <&L2>; + }; + + cpu@3 { + compatible = "arm,cortex-a9"; + reg = <3>; + next-level-cache = <&L2>; + }; +}; diff --git a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt index bf57ecd5d73a..bd7ce120bc13 100644 --- a/Documentation/devicetree/bindings/crypto/fsl-sec4.txt +++ b/Documentation/devicetree/bindings/crypto/fsl-sec4.txt @@ -9,6 +9,7 @@ Copyright (C) 2008-2011 Freescale Semiconductor Inc. -Run Time Integrity Check (RTIC) Node -Run Time Integrity Check (RTIC) Memory Node -Secure Non-Volatile Storage (SNVS) Node + -Secure Non-Volatile Storage (SNVS) Low Power (LP) RTC Node -Full Example NOTE: the SEC 4 is also known as Freescale's Cryptographic Accelerator @@ -294,6 +295,27 @@ Secure Non-Volatile Storage (SNVS) Node address and length of the SEC4 configuration registers. + - #address-cells + Usage: required + Value type: <u32> + Definition: A standard property. Defines the number of cells + for representing physical addresses in child nodes. Must + have a value of 1. + + - #size-cells + Usage: required + Value type: <u32> + Definition: A standard property. Defines the number of cells + for representing the size of physical addresses in + child nodes. Must have a value of 1. + + - ranges + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the physical address + range of the SNVS register space. A triplet that includes + the child address, parent address, & length. + - interrupts Usage: required Value type: <prop_encoded-array> @@ -314,11 +336,34 @@ EXAMPLE sec_mon@314000 { compatible = "fsl,sec-v4.0-mon"; reg = <0x314000 0x1000>; + ranges = <0 0x314000 0x1000>; interrupt-parent = <&mpic>; interrupts = <93 2>; }; ===================================================================== +Secure Non-Volatile Storage (SNVS) Low Power (LP) RTC Node + + A SNVS child node that defines SNVS LP RTC. + + - compatible + Usage: required + Value type: <string> + Definition: Must include "fsl,sec-v4.0-mon-rtc-lp". + + - reg + Usage: required + Value type: <prop-encoded-array> + Definition: A standard property. Specifies the physical + address and length of the SNVS LP configuration registers. + +EXAMPLE + sec_mon_rtc_lp@314000 { + compatible = "fsl,sec-v4.0-mon-rtc-lp"; + reg = <0x34 0x58>; + }; + +===================================================================== FULL EXAMPLE crypto: crypto@300000 { @@ -390,8 +435,14 @@ FULL EXAMPLE sec_mon: sec_mon@314000 { compatible = "fsl,sec-v4.0-mon"; reg = <0x314000 0x1000>; + ranges = <0 0x314000 0x1000>; interrupt-parent = <&mpic>; interrupts = <93 2>; + + sec_mon_rtc_lp@34 { + compatible = "fsl,sec-v4.0-mon-rtc-lp"; + reg = <0x34 0x58>; + }; }; ===================================================================== diff --git a/Documentation/devicetree/bindings/crypto/mv_cesa.txt b/Documentation/devicetree/bindings/crypto/mv_cesa.txt new file mode 100644 index 000000000000..47229b1a594b --- /dev/null +++ b/Documentation/devicetree/bindings/crypto/mv_cesa.txt @@ -0,0 +1,20 @@ +Marvell Cryptographic Engines And Security Accelerator + +Required properties: +- compatible : should be "marvell,orion-crypto" +- reg : base physical address of the engine and length of memory mapped + region, followed by base physical address of sram and its memory + length +- reg-names : "regs" , "sram"; +- interrupts : interrupt number + +Examples: + + crypto@30000 { + compatible = "marvell,orion-crypto"; + reg = <0x30000 0x10000>, + <0x4000000 0x800>; + reg-names = "regs" , "sram"; + interrupts = <22>; + status = "okay"; + }; diff --git a/Documentation/devicetree/bindings/dma/arm-pl330.txt b/Documentation/devicetree/bindings/dma/arm-pl330.txt index a4cd273b2a67..36e27d54260b 100644 --- a/Documentation/devicetree/bindings/dma/arm-pl330.txt +++ b/Documentation/devicetree/bindings/dma/arm-pl330.txt @@ -9,6 +9,9 @@ Required properties: region. - interrupts: interrupt number to the cpu. +Optional properties: +- dma-coherent : Present if dma operations are coherent + Example: pdma0: pdma@12680000 { diff --git a/Documentation/devicetree/bindings/dma/mmp-dma.txt b/Documentation/devicetree/bindings/dma/mmp-dma.txt new file mode 100644 index 000000000000..a4fa4efa1d83 --- /dev/null +++ b/Documentation/devicetree/bindings/dma/mmp-dma.txt @@ -0,0 +1,74 @@ +* MARVELL MMP DMA controller + +Marvell Peripheral DMA Controller +Used platfroms: pxa688, pxa910, pxa3xx, etc + +Required properties: +- compatible: Should be "marvell,pdma-1.0" +- reg: Should contain DMA registers location and length. +- interrupts: Either contain all of the per-channel DMA interrupts + or one irq for pdma device +- #dma-channels: Number of DMA channels supported by the controller. + +"marvell,pdma-1.0" +Used platfroms: pxa25x, pxa27x, pxa3xx, pxa93x, pxa168, pxa910, pxa688. + +Examples: + +/* + * Each channel has specific irq + * ICU parse out irq channel from ICU register, + * while DMA controller may not able to distinguish the irq channel + * Using this method, interrupt-parent is required as demuxer + * For example, pxa688 icu register 0x128, bit 0~15 is PDMA channel irq, + * 18~21 is ADMA irq + */ +pdma: dma-controller@d4000000 { + compatible = "marvell,pdma-1.0"; + reg = <0xd4000000 0x10000>; + interrupts = <0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15>; + interrupt-parent = <&intcmux32>; + #dma-channels = <16>; + }; + +/* + * One irq for all channels + * Dmaengine driver (DMA controller) distinguish irq channel via + * parsing internal register + */ +pdma: dma-controller@d4000000 { + compatible = "marvell,pdma-1.0"; + reg = <0xd4000000 0x10000>; + interrupts = <47>; + #dma-channels = <16>; + }; + + +Marvell Two Channel DMA Controller used specifically for audio +Used platfroms: pxa688, pxa910 + +Required properties: +- compatible: Should be "marvell,adma-1.0" or "marvell,pxa910-squ" +- reg: Should contain DMA registers location and length. +- interrupts: Either contain all of the per-channel DMA interrupts + or one irq for dma device + +"marvell,adma-1.0" used on pxa688 +"marvell,pxa910-squ" used on pxa910 + +Examples: + +/* each channel has specific irq */ +adma0: dma-controller@d42a0800 { + compatible = "marvell,adma-1.0"; + reg = <0xd42a0800 0x100>; + interrupts = <18 19>; + interrupt-parent = <&intcmux32>; + }; + +/* One irq for all channels */ +squ: dma-controller@d42a0800 { + compatible = "marvell,pxa910-squ"; + reg = <0xd42a0800 0x100>; + interrupts = <46>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-74x164.txt b/Documentation/devicetree/bindings/gpio/gpio-74x164.txt new file mode 100644 index 000000000000..cc2608021f26 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-74x164.txt @@ -0,0 +1,22 @@ +* Generic 8-bits shift register GPIO driver + +Required properties: +- compatible : Should be "fairchild,74hc595" +- reg : chip select number +- gpio-controller : Marks the device node as a gpio controller. +- #gpio-cells : Should be two. The first cell is the pin number and + the second cell is used to specify the gpio polarity: + 0 = active high + 1 = active low +- registers-number: Number of daisy-chained shift registers + +Example: + +gpio5: gpio5@0 { + compatible = "fairchild,74hc595"; + reg = <0>; + gpio-controller; + #gpio-cells = <2>; + registers-number = <4>; + spi-max-frequency = <100000>; +}; diff --git a/Documentation/devicetree/bindings/gpio/gpio-adnp.txt b/Documentation/devicetree/bindings/gpio/gpio-adnp.txt new file mode 100644 index 000000000000..af66b2724837 --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-adnp.txt @@ -0,0 +1,34 @@ +Avionic Design N-bit GPIO expander bindings + +Required properties: +- compatible: should be "ad,gpio-adnp" +- reg: The I2C slave address for this device. +- interrupt-parent: phandle of the parent interrupt controller. +- interrupts: Interrupt specifier for the controllers interrupt. +- #gpio-cells: Should be 2. The first cell is the GPIO number and the + second cell is used to specify optional parameters: + - bit 0: polarity (0: normal, 1: inverted) +- gpio-controller: Marks the device as a GPIO controller +- nr-gpios: The number of pins supported by the controller. + +The GPIO expander can optionally be used as an interrupt controller, in +which case it uses the default two cell specifier as described in +Documentation/devicetree/bindings/interrupt-controller/interrupts.txt. + +Example: + + gpioext: gpio-controller@41 { + compatible = "ad,gpio-adnp"; + reg = <0x41>; + + interrupt-parent = <&gpio>; + interrupts = <160 1>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + + nr-gpios = <64>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-fan.txt b/Documentation/devicetree/bindings/gpio/gpio-fan.txt new file mode 100644 index 000000000000..2dd457a3469a --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-fan.txt @@ -0,0 +1,25 @@ +Bindings for fan connected to GPIO lines + +Required properties: +- compatible : "gpio-fan" +- gpios: Specifies the pins that map to bits in the control value, + ordered MSB-->LSB. +- gpio-fan,speed-map: A mapping of possible fan RPM speeds and the + control value that should be set to achieve them. This array + must have the RPM values in ascending order. + +Optional properties: +- alarm-gpios: This pin going active indicates something is wrong with + the fan, and a udev event will be fired. + +Examples: + + gpio_fan { + compatible = "gpio-fan"; + gpios = <&gpio1 14 1 + &gpio1 13 1>; + gpio-fan,speed-map = <0 0 + 3000 1 + 6000 2>; + alarm-gpios = <&gpio1 15 1>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt new file mode 100644 index 000000000000..a6f3bec1da7d --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-mvebu.txt @@ -0,0 +1,53 @@ +* Marvell EBU GPIO controller + +Required properties: + +- compatible : Should be "marvell,orion-gpio", "marvell,mv78200-gpio" + or "marvell,armadaxp-gpio". "marvell,orion-gpio" should be used for + Orion, Kirkwood, Dove, Discovery (except MV78200) and Armada + 370. "marvell,mv78200-gpio" should be used for the Discovery + MV78200. "marvel,armadaxp-gpio" should be used for all Armada XP + SoCs (MV78230, MV78260, MV78460). + +- reg: Address and length of the register set for the device. Only one + entry is expected, except for the "marvell,armadaxp-gpio" variant + for which two entries are expected: one for the general registers, + one for the per-cpu registers. + +- interrupts: The list of interrupts that are used for all the pins + managed by this GPIO bank. There can be more than one interrupt + (example: 1 interrupt per 8 pins on Armada XP, which means 4 + interrupts per bank of 32 GPIOs). + +- interrupt-controller: identifies the node as an interrupt controller + +- #interrupt-cells: specifies the number of cells needed to encode an + interrupt source. Should be two. + The first cell is the GPIO number. + The second cell is used to specify flags: + bits[3:0] trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. + +- gpio-controller: marks the device node as a gpio controller + +- ngpios: number of GPIOs this controller has + +- #gpio-cells: Should be two. The first cell is the pin number. The + second cell is reserved for flags, unused at the moment. + +Example: + + gpio0: gpio@d0018100 { + compatible = "marvell,armadaxp-gpio"; + reg = <0xd0018100 0x40>, + <0xd0018800 0x30>; + ngpios = <32>; + gpio-controller; + #gpio-cells = <2>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <16>, <17>, <18>, <19>; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt b/Documentation/devicetree/bindings/gpio/gpio-samsung.txt index 5375625e8cd2..f1e5dfecf55d 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-samsung.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-samsung.txt @@ -39,3 +39,46 @@ Example: #gpio-cells = <4>; gpio-controller; }; + + +Samsung S3C24XX GPIO Controller + +Required properties: +- compatible: Compatible property value should be "samsung,s3c24xx-gpio". + +- reg: Physical base address of the controller and length of memory mapped + region. + +- #gpio-cells: Should be 3. The syntax of the gpio specifier used by client nodes + should be the following with values derived from the SoC user manual. + <[phandle of the gpio controller node] + [pin number within the gpio controller] + [mux function] + [flags and pull up/down] + + Values for gpio specifier: + - Pin number: depending on the controller a number from 0 up to 15. + - Mux function: Depending on the SoC and the gpio bank the gpio can be set + as input, output or a special function + - Flags and Pull Up/Down: the values to use differ for the individual SoCs + example S3C2416/S3C2450: + 0 - Pull Up/Down Disabled. + 1 - Pull Down Enabled. + 2 - Pull Up Enabled. + Bit 16 (0x00010000) - Input is active low. + Consult the user manual for the correct values of Mux and Pull Up/Down. + +- gpio-controller: Specifies that the node is a gpio controller. +- #address-cells: should be 1. +- #size-cells: should be 1. + +Example: + + gpa: gpio-controller@56000000 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "samsung,s3c24xx-gpio"; + reg = <0x56000000 0x10>; + #gpio-cells = <3>; + gpio-controller; + }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-twl4030.txt b/Documentation/devicetree/bindings/gpio/gpio-twl4030.txt index 16695d9cf1e8..66788fda1db3 100644 --- a/Documentation/devicetree/bindings/gpio/gpio-twl4030.txt +++ b/Documentation/devicetree/bindings/gpio/gpio-twl4030.txt @@ -11,6 +11,11 @@ Required properties: - interrupt-controller: Mark the device node as an interrupt controller The first cell is the GPIO number. The second cell is not used. +- ti,use-leds : Enables LEDA and LEDB outputs if set +- ti,debounce : if n-th bit is set, debounces GPIO-n +- ti,mmc-cd : if n-th bit is set, GPIO-n controls VMMC(n+1) +- ti,pullups : if n-th bit is set, set a pullup on GPIO-n +- ti,pulldowns : if n-th bit is set, set a pulldown on GPIO-n Example: @@ -20,4 +25,5 @@ twl_gpio: gpio { gpio-controller; #interrupt-cells = <2>; interrupt-controller; + ti,use-leds; }; diff --git a/Documentation/devicetree/bindings/gpio/gpio-vt8500.txt b/Documentation/devicetree/bindings/gpio/gpio-vt8500.txt new file mode 100644 index 000000000000..f4dc5233167e --- /dev/null +++ b/Documentation/devicetree/bindings/gpio/gpio-vt8500.txt @@ -0,0 +1,24 @@ +VIA/Wondermedia VT8500 GPIO Controller +----------------------------------------------------- + +Required properties: +- compatible : "via,vt8500-gpio", "wm,wm8505-gpio" + or "wm,wm8650-gpio" depending on your SoC +- reg : Should contain 1 register range (address and length) +- #gpio-cells : should be <3>. + 1) bank + 2) pin number + 3) flags - should be 0 + +Example: + + gpio: gpio-controller@d8110000 { + compatible = "via,vt8500-gpio"; + gpio-controller; + reg = <0xd8110000 0x10000>; + #gpio-cells = <3>; + }; + + vibrate { + gpios = <&gpio 0 1 0>; /* Bank 0, Pin 1, No flags */ + }; diff --git a/Documentation/devicetree/bindings/gpio/led.txt b/Documentation/devicetree/bindings/gpio/led.txt index 9bb308abd221..edc83c1c0d54 100644 --- a/Documentation/devicetree/bindings/gpio/led.txt +++ b/Documentation/devicetree/bindings/gpio/led.txt @@ -8,7 +8,7 @@ node's name represents the name of the corresponding LED. LED sub-node properties: - gpios : Should specify the LED's GPIO, see "gpios property" in - Documentation/devicetree/gpio.txt. Active low LEDs should be + Documentation/devicetree/bindings/gpio/gpio.txt. Active low LEDs should be indicated using flags in the GPIO specifier. - label : (optional) The label for this LED. If omitted, the label is taken from the node name (excluding the unit address). diff --git a/Documentation/devicetree/bindings/i2c/trivial-devices.txt b/Documentation/devicetree/bindings/i2c/trivial-devices.txt index 1a85f986961b..2f5322b119eb 100644 --- a/Documentation/devicetree/bindings/i2c/trivial-devices.txt +++ b/Documentation/devicetree/bindings/i2c/trivial-devices.txt @@ -56,3 +56,4 @@ stm,m41t00 Serial Access TIMEKEEPER stm,m41t62 Serial real-time clock (RTC) with alarm stm,m41t80 M41T80 - SERIAL ACCESS RTC WITH ALARMS ti,tsc2003 I2C Touch-Screen Controller +ti,tmp102 Low Power Digital Temperature Sensor with SMBUS/Two Wire Serial Interface diff --git a/Documentation/devicetree/bindings/input/gpio-keys-polled.txt b/Documentation/devicetree/bindings/input/gpio-keys-polled.txt new file mode 100644 index 000000000000..313abefa37cc --- /dev/null +++ b/Documentation/devicetree/bindings/input/gpio-keys-polled.txt @@ -0,0 +1,38 @@ +Device-Tree bindings for input/gpio_keys_polled.c keyboard driver + +Required properties: + - compatible = "gpio-keys-polled"; + - poll-interval: Poll interval time in milliseconds + +Optional properties: + - autorepeat: Boolean, Enable auto repeat feature of Linux input + subsystem. + +Each button (key) is represented as a sub-node of "gpio-keys-polled": +Subnode properties: + + - gpios: OF device-tree gpio specification. + - label: Descriptive name of the key. + - linux,code: Keycode to emit. + +Optional subnode-properties: + - linux,input-type: Specify event type this button/key generates. + If not specified defaults to <1> == EV_KEY. + - debounce-interval: Debouncing interval time in milliseconds. + If not specified defaults to 5. + - gpio-key,wakeup: Boolean, button can wake-up the system. + +Example nodes: + + gpio_keys_polled { + compatible = "gpio-keys-polled"; + #address-cells = <1>; + #size-cells = <0>; + poll-interval = <100>; + autorepeat; + button@21 { + label = "GPIO Key UP"; + linux,code = <103>; + gpios = <&gpio1 0 1>; + }; + ... diff --git a/Documentation/devicetree/bindings/input/rotary-encoder.txt b/Documentation/devicetree/bindings/input/rotary-encoder.txt new file mode 100644 index 000000000000..331549593ed5 --- /dev/null +++ b/Documentation/devicetree/bindings/input/rotary-encoder.txt @@ -0,0 +1,36 @@ +Rotary encoder DT bindings + +Required properties: +- gpios: a spec for two GPIOs to be used + +Optional properties: +- linux,axis: the input subsystem axis to map to this rotary encoder. + Defaults to 0 (ABS_X / REL_X) +- rotary-encoder,steps: Number of steps in a full turnaround of the + encoder. Only relevant for absolute axis. Defaults to 24 which is a + typical value for such devices. +- rotary-encoder,relative-axis: register a relative axis rather than an + absolute one. Relative axis will only generate +1/-1 events on the input + device, hence no steps need to be passed. +- rotary-encoder,rollover: Automatic rollove when the rotary value becomes + greater than the specified steps or smaller than 0. For absolute axis only. +- rotary-encoder,half-period: Makes the driver work on half-period mode. + +See Documentation/input/rotary-encoder.txt for more information. + +Example: + + rotary@0 { + compatible = "rotary-encoder"; + gpios = <&gpio 19 1>, <&gpio 20 0>; /* GPIO19 is inverted */ + linux,axis = <0>; /* REL_X */ + rotary-encoder,relative-axis; + }; + + rotary@1 { + compatible = "rotary-encoder"; + gpios = <&gpio 21 0>, <&gpio 22 0>; + linux,axis = <1>; /* ABS_Y */ + rotary-encoder,steps = <24>; + rotary-encoder,rollover; + }; diff --git a/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt new file mode 100644 index 000000000000..548892c08c59 --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/brcm,bcm2835-armctrl-ic.txt @@ -0,0 +1,110 @@ +BCM2835 Top-Level ("ARMCTRL") Interrupt Controller + +The BCM2835 contains a custom top-level interrupt controller, which supports +72 interrupt sources using a 2-level register scheme. The interrupt +controller, or the HW block containing it, is referred to occasionally +as "armctrl" in the SoC documentation, hence naming of this binding. + +Required properties: + +- compatible : should be "brcm,bcm2835-armctrl-ic.txt" +- reg : Specifies base physical address and size of the registers. +- interrupt-controller : Identifies the node as an interrupt controller +- #interrupt-cells : Specifies the number of cells needed to encode an + interrupt source. The value shall be 2. + + The 1st cell is the interrupt bank; 0 for interrupts in the "IRQ basic + pending" register, or 1/2 respectively for interrupts in the "IRQ pending + 1/2" register. + + The 2nd cell contains the interrupt number within the bank. Valid values + are 0..7 for bank 0, and 0..31 for bank 1. + +The interrupt sources are as follows: + +Bank 0: +0: ARM_TIMER +1: ARM_MAILBOX +2: ARM_DOORBELL_0 +3: ARM_DOORBELL_1 +4: VPU0_HALTED +5: VPU1_HALTED +6: ILLEGAL_TYPE0 +7: ILLEGAL_TYPE1 + +Bank 1: +0: TIMER0 +1: TIMER1 +2: TIMER2 +3: TIMER3 +4: CODEC0 +5: CODEC1 +6: CODEC2 +7: VC_JPEG +8: ISP +9: VC_USB +10: VC_3D +11: TRANSPOSER +12: MULTICORESYNC0 +13: MULTICORESYNC1 +14: MULTICORESYNC2 +15: MULTICORESYNC3 +16: DMA0 +17: DMA1 +18: VC_DMA2 +19: VC_DMA3 +20: DMA4 +21: DMA5 +22: DMA6 +23: DMA7 +24: DMA8 +25: DMA9 +26: DMA10 +27: DMA11 +28: DMA12 +29: AUX +30: ARM +31: VPUDMA + +Bank 2: +0: HOSTPORT +1: VIDEOSCALER +2: CCP2TX +3: SDC +4: DSI0 +5: AVE +6: CAM0 +7: CAM1 +8: HDMI0 +9: HDMI1 +10: PIXELVALVE1 +11: I2CSPISLV +12: DSI1 +13: PWA0 +14: PWA1 +15: CPR +16: SMI +17: GPIO0 +18: GPIO1 +19: GPIO2 +20: GPIO3 +21: VC_I2C +22: VC_SPI +23: VC_I2SPCM +24: VC_SDIO +25: VC_UART +26: SLIMBUS +27: VEC +28: CPG +29: RNG +30: VC_ARASANSDIO +31: AVSPMON + +Example: + +intc: interrupt-controller { + compatible = "brcm,bcm2835-armctrl-ic"; + reg = <0x7e00b200 0x200>; + interrupt-controller; + #interrupt-cells = <2>; +}; diff --git a/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt new file mode 100644 index 000000000000..72a06c0ab1db --- /dev/null +++ b/Documentation/devicetree/bindings/interrupt-controller/interrupts.txt @@ -0,0 +1,95 @@ +Specifying interrupt information for devices +============================================ + +1) Interrupt client nodes +------------------------- + +Nodes that describe devices which generate interrupts must contain an +"interrupts" property. This property must contain a list of interrupt +specifiers, one per output interrupt. The format of the interrupt specifier is +determined by the interrupt controller to which the interrupts are routed; see +section 2 below for details. + +The "interrupt-parent" property is used to specify the controller to which +interrupts are routed and contains a single phandle referring to the interrupt +controller node. This property is inherited, so it may be specified in an +interrupt client node or in any of its parent nodes. + +2) Interrupt controller nodes +----------------------------- + +A device is marked as an interrupt controller with the "interrupt-controller" +property. This is a empty, boolean property. An additional "#interrupt-cells" +property defines the number of cells needed to specify a single interrupt. + +It is the responsibility of the interrupt controller's binding to define the +length and format of the interrupt specifier. The following two variants are +commonly used: + + a) one cell + ----------- + The #interrupt-cells property is set to 1 and the single cell defines the + index of the interrupt within the controller. + + Example: + + vic: intc@10140000 { + compatible = "arm,versatile-vic"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x10140000 0x1000>; + }; + + sic: intc@10003000 { + compatible = "arm,versatile-sic"; + interrupt-controller; + #interrupt-cells = <1>; + reg = <0x10003000 0x1000>; + interrupt-parent = <&vic>; + interrupts = <31>; /* Cascaded to vic */ + }; + + b) two cells + ------------ + The #interrupt-cells property is set to 2 and the first cell defines the + index of the interrupt within the controller, while the second cell is used + to specify any of the following flags: + - bits[3:0] trigger type and level flags + 1 = low-to-high edge triggered + 2 = high-to-low edge triggered + 4 = active high level-sensitive + 8 = active low level-sensitive + + Example: + + i2c@7000c000 { + gpioext: gpio-adnp@41 { + compatible = "ad,gpio-adnp"; + reg = <0x41>; + + interrupt-parent = <&gpio>; + interrupts = <160 1>; + + gpio-controller; + #gpio-cells = <1>; + + interrupt-controller; + #interrupt-cells = <2>; + + nr-gpios = <64>; + }; + + sx8634@2b { + compatible = "smtc,sx8634"; + reg = <0x2b>; + + interrupt-parent = <&gpioext>; + interrupts = <3 0x8>; + + #address-cells = <1>; + #size-cells = <0>; + + threshold = <0x40>; + sensitivity = <7>; + }; + }; diff --git a/Documentation/devicetree/bindings/lpddr2/lpddr2-timings.txt b/Documentation/devicetree/bindings/lpddr2/lpddr2-timings.txt new file mode 100644 index 000000000000..9ceb19e0c7fd --- /dev/null +++ b/Documentation/devicetree/bindings/lpddr2/lpddr2-timings.txt @@ -0,0 +1,52 @@ +* AC timing parameters of LPDDR2(JESD209-2) memories for a given speed-bin + +Required properties: +- compatible : Should be "jedec,lpddr2-timings" +- min-freq : minimum DDR clock frequency for the speed-bin. Type is <u32> +- max-freq : maximum DDR clock frequency for the speed-bin. Type is <u32> + +Optional properties: + +The following properties represent AC timing parameters from the memory +data-sheet of the device for a given speed-bin. All these properties are +of type <u32> and the default unit is ps (pico seconds). Parameters with +a different unit have a suffix indicating the unit such as 'tRAS-max-ns' +- tRCD +- tWR +- tRAS-min +- tRRD +- tWTR +- tXP +- tRTP +- tDQSCK-max +- tFAW +- tZQCS +- tZQinit +- tRPab +- tZQCL +- tCKESR +- tRAS-max-ns +- tDQSCK-max-derated + +Example: + +timings_elpida_ECB240ABACN_400mhz: lpddr2-timings@0 { + compatible = "jedec,lpddr2-timings"; + min-freq = <10000000>; + max-freq = <400000000>; + tRPab = <21000>; + tRCD = <18000>; + tWR = <15000>; + tRAS-min = <42000>; + tRRD = <10000>; + tWTR = <7500>; + tXP = <7500>; + tRTP = <7500>; + tCKESR = <15000>; + tDQSCK-max = <5500>; + tFAW = <50000>; + tZQCS = <90000>; + tZQCL = <360000>; + tZQinit = <1000000>; + tRAS-max-ns = <70000>; +}; diff --git a/Documentation/devicetree/bindings/lpddr2/lpddr2.txt b/Documentation/devicetree/bindings/lpddr2/lpddr2.txt new file mode 100644 index 000000000000..58354a075e13 --- /dev/null +++ b/Documentation/devicetree/bindings/lpddr2/lpddr2.txt @@ -0,0 +1,102 @@ +* LPDDR2 SDRAM memories compliant to JEDEC JESD209-2 + +Required properties: +- compatible : Should be one of - "jedec,lpddr2-nvm", "jedec,lpddr2-s2", + "jedec,lpddr2-s4" + + "ti,jedec-lpddr2-s2" should be listed if the memory part is LPDDR2-S2 type + + "ti,jedec-lpddr2-s4" should be listed if the memory part is LPDDR2-S4 type + + "ti,jedec-lpddr2-nvm" should be listed if the memory part is LPDDR2-NVM type + +- density : <u32> representing density in Mb (Mega bits) + +- io-width : <u32> representing bus width. Possible values are 8, 16, and 32 + +Optional properties: + +The following optional properties represent the minimum value of some AC +timing parameters of the DDR device in terms of number of clock cycles. +These values shall be obtained from the device data-sheet. +- tRRD-min-tck +- tWTR-min-tck +- tXP-min-tck +- tRTP-min-tck +- tCKE-min-tck +- tRPab-min-tck +- tRCD-min-tck +- tWR-min-tck +- tRASmin-min-tck +- tCKESR-min-tck +- tFAW-min-tck + +Child nodes: +- The lpddr2 node may have one or more child nodes of type "lpddr2-timings". + "lpddr2-timings" provides AC timing parameters of the device for + a given speed-bin. The user may provide the timings for as many + speed-bins as is required. Please see Documentation/devicetree/ + bindings/lpddr2/lpddr2-timings.txt for more information on "lpddr2-timings" + +Example: + +elpida_ECB240ABACN : lpddr2 { + compatible = "Elpida,ECB240ABACN","jedec,lpddr2-s4"; + density = <2048>; + io-width = <32>; + + tRPab-min-tck = <3>; + tRCD-min-tck = <3>; + tWR-min-tck = <3>; + tRASmin-min-tck = <3>; + tRRD-min-tck = <2>; + tWTR-min-tck = <2>; + tXP-min-tck = <2>; + tRTP-min-tck = <2>; + tCKE-min-tck = <3>; + tCKESR-min-tck = <3>; + tFAW-min-tck = <8>; + + timings_elpida_ECB240ABACN_400mhz: lpddr2-timings@0 { + compatible = "jedec,lpddr2-timings"; + min-freq = <10000000>; + max-freq = <400000000>; + tRPab = <21000>; + tRCD = <18000>; + tWR = <15000>; + tRAS-min = <42000>; + tRRD = <10000>; + tWTR = <7500>; + tXP = <7500>; + tRTP = <7500>; + tCKESR = <15000>; + tDQSCK-max = <5500>; + tFAW = <50000>; + tZQCS = <90000>; + tZQCL = <360000>; + tZQinit = <1000000>; + tRAS-max-ns = <70000>; + }; + + timings_elpida_ECB240ABACN_200mhz: lpddr2-timings@1 { + compatible = "jedec,lpddr2-timings"; + min-freq = <10000000>; + max-freq = <200000000>; + tRPab = <21000>; + tRCD = <18000>; + tWR = <15000>; + tRAS-min = <42000>; + tRRD = <10000>; + tWTR = <10000>; + tXP = <7500>; + tRTP = <7500>; + tCKESR = <15000>; + tDQSCK-max = <5500>; + tFAW = <50000>; + tZQCS = <90000>; + tZQCL = <360000>; + tZQinit = <1000000>; + tRAS-max-ns = <70000>; + }; + +} diff --git a/Documentation/devicetree/bindings/media/exynos5-gsc.txt b/Documentation/devicetree/bindings/media/exynos5-gsc.txt new file mode 100644 index 000000000000..0604d42f38d1 --- /dev/null +++ b/Documentation/devicetree/bindings/media/exynos5-gsc.txt @@ -0,0 +1,30 @@ +* Samsung Exynos5 G-Scaler device + +G-Scaler is used for scaling and color space conversion on EXYNOS5 SoCs. + +Required properties: +- compatible: should be "samsung,exynos5-gsc" +- reg: should contain G-Scaler physical address location and length. +- interrupts: should contain G-Scaler interrupt number + +Example: + +gsc_0: gsc@0x13e00000 { + compatible = "samsung,exynos5-gsc"; + reg = <0x13e00000 0x1000>; + interrupts = <0 85 0>; +}; + +Aliases: +Each G-Scaler node should have a numbered alias in the aliases node, +in the form of gscN, N = 0...3. G-Scaler driver uses these aliases +to retrieve the device IDs using "of_alias_get_id()" call. + +Example: + +aliases { + gsc0 =&gsc_0; + gsc1 =&gsc_1; + gsc2 =&gsc_2; + gsc3 =&gsc_3; +}; diff --git a/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt new file mode 100644 index 000000000000..938f8e1ba205 --- /dev/null +++ b/Documentation/devicetree/bindings/memory-controllers/ti/emif.txt @@ -0,0 +1,55 @@ +* EMIF family of TI SDRAM controllers + +EMIF - External Memory Interface - is an SDRAM controller used in +TI SoCs. EMIF supports, based on the IP revision, one or more of +DDR2/DDR3/LPDDR2 protocols. This binding describes a given instance +of the EMIF IP and memory parts attached to it. + +Required properties: +- compatible : Should be of the form "ti,emif-<ip-rev>" where <ip-rev> + is the IP revision of the specific EMIF instance. + +- phy-type : <u32> indicating the DDR phy type. Following are the + allowed values + <1> : Attila PHY + <2> : Intelli PHY + +- device-handle : phandle to a "lpddr2" node representing the memory part + +- ti,hwmods : For TI hwmods processing and omap device creation + the value shall be "emif<n>" where <n> is the number of the EMIF + instance with base 1. + +Optional properties: +- cs1-used : Have this property if CS1 of this EMIF + instance has a memory part attached to it. If there is a memory + part attached to CS1, it should be the same type as the one on CS0, + so there is no need to give the details of this memory part. + +- cal-resistor-per-cs : Have this property if the board has one + calibration resistor per chip-select. + +- hw-caps-read-idle-ctrl: Have this property if the controller + supports read idle window programming + +- hw-caps-dll-calib-ctrl: Have this property if the controller + supports dll calibration control + +- hw-caps-ll-interface : Have this property if the controller + has a low latency interface and corresponding interrupt events + +- hw-caps-temp-alert : Have this property if the controller + has capability for generating SDRAM temperature alerts + +Example: + +emif1: emif@0x4c000000 { + compatible = "ti,emif-4d"; + ti,hwmods = "emif2"; + phy-type = <1>; + device-handle = <&elpida_ECB240ABACN>; + cs1-used; + hw-caps-read-idle-ctrl; + hw-caps-ll-interface; + hw-caps-temp-alert; +}; diff --git a/Documentation/devicetree/bindings/mfd/88pm860x.txt b/Documentation/devicetree/bindings/mfd/88pm860x.txt new file mode 100644 index 000000000000..63f3ee33759c --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/88pm860x.txt @@ -0,0 +1,85 @@ +* Marvell 88PM860x Power Management IC + +Required parent device properties: +- compatible : "marvell,88pm860x" +- reg : the I2C slave address for the 88pm860x chip +- interrupts : IRQ line for the 88pm860x chip +- interrupt-controller: describes the 88pm860x as an interrupt controller (has its own domain) +- #interrupt-cells : should be 1. + - The cell is the 88pm860x local IRQ number + +Optional parent device properties: +- marvell,88pm860x-irq-read-clr: inicates whether interrupt status is cleared by read +- marvell,88pm860x-slave-addr: 88pm860x are two chips solution. <reg> stores the I2C address + of one chip, and this property stores the I2C address of + another chip. + +88pm860x consists of a large and varied group of sub-devices: + +Device Supply Names Description +------ ------------ ----------- +88pm860x-onkey : : On key +88pm860x-rtc : : RTC +88pm8607 : : Regulators +88pm860x-backlight : : Backlight +88pm860x-led : : Led +88pm860x-touch : : Touchscreen + +Example: + + pmic: 88pm860x@34 { + compatible = "marvell,88pm860x"; + reg = <0x34>; + interrupts = <4>; + interrupt-parent = <&intc>; + interrupt-controller; + #interrupt-cells = <1>; + + marvell,88pm860x-irq-read-clr; + marvell,88pm860x-slave-addr = <0x11>; + + regulators { + BUCK1 { + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1500000>; + regulator-boot-on; + regulator-always-on; + }; + LDO1 { + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <2800000>; + regulator-boot-on; + regulator-always-on; + }; + }; + rtc { + marvell,88pm860x-vrtc = <1>; + }; + touch { + marvell,88pm860x-gpadc-prebias = <1>; + marvell,88pm860x-gpadc-slot-cycle = <1>; + marvell,88pm860x-tsi-prebias = <6>; + marvell,88pm860x-pen-prebias = <16>; + marvell,88pm860x-pen-prechg = <2>; + marvell,88pm860x-resistor-X = <300>; + }; + backlights { + backlight-0 { + marvell,88pm860x-iset = <4>; + marvell,88pm860x-pwm = <3>; + }; + backlight-2 { + }; + }; + leds { + led0-red { + marvell,88pm860x-iset = <12>; + }; + led0-green { + marvell,88pm860x-iset = <12>; + }; + led0-blue { + marvell,88pm860x-iset = <12>; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/mfd/ab8500.txt b/Documentation/devicetree/bindings/mfd/ab8500.txt index 69e757a657a0..ce83c8d3c00e 100644 --- a/Documentation/devicetree/bindings/mfd/ab8500.txt +++ b/Documentation/devicetree/bindings/mfd/ab8500.txt @@ -23,6 +23,7 @@ Device IRQ Names Supply Names Description ab8500-bm : : : Battery Manager ab8500-btemp : : : Battery Temperature ab8500-charger : : : Battery Charger +ab8500-codec : : : Audio Codec ab8500-fg : : : Fuel Gauge ab8500-gpadc : HW_CONV_END : vddadc : Analogue to Digital Converter SW_CONV_END : : @@ -52,6 +53,14 @@ Optional child device properties: supplied in the interrupts property - <supply_name>-supply : contains a phandle to the regulator supply node in Device Tree +Non-standard child device properties: + - Audio CODEC: + - stericsson,amic[1|2]-type-single-ended : Single-ended Analoge Mic (default: differential) + - stericsson,amic1a-bias-vamic2 : Analoge Mic wishes to use a non-standard Vamic + - stericsson,amic1b-bias-vamic2 : Analoge Mic wishes to use a non-standard Vamic + - stericsson,amic2-bias-vamic1 : Analoge Mic wishes to use a non-standard Vamic + - stericsson,earpeice-cmv : Earpeice voltage (only: 950 | 1100 | 1270 | 1580) + ab8500@5 { compatible = "stericsson,ab8500"; reg = <5>; /* mailbox 5 is i2c */ @@ -110,6 +119,12 @@ ab8500@5 { compatible = "stericsson,ab8500-pwm"; }; + codec: ab8500-codec { + compatible = "stericsson,ab8500-codec"; + + stericsson,earpeice-cmv = <950>; /* Units in mV. */ + }; + ab8500-regulators { compatible = "stericsson,ab8500-regulator"; diff --git a/Documentation/devicetree/bindings/mfd/syscon.txt b/Documentation/devicetree/bindings/mfd/syscon.txt new file mode 100644 index 000000000000..fe8150bb3248 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/syscon.txt @@ -0,0 +1,20 @@ +* System Controller Registers R/W driver + +System controller node represents a register region containing a set +of miscellaneous registers. The registers are not cohesive enough to +represent as any specific type of device. The typical use-case is for +some other node's driver, or platform-specific code, to acquire a +reference to the syscon node (e.g. by phandle, node path, or search +using a specific compatible value), interrogate the node (or associated +OS driver) to determine the location of the registers, and access the +registers directly. + +Required properties: +- compatible: Should contain "syscon". +- reg: the register region can be accessed from syscon + +Examples: +gpr: iomuxc-gpr@020e0000 { + compatible = "fsl,imx6q-iomuxc-gpr", "syscon"; + reg = <0x020e0000 0x38>; +}; diff --git a/Documentation/devicetree/bindings/mfd/tps65910.txt b/Documentation/devicetree/bindings/mfd/tps65910.txt index db03599ae4dc..2e3304888ffc 100644 --- a/Documentation/devicetree/bindings/mfd/tps65910.txt +++ b/Documentation/devicetree/bindings/mfd/tps65910.txt @@ -59,6 +59,8 @@ Optional properties: in TPS6591X datasheet) - ti,en-gpio-sleep: enable sleep control for gpios There should be 9 entries here, one for each gpio. +- ti,system-power-controller: Telling whether or not this pmic is controlling + the system power. Regulator Optional properties: - ti,regulator-ext-sleep-control: enable external sleep @@ -79,6 +81,8 @@ Example: #interrupt-cells = <2>; interrupt-controller; + ti,system-power-controller; + ti,vmbch-threshold = 0; ti,vmbch2-threshold = 0; ti,en-ck32k-xtal; diff --git a/Documentation/devicetree/bindings/mfd/twl4030-audio.txt b/Documentation/devicetree/bindings/mfd/twl4030-audio.txt new file mode 100644 index 000000000000..414d2ae0adf6 --- /dev/null +++ b/Documentation/devicetree/bindings/mfd/twl4030-audio.txt @@ -0,0 +1,46 @@ +Texas Instruments TWL family (twl4030) audio module + +The audio module inside the TWL family consist of an audio codec and a vibra +driver. + +Required properties: +- compatible : must be "ti,twl4030-audio" + +Optional properties, nodes: + +Audio functionality: +- codec { }: Need to be present if the audio functionality is used. Within this + section the following options can be used: +- ti,digimic_delay: Delay need after enabling the digimic to reduce artifacts + from the start of the recorded sample (in ms) +-ti,ramp_delay_value: HS ramp delay configuration to reduce pop noise +-ti,hs_extmute: Use external mute for HS pop reduction +-ti,hs_extmute_gpio: Use external GPIO to control the external mute +-ti,offset_cncl_path: Offset cancellation path selection, refer to TRM for the + valid values. + +Vibra functionality +- ti,enable-vibra: Need to be set to <1> if the vibra functionality is used. if + missing or it is 0, the vibra functionality is disabled. + +Example: +&i2c1 { + clock-frequency = <2600000>; + + twl: twl@48 { + reg = <0x48>; + interrupts = <7>; /* SYS_NIRQ cascaded to intc */ + interrupt-parent = <&intc>; + + twl_audio: audio { + compatible = "ti,twl4030-audio"; + + ti,enable-vibra = <1>; + + codec { + ti,ramp_delay_value = <3>; + }; + + }; + }; +}; diff --git a/Documentation/devicetree/bindings/mfd/twl6040.txt b/Documentation/devicetree/bindings/mfd/twl6040.txt index c855240f3a0e..0f5dd709d752 100644 --- a/Documentation/devicetree/bindings/mfd/twl6040.txt +++ b/Documentation/devicetree/bindings/mfd/twl6040.txt @@ -1,7 +1,7 @@ Texas Instruments TWL6040 family -The TWL6040s are 8-channel high quality low-power audio codecs providing audio -and vibra functionality on OMAP4+ platforms. +The TWL6040s are 8-channel high quality low-power audio codecs providing audio, +vibra and GPO functionality on OMAP4+ platforms. They are connected ot the host processor via i2c for commands, McPDM for audio data and commands. @@ -10,6 +10,8 @@ Required properties: - reg: must be 0x4b for i2c address - interrupts: twl6040 has one interrupt line connecteded to the main SoC - interrupt-parent: The parent interrupt controller +- gpio-controller: +- #gpio-cells = <1>: twl6040 provides GPO lines. - twl6040,audpwron-gpio: Power on GPIO line for the twl6040 - vio-supply: Regulator for the twl6040 VIO supply @@ -37,7 +39,6 @@ Example: &i2c1 { twl6040: twl@4b { compatible = "ti,twl6040"; - reg = <0x4b>; interrupts = <0 119 4>; interrupt-parent = <&gic>; @@ -60,3 +61,5 @@ Example: }; }; }; + +/include/ "twl6040.dtsi" diff --git a/Documentation/devicetree/bindings/misc/at25.txt b/Documentation/devicetree/bindings/misc/at25.txt index ab3c327929dd..1d3447165c37 100644 --- a/Documentation/devicetree/bindings/misc/at25.txt +++ b/Documentation/devicetree/bindings/misc/at25.txt @@ -1,21 +1,35 @@ -Atmel AT25 eeprom +EEPROMs (SPI) compatible with Atmel at25. Required properties: - compatible : "atmel,at25". - reg : chip select number - spi-max-frequency : max spi frequency to use +- pagesize : size of the eeprom page +- size : total eeprom size in bytes +- address-width : number of address bits (one of 8, 16, or 24) +Optional properties: +- spi-cpha : SPI shifted clock phase, as per spi-bus bindings. +- spi-cpol : SPI inverse clock polarity, as per spi-bus bindings. +- read-only : this parameter-less property disables writes to the eeprom + +Obsolete legacy properties are can be used in place of "size", "pagesize", +"address-width", and "read-only": - at25,byte-len : total eeprom size in bytes - at25,addr-mode : addr-mode flags, as defined in include/linux/spi/eeprom.h - at25,page-size : size of the eeprom page -Examples: -at25@0 { - compatible = "atmel,at25"; - reg = <0> - spi-max-frequency = <5000000>; +Additional compatible properties are also allowed. + +Example: + at25@0 { + compatible = "atmel,at25", "st,m95256"; + reg = <0> + spi-max-frequency = <5000000>; + spi-cpha; + spi-cpol; - at25,byte-len = <0x8000>; - at25,addr-mode = <2>; - at25,page-size = <64>; -}; + pagesize = <64>; + size = <32768>; + address-width = <16>; + }; diff --git a/Documentation/devicetree/bindings/misc/ifm-csi.txt b/Documentation/devicetree/bindings/misc/ifm-csi.txt new file mode 100644 index 000000000000..5bdfffb0b9f7 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/ifm-csi.txt @@ -0,0 +1,41 @@ +IFM camera sensor interface on mpc5200 LocalPlus bus + +Required properties: +- compatible: "ifm,o2d-csi" +- reg: specifies sensor chip select number and associated address range +- interrupts: external interrupt line number and interrupt sense mode + of the interrupt line signaling frame valid events +- gpios: three gpio-specifiers for "capture", "reset" and "master enable" + GPIOs (strictly in this order). +- ifm,csi-clk-handle: the phandle to a node in the DT describing the sensor + clock generator. This node is usually a general purpose timer controller. +- ifm,csi-addr-bus-width: address bus width (valid values are 16, 24, 25) +- ifm,csi-data-bus-width: data bus width (valid values are 8 and 16) +- ifm,csi-wait-cycles: sensor bus wait cycles + +Optional properties: +- ifm,csi-byte-swap: if this property is present, the byte swapping on + the bus will be enabled. + +Example: + + csi@3,0 { + compatible = "ifm,o2d-csi"; + reg = <3 0 0x00100000>; /* CS 3, 1 MiB range */ + interrupts = <1 1 2>; /* IRQ1, edge falling */ + + ifm,csi-clk-handle = <&timer7>; + gpios = <&gpio_simple 23 0 /* image_capture */ + &gpio_simple 26 0 /* image_reset */ + &gpio_simple 29 0>; /* image_master_en */ + + ifm,csi-addr-bus-width = <24>; + ifm,csi-data-bus-width = <8>; + ifm,csi-wait-cycles = <0>; + }; + +The base address of the used chip select is specified in the +ranges property of the parent localbus node, for example: + + ranges = <0 0 0xff000000 0x01000000 + 3 0 0xe3000000 0x00100000>; diff --git a/Documentation/devicetree/bindings/misc/lis302.txt b/Documentation/devicetree/bindings/misc/lis302.txt new file mode 100644 index 000000000000..6def86f6b053 --- /dev/null +++ b/Documentation/devicetree/bindings/misc/lis302.txt @@ -0,0 +1,112 @@ +LIS302 accelerometer devicetree bindings + +This device is matched via its bus drivers, and has a number of properties +that apply in on the generic device (independent from the bus). + + +Required properties for the SPI bindings: + - compatible: should be set to "st,lis3lv02d_spi" + - reg: the chipselect index + - spi-max-frequency: maximal bus speed, should be set to 1000000 unless + constrained by external circuitry + - interrupts: the interrupt generated by the device + +Required properties for the I2C bindings: + - compatible: should be set to "st,lis3lv02d" + - reg: i2c slave address + - Vdd-supply: The input supply for Vdd + - Vdd_IO-supply: The input supply for Vdd_IO + + +Optional properties for all bus drivers: + + - st,click-single-{x,y,z}: if present, tells the device to issue an + interrupt on single click events on the + x/y/z axis. + - st,click-double-{x,y,z}: if present, tells the device to issue an + interrupt on double click events on the + x/y/z axis. + - st,click-thresh-{x,y,z}: set the x/y/z axis threshold + - st,click-click-time-limit: click time limit, from 0 to 127.5msec + with step of 0.5 msec + - st,click-latency: click latency, from 0 to 255 msec with + step of 1 msec. + - st,click-window: click window, from 0 to 255 msec with + step of 1 msec. + - st,irq{1,2}-disable: disable IRQ 1/2 + - st,irq{1,2}-ff-wu-1: raise IRQ 1/2 on FF_WU_1 condition + - st,irq{1,2}-ff-wu-2: raise IRQ 1/2 on FF_WU_2 condition + - st,irq{1,2}-data-ready: raise IRQ 1/2 on data ready contition + - st,irq{1,2}-click: raise IRQ 1/2 on click condition + - st,irq-open-drain: consider IRQ lines open-drain + - st,irq-active-low: make IRQ lines active low + - st,wu-duration-1: duration register for Free-Fall/Wake-Up + interrupt 1 + - st,wu-duration-2: duration register for Free-Fall/Wake-Up + interrupt 2 + - st,wakeup-{x,y,z}-{lo,hi}: set wakeup condition on x/y/z axis for + upper/lower limit + - st,highpass-cutoff-hz=: 1, 2, 4 or 8 for 1Hz, 2Hz, 4Hz or 8Hz of + highpass cut-off frequency + - st,hipass{1,2}-disable: disable highpass 1/2. + - st,default-rate=: set the default rate + - st,axis-{x,y,z}=: set the axis to map to the three coordinates + - st,{min,max}-limit-{x,y,z} set the min/max limits for x/y/z axis + (used by self-test) + + +Example for a SPI device node: + + lis302@0 { + compatible = "st,lis302dl-spi"; + reg = <0>; + spi-max-frequency = <1000000>; + interrupt-parent = <&gpio>; + interrupts = <104 0>; + + st,click-single-x; + st,click-single-y; + st,click-single-z; + st,click-thresh-x = <10>; + st,click-thresh-y = <10>; + st,click-thresh-z = <10>; + st,irq1-click; + st,irq2-click; + st,wakeup-x-lo; + st,wakeup-x-hi; + st,wakeup-y-lo; + st,wakeup-y-hi; + st,wakeup-z-lo; + st,wakeup-z-hi; + }; + +Example for a I2C device node: + + lis331dlh: lis331dlh@18 { + compatible = "st,lis331dlh", "st,lis3lv02d"; + reg = <0x18>; + Vdd-supply = <&lis3_reg>; + Vdd_IO-supply = <&lis3_reg>; + + st,click-single-x; + st,click-single-y; + st,click-single-z; + st,click-thresh-x = <10>; + st,click-thresh-y = <10>; + st,click-thresh-z = <10>; + st,irq1-click; + st,irq2-click; + st,wakeup-x-lo; + st,wakeup-x-hi; + st,wakeup-y-lo; + st,wakeup-y-hi; + st,wakeup-z-lo; + st,wakeup-z-hi; + st,min-limit-x = <120>; + st,min-limit-y = <120>; + st,min-limit-z = <140>; + st,max-limit-x = <550>; + st,max-limit-y = <550>; + st,max-limit-z = <750>; + }; + diff --git a/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt b/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt new file mode 100644 index 000000000000..0a85c70cd30a --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt @@ -0,0 +1,68 @@ +* Atmel High Speed MultiMedia Card Interface + +This controller on atmel products provides an interface for MMC, SD and SDIO +types of memory cards. + +This file documents differences between the core properties described +by mmc.txt and the properties used by the atmel-mci driver. + +1) MCI node + +Required properties: +- compatible: should be "atmel,hsmci" +- #address-cells: should be one. The cell is the slot id. +- #size-cells: should be zero. +- at least one slot node + +The node contains child nodes for each slot that the platform uses + +Example MCI node: + +mmc0: mmc@f0008000 { + compatible = "atmel,hsmci"; + reg = <0xf0008000 0x600>; + interrupts = <12 4>; + #address-cells = <1>; + #size-cells = <0>; + + [ child node definitions...] +}; + +2) slot nodes + +Required properties: +- reg: should contain the slot id. +- bus-width: number of data lines connected to the controller + +Optional properties: +- cd-gpios: specify GPIOs for card detection +- cd-inverted: invert the value of external card detect gpio line +- wp-gpios: specify GPIOs for write protection + +Example slot node: + +slot@0 { + reg = <0>; + bus-width = <4>; + cd-gpios = <&pioD 15 0> + cd-inverted; +}; + +Example full MCI node: +mmc0: mmc@f0008000 { + compatible = "atmel,hsmci"; + reg = <0xf0008000 0x600>; + interrupts = <12 4>; + #address-cells = <1>; + #size-cells = <0>; + slot@0 { + reg = <0>; + bus-width = <4>; + cd-gpios = <&pioD 15 0> + cd-inverted; + }; + slot@1 { + reg = <1>; + bus-width = <4>; + }; +}; diff --git a/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt new file mode 100644 index 000000000000..792768953330 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/exynos-dw-mshc.txt @@ -0,0 +1,87 @@ +* Samsung Exynos specific extensions to the Synopsis Designware Mobile + Storage Host Controller + +The Synopsis designware mobile storage host controller is used to interface +a SoC with storage medium such as eMMC or SD/MMC cards. This file documents +differences between the core Synopsis dw mshc controller properties described +by synposis-dw-mshc.txt and the properties used by the Samsung Exynos specific +extensions to the Synopsis Designware Mobile Storage Host Controller. + +Required Properties: + +* compatible: should be + - "samsung,exynos4210-dw-mshc": for controllers with Samsung Exynos4210 + specific extentions. + - "samsung,exynos4412-dw-mshc": for controllers with Samsung Exynos4412 + specific extentions. + - "samsung,exynos5250-dw-mshc": for controllers with Samsung Exynos5250 + specific extentions. + +* samsung,dw-mshc-ciu-div: Specifies the divider value for the card interface + unit (ciu) clock. This property is applicable only for Exynos5 SoC's and + ignored for Exynos4 SoC's. The valid range of divider value is 0 to 7. + +* samsung,dw-mshc-sdr-timing: Specifies the value of CIU clock phase shift value + in transmit mode and CIU clock phase shift value in receive mode for single + data rate mode operation. Refer notes below for the order of the cells and the + valid values. + +* samsung,dw-mshc-ddr-timing: Specifies the value of CUI clock phase shift value + in transmit mode and CIU clock phase shift value in receive mode for double + data rate mode operation. Refer notes below for the order of the cells and the + valid values. + + Notes for the sdr-timing and ddr-timing values: + + The order of the cells should be + - First Cell: CIU clock phase shift value for tx mode. + - Second Cell: CIU clock phase shift value for rx mode. + + Valid values for SDR and DDR CIU clock timing for Exynos5250: + - valid value for tx phase shift and rx phase shift is 0 to 7. + - when CIU clock divider value is set to 3, all possible 8 phase shift + values can be used. + - if CIU clock divider value is 0 (that is divide by 1), both tx and rx + phase shift clocks should be 0. + +Required properties for a slot: + +* gpios: specifies a list of gpios used for command, clock and data bus. The + first gpio is the command line and the second gpio is the clock line. The + rest of the gpios (depending on the bus-width property) are the data lines in + no particular order. The format of the gpio specifier depends on the gpio + controller. + +Example: + + The MSHC controller node can be split into two portions, SoC specific and + board specific portions as listed below. + + dwmmc0@12200000 { + compatible = "samsung,exynos5250-dw-mshc"; + reg = <0x12200000 0x1000>; + interrupts = <0 75 0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + dwmmc0@12200000 { + num-slots = <1>; + supports-highspeed; + broken-cd; + fifo-depth = <0x80>; + card-detect-delay = <200>; + samsung,dw-mshc-ciu-div = <3>; + samsung,dw-mshc-sdr-timing = <2 3>; + samsung,dw-mshc-ddr-timing = <1 2>; + + slot@0 { + reg = <0>; + bus-width = <8>; + gpios = <&gpc0 0 2 0 3>, <&gpc0 1 2 0 3>, + <&gpc1 0 2 3 3>, <&gpc1 1 2 3 3>, + <&gpc1 2 2 3 3>, <&gpc1 3 2 3 3>, + <&gpc0 3 2 3 3>, <&gpc0 4 2 3 3>, + <&gpc0 5 2 3 3>, <&gpc0 6 2 3 3>; + }; + }; diff --git a/Documentation/devicetree/bindings/mmc/mmc.txt b/Documentation/devicetree/bindings/mmc/mmc.txt index 8a6811f4a02f..8e2e0ba2f486 100644 --- a/Documentation/devicetree/bindings/mmc/mmc.txt +++ b/Documentation/devicetree/bindings/mmc/mmc.txt @@ -9,12 +9,17 @@ Interpreted by the OF core: Required properties: - bus-width: Number of data lines, can be <1>, <4>, or <8> +Card detection: +If no property below is supplied, standard SDHCI card detect is used. +Only one of the properties in this section should be supplied: + - broken-cd: There is no card detection available; polling must be used. + - cd-gpios: Specify GPIOs for card detection, see gpio binding + - non-removable: non-removable slot (like eMMC); assume always present. + Optional properties: -- cd-gpios: Specify GPIOs for card detection, see gpio binding - wp-gpios: Specify GPIOs for write protection, see gpio binding - cd-inverted: when present, polarity on the cd gpio line is inverted - wp-inverted: when present, polarity on the wp gpio line is inverted -- non-removable: non-removable slot (like eMMC) - max-frequency: maximum operating clock frequency Example: diff --git a/Documentation/devicetree/bindings/mmc/pxa-mmc.txt b/Documentation/devicetree/bindings/mmc/pxa-mmc.txt new file mode 100644 index 000000000000..b7025de7dced --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/pxa-mmc.txt @@ -0,0 +1,25 @@ +* PXA MMC drivers + +Driver bindings for the PXA MCI (MMC/SDIO) interfaces + +Required properties: +- compatible: Should be "marvell,pxa-mmc". +- vmmc-supply: A regulator for VMMC + +Optional properties: +- marvell,detect-delay-ms: sets the detection delay timeout in ms. +- marvell,gpio-power: GPIO spec for the card power enable pin + +This file documents differences between the core properties in mmc.txt +and the properties used by the pxa-mmc driver. + +Examples: + +mmc0: mmc@41100000 { + compatible = "marvell,pxa-mmc"; + reg = <0x41100000 0x1000>; + interrupts = <23>; + cd-gpios = <&gpio 23 0>; + wp-gpios = <&gpio 24 0>; +}; + diff --git a/Documentation/devicetree/bindings/mmc/samsung-sdhci.txt b/Documentation/devicetree/bindings/mmc/samsung-sdhci.txt new file mode 100644 index 000000000000..630a7d7f4718 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/samsung-sdhci.txt @@ -0,0 +1,53 @@ +* Samsung's SDHCI Controller device tree bindings + +Samsung's SDHCI controller is used as a connectivity interface with external +MMC, SD and eMMC storage mediums. This file documents differences between the +core mmc properties described by mmc.txt and the properties used by the +Samsung implmentation of the SDHCI controller. + +Note: The mmc core bindings documentation states that if none of the core +card-detect bindings are used, then the standard sdhci card detect mechanism +is used. The Samsung's SDHCI controller bindings extends this as listed below. + +[A] The property "samsung,cd-pinmux-gpio" can be used as stated in the + "Optional Board Specific Properties" section below. + +[B] If core card-detect bindings and "samsung,cd-pinmux-gpio" property + is not specified, it is assumed that there is no card detection + mechanism used. + +Required SoC Specific Properties: +- compatible: should be one of the following + - "samsung,s3c6410-sdhci": For controllers compatible with s3c6410 sdhci + controller. + - "samsung,exynos4210-sdhci": For controllers compatible with Exynos4 sdhci + controller. + +Required Board Specific Properties: +- gpios: Should specify the gpios used for clock, command and data lines. The + gpio specifier format depends on the gpio controller. + +Optional Board Specific Properties: +- samsung,cd-pinmux-gpio: Specifies the card detect line that is routed + through a pinmux to the card-detect pin of the card slot. This property + should be used only if none of the mmc core card-detect properties are + used. + +Example: + sdhci@12530000 { + compatible = "samsung,exynos4210-sdhci"; + reg = <0x12530000 0x100>; + interrupts = <0 75 0>; + bus-width = <4>; + cd-gpios = <&gpk2 2 2 3 3>; + gpios = <&gpk2 0 2 0 3>, /* clock line */ + <&gpk2 1 2 0 3>, /* command line */ + <&gpk2 3 2 3 3>, /* data line 0 */ + <&gpk2 4 2 3 3>, /* data line 1 */ + <&gpk2 5 2 3 3>, /* data line 2 */ + <&gpk2 6 2 3 3>; /* data line 3 */ + }; + + Note: This example shows both SoC specific and board specific properties + in a single device node. The properties can be actually be seperated + into SoC specific node and board specific node. diff --git a/Documentation/devicetree/bindings/mmc/sdhci-dove.txt b/Documentation/devicetree/bindings/mmc/sdhci-dove.txt new file mode 100644 index 000000000000..ae9aab9abcd7 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/sdhci-dove.txt @@ -0,0 +1,14 @@ +* Marvell sdhci-dove controller + +This file documents differences between the core properties in mmc.txt +and the properties used by the sdhci-pxav2 and sdhci-pxav3 drivers. + +- compatible: Should be "marvell,dove-sdhci". + +Example: + +sdio0: sdio@92000 { + compatible = "marvell,dove-sdhci"; + reg = <0x92000 0x100>; + interrupts = <35>; +}; diff --git a/Documentation/devicetree/bindings/mmc/sdhci-spear.txt b/Documentation/devicetree/bindings/mmc/sdhci-spear.txt new file mode 100644 index 000000000000..fd3643e7e467 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/sdhci-spear.txt @@ -0,0 +1,18 @@ +* SPEAr SDHCI Controller + +This file documents differences between the core properties in mmc.txt +and the properties used by the sdhci-spear driver. + +Required properties: +- compatible: "st,spear300-sdhci" + +Optional properties: +- cd-gpios: card detect gpio, with zero flags. + +Example: + + sdhci@fc000000 { + compatible = "st,spear300-sdhci"; + reg = <0xfc000000 0x1000>; + cd-gpios = <&gpio0 6 0>; + }; diff --git a/Documentation/devicetree/bindings/mmc/synposis-dw-mshc.txt b/Documentation/devicetree/bindings/mmc/synposis-dw-mshc.txt new file mode 100644 index 000000000000..06cd32d08052 --- /dev/null +++ b/Documentation/devicetree/bindings/mmc/synposis-dw-mshc.txt @@ -0,0 +1,79 @@ +* Synopsis Designware Mobile Storage Host Controller + +The Synopsis designware mobile storage host controller is used to interface +a SoC with storage medium such as eMMC or SD/MMC cards. This file documents +differences between the core mmc properties described by mmc.txt and the +properties used by the Synopsis Designware Mobile Storage Host Controller. + +Required Properties: + +* compatible: should be + - snps,dw-mshc: for controllers compliant with synopsis dw-mshc. +* #address-cells: should be 1. +* #size-cells: should be 0. + +# Slots: The slot specific information are contained within child-nodes with + each child-node representing a supported slot. There should be atleast one + child node representing a card slot. The name of the child node representing + the slot is recommended to be slot@n where n is the unique number of the slot + connnected to the controller. The following are optional properties which + can be included in the slot child node. + + * reg: specifies the physical slot number. The valid values of this + property is 0 to (num-slots -1), where num-slots is the value + specified by the num-slots property. + + * bus-width: as documented in mmc core bindings. + + * wp-gpios: specifies the write protect gpio line. The format of the + gpio specifier depends on the gpio controller. If the write-protect + line is not available, this property is optional. + +Optional properties: + +* num-slots: specifies the number of slots supported by the controller. + The number of physical slots actually used could be equal or less than the + value specified by num-slots. If this property is not specified, the value + of num-slot property is assumed to be 1. + +* fifo-depth: The maximum size of the tx/rx fifo's. If this property is not + specified, the default value of the fifo size is determined from the + controller registers. + +* card-detect-delay: Delay in milli-seconds before detecting card after card + insert event. The default value is 0. + +* supports-highspeed: Enables support for high speed cards (upto 50MHz) + +* broken-cd: as documented in mmc core bindings. + +Aliases: + +- All the MSHC controller nodes should be represented in the aliases node using + the following format 'mshc{n}' where n is a unique number for the alias. + +Example: + +The MSHC controller node can be split into two portions, SoC specific and +board specific portions as listed below. + + dwmmc0@12200000 { + compatible = "snps,dw-mshc"; + reg = <0x12200000 0x1000>; + interrupts = <0 75 0>; + #address-cells = <1>; + #size-cells = <0>; + }; + + dwmmc0@12200000 { + num-slots = <1>; + supports-highspeed; + broken-cd; + fifo-depth = <0x80>; + card-detect-delay = <200>; + + slot@0 { + reg = <0>; + bus-width = <8>; + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/atmel-nand.txt b/Documentation/devicetree/bindings/mtd/atmel-nand.txt index a20069502f5a..d555421ea49f 100644 --- a/Documentation/devicetree/bindings/mtd/atmel-nand.txt +++ b/Documentation/devicetree/bindings/mtd/atmel-nand.txt @@ -3,7 +3,9 @@ Atmel NAND flash Required properties: - compatible : "atmel,at91rm9200-nand". - reg : should specify localbus address and size used for the chip, - and if availlable the ECC. + and hardware ECC controller if available. + If the hardware ECC is PMECC, it should contain address and size for + PMECC, PMECC Error Location controller and ROM which has lookup tables. - atmel,nand-addr-offset : offset for the address latch. - atmel,nand-cmd-offset : offset for the command latch. - #address-cells, #size-cells : Must be present if the device has sub-nodes @@ -16,6 +18,15 @@ Optional properties: - nand-ecc-mode : String, operation mode of the NAND ecc mode, soft by default. Supported values are: "none", "soft", "hw", "hw_syndrome", "hw_oob_first", "soft_bch". +- atmel,has-pmecc : boolean to enable Programmable Multibit ECC hardware. + Only supported by at91sam9x5 or later sam9 product. +- atmel,pmecc-cap : error correct capability for Programmable Multibit ECC + Controller. Supported values are: 2, 4, 8, 12, 24. +- atmel,pmecc-sector-size : sector size for ECC computation. Supported values + are: 512, 1024. +- atmel,pmecc-lookup-table-offset : includes two offsets of lookup table in ROM + for different sector size. First one is for sector size 512, the next is for + sector size 1024. - nand-bus-width : 8 or 16 bus width if not present 8 - nand-on-flash-bbt: boolean to enable on flash bbt option if not present false @@ -39,3 +50,30 @@ nand0: nand@40000000,0 { ... }; }; + +/* for PMECC supported chips */ +nand0: nand@40000000 { + compatible = "atmel,at91rm9200-nand"; + #address-cells = <1>; + #size-cells = <1>; + reg = < 0x40000000 0x10000000 /* bus addr & size */ + 0xffffe000 0x00000600 /* PMECC addr & size */ + 0xffffe600 0x00000200 /* PMECC ERRLOC addr & size */ + 0x00100000 0x00100000 /* ROM addr & size */ + >; + atmel,nand-addr-offset = <21>; /* ale */ + atmel,nand-cmd-offset = <22>; /* cle */ + nand-on-flash-bbt; + nand-ecc-mode = "hw"; + atmel,has-pmecc; /* enable PMECC */ + atmel,pmecc-cap = <2>; + atmel,pmecc-sector-size = <512>; + atmel,pmecc-lookup-table-offset = <0x8000 0x10000>; + gpios = <&pioD 5 0 /* rdy */ + &pioD 4 0 /* nce */ + 0 /* cd */ + >; + partition@0 { + ... + }; +}; diff --git a/Documentation/devicetree/bindings/mtd/gpmi-nand.txt b/Documentation/devicetree/bindings/mtd/gpmi-nand.txt index 1a5bbd346d22..3fb3f9015365 100644 --- a/Documentation/devicetree/bindings/mtd/gpmi-nand.txt +++ b/Documentation/devicetree/bindings/mtd/gpmi-nand.txt @@ -12,6 +12,10 @@ Required properties: - interrupt-names : The interrupt names "gpmi-dma", "bch"; - fsl,gpmi-dma-channel : Should contain the dma channel it uses. +Optional properties: + - nand-on-flash-bbt: boolean to enable on flash bbt option if not + present false + The device tree may optionally contain sub-nodes describing partitions of the address space. See partition.txt for more detail. diff --git a/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt b/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt new file mode 100644 index 000000000000..d0a37252eb22 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/lpc32xx-mlc.txt @@ -0,0 +1,50 @@ +NXP LPC32xx SoC NAND MLC controller + +Required properties: +- compatible: "nxp,lpc3220-mlc" +- reg: Address and size of the controller +- interrupts: The NAND interrupt specification +- gpios: GPIO specification for NAND write protect + +The following required properties are very controller specific. See the LPC32xx +User Manual 7.5.14 MLC NAND Timing Register (the values here are specified in +Hz, to make them independent of actual clock speed and to provide for good +accuracy:) +- nxp,tcea_delay: TCEA_DELAY +- nxp,busy_delay: BUSY_DELAY +- nxp,nand_ta: NAND_TA +- nxp,rd_high: RD_HIGH +- nxp,rd_low: RD_LOW +- nxp,wr_high: WR_HIGH +- nxp,wr_low: WR_LOW + +Optional subnodes: +- Partitions, see Documentation/devicetree/bindings/mtd/partition.txt + +Example: + + mlc: flash@200A8000 { + compatible = "nxp,lpc3220-mlc"; + reg = <0x200A8000 0x11000>; + interrupts = <11 0>; + #address-cells = <1>; + #size-cells = <1>; + + nxp,tcea-delay = <333333333>; + nxp,busy-delay = <10000000>; + nxp,nand-ta = <18181818>; + nxp,rd-high = <31250000>; + nxp,rd-low = <45454545>; + nxp,wr-high = <40000000>; + nxp,wr-low = <83333333>; + gpios = <&gpio 5 19 1>; /* GPO_P3 19, active low */ + + mtd0@00000000 { + label = "boot"; + reg = <0x00000000 0x00064000>; + read-only; + }; + + ... + + }; diff --git a/Documentation/devicetree/bindings/mtd/lpc32xx-slc.txt b/Documentation/devicetree/bindings/mtd/lpc32xx-slc.txt new file mode 100644 index 000000000000..d94edc0fc554 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/lpc32xx-slc.txt @@ -0,0 +1,52 @@ +NXP LPC32xx SoC NAND SLC controller + +Required properties: +- compatible: "nxp,lpc3220-slc" +- reg: Address and size of the controller +- nand-on-flash-bbt: Use bad block table on flash +- gpios: GPIO specification for NAND write protect + +The following required properties are very controller specific. See the LPC32xx +User Manual: +- nxp,wdr-clks: Delay before Ready signal is tested on write (W_RDY) +- nxp,rdr-clks: Delay before Ready signal is tested on read (R_RDY) +(The following values are specified in Hz, to make them independent of actual +clock speed:) +- nxp,wwidth: Write pulse width (W_WIDTH) +- nxp,whold: Write hold time (W_HOLD) +- nxp,wsetup: Write setup time (W_SETUP) +- nxp,rwidth: Read pulse width (R_WIDTH) +- nxp,rhold: Read hold time (R_HOLD) +- nxp,rsetup: Read setup time (R_SETUP) + +Optional subnodes: +- Partitions, see Documentation/devicetree/bindings/mtd/partition.txt + +Example: + + slc: flash@20020000 { + compatible = "nxp,lpc3220-slc"; + reg = <0x20020000 0x1000>; + #address-cells = <1>; + #size-cells = <1>; + + nxp,wdr-clks = <14>; + nxp,wwidth = <40000000>; + nxp,whold = <100000000>; + nxp,wsetup = <100000000>; + nxp,rdr-clks = <14>; + nxp,rwidth = <40000000>; + nxp,rhold = <66666666>; + nxp,rsetup = <100000000>; + nand-on-flash-bbt; + gpios = <&gpio 5 19 1>; /* GPO_P3 19, active low */ + + mtd0@00000000 { + label = "phy3250-boot"; + reg = <0x00000000 0x00064000>; + read-only; + }; + + ... + + }; diff --git a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt index a63c2bd7de2b..94de19b8f16b 100644 --- a/Documentation/devicetree/bindings/mtd/mtd-physmap.txt +++ b/Documentation/devicetree/bindings/mtd/mtd-physmap.txt @@ -16,6 +16,13 @@ file systems on embedded devices. - #address-cells, #size-cells : Must be present if the device has sub-nodes representing partitions (see below). In this case both #address-cells and #size-cells must be equal to 1. + - no-unaligned-direct-access: boolean to disable the default direct + mapping of the flash. + On some platforms (e.g. MPC5200) a direct 1:1 mapping may cause + problems with JFFS2 usage, as the local bus (LPB) doesn't support + unaligned accesses as implemented in the JFFS2 code via memcpy(). + By defining "no-unaligned-direct-access", the flash will not be + exposed directly to the MTD users (e.g. JFFS2) any more. For JEDEC compatible devices, the following additional properties are defined: diff --git a/Documentation/devicetree/bindings/mtd/pxa3xx-nand.txt b/Documentation/devicetree/bindings/mtd/pxa3xx-nand.txt new file mode 100644 index 000000000000..f1421e2bbab7 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/pxa3xx-nand.txt @@ -0,0 +1,31 @@ +PXA3xx NAND DT bindings + +Required properties: + + - compatible: Should be "marvell,pxa3xx-nand" + - reg: The register base for the controller + - interrupts: The interrupt to map + - #address-cells: Set to <1> if the node includes partitions + +Optional properties: + + - marvell,nand-enable-arbiter: Set to enable the bus arbiter + - marvell,nand-keep-config: Set to keep the NAND controller config as set + by the bootloader + - num-cs: Number of chipselect lines to usw + +Example: + + nand0: nand@43100000 { + compatible = "marvell,pxa3xx-nand"; + reg = <0x43100000 90>; + interrupts = <45>; + #address-cells = <1>; + + marvell,nand-enable-arbiter; + marvell,nand-keep-config; + num-cs = <1>; + + /* partitions (optional) */ + }; + diff --git a/Documentation/devicetree/bindings/net/calxeda-xgmac.txt b/Documentation/devicetree/bindings/net/calxeda-xgmac.txt index 411727a3f82d..c8ae996bd8f2 100644 --- a/Documentation/devicetree/bindings/net/calxeda-xgmac.txt +++ b/Documentation/devicetree/bindings/net/calxeda-xgmac.txt @@ -6,6 +6,9 @@ Required properties: - interrupts : Should contain 3 xgmac interrupts. The 1st is main interrupt. The 2nd is pwr mgt interrupt. The 3rd is low power state interrupt. +Optional properties: +- dma-coherent : Present if dma operations are coherent + Example: ethernet@fff50000 { diff --git a/Documentation/devicetree/bindings/net/can/c_can.txt b/Documentation/devicetree/bindings/net/can/c_can.txt new file mode 100644 index 000000000000..8f1ae81228e3 --- /dev/null +++ b/Documentation/devicetree/bindings/net/can/c_can.txt @@ -0,0 +1,49 @@ +Bosch C_CAN/D_CAN controller Device Tree Bindings +------------------------------------------------- + +Required properties: +- compatible : Should be "bosch,c_can" for C_CAN controllers and + "bosch,d_can" for D_CAN controllers. +- reg : physical base address and size of the C_CAN/D_CAN + registers map +- interrupts : property with a value describing the interrupt + number + +Optional properties: +- ti,hwmods : Must be "d_can<n>" or "c_can<n>", n being the + instance number + +Note: "ti,hwmods" field is used to fetch the base address and irq +resources from TI, omap hwmod data base during device registration. +Future plan is to migrate hwmod data base contents into device tree +blob so that, all the required data will be used from device tree dts +file. + +Example: + +Step1: SoC common .dtsi file + + dcan1: d_can@481d0000 { + compatible = "bosch,d_can"; + reg = <0x481d0000 0x2000>; + interrupts = <55>; + interrupt-parent = <&intc>; + status = "disabled"; + }; + +(or) + + dcan1: d_can@481d0000 { + compatible = "bosch,d_can"; + ti,hwmods = "d_can1"; + reg = <0x481d0000 0x2000>; + interrupts = <55>; + interrupt-parent = <&intc>; + status = "disabled"; + }; + +Step 2: board specific .dts file + + &dcan1 { + status = "okay"; + }; diff --git a/Documentation/devicetree/bindings/net/cpsw.txt b/Documentation/devicetree/bindings/net/cpsw.txt new file mode 100644 index 000000000000..dcaabe9fe869 --- /dev/null +++ b/Documentation/devicetree/bindings/net/cpsw.txt @@ -0,0 +1,109 @@ +TI SoC Ethernet Switch Controller Device Tree Bindings +------------------------------------------------------ + +Required properties: +- compatible : Should be "ti,cpsw" +- reg : physical base address and size of the cpsw + registers map +- interrupts : property with a value describing the interrupt + number +- interrupt-parent : The parent interrupt controller +- cpdma_channels : Specifies number of channels in CPDMA +- host_port_no : Specifies host port shift +- cpdma_reg_ofs : Specifies CPDMA submodule register offset +- cpdma_sram_ofs : Specifies CPDMA SRAM offset +- ale_reg_ofs : Specifies ALE submodule register offset +- ale_entries : Specifies No of entries ALE can hold +- host_port_reg_ofs : Specifies host port register offset +- hw_stats_reg_ofs : Specifies hardware statistics register offset +- bd_ram_ofs : Specifies internal desciptor RAM offset +- bd_ram_size : Specifies internal descriptor RAM size +- rx_descs : Specifies number of Rx descriptors +- mac_control : Specifies Default MAC control register content + for the specific platform +- slaves : Specifies number for slaves +- slave_reg_ofs : Specifies slave register offset +- sliver_reg_ofs : Specifies slave sliver register offset +- phy_id : Specifies slave phy id +- mac-address : Specifies slave MAC address + +Optional properties: +- ti,hwmods : Must be "cpgmac0" +- no_bd_ram : Must be 0 or 1 + +Note: "ti,hwmods" field is used to fetch the base address and irq +resources from TI, omap hwmod data base during device registration. +Future plan is to migrate hwmod data base contents into device tree +blob so that, all the required data will be used from device tree dts +file. + +Examples: + + mac: ethernet@4A100000 { + compatible = "ti,cpsw"; + reg = <0x4A100000 0x1000>; + interrupts = <55 0x4>; + interrupt-parent = <&intc>; + cpdma_channels = <8>; + host_port_no = <0>; + cpdma_reg_ofs = <0x800>; + cpdma_sram_ofs = <0xa00>; + ale_reg_ofs = <0xd00>; + ale_entries = <1024>; + host_port_reg_ofs = <0x108>; + hw_stats_reg_ofs = <0x900>; + bd_ram_ofs = <0x2000>; + bd_ram_size = <0x2000>; + no_bd_ram = <0>; + rx_descs = <64>; + mac_control = <0x20>; + slaves = <2>; + cpsw_emac0: slave@0 { + slave_reg_ofs = <0x208>; + sliver_reg_ofs = <0xd80>; + phy_id = "davinci_mdio.16:00"; + /* Filled in by U-Boot */ + mac-address = [ 00 00 00 00 00 00 ]; + }; + cpsw_emac1: slave@1 { + slave_reg_ofs = <0x308>; + sliver_reg_ofs = <0xdc0>; + phy_id = "davinci_mdio.16:01"; + /* Filled in by U-Boot */ + mac-address = [ 00 00 00 00 00 00 ]; + }; + }; + +(or) + mac: ethernet@4A100000 { + compatible = "ti,cpsw"; + ti,hwmods = "cpgmac0"; + cpdma_channels = <8>; + host_port_no = <0>; + cpdma_reg_ofs = <0x800>; + cpdma_sram_ofs = <0xa00>; + ale_reg_ofs = <0xd00>; + ale_entries = <1024>; + host_port_reg_ofs = <0x108>; + hw_stats_reg_ofs = <0x900>; + bd_ram_ofs = <0x2000>; + bd_ram_size = <0x2000>; + no_bd_ram = <0>; + rx_descs = <64>; + mac_control = <0x20>; + slaves = <2>; + cpsw_emac0: slave@0 { + slave_reg_ofs = <0x208>; + sliver_reg_ofs = <0xd80>; + phy_id = "davinci_mdio.16:00"; + /* Filled in by U-Boot */ + mac-address = [ 00 00 00 00 00 00 ]; + }; + cpsw_emac1: slave@1 { + slave_reg_ofs = <0x308>; + sliver_reg_ofs = <0xdc0>; + phy_id = "davinci_mdio.16:01"; + /* Filled in by U-Boot */ + mac-address = [ 00 00 00 00 00 00 ]; + }; + }; diff --git a/Documentation/devicetree/bindings/net/davinci-mdio.txt b/Documentation/devicetree/bindings/net/davinci-mdio.txt new file mode 100644 index 000000000000..72efaaf764f7 --- /dev/null +++ b/Documentation/devicetree/bindings/net/davinci-mdio.txt @@ -0,0 +1,33 @@ +TI SoC Davinci MDIO Controller Device Tree Bindings +--------------------------------------------------- + +Required properties: +- compatible : Should be "ti,davinci_mdio" +- reg : physical base address and size of the davinci mdio + registers map +- bus_freq : Mdio Bus frequency + +Optional properties: +- ti,hwmods : Must be "davinci_mdio" + +Note: "ti,hwmods" field is used to fetch the base address and irq +resources from TI, omap hwmod data base during device registration. +Future plan is to migrate hwmod data base contents into device tree +blob so that, all the required data will be used from device tree dts +file. + +Examples: + + mdio: davinci_mdio@4A101000 { + compatible = "ti,cpsw"; + reg = <0x4A101000 0x1000>; + bus_freq = <1000000>; + }; + +(or) + + mdio: davinci_mdio@4A101000 { + compatible = "ti,cpsw"; + ti,hwmods = "davinci_mdio"; + bus_freq = <1000000>; + }; diff --git a/Documentation/devicetree/bindings/net/mdio-mux-mmioreg.txt b/Documentation/devicetree/bindings/net/mdio-mux-mmioreg.txt new file mode 100644 index 000000000000..8516929c7251 --- /dev/null +++ b/Documentation/devicetree/bindings/net/mdio-mux-mmioreg.txt @@ -0,0 +1,75 @@ +Properties for an MDIO bus multiplexer controlled by a memory-mapped device + +This is a special case of a MDIO bus multiplexer. A memory-mapped device, +like an FPGA, is used to control which child bus is connected. The mdio-mux +node must be a child of the memory-mapped device. The driver currently only +supports devices with eight-bit registers. + +Required properties in addition to the generic multiplexer properties: + +- compatible : string, must contain "mdio-mux-mmioreg" + +- reg : integer, contains the offset of the register that controls the bus + multiplexer. The size field in the 'reg' property is the size of + register, and must therefore be 1. + +- mux-mask : integer, contains an eight-bit mask that specifies which + bits in the register control the actual bus multiplexer. The + 'reg' property of each child mdio-mux node must be constrained by + this mask. + +Example: + +The FPGA node defines a memory-mapped FPGA with a register space of 0x30 bytes. +For the "EMI2" MDIO bus, register 9 (BRDCFG1) controls the mux on that bus. +A bitmask of 0x6 means that bits 1 and 2 (bit 0 is lsb) are the bits on +BRDCFG1 that control the actual mux. + + /* The FPGA node */ + fpga: board-control@3,0 { + #address-cells = <1>; + #size-cells = <1>; + compatible = "fsl,p5020ds-fpga", "fsl,fpga-ngpixis"; + reg = <3 0 0x30>; + ranges = <0 3 0 0x30>; + + mdio-mux-emi2 { + compatible = "mdio-mux-mmioreg", "mdio-mux"; + mdio-parent-bus = <&xmdio0>; + #address-cells = <1>; + #size-cells = <0>; + reg = <9 1>; // BRDCFG1 + mux-mask = <0x6>; // EMI2 + + emi2_slot1: mdio@0 { // Slot 1 XAUI (FM2) + reg = <0>; + #address-cells = <1>; + #size-cells = <0>; + + phy_xgmii_slot1: ethernet-phy@0 { + compatible = "ethernet-phy-ieee802.3-c45"; + reg = <4>; + }; + }; + + emi2_slot2: mdio@2 { // Slot 2 XAUI (FM1) + reg = <2>; + #address-cells = <1>; + #size-cells = <0>; + + phy_xgmii_slot2: ethernet-phy@4 { + compatible = "ethernet-phy-ieee802.3-c45"; + reg = <0>; + }; + }; + }; + }; + + /* The parent MDIO bus. */ + xmdio0: mdio@f1000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,fman-xmdio"; + reg = <0xf1000 0x1000>; + interrupts = <100 1 0 0>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt new file mode 100644 index 000000000000..8edc20e1b09e --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/brcm,bcm2835-gpio.txt @@ -0,0 +1,74 @@ +Broadcom BCM2835 GPIO (and pinmux) controller + +The BCM2835 GPIO module is a combined GPIO controller, (GPIO) interrupt +controller, and pinmux/control device. + +Required properties: +- compatible: "brcm,bcm2835-gpio" +- reg: Should contain the physical address of the GPIO module's registes. +- gpio-controller: Marks the device node as a GPIO controller. +- #gpio-cells : Should be two. The first cell is the pin number and the + second cell is used to specify optional parameters: + - bit 0 specifies polarity (0 for normal, 1 for inverted) +- interrupts : The interrupt outputs from the controller. One interrupt per + individual bank followed by the "all banks" interrupt. +- interrupt-controller: Marks the device node as an interrupt controller. +- #interrupt-cells : Should be 2. + The first cell is the GPIO number. + The second cell is used to specify flags: + bits[3:0] trigger type and level flags: + 1 = low-to-high edge triggered. + 2 = high-to-low edge triggered. + 4 = active high level-sensitive. + 8 = active low level-sensitive. + Valid combinations are 1, 2, 3, 4, 8. + +Please refer to ../gpio/gpio.txt for a general description of GPIO bindings. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +Each pin configuration node lists the pin(s) to which it applies, and one or +more of the mux function to select on those pin(s), and pull-up/down +configuration. Each subnode only affects those parameters that are explicitly +listed. In other words, a subnode that lists only a mux function implies no +information about any pull configuration. Similarly, a subnode that lists only +a pul parameter implies no information about the mux function. + +Required subnode-properties: +- brcm,pins: An array of cells. Each cell contains the ID of a pin. Valid IDs + are the integer GPIO IDs; 0==GPIO0, 1==GPIO1, ... 53==GPIO53. + +Optional subnode-properties: +- brcm,function: Integer, containing the function to mux to the pin(s): + 0: GPIO in + 1: GPIO out + 2: alt5 + 3: alt4 + 4: alt0 + 5: alt1 + 6: alt2 + 7: alt3 +- brcm,pull: Integer, representing the pull-down/up to apply to the pin(s): + 0: none + 1: down + 2: up + +Each of brcm,function and brcm,pull may contain either a single value which +will be applied to all pins in brcm,pins, or 1 value for each entry in +brcm,pins. + +Example: + + gpio: gpio { + compatible = "brcm,bcm2835-gpio"; + reg = <0x2200000 0xb4>; + interrupts = <2 17>, <2 19>, <2 18>, <2 20>; + + gpio-controller; + #gpio-cells = <2>; + + interrupt-controller; + #interrupt-cells = <2>; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/fsl,imx35-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/fsl,imx35-pinctrl.txt new file mode 100644 index 000000000000..1183f1a3be33 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/fsl,imx35-pinctrl.txt @@ -0,0 +1,984 @@ +* Freescale IMX35 IOMUX Controller + +Please refer to fsl,imx-pinctrl.txt in this directory for common binding part +and usage. + +Required properties: +- compatible: "fsl,imx35-iomuxc" +- fsl,pins: two integers array, represents a group of pins mux and config + setting. The format is fsl,pins = <PIN_FUNC_ID CONFIG>, PIN_FUNC_ID is a + pin working on a specific function, CONFIG is the pad setting value like + pull-up for this pin. Please refer to imx35 datasheet for the valid pad + config settings. + +CONFIG bits definition: +PAD_CTL_DRIVE_VOLAGAGE_18 (1 << 13) +PAD_CTL_DRIVE_VOLAGAGE_33 (0 << 13) +PAD_CTL_HYS (1 << 8) +PAD_CTL_PKE (1 << 7) +PAD_CTL_PUE (1 << 6) +PAD_CTL_PUS_100K_DOWN (0 << 4) +PAD_CTL_PUS_47K_UP (1 << 4) +PAD_CTL_PUS_100K_UP (2 << 4) +PAD_CTL_PUS_22K_UP (3 << 4) +PAD_CTL_ODE_CMOS (0 << 3) +PAD_CTL_ODE_OPENDRAIN (1 << 3) +PAD_CTL_DSE_NOMINAL (0 << 1) +PAD_CTL_DSE_HIGH (1 << 1) +PAD_CTL_DSE_MAX (2 << 1) +PAD_CTL_SRE_FAST (1 << 0) +PAD_CTL_SRE_SLOW (0 << 0) + +See below for available PIN_FUNC_ID for imx35: +0 MX35_PAD_CAPTURE__GPT_CAPIN1 +1 MX35_PAD_CAPTURE__GPT_CMPOUT2 +2 MX35_PAD_CAPTURE__CSPI2_SS1 +3 MX35_PAD_CAPTURE__EPIT1_EPITO +4 MX35_PAD_CAPTURE__CCM_CLK32K +5 MX35_PAD_CAPTURE__GPIO1_4 +6 MX35_PAD_COMPARE__GPT_CMPOUT1 +7 MX35_PAD_COMPARE__GPT_CAPIN2 +8 MX35_PAD_COMPARE__GPT_CMPOUT3 +9 MX35_PAD_COMPARE__EPIT2_EPITO +10 MX35_PAD_COMPARE__GPIO1_5 +11 MX35_PAD_COMPARE__SDMA_EXTDMA_2 +12 MX35_PAD_WDOG_RST__WDOG_WDOG_B +13 MX35_PAD_WDOG_RST__IPU_FLASH_STROBE +14 MX35_PAD_WDOG_RST__GPIO1_6 +15 MX35_PAD_GPIO1_0__GPIO1_0 +16 MX35_PAD_GPIO1_0__CCM_PMIC_RDY +17 MX35_PAD_GPIO1_0__OWIRE_LINE +18 MX35_PAD_GPIO1_0__SDMA_EXTDMA_0 +19 MX35_PAD_GPIO1_1__GPIO1_1 +20 MX35_PAD_GPIO1_1__PWM_PWMO +21 MX35_PAD_GPIO1_1__CSPI1_SS2 +22 MX35_PAD_GPIO1_1__SCC_TAMPER_DETECT +23 MX35_PAD_GPIO1_1__SDMA_EXTDMA_1 +24 MX35_PAD_GPIO2_0__GPIO2_0 +25 MX35_PAD_GPIO2_0__USB_TOP_USBOTG_CLK +26 MX35_PAD_GPIO3_0__GPIO3_0 +27 MX35_PAD_GPIO3_0__USB_TOP_USBH2_CLK +28 MX35_PAD_RESET_IN_B__CCM_RESET_IN_B +29 MX35_PAD_POR_B__CCM_POR_B +30 MX35_PAD_CLKO__CCM_CLKO +31 MX35_PAD_CLKO__GPIO1_8 +32 MX35_PAD_BOOT_MODE0__CCM_BOOT_MODE_0 +33 MX35_PAD_BOOT_MODE1__CCM_BOOT_MODE_1 +34 MX35_PAD_CLK_MODE0__CCM_CLK_MODE_0 +35 MX35_PAD_CLK_MODE1__CCM_CLK_MODE_1 +36 MX35_PAD_POWER_FAIL__CCM_DSM_WAKEUP_INT_26 +37 MX35_PAD_VSTBY__CCM_VSTBY +38 MX35_PAD_VSTBY__GPIO1_7 +39 MX35_PAD_A0__EMI_EIM_DA_L_0 +40 MX35_PAD_A1__EMI_EIM_DA_L_1 +41 MX35_PAD_A2__EMI_EIM_DA_L_2 +42 MX35_PAD_A3__EMI_EIM_DA_L_3 +43 MX35_PAD_A4__EMI_EIM_DA_L_4 +44 MX35_PAD_A5__EMI_EIM_DA_L_5 +45 MX35_PAD_A6__EMI_EIM_DA_L_6 +46 MX35_PAD_A7__EMI_EIM_DA_L_7 +47 MX35_PAD_A8__EMI_EIM_DA_H_8 +48 MX35_PAD_A9__EMI_EIM_DA_H_9 +49 MX35_PAD_A10__EMI_EIM_DA_H_10 +50 MX35_PAD_MA10__EMI_MA10 +51 MX35_PAD_A11__EMI_EIM_DA_H_11 +52 MX35_PAD_A12__EMI_EIM_DA_H_12 +53 MX35_PAD_A13__EMI_EIM_DA_H_13 +54 MX35_PAD_A14__EMI_EIM_DA_H2_14 +55 MX35_PAD_A15__EMI_EIM_DA_H2_15 +56 MX35_PAD_A16__EMI_EIM_A_16 +57 MX35_PAD_A17__EMI_EIM_A_17 +58 MX35_PAD_A18__EMI_EIM_A_18 +59 MX35_PAD_A19__EMI_EIM_A_19 +60 MX35_PAD_A20__EMI_EIM_A_20 +61 MX35_PAD_A21__EMI_EIM_A_21 +62 MX35_PAD_A22__EMI_EIM_A_22 +63 MX35_PAD_A23__EMI_EIM_A_23 +64 MX35_PAD_A24__EMI_EIM_A_24 +65 MX35_PAD_A25__EMI_EIM_A_25 +66 MX35_PAD_SDBA1__EMI_EIM_SDBA1 +67 MX35_PAD_SDBA0__EMI_EIM_SDBA0 +68 MX35_PAD_SD0__EMI_DRAM_D_0 +69 MX35_PAD_SD1__EMI_DRAM_D_1 +70 MX35_PAD_SD2__EMI_DRAM_D_2 +71 MX35_PAD_SD3__EMI_DRAM_D_3 +72 MX35_PAD_SD4__EMI_DRAM_D_4 +73 MX35_PAD_SD5__EMI_DRAM_D_5 +74 MX35_PAD_SD6__EMI_DRAM_D_6 +75 MX35_PAD_SD7__EMI_DRAM_D_7 +76 MX35_PAD_SD8__EMI_DRAM_D_8 +77 MX35_PAD_SD9__EMI_DRAM_D_9 +78 MX35_PAD_SD10__EMI_DRAM_D_10 +79 MX35_PAD_SD11__EMI_DRAM_D_11 +80 MX35_PAD_SD12__EMI_DRAM_D_12 +81 MX35_PAD_SD13__EMI_DRAM_D_13 +82 MX35_PAD_SD14__EMI_DRAM_D_14 +83 MX35_PAD_SD15__EMI_DRAM_D_15 +84 MX35_PAD_SD16__EMI_DRAM_D_16 +85 MX35_PAD_SD17__EMI_DRAM_D_17 +86 MX35_PAD_SD18__EMI_DRAM_D_18 +87 MX35_PAD_SD19__EMI_DRAM_D_19 +88 MX35_PAD_SD20__EMI_DRAM_D_20 +89 MX35_PAD_SD21__EMI_DRAM_D_21 +90 MX35_PAD_SD22__EMI_DRAM_D_22 +91 MX35_PAD_SD23__EMI_DRAM_D_23 +92 MX35_PAD_SD24__EMI_DRAM_D_24 +93 MX35_PAD_SD25__EMI_DRAM_D_25 +94 MX35_PAD_SD26__EMI_DRAM_D_26 +95 MX35_PAD_SD27__EMI_DRAM_D_27 +96 MX35_PAD_SD28__EMI_DRAM_D_28 +97 MX35_PAD_SD29__EMI_DRAM_D_29 +98 MX35_PAD_SD30__EMI_DRAM_D_30 +99 MX35_PAD_SD31__EMI_DRAM_D_31 +100 MX35_PAD_DQM0__EMI_DRAM_DQM_0 +101 MX35_PAD_DQM1__EMI_DRAM_DQM_1 +102 MX35_PAD_DQM2__EMI_DRAM_DQM_2 +103 MX35_PAD_DQM3__EMI_DRAM_DQM_3 +104 MX35_PAD_EB0__EMI_EIM_EB0_B +105 MX35_PAD_EB1__EMI_EIM_EB1_B +106 MX35_PAD_OE__EMI_EIM_OE +107 MX35_PAD_CS0__EMI_EIM_CS0 +108 MX35_PAD_CS1__EMI_EIM_CS1 +109 MX35_PAD_CS1__EMI_NANDF_CE3 +110 MX35_PAD_CS2__EMI_EIM_CS2 +111 MX35_PAD_CS3__EMI_EIM_CS3 +112 MX35_PAD_CS4__EMI_EIM_CS4 +113 MX35_PAD_CS4__EMI_DTACK_B +114 MX35_PAD_CS4__EMI_NANDF_CE1 +115 MX35_PAD_CS4__GPIO1_20 +116 MX35_PAD_CS5__EMI_EIM_CS5 +117 MX35_PAD_CS5__CSPI2_SS2 +118 MX35_PAD_CS5__CSPI1_SS2 +119 MX35_PAD_CS5__EMI_NANDF_CE2 +120 MX35_PAD_CS5__GPIO1_21 +121 MX35_PAD_NF_CE0__EMI_NANDF_CE0 +122 MX35_PAD_NF_CE0__GPIO1_22 +123 MX35_PAD_ECB__EMI_EIM_ECB +124 MX35_PAD_LBA__EMI_EIM_LBA +125 MX35_PAD_BCLK__EMI_EIM_BCLK +126 MX35_PAD_RW__EMI_EIM_RW +127 MX35_PAD_RAS__EMI_DRAM_RAS +128 MX35_PAD_CAS__EMI_DRAM_CAS +129 MX35_PAD_SDWE__EMI_DRAM_SDWE +130 MX35_PAD_SDCKE0__EMI_DRAM_SDCKE_0 +131 MX35_PAD_SDCKE1__EMI_DRAM_SDCKE_1 +132 MX35_PAD_SDCLK__EMI_DRAM_SDCLK +133 MX35_PAD_SDQS0__EMI_DRAM_SDQS_0 +134 MX35_PAD_SDQS1__EMI_DRAM_SDQS_1 +135 MX35_PAD_SDQS2__EMI_DRAM_SDQS_2 +136 MX35_PAD_SDQS3__EMI_DRAM_SDQS_3 +137 MX35_PAD_NFWE_B__EMI_NANDF_WE_B +138 MX35_PAD_NFWE_B__USB_TOP_USBH2_DATA_3 +139 MX35_PAD_NFWE_B__IPU_DISPB_D0_VSYNC +140 MX35_PAD_NFWE_B__GPIO2_18 +141 MX35_PAD_NFWE_B__ARM11P_TOP_TRACE_0 +142 MX35_PAD_NFRE_B__EMI_NANDF_RE_B +143 MX35_PAD_NFRE_B__USB_TOP_USBH2_DIR +144 MX35_PAD_NFRE_B__IPU_DISPB_BCLK +145 MX35_PAD_NFRE_B__GPIO2_19 +146 MX35_PAD_NFRE_B__ARM11P_TOP_TRACE_1 +147 MX35_PAD_NFALE__EMI_NANDF_ALE +148 MX35_PAD_NFALE__USB_TOP_USBH2_STP +149 MX35_PAD_NFALE__IPU_DISPB_CS0 +150 MX35_PAD_NFALE__GPIO2_20 +151 MX35_PAD_NFALE__ARM11P_TOP_TRACE_2 +152 MX35_PAD_NFCLE__EMI_NANDF_CLE +153 MX35_PAD_NFCLE__USB_TOP_USBH2_NXT +154 MX35_PAD_NFCLE__IPU_DISPB_PAR_RS +155 MX35_PAD_NFCLE__GPIO2_21 +156 MX35_PAD_NFCLE__ARM11P_TOP_TRACE_3 +157 MX35_PAD_NFWP_B__EMI_NANDF_WP_B +158 MX35_PAD_NFWP_B__USB_TOP_USBH2_DATA_7 +159 MX35_PAD_NFWP_B__IPU_DISPB_WR +160 MX35_PAD_NFWP_B__GPIO2_22 +161 MX35_PAD_NFWP_B__ARM11P_TOP_TRCTL +162 MX35_PAD_NFRB__EMI_NANDF_RB +163 MX35_PAD_NFRB__IPU_DISPB_RD +164 MX35_PAD_NFRB__GPIO2_23 +165 MX35_PAD_NFRB__ARM11P_TOP_TRCLK +166 MX35_PAD_D15__EMI_EIM_D_15 +167 MX35_PAD_D14__EMI_EIM_D_14 +168 MX35_PAD_D13__EMI_EIM_D_13 +169 MX35_PAD_D12__EMI_EIM_D_12 +170 MX35_PAD_D11__EMI_EIM_D_11 +171 MX35_PAD_D10__EMI_EIM_D_10 +172 MX35_PAD_D9__EMI_EIM_D_9 +173 MX35_PAD_D8__EMI_EIM_D_8 +174 MX35_PAD_D7__EMI_EIM_D_7 +175 MX35_PAD_D6__EMI_EIM_D_6 +176 MX35_PAD_D5__EMI_EIM_D_5 +177 MX35_PAD_D4__EMI_EIM_D_4 +178 MX35_PAD_D3__EMI_EIM_D_3 +179 MX35_PAD_D2__EMI_EIM_D_2 +180 MX35_PAD_D1__EMI_EIM_D_1 +181 MX35_PAD_D0__EMI_EIM_D_0 +182 MX35_PAD_CSI_D8__IPU_CSI_D_8 +183 MX35_PAD_CSI_D8__KPP_COL_0 +184 MX35_PAD_CSI_D8__GPIO1_20 +185 MX35_PAD_CSI_D8__ARM11P_TOP_EVNTBUS_13 +186 MX35_PAD_CSI_D9__IPU_CSI_D_9 +187 MX35_PAD_CSI_D9__KPP_COL_1 +188 MX35_PAD_CSI_D9__GPIO1_21 +189 MX35_PAD_CSI_D9__ARM11P_TOP_EVNTBUS_14 +190 MX35_PAD_CSI_D10__IPU_CSI_D_10 +191 MX35_PAD_CSI_D10__KPP_COL_2 +192 MX35_PAD_CSI_D10__GPIO1_22 +193 MX35_PAD_CSI_D10__ARM11P_TOP_EVNTBUS_15 +194 MX35_PAD_CSI_D11__IPU_CSI_D_11 +195 MX35_PAD_CSI_D11__KPP_COL_3 +196 MX35_PAD_CSI_D11__GPIO1_23 +197 MX35_PAD_CSI_D12__IPU_CSI_D_12 +198 MX35_PAD_CSI_D12__KPP_ROW_0 +199 MX35_PAD_CSI_D12__GPIO1_24 +200 MX35_PAD_CSI_D13__IPU_CSI_D_13 +201 MX35_PAD_CSI_D13__KPP_ROW_1 +202 MX35_PAD_CSI_D13__GPIO1_25 +203 MX35_PAD_CSI_D14__IPU_CSI_D_14 +204 MX35_PAD_CSI_D14__KPP_ROW_2 +205 MX35_PAD_CSI_D14__GPIO1_26 +206 MX35_PAD_CSI_D15__IPU_CSI_D_15 +207 MX35_PAD_CSI_D15__KPP_ROW_3 +208 MX35_PAD_CSI_D15__GPIO1_27 +209 MX35_PAD_CSI_MCLK__IPU_CSI_MCLK +210 MX35_PAD_CSI_MCLK__GPIO1_28 +211 MX35_PAD_CSI_VSYNC__IPU_CSI_VSYNC +212 MX35_PAD_CSI_VSYNC__GPIO1_29 +213 MX35_PAD_CSI_HSYNC__IPU_CSI_HSYNC +214 MX35_PAD_CSI_HSYNC__GPIO1_30 +215 MX35_PAD_CSI_PIXCLK__IPU_CSI_PIXCLK +216 MX35_PAD_CSI_PIXCLK__GPIO1_31 +217 MX35_PAD_I2C1_CLK__I2C1_SCL +218 MX35_PAD_I2C1_CLK__GPIO2_24 +219 MX35_PAD_I2C1_CLK__CCM_USB_BYP_CLK +220 MX35_PAD_I2C1_DAT__I2C1_SDA +221 MX35_PAD_I2C1_DAT__GPIO2_25 +222 MX35_PAD_I2C2_CLK__I2C2_SCL +223 MX35_PAD_I2C2_CLK__CAN1_TXCAN +224 MX35_PAD_I2C2_CLK__USB_TOP_USBH2_PWR +225 MX35_PAD_I2C2_CLK__GPIO2_26 +226 MX35_PAD_I2C2_CLK__SDMA_DEBUG_BUS_DEVICE_2 +227 MX35_PAD_I2C2_DAT__I2C2_SDA +228 MX35_PAD_I2C2_DAT__CAN1_RXCAN +229 MX35_PAD_I2C2_DAT__USB_TOP_USBH2_OC +230 MX35_PAD_I2C2_DAT__GPIO2_27 +231 MX35_PAD_I2C2_DAT__SDMA_DEBUG_BUS_DEVICE_3 +232 MX35_PAD_STXD4__AUDMUX_AUD4_TXD +233 MX35_PAD_STXD4__GPIO2_28 +234 MX35_PAD_STXD4__ARM11P_TOP_ARM_COREASID0 +235 MX35_PAD_SRXD4__AUDMUX_AUD4_RXD +236 MX35_PAD_SRXD4__GPIO2_29 +237 MX35_PAD_SRXD4__ARM11P_TOP_ARM_COREASID1 +238 MX35_PAD_SCK4__AUDMUX_AUD4_TXC +239 MX35_PAD_SCK4__GPIO2_30 +240 MX35_PAD_SCK4__ARM11P_TOP_ARM_COREASID2 +241 MX35_PAD_STXFS4__AUDMUX_AUD4_TXFS +242 MX35_PAD_STXFS4__GPIO2_31 +243 MX35_PAD_STXFS4__ARM11P_TOP_ARM_COREASID3 +244 MX35_PAD_STXD5__AUDMUX_AUD5_TXD +245 MX35_PAD_STXD5__SPDIF_SPDIF_OUT1 +246 MX35_PAD_STXD5__CSPI2_MOSI +247 MX35_PAD_STXD5__GPIO1_0 +248 MX35_PAD_STXD5__ARM11P_TOP_ARM_COREASID4 +249 MX35_PAD_SRXD5__AUDMUX_AUD5_RXD +250 MX35_PAD_SRXD5__SPDIF_SPDIF_IN1 +251 MX35_PAD_SRXD5__CSPI2_MISO +252 MX35_PAD_SRXD5__GPIO1_1 +253 MX35_PAD_SRXD5__ARM11P_TOP_ARM_COREASID5 +254 MX35_PAD_SCK5__AUDMUX_AUD5_TXC +255 MX35_PAD_SCK5__SPDIF_SPDIF_EXTCLK +256 MX35_PAD_SCK5__CSPI2_SCLK +257 MX35_PAD_SCK5__GPIO1_2 +258 MX35_PAD_SCK5__ARM11P_TOP_ARM_COREASID6 +259 MX35_PAD_STXFS5__AUDMUX_AUD5_TXFS +260 MX35_PAD_STXFS5__CSPI2_RDY +261 MX35_PAD_STXFS5__GPIO1_3 +262 MX35_PAD_STXFS5__ARM11P_TOP_ARM_COREASID7 +263 MX35_PAD_SCKR__ESAI_SCKR +264 MX35_PAD_SCKR__GPIO1_4 +265 MX35_PAD_SCKR__ARM11P_TOP_EVNTBUS_10 +266 MX35_PAD_FSR__ESAI_FSR +267 MX35_PAD_FSR__GPIO1_5 +268 MX35_PAD_FSR__ARM11P_TOP_EVNTBUS_11 +269 MX35_PAD_HCKR__ESAI_HCKR +270 MX35_PAD_HCKR__AUDMUX_AUD5_RXFS +271 MX35_PAD_HCKR__CSPI2_SS0 +272 MX35_PAD_HCKR__IPU_FLASH_STROBE +273 MX35_PAD_HCKR__GPIO1_6 +274 MX35_PAD_HCKR__ARM11P_TOP_EVNTBUS_12 +275 MX35_PAD_SCKT__ESAI_SCKT +276 MX35_PAD_SCKT__GPIO1_7 +277 MX35_PAD_SCKT__IPU_CSI_D_0 +278 MX35_PAD_SCKT__KPP_ROW_2 +279 MX35_PAD_FST__ESAI_FST +280 MX35_PAD_FST__GPIO1_8 +281 MX35_PAD_FST__IPU_CSI_D_1 +282 MX35_PAD_FST__KPP_ROW_3 +283 MX35_PAD_HCKT__ESAI_HCKT +284 MX35_PAD_HCKT__AUDMUX_AUD5_RXC +285 MX35_PAD_HCKT__GPIO1_9 +286 MX35_PAD_HCKT__IPU_CSI_D_2 +287 MX35_PAD_HCKT__KPP_COL_3 +288 MX35_PAD_TX5_RX0__ESAI_TX5_RX0 +289 MX35_PAD_TX5_RX0__AUDMUX_AUD4_RXC +290 MX35_PAD_TX5_RX0__CSPI2_SS2 +291 MX35_PAD_TX5_RX0__CAN2_TXCAN +292 MX35_PAD_TX5_RX0__UART2_DTR +293 MX35_PAD_TX5_RX0__GPIO1_10 +294 MX35_PAD_TX5_RX0__EMI_M3IF_CHOSEN_MASTER_0 +295 MX35_PAD_TX4_RX1__ESAI_TX4_RX1 +296 MX35_PAD_TX4_RX1__AUDMUX_AUD4_RXFS +297 MX35_PAD_TX4_RX1__CSPI2_SS3 +298 MX35_PAD_TX4_RX1__CAN2_RXCAN +299 MX35_PAD_TX4_RX1__UART2_DSR +300 MX35_PAD_TX4_RX1__GPIO1_11 +301 MX35_PAD_TX4_RX1__IPU_CSI_D_3 +302 MX35_PAD_TX4_RX1__KPP_ROW_0 +303 MX35_PAD_TX3_RX2__ESAI_TX3_RX2 +304 MX35_PAD_TX3_RX2__I2C3_SCL +305 MX35_PAD_TX3_RX2__EMI_NANDF_CE1 +306 MX35_PAD_TX3_RX2__GPIO1_12 +307 MX35_PAD_TX3_RX2__IPU_CSI_D_4 +308 MX35_PAD_TX3_RX2__KPP_ROW_1 +309 MX35_PAD_TX2_RX3__ESAI_TX2_RX3 +310 MX35_PAD_TX2_RX3__I2C3_SDA +311 MX35_PAD_TX2_RX3__EMI_NANDF_CE2 +312 MX35_PAD_TX2_RX3__GPIO1_13 +313 MX35_PAD_TX2_RX3__IPU_CSI_D_5 +314 MX35_PAD_TX2_RX3__KPP_COL_0 +315 MX35_PAD_TX1__ESAI_TX1 +316 MX35_PAD_TX1__CCM_PMIC_RDY +317 MX35_PAD_TX1__CSPI1_SS2 +318 MX35_PAD_TX1__EMI_NANDF_CE3 +319 MX35_PAD_TX1__UART2_RI +320 MX35_PAD_TX1__GPIO1_14 +321 MX35_PAD_TX1__IPU_CSI_D_6 +322 MX35_PAD_TX1__KPP_COL_1 +323 MX35_PAD_TX0__ESAI_TX0 +324 MX35_PAD_TX0__SPDIF_SPDIF_EXTCLK +325 MX35_PAD_TX0__CSPI1_SS3 +326 MX35_PAD_TX0__EMI_DTACK_B +327 MX35_PAD_TX0__UART2_DCD +328 MX35_PAD_TX0__GPIO1_15 +329 MX35_PAD_TX0__IPU_CSI_D_7 +330 MX35_PAD_TX0__KPP_COL_2 +331 MX35_PAD_CSPI1_MOSI__CSPI1_MOSI +332 MX35_PAD_CSPI1_MOSI__GPIO1_16 +333 MX35_PAD_CSPI1_MOSI__ECT_CTI_TRIG_OUT1_2 +334 MX35_PAD_CSPI1_MISO__CSPI1_MISO +335 MX35_PAD_CSPI1_MISO__GPIO1_17 +336 MX35_PAD_CSPI1_MISO__ECT_CTI_TRIG_OUT1_3 +337 MX35_PAD_CSPI1_SS0__CSPI1_SS0 +338 MX35_PAD_CSPI1_SS0__OWIRE_LINE +339 MX35_PAD_CSPI1_SS0__CSPI2_SS3 +340 MX35_PAD_CSPI1_SS0__GPIO1_18 +341 MX35_PAD_CSPI1_SS0__ECT_CTI_TRIG_OUT1_4 +342 MX35_PAD_CSPI1_SS1__CSPI1_SS1 +343 MX35_PAD_CSPI1_SS1__PWM_PWMO +344 MX35_PAD_CSPI1_SS1__CCM_CLK32K +345 MX35_PAD_CSPI1_SS1__GPIO1_19 +346 MX35_PAD_CSPI1_SS1__IPU_DIAGB_29 +347 MX35_PAD_CSPI1_SS1__ECT_CTI_TRIG_OUT1_5 +348 MX35_PAD_CSPI1_SCLK__CSPI1_SCLK +349 MX35_PAD_CSPI1_SCLK__GPIO3_4 +350 MX35_PAD_CSPI1_SCLK__IPU_DIAGB_30 +351 MX35_PAD_CSPI1_SCLK__EMI_M3IF_CHOSEN_MASTER_1 +352 MX35_PAD_CSPI1_SPI_RDY__CSPI1_RDY +353 MX35_PAD_CSPI1_SPI_RDY__GPIO3_5 +354 MX35_PAD_CSPI1_SPI_RDY__IPU_DIAGB_31 +355 MX35_PAD_CSPI1_SPI_RDY__EMI_M3IF_CHOSEN_MASTER_2 +356 MX35_PAD_RXD1__UART1_RXD_MUX +357 MX35_PAD_RXD1__CSPI2_MOSI +358 MX35_PAD_RXD1__KPP_COL_4 +359 MX35_PAD_RXD1__GPIO3_6 +360 MX35_PAD_RXD1__ARM11P_TOP_EVNTBUS_16 +361 MX35_PAD_TXD1__UART1_TXD_MUX +362 MX35_PAD_TXD1__CSPI2_MISO +363 MX35_PAD_TXD1__KPP_COL_5 +364 MX35_PAD_TXD1__GPIO3_7 +365 MX35_PAD_TXD1__ARM11P_TOP_EVNTBUS_17 +366 MX35_PAD_RTS1__UART1_RTS +367 MX35_PAD_RTS1__CSPI2_SCLK +368 MX35_PAD_RTS1__I2C3_SCL +369 MX35_PAD_RTS1__IPU_CSI_D_0 +370 MX35_PAD_RTS1__KPP_COL_6 +371 MX35_PAD_RTS1__GPIO3_8 +372 MX35_PAD_RTS1__EMI_NANDF_CE1 +373 MX35_PAD_RTS1__ARM11P_TOP_EVNTBUS_18 +374 MX35_PAD_CTS1__UART1_CTS +375 MX35_PAD_CTS1__CSPI2_RDY +376 MX35_PAD_CTS1__I2C3_SDA +377 MX35_PAD_CTS1__IPU_CSI_D_1 +378 MX35_PAD_CTS1__KPP_COL_7 +379 MX35_PAD_CTS1__GPIO3_9 +380 MX35_PAD_CTS1__EMI_NANDF_CE2 +381 MX35_PAD_CTS1__ARM11P_TOP_EVNTBUS_19 +382 MX35_PAD_RXD2__UART2_RXD_MUX +383 MX35_PAD_RXD2__KPP_ROW_4 +384 MX35_PAD_RXD2__GPIO3_10 +385 MX35_PAD_TXD2__UART2_TXD_MUX +386 MX35_PAD_TXD2__SPDIF_SPDIF_EXTCLK +387 MX35_PAD_TXD2__KPP_ROW_5 +388 MX35_PAD_TXD2__GPIO3_11 +389 MX35_PAD_RTS2__UART2_RTS +390 MX35_PAD_RTS2__SPDIF_SPDIF_IN1 +391 MX35_PAD_RTS2__CAN2_RXCAN +392 MX35_PAD_RTS2__IPU_CSI_D_2 +393 MX35_PAD_RTS2__KPP_ROW_6 +394 MX35_PAD_RTS2__GPIO3_12 +395 MX35_PAD_RTS2__AUDMUX_AUD5_RXC +396 MX35_PAD_RTS2__UART3_RXD_MUX +397 MX35_PAD_CTS2__UART2_CTS +398 MX35_PAD_CTS2__SPDIF_SPDIF_OUT1 +399 MX35_PAD_CTS2__CAN2_TXCAN +400 MX35_PAD_CTS2__IPU_CSI_D_3 +401 MX35_PAD_CTS2__KPP_ROW_7 +402 MX35_PAD_CTS2__GPIO3_13 +403 MX35_PAD_CTS2__AUDMUX_AUD5_RXFS +404 MX35_PAD_CTS2__UART3_TXD_MUX +405 MX35_PAD_RTCK__ARM11P_TOP_RTCK +406 MX35_PAD_TCK__SJC_TCK +407 MX35_PAD_TMS__SJC_TMS +408 MX35_PAD_TDI__SJC_TDI +409 MX35_PAD_TDO__SJC_TDO +410 MX35_PAD_TRSTB__SJC_TRSTB +411 MX35_PAD_DE_B__SJC_DE_B +412 MX35_PAD_SJC_MOD__SJC_MOD +413 MX35_PAD_USBOTG_PWR__USB_TOP_USBOTG_PWR +414 MX35_PAD_USBOTG_PWR__USB_TOP_USBH2_PWR +415 MX35_PAD_USBOTG_PWR__GPIO3_14 +416 MX35_PAD_USBOTG_OC__USB_TOP_USBOTG_OC +417 MX35_PAD_USBOTG_OC__USB_TOP_USBH2_OC +418 MX35_PAD_USBOTG_OC__GPIO3_15 +419 MX35_PAD_LD0__IPU_DISPB_DAT_0 +420 MX35_PAD_LD0__GPIO2_0 +421 MX35_PAD_LD0__SDMA_SDMA_DEBUG_PC_0 +422 MX35_PAD_LD1__IPU_DISPB_DAT_1 +423 MX35_PAD_LD1__GPIO2_1 +424 MX35_PAD_LD1__SDMA_SDMA_DEBUG_PC_1 +425 MX35_PAD_LD2__IPU_DISPB_DAT_2 +426 MX35_PAD_LD2__GPIO2_2 +427 MX35_PAD_LD2__SDMA_SDMA_DEBUG_PC_2 +428 MX35_PAD_LD3__IPU_DISPB_DAT_3 +429 MX35_PAD_LD3__GPIO2_3 +430 MX35_PAD_LD3__SDMA_SDMA_DEBUG_PC_3 +431 MX35_PAD_LD4__IPU_DISPB_DAT_4 +432 MX35_PAD_LD4__GPIO2_4 +433 MX35_PAD_LD4__SDMA_SDMA_DEBUG_PC_4 +434 MX35_PAD_LD5__IPU_DISPB_DAT_5 +435 MX35_PAD_LD5__GPIO2_5 +436 MX35_PAD_LD5__SDMA_SDMA_DEBUG_PC_5 +437 MX35_PAD_LD6__IPU_DISPB_DAT_6 +438 MX35_PAD_LD6__GPIO2_6 +439 MX35_PAD_LD6__SDMA_SDMA_DEBUG_PC_6 +440 MX35_PAD_LD7__IPU_DISPB_DAT_7 +441 MX35_PAD_LD7__GPIO2_7 +442 MX35_PAD_LD7__SDMA_SDMA_DEBUG_PC_7 +443 MX35_PAD_LD8__IPU_DISPB_DAT_8 +444 MX35_PAD_LD8__GPIO2_8 +445 MX35_PAD_LD8__SDMA_SDMA_DEBUG_PC_8 +446 MX35_PAD_LD9__IPU_DISPB_DAT_9 +447 MX35_PAD_LD9__GPIO2_9 +448 MX35_PAD_LD9__SDMA_SDMA_DEBUG_PC_9 +449 MX35_PAD_LD10__IPU_DISPB_DAT_10 +450 MX35_PAD_LD10__GPIO2_10 +451 MX35_PAD_LD10__SDMA_SDMA_DEBUG_PC_10 +452 MX35_PAD_LD11__IPU_DISPB_DAT_11 +453 MX35_PAD_LD11__GPIO2_11 +454 MX35_PAD_LD11__SDMA_SDMA_DEBUG_PC_11 +455 MX35_PAD_LD11__ARM11P_TOP_TRACE_4 +456 MX35_PAD_LD12__IPU_DISPB_DAT_12 +457 MX35_PAD_LD12__GPIO2_12 +458 MX35_PAD_LD12__SDMA_SDMA_DEBUG_PC_12 +459 MX35_PAD_LD12__ARM11P_TOP_TRACE_5 +460 MX35_PAD_LD13__IPU_DISPB_DAT_13 +461 MX35_PAD_LD13__GPIO2_13 +462 MX35_PAD_LD13__SDMA_SDMA_DEBUG_PC_13 +463 MX35_PAD_LD13__ARM11P_TOP_TRACE_6 +464 MX35_PAD_LD14__IPU_DISPB_DAT_14 +465 MX35_PAD_LD14__GPIO2_14 +466 MX35_PAD_LD14__SDMA_SDMA_DEBUG_EVENT_CHANNEL_0 +467 MX35_PAD_LD14__ARM11P_TOP_TRACE_7 +468 MX35_PAD_LD15__IPU_DISPB_DAT_15 +469 MX35_PAD_LD15__GPIO2_15 +470 MX35_PAD_LD15__SDMA_SDMA_DEBUG_EVENT_CHANNEL_1 +471 MX35_PAD_LD15__ARM11P_TOP_TRACE_8 +472 MX35_PAD_LD16__IPU_DISPB_DAT_16 +473 MX35_PAD_LD16__IPU_DISPB_D12_VSYNC +474 MX35_PAD_LD16__GPIO2_16 +475 MX35_PAD_LD16__SDMA_SDMA_DEBUG_EVENT_CHANNEL_2 +476 MX35_PAD_LD16__ARM11P_TOP_TRACE_9 +477 MX35_PAD_LD17__IPU_DISPB_DAT_17 +478 MX35_PAD_LD17__IPU_DISPB_CS2 +479 MX35_PAD_LD17__GPIO2_17 +480 MX35_PAD_LD17__SDMA_SDMA_DEBUG_EVENT_CHANNEL_3 +481 MX35_PAD_LD17__ARM11P_TOP_TRACE_10 +482 MX35_PAD_LD18__IPU_DISPB_DAT_18 +483 MX35_PAD_LD18__IPU_DISPB_D0_VSYNC +484 MX35_PAD_LD18__IPU_DISPB_D12_VSYNC +485 MX35_PAD_LD18__ESDHC3_CMD +486 MX35_PAD_LD18__USB_TOP_USBOTG_DATA_3 +487 MX35_PAD_LD18__GPIO3_24 +488 MX35_PAD_LD18__SDMA_SDMA_DEBUG_EVENT_CHANNEL_4 +489 MX35_PAD_LD18__ARM11P_TOP_TRACE_11 +490 MX35_PAD_LD19__IPU_DISPB_DAT_19 +491 MX35_PAD_LD19__IPU_DISPB_BCLK +492 MX35_PAD_LD19__IPU_DISPB_CS1 +493 MX35_PAD_LD19__ESDHC3_CLK +494 MX35_PAD_LD19__USB_TOP_USBOTG_DIR +495 MX35_PAD_LD19__GPIO3_25 +496 MX35_PAD_LD19__SDMA_SDMA_DEBUG_EVENT_CHANNEL_5 +497 MX35_PAD_LD19__ARM11P_TOP_TRACE_12 +498 MX35_PAD_LD20__IPU_DISPB_DAT_20 +499 MX35_PAD_LD20__IPU_DISPB_CS0 +500 MX35_PAD_LD20__IPU_DISPB_SD_CLK +501 MX35_PAD_LD20__ESDHC3_DAT0 +502 MX35_PAD_LD20__GPIO3_26 +503 MX35_PAD_LD20__SDMA_SDMA_DEBUG_CORE_STATUS_3 +504 MX35_PAD_LD20__ARM11P_TOP_TRACE_13 +505 MX35_PAD_LD21__IPU_DISPB_DAT_21 +506 MX35_PAD_LD21__IPU_DISPB_PAR_RS +507 MX35_PAD_LD21__IPU_DISPB_SER_RS +508 MX35_PAD_LD21__ESDHC3_DAT1 +509 MX35_PAD_LD21__USB_TOP_USBOTG_STP +510 MX35_PAD_LD21__GPIO3_27 +511 MX35_PAD_LD21__SDMA_DEBUG_EVENT_CHANNEL_SEL +512 MX35_PAD_LD21__ARM11P_TOP_TRACE_14 +513 MX35_PAD_LD22__IPU_DISPB_DAT_22 +514 MX35_PAD_LD22__IPU_DISPB_WR +515 MX35_PAD_LD22__IPU_DISPB_SD_D_I +516 MX35_PAD_LD22__ESDHC3_DAT2 +517 MX35_PAD_LD22__USB_TOP_USBOTG_NXT +518 MX35_PAD_LD22__GPIO3_28 +519 MX35_PAD_LD22__SDMA_DEBUG_BUS_ERROR +520 MX35_PAD_LD22__ARM11P_TOP_TRCTL +521 MX35_PAD_LD23__IPU_DISPB_DAT_23 +522 MX35_PAD_LD23__IPU_DISPB_RD +523 MX35_PAD_LD23__IPU_DISPB_SD_D_IO +524 MX35_PAD_LD23__ESDHC3_DAT3 +525 MX35_PAD_LD23__USB_TOP_USBOTG_DATA_7 +526 MX35_PAD_LD23__GPIO3_29 +527 MX35_PAD_LD23__SDMA_DEBUG_MATCHED_DMBUS +528 MX35_PAD_LD23__ARM11P_TOP_TRCLK +529 MX35_PAD_D3_HSYNC__IPU_DISPB_D3_HSYNC +530 MX35_PAD_D3_HSYNC__IPU_DISPB_SD_D_IO +531 MX35_PAD_D3_HSYNC__GPIO3_30 +532 MX35_PAD_D3_HSYNC__SDMA_DEBUG_RTBUFFER_WRITE +533 MX35_PAD_D3_HSYNC__ARM11P_TOP_TRACE_15 +534 MX35_PAD_D3_FPSHIFT__IPU_DISPB_D3_CLK +535 MX35_PAD_D3_FPSHIFT__IPU_DISPB_SD_CLK +536 MX35_PAD_D3_FPSHIFT__GPIO3_31 +537 MX35_PAD_D3_FPSHIFT__SDMA_SDMA_DEBUG_CORE_STATUS_0 +538 MX35_PAD_D3_FPSHIFT__ARM11P_TOP_TRACE_16 +539 MX35_PAD_D3_DRDY__IPU_DISPB_D3_DRDY +540 MX35_PAD_D3_DRDY__IPU_DISPB_SD_D_O +541 MX35_PAD_D3_DRDY__GPIO1_0 +542 MX35_PAD_D3_DRDY__SDMA_SDMA_DEBUG_CORE_STATUS_1 +543 MX35_PAD_D3_DRDY__ARM11P_TOP_TRACE_17 +544 MX35_PAD_CONTRAST__IPU_DISPB_CONTR +545 MX35_PAD_CONTRAST__GPIO1_1 +546 MX35_PAD_CONTRAST__SDMA_SDMA_DEBUG_CORE_STATUS_2 +547 MX35_PAD_CONTRAST__ARM11P_TOP_TRACE_18 +548 MX35_PAD_D3_VSYNC__IPU_DISPB_D3_VSYNC +549 MX35_PAD_D3_VSYNC__IPU_DISPB_CS1 +550 MX35_PAD_D3_VSYNC__GPIO1_2 +551 MX35_PAD_D3_VSYNC__SDMA_DEBUG_YIELD +552 MX35_PAD_D3_VSYNC__ARM11P_TOP_TRACE_19 +553 MX35_PAD_D3_REV__IPU_DISPB_D3_REV +554 MX35_PAD_D3_REV__IPU_DISPB_SER_RS +555 MX35_PAD_D3_REV__GPIO1_3 +556 MX35_PAD_D3_REV__SDMA_DEBUG_BUS_RWB +557 MX35_PAD_D3_REV__ARM11P_TOP_TRACE_20 +558 MX35_PAD_D3_CLS__IPU_DISPB_D3_CLS +559 MX35_PAD_D3_CLS__IPU_DISPB_CS2 +560 MX35_PAD_D3_CLS__GPIO1_4 +561 MX35_PAD_D3_CLS__SDMA_DEBUG_BUS_DEVICE_0 +562 MX35_PAD_D3_CLS__ARM11P_TOP_TRACE_21 +563 MX35_PAD_D3_SPL__IPU_DISPB_D3_SPL +564 MX35_PAD_D3_SPL__IPU_DISPB_D12_VSYNC +565 MX35_PAD_D3_SPL__GPIO1_5 +566 MX35_PAD_D3_SPL__SDMA_DEBUG_BUS_DEVICE_1 +567 MX35_PAD_D3_SPL__ARM11P_TOP_TRACE_22 +568 MX35_PAD_SD1_CMD__ESDHC1_CMD +569 MX35_PAD_SD1_CMD__MSHC_SCLK +570 MX35_PAD_SD1_CMD__IPU_DISPB_D0_VSYNC +571 MX35_PAD_SD1_CMD__USB_TOP_USBOTG_DATA_4 +572 MX35_PAD_SD1_CMD__GPIO1_6 +573 MX35_PAD_SD1_CMD__ARM11P_TOP_TRCTL +574 MX35_PAD_SD1_CLK__ESDHC1_CLK +575 MX35_PAD_SD1_CLK__MSHC_BS +576 MX35_PAD_SD1_CLK__IPU_DISPB_BCLK +577 MX35_PAD_SD1_CLK__USB_TOP_USBOTG_DATA_5 +578 MX35_PAD_SD1_CLK__GPIO1_7 +579 MX35_PAD_SD1_CLK__ARM11P_TOP_TRCLK +580 MX35_PAD_SD1_DATA0__ESDHC1_DAT0 +581 MX35_PAD_SD1_DATA0__MSHC_DATA_0 +582 MX35_PAD_SD1_DATA0__IPU_DISPB_CS0 +583 MX35_PAD_SD1_DATA0__USB_TOP_USBOTG_DATA_6 +584 MX35_PAD_SD1_DATA0__GPIO1_8 +585 MX35_PAD_SD1_DATA0__ARM11P_TOP_TRACE_23 +586 MX35_PAD_SD1_DATA1__ESDHC1_DAT1 +587 MX35_PAD_SD1_DATA1__MSHC_DATA_1 +588 MX35_PAD_SD1_DATA1__IPU_DISPB_PAR_RS +589 MX35_PAD_SD1_DATA1__USB_TOP_USBOTG_DATA_0 +590 MX35_PAD_SD1_DATA1__GPIO1_9 +591 MX35_PAD_SD1_DATA1__ARM11P_TOP_TRACE_24 +592 MX35_PAD_SD1_DATA2__ESDHC1_DAT2 +593 MX35_PAD_SD1_DATA2__MSHC_DATA_2 +594 MX35_PAD_SD1_DATA2__IPU_DISPB_WR +595 MX35_PAD_SD1_DATA2__USB_TOP_USBOTG_DATA_1 +596 MX35_PAD_SD1_DATA2__GPIO1_10 +597 MX35_PAD_SD1_DATA2__ARM11P_TOP_TRACE_25 +598 MX35_PAD_SD1_DATA3__ESDHC1_DAT3 +599 MX35_PAD_SD1_DATA3__MSHC_DATA_3 +600 MX35_PAD_SD1_DATA3__IPU_DISPB_RD +601 MX35_PAD_SD1_DATA3__USB_TOP_USBOTG_DATA_2 +602 MX35_PAD_SD1_DATA3__GPIO1_11 +603 MX35_PAD_SD1_DATA3__ARM11P_TOP_TRACE_26 +604 MX35_PAD_SD2_CMD__ESDHC2_CMD +605 MX35_PAD_SD2_CMD__I2C3_SCL +606 MX35_PAD_SD2_CMD__ESDHC1_DAT4 +607 MX35_PAD_SD2_CMD__IPU_CSI_D_2 +608 MX35_PAD_SD2_CMD__USB_TOP_USBH2_DATA_4 +609 MX35_PAD_SD2_CMD__GPIO2_0 +610 MX35_PAD_SD2_CMD__SPDIF_SPDIF_OUT1 +611 MX35_PAD_SD2_CMD__IPU_DISPB_D12_VSYNC +612 MX35_PAD_SD2_CLK__ESDHC2_CLK +613 MX35_PAD_SD2_CLK__I2C3_SDA +614 MX35_PAD_SD2_CLK__ESDHC1_DAT5 +615 MX35_PAD_SD2_CLK__IPU_CSI_D_3 +616 MX35_PAD_SD2_CLK__USB_TOP_USBH2_DATA_5 +617 MX35_PAD_SD2_CLK__GPIO2_1 +618 MX35_PAD_SD2_CLK__SPDIF_SPDIF_IN1 +619 MX35_PAD_SD2_CLK__IPU_DISPB_CS2 +620 MX35_PAD_SD2_DATA0__ESDHC2_DAT0 +621 MX35_PAD_SD2_DATA0__UART3_RXD_MUX +622 MX35_PAD_SD2_DATA0__ESDHC1_DAT6 +623 MX35_PAD_SD2_DATA0__IPU_CSI_D_4 +624 MX35_PAD_SD2_DATA0__USB_TOP_USBH2_DATA_6 +625 MX35_PAD_SD2_DATA0__GPIO2_2 +626 MX35_PAD_SD2_DATA0__SPDIF_SPDIF_EXTCLK +627 MX35_PAD_SD2_DATA1__ESDHC2_DAT1 +628 MX35_PAD_SD2_DATA1__UART3_TXD_MUX +629 MX35_PAD_SD2_DATA1__ESDHC1_DAT7 +630 MX35_PAD_SD2_DATA1__IPU_CSI_D_5 +631 MX35_PAD_SD2_DATA1__USB_TOP_USBH2_DATA_0 +632 MX35_PAD_SD2_DATA1__GPIO2_3 +633 MX35_PAD_SD2_DATA2__ESDHC2_DAT2 +634 MX35_PAD_SD2_DATA2__UART3_RTS +635 MX35_PAD_SD2_DATA2__CAN1_RXCAN +636 MX35_PAD_SD2_DATA2__IPU_CSI_D_6 +637 MX35_PAD_SD2_DATA2__USB_TOP_USBH2_DATA_1 +638 MX35_PAD_SD2_DATA2__GPIO2_4 +639 MX35_PAD_SD2_DATA3__ESDHC2_DAT3 +640 MX35_PAD_SD2_DATA3__UART3_CTS +641 MX35_PAD_SD2_DATA3__CAN1_TXCAN +642 MX35_PAD_SD2_DATA3__IPU_CSI_D_7 +643 MX35_PAD_SD2_DATA3__USB_TOP_USBH2_DATA_2 +644 MX35_PAD_SD2_DATA3__GPIO2_5 +645 MX35_PAD_ATA_CS0__ATA_CS0 +646 MX35_PAD_ATA_CS0__CSPI1_SS3 +647 MX35_PAD_ATA_CS0__IPU_DISPB_CS1 +648 MX35_PAD_ATA_CS0__GPIO2_6 +649 MX35_PAD_ATA_CS0__IPU_DIAGB_0 +650 MX35_PAD_ATA_CS0__ARM11P_TOP_MAX1_HMASTER_0 +651 MX35_PAD_ATA_CS1__ATA_CS1 +652 MX35_PAD_ATA_CS1__IPU_DISPB_CS2 +653 MX35_PAD_ATA_CS1__CSPI2_SS0 +654 MX35_PAD_ATA_CS1__GPIO2_7 +655 MX35_PAD_ATA_CS1__IPU_DIAGB_1 +656 MX35_PAD_ATA_CS1__ARM11P_TOP_MAX1_HMASTER_1 +657 MX35_PAD_ATA_DIOR__ATA_DIOR +658 MX35_PAD_ATA_DIOR__ESDHC3_DAT0 +659 MX35_PAD_ATA_DIOR__USB_TOP_USBOTG_DIR +660 MX35_PAD_ATA_DIOR__IPU_DISPB_BE0 +661 MX35_PAD_ATA_DIOR__CSPI2_SS1 +662 MX35_PAD_ATA_DIOR__GPIO2_8 +663 MX35_PAD_ATA_DIOR__IPU_DIAGB_2 +664 MX35_PAD_ATA_DIOR__ARM11P_TOP_MAX1_HMASTER_2 +665 MX35_PAD_ATA_DIOW__ATA_DIOW +666 MX35_PAD_ATA_DIOW__ESDHC3_DAT1 +667 MX35_PAD_ATA_DIOW__USB_TOP_USBOTG_STP +668 MX35_PAD_ATA_DIOW__IPU_DISPB_BE1 +669 MX35_PAD_ATA_DIOW__CSPI2_MOSI +670 MX35_PAD_ATA_DIOW__GPIO2_9 +671 MX35_PAD_ATA_DIOW__IPU_DIAGB_3 +672 MX35_PAD_ATA_DIOW__ARM11P_TOP_MAX1_HMASTER_3 +673 MX35_PAD_ATA_DMACK__ATA_DMACK +674 MX35_PAD_ATA_DMACK__ESDHC3_DAT2 +675 MX35_PAD_ATA_DMACK__USB_TOP_USBOTG_NXT +676 MX35_PAD_ATA_DMACK__CSPI2_MISO +677 MX35_PAD_ATA_DMACK__GPIO2_10 +678 MX35_PAD_ATA_DMACK__IPU_DIAGB_4 +679 MX35_PAD_ATA_DMACK__ARM11P_TOP_MAX0_HMASTER_0 +680 MX35_PAD_ATA_RESET_B__ATA_RESET_B +681 MX35_PAD_ATA_RESET_B__ESDHC3_DAT3 +682 MX35_PAD_ATA_RESET_B__USB_TOP_USBOTG_DATA_0 +683 MX35_PAD_ATA_RESET_B__IPU_DISPB_SD_D_O +684 MX35_PAD_ATA_RESET_B__CSPI2_RDY +685 MX35_PAD_ATA_RESET_B__GPIO2_11 +686 MX35_PAD_ATA_RESET_B__IPU_DIAGB_5 +687 MX35_PAD_ATA_RESET_B__ARM11P_TOP_MAX0_HMASTER_1 +688 MX35_PAD_ATA_IORDY__ATA_IORDY +689 MX35_PAD_ATA_IORDY__ESDHC3_DAT4 +690 MX35_PAD_ATA_IORDY__USB_TOP_USBOTG_DATA_1 +691 MX35_PAD_ATA_IORDY__IPU_DISPB_SD_D_IO +692 MX35_PAD_ATA_IORDY__ESDHC2_DAT4 +693 MX35_PAD_ATA_IORDY__GPIO2_12 +694 MX35_PAD_ATA_IORDY__IPU_DIAGB_6 +695 MX35_PAD_ATA_IORDY__ARM11P_TOP_MAX0_HMASTER_2 +696 MX35_PAD_ATA_DATA0__ATA_DATA_0 +697 MX35_PAD_ATA_DATA0__ESDHC3_DAT5 +698 MX35_PAD_ATA_DATA0__USB_TOP_USBOTG_DATA_2 +699 MX35_PAD_ATA_DATA0__IPU_DISPB_D12_VSYNC +700 MX35_PAD_ATA_DATA0__ESDHC2_DAT5 +701 MX35_PAD_ATA_DATA0__GPIO2_13 +702 MX35_PAD_ATA_DATA0__IPU_DIAGB_7 +703 MX35_PAD_ATA_DATA0__ARM11P_TOP_MAX0_HMASTER_3 +704 MX35_PAD_ATA_DATA1__ATA_DATA_1 +705 MX35_PAD_ATA_DATA1__ESDHC3_DAT6 +706 MX35_PAD_ATA_DATA1__USB_TOP_USBOTG_DATA_3 +707 MX35_PAD_ATA_DATA1__IPU_DISPB_SD_CLK +708 MX35_PAD_ATA_DATA1__ESDHC2_DAT6 +709 MX35_PAD_ATA_DATA1__GPIO2_14 +710 MX35_PAD_ATA_DATA1__IPU_DIAGB_8 +711 MX35_PAD_ATA_DATA1__ARM11P_TOP_TRACE_27 +712 MX35_PAD_ATA_DATA2__ATA_DATA_2 +713 MX35_PAD_ATA_DATA2__ESDHC3_DAT7 +714 MX35_PAD_ATA_DATA2__USB_TOP_USBOTG_DATA_4 +715 MX35_PAD_ATA_DATA2__IPU_DISPB_SER_RS +716 MX35_PAD_ATA_DATA2__ESDHC2_DAT7 +717 MX35_PAD_ATA_DATA2__GPIO2_15 +718 MX35_PAD_ATA_DATA2__IPU_DIAGB_9 +719 MX35_PAD_ATA_DATA2__ARM11P_TOP_TRACE_28 +720 MX35_PAD_ATA_DATA3__ATA_DATA_3 +721 MX35_PAD_ATA_DATA3__ESDHC3_CLK +722 MX35_PAD_ATA_DATA3__USB_TOP_USBOTG_DATA_5 +723 MX35_PAD_ATA_DATA3__CSPI2_SCLK +724 MX35_PAD_ATA_DATA3__GPIO2_16 +725 MX35_PAD_ATA_DATA3__IPU_DIAGB_10 +726 MX35_PAD_ATA_DATA3__ARM11P_TOP_TRACE_29 +727 MX35_PAD_ATA_DATA4__ATA_DATA_4 +728 MX35_PAD_ATA_DATA4__ESDHC3_CMD +729 MX35_PAD_ATA_DATA4__USB_TOP_USBOTG_DATA_6 +730 MX35_PAD_ATA_DATA4__GPIO2_17 +731 MX35_PAD_ATA_DATA4__IPU_DIAGB_11 +732 MX35_PAD_ATA_DATA4__ARM11P_TOP_TRACE_30 +733 MX35_PAD_ATA_DATA5__ATA_DATA_5 +734 MX35_PAD_ATA_DATA5__USB_TOP_USBOTG_DATA_7 +735 MX35_PAD_ATA_DATA5__GPIO2_18 +736 MX35_PAD_ATA_DATA5__IPU_DIAGB_12 +737 MX35_PAD_ATA_DATA5__ARM11P_TOP_TRACE_31 +738 MX35_PAD_ATA_DATA6__ATA_DATA_6 +739 MX35_PAD_ATA_DATA6__CAN1_TXCAN +740 MX35_PAD_ATA_DATA6__UART1_DTR +741 MX35_PAD_ATA_DATA6__AUDMUX_AUD6_TXD +742 MX35_PAD_ATA_DATA6__GPIO2_19 +743 MX35_PAD_ATA_DATA6__IPU_DIAGB_13 +744 MX35_PAD_ATA_DATA7__ATA_DATA_7 +745 MX35_PAD_ATA_DATA7__CAN1_RXCAN +746 MX35_PAD_ATA_DATA7__UART1_DSR +747 MX35_PAD_ATA_DATA7__AUDMUX_AUD6_RXD +748 MX35_PAD_ATA_DATA7__GPIO2_20 +749 MX35_PAD_ATA_DATA7__IPU_DIAGB_14 +750 MX35_PAD_ATA_DATA8__ATA_DATA_8 +751 MX35_PAD_ATA_DATA8__UART3_RTS +752 MX35_PAD_ATA_DATA8__UART1_RI +753 MX35_PAD_ATA_DATA8__AUDMUX_AUD6_TXC +754 MX35_PAD_ATA_DATA8__GPIO2_21 +755 MX35_PAD_ATA_DATA8__IPU_DIAGB_15 +756 MX35_PAD_ATA_DATA9__ATA_DATA_9 +757 MX35_PAD_ATA_DATA9__UART3_CTS +758 MX35_PAD_ATA_DATA9__UART1_DCD +759 MX35_PAD_ATA_DATA9__AUDMUX_AUD6_TXFS +760 MX35_PAD_ATA_DATA9__GPIO2_22 +761 MX35_PAD_ATA_DATA9__IPU_DIAGB_16 +762 MX35_PAD_ATA_DATA10__ATA_DATA_10 +763 MX35_PAD_ATA_DATA10__UART3_RXD_MUX +764 MX35_PAD_ATA_DATA10__AUDMUX_AUD6_RXC +765 MX35_PAD_ATA_DATA10__GPIO2_23 +766 MX35_PAD_ATA_DATA10__IPU_DIAGB_17 +767 MX35_PAD_ATA_DATA11__ATA_DATA_11 +768 MX35_PAD_ATA_DATA11__UART3_TXD_MUX +769 MX35_PAD_ATA_DATA11__AUDMUX_AUD6_RXFS +770 MX35_PAD_ATA_DATA11__GPIO2_24 +771 MX35_PAD_ATA_DATA11__IPU_DIAGB_18 +772 MX35_PAD_ATA_DATA12__ATA_DATA_12 +773 MX35_PAD_ATA_DATA12__I2C3_SCL +774 MX35_PAD_ATA_DATA12__GPIO2_25 +775 MX35_PAD_ATA_DATA12__IPU_DIAGB_19 +776 MX35_PAD_ATA_DATA13__ATA_DATA_13 +777 MX35_PAD_ATA_DATA13__I2C3_SDA +778 MX35_PAD_ATA_DATA13__GPIO2_26 +779 MX35_PAD_ATA_DATA13__IPU_DIAGB_20 +780 MX35_PAD_ATA_DATA14__ATA_DATA_14 +781 MX35_PAD_ATA_DATA14__IPU_CSI_D_0 +782 MX35_PAD_ATA_DATA14__KPP_ROW_0 +783 MX35_PAD_ATA_DATA14__GPIO2_27 +784 MX35_PAD_ATA_DATA14__IPU_DIAGB_21 +785 MX35_PAD_ATA_DATA15__ATA_DATA_15 +786 MX35_PAD_ATA_DATA15__IPU_CSI_D_1 +787 MX35_PAD_ATA_DATA15__KPP_ROW_1 +788 MX35_PAD_ATA_DATA15__GPIO2_28 +789 MX35_PAD_ATA_DATA15__IPU_DIAGB_22 +790 MX35_PAD_ATA_INTRQ__ATA_INTRQ +791 MX35_PAD_ATA_INTRQ__IPU_CSI_D_2 +792 MX35_PAD_ATA_INTRQ__KPP_ROW_2 +793 MX35_PAD_ATA_INTRQ__GPIO2_29 +794 MX35_PAD_ATA_INTRQ__IPU_DIAGB_23 +795 MX35_PAD_ATA_BUFF_EN__ATA_BUFFER_EN +796 MX35_PAD_ATA_BUFF_EN__IPU_CSI_D_3 +797 MX35_PAD_ATA_BUFF_EN__KPP_ROW_3 +798 MX35_PAD_ATA_BUFF_EN__GPIO2_30 +799 MX35_PAD_ATA_BUFF_EN__IPU_DIAGB_24 +800 MX35_PAD_ATA_DMARQ__ATA_DMARQ +801 MX35_PAD_ATA_DMARQ__IPU_CSI_D_4 +802 MX35_PAD_ATA_DMARQ__KPP_COL_0 +803 MX35_PAD_ATA_DMARQ__GPIO2_31 +804 MX35_PAD_ATA_DMARQ__IPU_DIAGB_25 +805 MX35_PAD_ATA_DMARQ__ECT_CTI_TRIG_IN1_4 +806 MX35_PAD_ATA_DA0__ATA_DA_0 +807 MX35_PAD_ATA_DA0__IPU_CSI_D_5 +808 MX35_PAD_ATA_DA0__KPP_COL_1 +809 MX35_PAD_ATA_DA0__GPIO3_0 +810 MX35_PAD_ATA_DA0__IPU_DIAGB_26 +811 MX35_PAD_ATA_DA0__ECT_CTI_TRIG_IN1_5 +812 MX35_PAD_ATA_DA1__ATA_DA_1 +813 MX35_PAD_ATA_DA1__IPU_CSI_D_6 +814 MX35_PAD_ATA_DA1__KPP_COL_2 +815 MX35_PAD_ATA_DA1__GPIO3_1 +816 MX35_PAD_ATA_DA1__IPU_DIAGB_27 +817 MX35_PAD_ATA_DA1__ECT_CTI_TRIG_IN1_6 +818 MX35_PAD_ATA_DA2__ATA_DA_2 +819 MX35_PAD_ATA_DA2__IPU_CSI_D_7 +820 MX35_PAD_ATA_DA2__KPP_COL_3 +821 MX35_PAD_ATA_DA2__GPIO3_2 +822 MX35_PAD_ATA_DA2__IPU_DIAGB_28 +823 MX35_PAD_ATA_DA2__ECT_CTI_TRIG_IN1_7 +824 MX35_PAD_MLB_CLK__MLB_MLBCLK +825 MX35_PAD_MLB_CLK__GPIO3_3 +826 MX35_PAD_MLB_DAT__MLB_MLBDAT +827 MX35_PAD_MLB_DAT__GPIO3_4 +828 MX35_PAD_MLB_SIG__MLB_MLBSIG +829 MX35_PAD_MLB_SIG__GPIO3_5 +830 MX35_PAD_FEC_TX_CLK__FEC_TX_CLK +831 MX35_PAD_FEC_TX_CLK__ESDHC1_DAT4 +832 MX35_PAD_FEC_TX_CLK__UART3_RXD_MUX +833 MX35_PAD_FEC_TX_CLK__USB_TOP_USBH2_DIR +834 MX35_PAD_FEC_TX_CLK__CSPI2_MOSI +835 MX35_PAD_FEC_TX_CLK__GPIO3_6 +836 MX35_PAD_FEC_TX_CLK__IPU_DISPB_D12_VSYNC +837 MX35_PAD_FEC_TX_CLK__ARM11P_TOP_EVNTBUS_0 +838 MX35_PAD_FEC_RX_CLK__FEC_RX_CLK +839 MX35_PAD_FEC_RX_CLK__ESDHC1_DAT5 +840 MX35_PAD_FEC_RX_CLK__UART3_TXD_MUX +841 MX35_PAD_FEC_RX_CLK__USB_TOP_USBH2_STP +842 MX35_PAD_FEC_RX_CLK__CSPI2_MISO +843 MX35_PAD_FEC_RX_CLK__GPIO3_7 +844 MX35_PAD_FEC_RX_CLK__IPU_DISPB_SD_D_I +845 MX35_PAD_FEC_RX_CLK__ARM11P_TOP_EVNTBUS_1 +846 MX35_PAD_FEC_RX_DV__FEC_RX_DV +847 MX35_PAD_FEC_RX_DV__ESDHC1_DAT6 +848 MX35_PAD_FEC_RX_DV__UART3_RTS +849 MX35_PAD_FEC_RX_DV__USB_TOP_USBH2_NXT +850 MX35_PAD_FEC_RX_DV__CSPI2_SCLK +851 MX35_PAD_FEC_RX_DV__GPIO3_8 +852 MX35_PAD_FEC_RX_DV__IPU_DISPB_SD_CLK +853 MX35_PAD_FEC_RX_DV__ARM11P_TOP_EVNTBUS_2 +854 MX35_PAD_FEC_COL__FEC_COL +855 MX35_PAD_FEC_COL__ESDHC1_DAT7 +856 MX35_PAD_FEC_COL__UART3_CTS +857 MX35_PAD_FEC_COL__USB_TOP_USBH2_DATA_0 +858 MX35_PAD_FEC_COL__CSPI2_RDY +859 MX35_PAD_FEC_COL__GPIO3_9 +860 MX35_PAD_FEC_COL__IPU_DISPB_SER_RS +861 MX35_PAD_FEC_COL__ARM11P_TOP_EVNTBUS_3 +862 MX35_PAD_FEC_RDATA0__FEC_RDATA_0 +863 MX35_PAD_FEC_RDATA0__PWM_PWMO +864 MX35_PAD_FEC_RDATA0__UART3_DTR +865 MX35_PAD_FEC_RDATA0__USB_TOP_USBH2_DATA_1 +866 MX35_PAD_FEC_RDATA0__CSPI2_SS0 +867 MX35_PAD_FEC_RDATA0__GPIO3_10 +868 MX35_PAD_FEC_RDATA0__IPU_DISPB_CS1 +869 MX35_PAD_FEC_RDATA0__ARM11P_TOP_EVNTBUS_4 +870 MX35_PAD_FEC_TDATA0__FEC_TDATA_0 +871 MX35_PAD_FEC_TDATA0__SPDIF_SPDIF_OUT1 +872 MX35_PAD_FEC_TDATA0__UART3_DSR +873 MX35_PAD_FEC_TDATA0__USB_TOP_USBH2_DATA_2 +874 MX35_PAD_FEC_TDATA0__CSPI2_SS1 +875 MX35_PAD_FEC_TDATA0__GPIO3_11 +876 MX35_PAD_FEC_TDATA0__IPU_DISPB_CS0 +877 MX35_PAD_FEC_TDATA0__ARM11P_TOP_EVNTBUS_5 +878 MX35_PAD_FEC_TX_EN__FEC_TX_EN +879 MX35_PAD_FEC_TX_EN__SPDIF_SPDIF_IN1 +880 MX35_PAD_FEC_TX_EN__UART3_RI +881 MX35_PAD_FEC_TX_EN__USB_TOP_USBH2_DATA_3 +882 MX35_PAD_FEC_TX_EN__GPIO3_12 +883 MX35_PAD_FEC_TX_EN__IPU_DISPB_PAR_RS +884 MX35_PAD_FEC_TX_EN__ARM11P_TOP_EVNTBUS_6 +885 MX35_PAD_FEC_MDC__FEC_MDC +886 MX35_PAD_FEC_MDC__CAN2_TXCAN +887 MX35_PAD_FEC_MDC__UART3_DCD +888 MX35_PAD_FEC_MDC__USB_TOP_USBH2_DATA_4 +889 MX35_PAD_FEC_MDC__GPIO3_13 +890 MX35_PAD_FEC_MDC__IPU_DISPB_WR +891 MX35_PAD_FEC_MDC__ARM11P_TOP_EVNTBUS_7 +892 MX35_PAD_FEC_MDIO__FEC_MDIO +893 MX35_PAD_FEC_MDIO__CAN2_RXCAN +894 MX35_PAD_FEC_MDIO__USB_TOP_USBH2_DATA_5 +895 MX35_PAD_FEC_MDIO__GPIO3_14 +896 MX35_PAD_FEC_MDIO__IPU_DISPB_RD +897 MX35_PAD_FEC_MDIO__ARM11P_TOP_EVNTBUS_8 +898 MX35_PAD_FEC_TX_ERR__FEC_TX_ERR +899 MX35_PAD_FEC_TX_ERR__OWIRE_LINE +900 MX35_PAD_FEC_TX_ERR__SPDIF_SPDIF_EXTCLK +901 MX35_PAD_FEC_TX_ERR__USB_TOP_USBH2_DATA_6 +902 MX35_PAD_FEC_TX_ERR__GPIO3_15 +903 MX35_PAD_FEC_TX_ERR__IPU_DISPB_D0_VSYNC +904 MX35_PAD_FEC_TX_ERR__ARM11P_TOP_EVNTBUS_9 +905 MX35_PAD_FEC_RX_ERR__FEC_RX_ERR +906 MX35_PAD_FEC_RX_ERR__IPU_CSI_D_0 +907 MX35_PAD_FEC_RX_ERR__USB_TOP_USBH2_DATA_7 +908 MX35_PAD_FEC_RX_ERR__KPP_COL_4 +909 MX35_PAD_FEC_RX_ERR__GPIO3_16 +910 MX35_PAD_FEC_RX_ERR__IPU_DISPB_SD_D_IO +911 MX35_PAD_FEC_CRS__FEC_CRS +912 MX35_PAD_FEC_CRS__IPU_CSI_D_1 +913 MX35_PAD_FEC_CRS__USB_TOP_USBH2_PWR +914 MX35_PAD_FEC_CRS__KPP_COL_5 +915 MX35_PAD_FEC_CRS__GPIO3_17 +916 MX35_PAD_FEC_CRS__IPU_FLASH_STROBE +917 MX35_PAD_FEC_RDATA1__FEC_RDATA_1 +918 MX35_PAD_FEC_RDATA1__IPU_CSI_D_2 +919 MX35_PAD_FEC_RDATA1__AUDMUX_AUD6_RXC +920 MX35_PAD_FEC_RDATA1__USB_TOP_USBH2_OC +921 MX35_PAD_FEC_RDATA1__KPP_COL_6 +922 MX35_PAD_FEC_RDATA1__GPIO3_18 +923 MX35_PAD_FEC_RDATA1__IPU_DISPB_BE0 +924 MX35_PAD_FEC_TDATA1__FEC_TDATA_1 +925 MX35_PAD_FEC_TDATA1__IPU_CSI_D_3 +926 MX35_PAD_FEC_TDATA1__AUDMUX_AUD6_RXFS +927 MX35_PAD_FEC_TDATA1__KPP_COL_7 +928 MX35_PAD_FEC_TDATA1__GPIO3_19 +929 MX35_PAD_FEC_TDATA1__IPU_DISPB_BE1 +930 MX35_PAD_FEC_RDATA2__FEC_RDATA_2 +931 MX35_PAD_FEC_RDATA2__IPU_CSI_D_4 +932 MX35_PAD_FEC_RDATA2__AUDMUX_AUD6_TXD +933 MX35_PAD_FEC_RDATA2__KPP_ROW_4 +934 MX35_PAD_FEC_RDATA2__GPIO3_20 +935 MX35_PAD_FEC_TDATA2__FEC_TDATA_2 +936 MX35_PAD_FEC_TDATA2__IPU_CSI_D_5 +937 MX35_PAD_FEC_TDATA2__AUDMUX_AUD6_RXD +938 MX35_PAD_FEC_TDATA2__KPP_ROW_5 +939 MX35_PAD_FEC_TDATA2__GPIO3_21 +940 MX35_PAD_FEC_RDATA3__FEC_RDATA_3 +941 MX35_PAD_FEC_RDATA3__IPU_CSI_D_6 +942 MX35_PAD_FEC_RDATA3__AUDMUX_AUD6_TXC +943 MX35_PAD_FEC_RDATA3__KPP_ROW_6 +944 MX35_PAD_FEC_RDATA3__GPIO3_22 +945 MX35_PAD_FEC_TDATA3__FEC_TDATA_3 +946 MX35_PAD_FEC_TDATA3__IPU_CSI_D_7 +947 MX35_PAD_FEC_TDATA3__AUDMUX_AUD6_TXFS +948 MX35_PAD_FEC_TDATA3__KPP_ROW_7 +949 MX35_PAD_FEC_TDATA3__GPIO3_23 +950 MX35_PAD_EXT_ARMCLK__CCM_EXT_ARMCLK +951 MX35_PAD_TEST_MODE__TCU_TEST_MODE diff --git a/Documentation/devicetree/bindings/pinctrl/lantiq,falcon-pinumx.txt b/Documentation/devicetree/bindings/pinctrl/lantiq,falcon-pinumx.txt new file mode 100644 index 000000000000..daa768956069 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/lantiq,falcon-pinumx.txt @@ -0,0 +1,83 @@ +Lantiq FALCON pinmux controller + +Required properties: +- compatible: "lantiq,pinctrl-falcon" +- reg: Should contain the physical address and length of the gpio/pinmux + register range + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +Lantiq's pin configuration nodes act as a container for an abitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those group(s), and two pin configuration parameters: +pull-up and open-drain + +The name of each subnode is not important as long as it is unique; all subnodes +should be enumerated and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + +We support 2 types of nodes. + +Definition of mux function groups: + +Required subnode-properties: +- lantiq,groups : An array of strings. Each string contains the name of a group. + Valid values for these names are listed below. +- lantiq,function: A string containing the name of the function to mux to the + group. Valid values for function names are listed below. + +Valid values for group and function names: + + mux groups: + por, ntr, ntr8k, hrst, mdio, bootled, asc0, spi, spi cs0, spi cs1, i2c, + jtag, slic, pcm, asc1 + + functions: + rst, ntr, mdio, led, asc, spi, i2c, jtag, slic, pcm + + +Definition of pin configurations: + +Required subnode-properties: +- lantiq,pins : An array of strings. Each string contains the name of a pin. + Valid values for these names are listed below. + +Optional subnode-properties: +- lantiq,pull: Integer, representing the pull-down/up to apply to the pin. + 0: none, 1: down +- lantiq,drive-current: Boolean, enables drive-current +- lantiq,slew-rate: Boolean, enables slew-rate + +Example: + pinmux0 { + compatible = "lantiq,pinctrl-falcon"; + pinctrl-names = "default"; + pinctrl-0 = <&state_default>; + + state_default: pinmux { + asc0 { + lantiq,groups = "asc0"; + lantiq,function = "asc"; + }; + ntr { + lantiq,groups = "ntr8k"; + lantiq,function = "ntr"; + }; + i2c { + lantiq,groups = "i2c"; + lantiq,function = "i2c"; + }; + hrst { + lantiq,groups = "hrst"; + lantiq,function = "rst"; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/pinctrl/lantiq,xway-pinumx.txt b/Documentation/devicetree/bindings/pinctrl/lantiq,xway-pinumx.txt new file mode 100644 index 000000000000..b5469db1d7ad --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/lantiq,xway-pinumx.txt @@ -0,0 +1,97 @@ +Lantiq XWAY pinmux controller + +Required properties: +- compatible: "lantiq,pinctrl-xway" or "lantiq,pinctrl-xr9" +- reg: Should contain the physical address and length of the gpio/pinmux + register range + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +Lantiq's pin configuration nodes act as a container for an abitrary number of +subnodes. Each of these subnodes represents some desired configuration for a +pin, a group, or a list of pins or groups. This configuration can include the +mux function to select on those group(s), and two pin configuration parameters: +pull-up and open-drain + +The name of each subnode is not important as long as it is unique; all subnodes +should be enumerated and processed purely based on their content. + +Each subnode only affects those parameters that are explicitly listed. In +other words, a subnode that lists a mux function but no pin configuration +parameters implies no information about any pin configuration parameters. +Similarly, a pin subnode that describes a pullup parameter implies no +information about e.g. the mux function. + +We support 2 types of nodes. + +Definition of mux function groups: + +Required subnode-properties: +- lantiq,groups : An array of strings. Each string contains the name of a group. + Valid values for these names are listed below. +- lantiq,function: A string containing the name of the function to mux to the + group. Valid values for function names are listed below. + +Valid values for group and function names: + + mux groups: + exin0, exin1, exin2, jtag, ebu a23, ebu a24, ebu a25, ebu clk, ebu cs1, + ebu wait, nand ale, nand cs1, nand cle, spi, spi_cs1, spi_cs2, spi_cs3, + spi_cs4, spi_cs5, spi_cs6, asc0, asc0 cts rts, stp, nmi , gpt1, gpt2, + gpt3, clkout0, clkout1, clkout2, clkout3, gnt1, gnt2, gnt3, req1, req2, + req3 + + additional mux groups (XR9 only): + mdio, nand rdy, nand rd, exin3, exin4, gnt4, req4 + + functions: + spi, asc, cgu, jtag, exin, stp, gpt, nmi, pci, ebu, mdio + + + +Definition of pin configurations: + +Required subnode-properties: +- lantiq,pins : An array of strings. Each string contains the name of a pin. + Valid values for these names are listed below. + +Optional subnode-properties: +- lantiq,pull: Integer, representing the pull-down/up to apply to the pin. + 0: none, 1: down, 2: up. +- lantiq,open-drain: Boolean, enables open-drain on the defined pin. + +Valid values for XWAY pin names: + Pinconf pins can be referenced via the names io0-io31. + +Valid values for XR9 pin names: + Pinconf pins can be referenced via the names io0-io55. + +Example: + gpio: pinmux@E100B10 { + compatible = "lantiq,pinctrl-xway"; + pinctrl-names = "default"; + pinctrl-0 = <&state_default>; + + #gpio-cells = <2>; + gpio-controller; + reg = <0xE100B10 0xA0>; + + state_default: pinmux { + stp { + lantiq,groups = "stp"; + lantiq,function = "stp"; + }; + pci { + lantiq,groups = "gnt1"; + lantiq,function = "pci"; + }; + conf_out { + lantiq,pins = "io4", "io5", "io6"; /* stp */ + lantiq,open-drain; + lantiq,pull = <0>; + }; + }; + }; + diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,armada-370-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,armada-370-pinctrl.txt new file mode 100644 index 000000000000..01ef408e205f --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/marvell,armada-370-pinctrl.txt @@ -0,0 +1,95 @@ +* Marvell Armada 370 SoC pinctrl driver for mpp + +Please refer to marvell,mvebu-pinctrl.txt in this directory for common binding +part and usage. + +Required properties: +- compatible: "marvell,88f6710-pinctrl" + +Available mpp pins/groups and functions: +Note: brackets (x) are not part of the mpp name for marvell,function and given +only for more detailed description in this document. + +name pins functions +================================================================================ +mpp0 0 gpio, uart0(rxd) +mpp1 1 gpo, uart0(txd) +mpp2 2 gpio, i2c0(sck), uart0(txd) +mpp3 3 gpio, i2c0(sda), uart0(rxd) +mpp4 4 gpio, cpu_pd(vdd) +mpp5 5 gpo, ge0(txclko), uart1(txd), spi1(clk), audio(mclk) +mpp6 6 gpio, ge0(txd0), sata0(prsnt), tdm(rst), audio(sdo) +mpp7 7 gpo, ge0(txd1), tdm(tdx), audio(lrclk) +mpp8 8 gpio, ge0(txd2), uart0(rts), tdm(drx), audio(bclk) +mpp9 9 gpo, ge0(txd3), uart1(txd), sd0(clk), audio(spdifo) +mpp10 10 gpio, ge0(txctl), uart0(cts), tdm(fsync), audio(sdi) +mpp11 11 gpio, ge0(rxd0), uart1(rxd), sd0(cmd), spi0(cs1), + sata1(prsnt), spi1(cs1) +mpp12 12 gpio, ge0(rxd1), i2c1(sda), sd0(d0), spi1(cs0), + audio(spdifi) +mpp13 13 gpio, ge0(rxd2), i2c1(sck), sd0(d1), tdm(pclk), + audio(rmclk) +mpp14 14 gpio, ge0(rxd3), pcie(clkreq0), sd0(d2), spi1(mosi), + spi0(cs2) +mpp15 15 gpio, ge0(rxctl), pcie(clkreq1), sd0(d3), spi1(miso), + spi0(cs3) +mpp16 16 gpio, ge0(rxclk), uart1(rxd), tdm(int), audio(extclk) +mpp17 17 gpo, ge(mdc) +mpp18 18 gpio, ge(mdio) +mpp19 19 gpio, ge0(txclk), ge1(txclkout), tdm(pclk) +mpp20 20 gpo, ge0(txd4), ge1(txd0) +mpp21 21 gpo, ge0(txd5), ge1(txd1), uart1(txd) +mpp22 22 gpo, ge0(txd6), ge1(txd2), uart0(rts) +mpp23 23 gpo, ge0(txd7), ge1(txd3), spi1(mosi) +mpp24 24 gpio, ge0(col), ge1(txctl), spi1(cs0) +mpp25 25 gpio, ge0(rxerr), ge1(rxd0), uart1(rxd) +mpp26 26 gpio, ge0(crs), ge1(rxd1), spi1(miso) +mpp27 27 gpio, ge0(rxd4), ge1(rxd2), uart0(cts) +mpp28 28 gpio, ge0(rxd5), ge1(rxd3) +mpp29 29 gpio, ge0(rxd6), ge1(rxctl), i2c1(sda) +mpp30 30 gpio, ge0(rxd7), ge1(rxclk), i2c1(sck) +mpp31 31 gpio, tclk, ge0(txerr) +mpp32 32 gpio, spi0(cs0) +mpp33 33 gpio, dev(bootcs), spi0(cs0) +mpp34 34 gpo, dev(wen0), spi0(mosi) +mpp35 35 gpo, dev(oen), spi0(sck) +mpp36 36 gpo, dev(a1), spi0(miso) +mpp37 37 gpo, dev(a0), sata0(prsnt) +mpp38 38 gpio, dev(ready), uart1(cts), uart0(cts) +mpp39 39 gpo, dev(ad0), audio(spdifo) +mpp40 40 gpio, dev(ad1), uart1(rts), uart0(rts) +mpp41 41 gpio, dev(ad2), uart1(rxd) +mpp42 42 gpo, dev(ad3), uart1(txd) +mpp43 43 gpo, dev(ad4), audio(bclk) +mpp44 44 gpo, dev(ad5), audio(mclk) +mpp45 45 gpo, dev(ad6), audio(lrclk) +mpp46 46 gpo, dev(ad7), audio(sdo) +mpp47 47 gpo, dev(ad8), sd0(clk), audio(spdifo) +mpp48 48 gpio, dev(ad9), uart0(rts), sd0(cmd), sata1(prsnt), + spi0(cs1) +mpp49 49 gpio, dev(ad10), pcie(clkreq1), sd0(d0), spi1(cs0), + audio(spdifi) +mpp50 50 gpio, dev(ad11), uart0(cts), sd0(d1), spi1(miso), + audio(rmclk) +mpp51 51 gpio, dev(ad12), i2c1(sda), sd0(d2), spi1(mosi) +mpp52 52 gpio, dev(ad13), i2c1(sck), sd0(d3), spi1(sck) +mpp53 53 gpio, dev(ad14), sd0(clk), tdm(pclk), spi0(cs2), + pcie(clkreq1) +mpp54 54 gpo, dev(ad15), tdm(dtx) +mpp55 55 gpio, dev(cs1), uart1(txd), tdm(rst), sata1(prsnt), + sata0(prsnt) +mpp56 56 gpio, dev(cs2), uart1(cts), uart0(cts), spi0(cs3), + pcie(clkreq0), spi1(cs1) +mpp57 57 gpio, dev(cs3), uart1(rxd), tdm(fsync), sata0(prsnt), + audio(sdo) +mpp58 58 gpio, dev(cs0), uart1(rts), tdm(int), audio(extclk), + uart0(rts) +mpp59 59 gpo, dev(ale0), uart1(rts), uart0(rts), audio(bclk) +mpp60 60 gpio, dev(ale1), uart1(rxd), sata0(prsnt), pcie(rst-out), + audio(sdi) +mpp61 61 gpo, dev(wen1), uart1(txd), audio(rclk) +mpp62 62 gpio, dev(a2), uart1(cts), tdm(drx), pcie(clkreq0), + audio(mclk), uart0(cts) +mpp63 63 gpo, spi0(sck), tclk +mpp64 64 gpio, spi0(miso), spi0-1(cs1) +mpp65 65 gpio, spi0(mosi), spi0-1(cs2) diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,armada-xp-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,armada-xp-pinctrl.txt new file mode 100644 index 000000000000..bfa0a2e5e0cb --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/marvell,armada-xp-pinctrl.txt @@ -0,0 +1,100 @@ +* Marvell Armada XP SoC pinctrl driver for mpp + +Please refer to marvell,mvebu-pinctrl.txt in this directory for common binding +part and usage. + +Required properties: +- compatible: "marvell,mv78230-pinctrl", "marvell,mv78260-pinctrl", + "marvell,mv78460-pinctrl" + +This driver supports all Armada XP variants, i.e. mv78230, mv78260, and mv78460. + +Available mpp pins/groups and functions: +Note: brackets (x) are not part of the mpp name for marvell,function and given +only for more detailed description in this document. + +* Marvell Armada XP (all variants) + +name pins functions +================================================================================ +mpp0 0 gpio, ge0(txclko), lcd(d0) +mpp1 1 gpio, ge0(txd0), lcd(d1) +mpp2 2 gpio, ge0(txd1), lcd(d2) +mpp3 3 gpio, ge0(txd2), lcd(d3) +mpp4 4 gpio, ge0(txd3), lcd(d4) +mpp5 5 gpio, ge0(txctl), lcd(d5) +mpp6 6 gpio, ge0(rxd0), lcd(d6) +mpp7 7 gpio, ge0(rxd1), lcd(d7) +mpp8 8 gpio, ge0(rxd2), lcd(d8) +mpp9 9 gpio, ge0(rxd3), lcd(d9) +mpp10 10 gpio, ge0(rxctl), lcd(d10) +mpp11 11 gpio, ge0(rxclk), lcd(d11) +mpp12 12 gpio, ge0(txd4), ge1(txd0), lcd(d12) +mpp13 13 gpio, ge0(txd5), ge1(txd1), lcd(d13) +mpp14 14 gpio, ge0(txd6), ge1(txd2), lcd(d15) +mpp15 15 gpio, ge0(txd7), ge1(txd3), lcd(d16) +mpp16 16 gpio, ge0(txd7), ge1(txd3), lcd(d16) +mpp17 17 gpio, ge0(col), ge1(txctl), lcd(d17) +mpp18 18 gpio, ge0(rxerr), ge1(rxd0), lcd(d18), ptp(trig) +mpp19 19 gpio, ge0(crs), ge1(rxd1), lcd(d19), ptp(evreq) +mpp20 20 gpio, ge0(rxd4), ge1(rxd2), lcd(d20), ptp(clk) +mpp21 21 gpio, ge0(rxd5), ge1(rxd3), lcd(d21), mem(bat) +mpp22 22 gpio, ge0(rxd6), ge1(rxctl), lcd(d22), sata0(prsnt) +mpp23 23 gpio, ge0(rxd7), ge1(rxclk), lcd(d23), sata1(prsnt) +mpp24 24 gpio, lcd(hsync), sata1(prsnt), nf(bootcs-re), tdm(rst) +mpp25 25 gpio, lcd(vsync), sata0(prsnt), nf(bootcs-we), tdm(pclk) +mpp26 26 gpio, lcd(clk), tdm(fsync), vdd(cpu1-pd) +mpp27 27 gpio, lcd(e), tdm(dtx), ptp(trig) +mpp28 28 gpio, lcd(pwm), tdm(drx), ptp(evreq) +mpp29 29 gpio, lcd(ref-clk), tdm(int0), ptp(clk), vdd(cpu0-pd) +mpp30 30 gpio, tdm(int1), sd0(clk) +mpp31 31 gpio, tdm(int2), sd0(cmd), vdd(cpu0-pd) +mpp32 32 gpio, tdm(int3), sd0(d0), vdd(cpu1-pd) +mpp33 33 gpio, tdm(int4), sd0(d1), mem(bat) +mpp34 34 gpio, tdm(int5), sd0(d2), sata0(prsnt) +mpp35 35 gpio, tdm(int6), sd0(d3), sata1(prsnt) +mpp36 36 gpio, spi(mosi) +mpp37 37 gpio, spi(miso) +mpp38 38 gpio, spi(sck) +mpp39 39 gpio, spi(cs0) +mpp40 40 gpio, spi(cs1), uart2(cts), lcd(vga-hsync), vdd(cpu1-pd), + pcie(clkreq0) +mpp41 41 gpio, spi(cs2), uart2(rts), lcd(vga-vsync), sata1(prsnt), + pcie(clkreq1) +mpp42 42 gpio, uart2(rxd), uart0(cts), tdm(int7), tdm-1(timer), + vdd(cpu0-pd) +mpp43 43 gpio, uart2(txd), uart0(rts), spi(cs3), pcie(rstout), + vdd(cpu2-3-pd){1} +mpp44 44 gpio, uart2(cts), uart3(rxd), spi(cs4), pcie(clkreq2), + mem(bat) +mpp45 45 gpio, uart2(rts), uart3(txd), spi(cs5), sata1(prsnt) +mpp46 46 gpio, uart3(rts), uart1(rts), spi(cs6), sata0(prsnt) +mpp47 47 gpio, uart3(cts), uart1(cts), spi(cs7), pcie(clkreq3), + ref(clkout) +mpp48 48 gpio, tclk, dev(burst/last) + +* Marvell Armada XP (mv78260 and mv78460 only) + +name pins functions +================================================================================ +mpp49 49 gpio, dev(we3) +mpp50 50 gpio, dev(we2) +mpp51 51 gpio, dev(ad16) +mpp52 52 gpio, dev(ad17) +mpp53 53 gpio, dev(ad18) +mpp54 54 gpio, dev(ad19) +mpp55 55 gpio, dev(ad20), vdd(cpu0-pd) +mpp56 56 gpio, dev(ad21), vdd(cpu1-pd) +mpp57 57 gpio, dev(ad22), vdd(cpu2-3-pd){1} +mpp58 58 gpio, dev(ad23) +mpp59 59 gpio, dev(ad24) +mpp60 60 gpio, dev(ad25) +mpp61 61 gpio, dev(ad26) +mpp62 62 gpio, dev(ad27) +mpp63 63 gpio, dev(ad28) +mpp64 64 gpio, dev(ad29) +mpp65 65 gpio, dev(ad30) +mpp66 66 gpio, dev(ad31) + +Notes: +* {1} vdd(cpu2-3-pd) only available on mv78460. diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,dove-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,dove-pinctrl.txt new file mode 100644 index 000000000000..a648aaad6110 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/marvell,dove-pinctrl.txt @@ -0,0 +1,72 @@ +* Marvell Dove SoC pinctrl driver for mpp + +Please refer to marvell,mvebu-pinctrl.txt in this directory for common binding +part and usage. + +Required properties: +- compatible: "marvell,dove-pinctrl" +- clocks: (optional) phandle of pdma clock + +Available mpp pins/groups and functions: +Note: brackets (x) are not part of the mpp name for marvell,function and given +only for more detailed description in this document. + +name pins functions +================================================================================ +mpp0 0 gpio, pmu, uart2(rts), sdio0(cd), lcd0(pwm) +mpp1 1 gpio, pmu, uart2(cts), sdio0(wp), lcd1(pwm) +mpp2 2 gpio, pmu, uart2(txd), sdio0(buspwr), sata(prsnt), + uart1(rts) +mpp3 3 gpio, pmu, uart2(rxd), sdio0(ledctrl), sata(act), + uart1(cts), lcd-spi(cs1) +mpp4 4 gpio, pmu, uart3(rts), sdio1(cd), spi1(miso) +mpp5 5 gpio, pmu, uart3(cts), sdio1(wp), spi1(cs) +mpp6 6 gpio, pmu, uart3(txd), sdio1(buspwr), spi1(mosi) +mpp7 7 gpio, pmu, uart3(rxd), sdio1(ledctrl), spi1(sck) +mpp8 8 gpio, pmu, watchdog(rstout) +mpp9 9 gpio, pmu, pex1(clkreq) +mpp10 10 gpio, pmu, ssp(sclk) +mpp11 11 gpio, pmu, sata(prsnt), sata-1(act), sdio0(ledctrl), + sdio1(ledctrl), pex0(clkreq) +mpp12 12 gpio, pmu, uart2(rts), audio0(extclk), sdio1(cd), sata(act) +mpp13 13 gpio, pmu, uart2(cts), audio1(extclk), sdio1(wp), + ssp(extclk) +mpp14 14 gpio, pmu, uart2(txd), sdio1(buspwr), ssp(rxd) +mpp15 15 gpio, pmu, uart2(rxd), sdio1(ledctrl), ssp(sfrm) +mpp16 16 gpio, uart3(rts), sdio0(cd), ac97(sdi1), lcd-spi(cs1) +mpp17 17 gpio, uart3(cts), sdio0(wp), ac97(sdi2), twsi(sda), + ac97-1(sysclko) +mpp18 18 gpio, uart3(txd), sdio0(buspwr), ac97(sdi3), lcd0(pwm) +mpp19 19 gpio, uart3(rxd), sdio0(ledctrl), twsi(sck) +mpp20 20 gpio, sdio0(cd), sdio1(cd), spi1(miso), lcd-spi(miso), + ac97(sysclko) +mpp21 21 gpio, sdio0(wp), sdio1(wp), spi1(cs), lcd-spi(cs0), + uart1(cts), ssp(sfrm) +mpp22 22 gpio, sdio0(buspwr), sdio1(buspwr), spi1(mosi), + lcd-spi(mosi), uart1(cts), ssp(txd) +mpp23 23 gpio, sdio0(ledctrl), sdio1(ledctrl), spi1(sck), + lcd-spi(sck), ssp(sclk) +mpp_camera 24-39 gpio, camera +mpp_sdio0 40-45 gpio, sdio0 +mpp_sdio1 46-51 gpio, sdio1 +mpp_audio1 52-57 gpio, i2s1/spdifo, i2s1, spdifo, twsi, ssp/spdifo, ssp, + ssp/twsi +mpp_spi0 58-61 gpio, spi0 +mpp_uart1 62-63 gpio, uart1 +mpp_nand 64-71 gpo, nand +audio0 - i2s, ac97 +twsi - none, opt1, opt2, opt3 + +Notes: +* group "mpp_audio1" allows the following functions and gpio pins: + - gpio : gpio on pins 52-57 + - i2s1/spdifo : audio1 i2s on pins 52-55 and spdifo on 57, no gpios + - i2s1 : audio1 i2s on pins 52-55, gpio on pins 56,57 + - spdifo : spdifo on pin 57, gpio on pins 52-55 + - twsi : twsi on pins 56,57, gpio on pins 52-55 + - ssp/spdifo : ssp on pins 52-55, spdifo on pin 57, no gpios + - ssp : ssp on pins 52-55, gpio on pins 56,57 + - ssp/twsi : ssp on pins 52-55, twsi on pins 56,57, no gpios +* group "audio0" internally muxes i2s0 or ac97 controller to the dedicated + audio0 pins. +* group "twsi" internally muxes twsi controller to the dedicated or option pins. diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt new file mode 100644 index 000000000000..361bccb7ec89 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/marvell,kirkwood-pinctrl.txt @@ -0,0 +1,279 @@ +* Marvell Kirkwood SoC pinctrl driver for mpp + +Please refer to marvell,mvebu-pinctrl.txt in this directory for common binding +part and usage. + +Required properties: +- compatible: "marvell,88f6180-pinctrl", + "marvell,88f6190-pinctrl", "marvell,88f6192-pinctrl", + "marvell,88f6281-pinctrl", "marvell,88f6282-pinctrl" + +This driver supports all kirkwood variants, i.e. 88f6180, 88f619x, and 88f628x. + +Available mpp pins/groups and functions: +Note: brackets (x) are not part of the mpp name for marvell,function and given +only for more detailed description in this document. + +* Marvell Kirkwood 88f6180 + +name pins functions +================================================================================ +mpp0 0 gpio, nand(io2), spi(cs) +mpp1 1 gpo, nand(io3), spi(mosi) +mpp2 2 gpo, nand(io4), spi(sck) +mpp3 3 gpo, nand(io5), spi(miso) +mpp4 4 gpio, nand(io6), uart0(rxd), ptp(clk) +mpp5 5 gpo, nand(io7), uart0(txd), ptp(trig) +mpp6 6 sysrst(out), spi(mosi), ptp(trig) +mpp7 7 gpo, pex(rsto), spi(cs), ptp(trig) +mpp8 8 gpio, twsi0(sda), uart0(rts), uart1(rts), ptp(clk), + mii(col) +mpp9 9 gpio, twsi(sck), uart0(cts), uart1(cts), ptp(evreq), + mii(crs) +mpp10 10 gpo, spi(sck), uart0(txd), ptp(trig) +mpp11 11 gpio, spi(miso), uart0(rxd), ptp(clk), ptp-1(evreq), + ptp-2(trig) +mpp12 12 gpo, sdio(clk) +mpp13 13 gpio, sdio(cmd), uart1(txd) +mpp14 14 gpio, sdio(d0), uart1(rxd), mii(col) +mpp15 15 gpio, sdio(d1), uart0(rts), uart1(txd) +mpp16 16 gpio, sdio(d2), uart0(cts), uart1(rxd), mii(crs) +mpp17 17 gpio, sdio(d3) +mpp18 18 gpo, nand(io0) +mpp19 19 gpo, nand(io1) +mpp20 20 gpio, mii(rxerr) +mpp21 21 gpio, audio(spdifi) +mpp22 22 gpio, audio(spdifo) +mpp23 23 gpio, audio(rmclk) +mpp24 24 gpio, audio(bclk) +mpp25 25 gpio, audio(sdo) +mpp26 26 gpio, audio(lrclk) +mpp27 27 gpio, audio(mclk) +mpp28 28 gpio, audio(sdi) +mpp29 29 gpio, audio(extclk) + +* Marvell Kirkwood 88f6190 + +name pins functions +================================================================================ +mpp0 0 gpio, nand(io2), spi(cs) +mpp1 1 gpo, nand(io3), spi(mosi) +mpp2 2 gpo, nand(io4), spi(sck) +mpp3 3 gpo, nand(io5), spi(miso) +mpp4 4 gpio, nand(io6), uart0(rxd), ptp(clk) +mpp5 5 gpo, nand(io7), uart0(txd), ptp(trig), sata0(act) +mpp6 6 sysrst(out), spi(mosi), ptp(trig) +mpp7 7 gpo, pex(rsto), spi(cs), ptp(trig) +mpp8 8 gpio, twsi0(sda), uart0(rts), uart1(rts), ptp(clk), + mii(col), mii-1(rxerr) +mpp9 9 gpio, twsi(sck), uart0(cts), uart1(cts), ptp(evreq), + mii(crs), sata0(prsnt) +mpp10 10 gpo, spi(sck), uart0(txd), ptp(trig) +mpp11 11 gpio, spi(miso), uart0(rxd), ptp(clk), ptp-1(evreq), + ptp-2(trig), sata0(act) +mpp12 12 gpo, sdio(clk) +mpp13 13 gpio, sdio(cmd), uart1(txd) +mpp14 14 gpio, sdio(d0), uart1(rxd), mii(col) +mpp15 15 gpio, sdio(d1), uart0(rts), uart1(txd), sata0(act) +mpp16 16 gpio, sdio(d2), uart0(cts), uart1(rxd), mii(crs) +mpp17 17 gpio, sdio(d3), sata0(prsnt) +mpp18 18 gpo, nand(io0) +mpp19 19 gpo, nand(io1) +mpp20 20 gpio, ge1(txd0) +mpp21 21 gpio, ge1(txd1), sata0(act) +mpp22 22 gpio, ge1(txd2) +mpp23 23 gpio, ge1(txd3), sata0(prsnt) +mpp24 24 gpio, ge1(rxd0) +mpp25 25 gpio, ge1(rxd1) +mpp26 26 gpio, ge1(rxd2) +mpp27 27 gpio, ge1(rxd3) +mpp28 28 gpio, ge1(col) +mpp29 29 gpio, ge1(txclk) +mpp30 30 gpio, ge1(rxclk) +mpp31 31 gpio, ge1(rxclk) +mpp32 32 gpio, ge1(txclko) +mpp33 33 gpo, ge1(txclk) +mpp34 34 gpio, ge1(txen) +mpp35 35 gpio, ge1(rxerr), sata0(act), mii(rxerr) + +* Marvell Kirkwood 88f6192 + +name pins functions +================================================================================ +mpp0 0 gpio, nand(io2), spi(cs) +mpp1 1 gpo, nand(io3), spi(mosi) +mpp2 2 gpo, nand(io4), spi(sck) +mpp3 3 gpo, nand(io5), spi(miso) +mpp4 4 gpio, nand(io6), uart0(rxd), ptp(clk), sata1(act) +mpp5 5 gpo, nand(io7), uart0(txd), ptp(trig), sata0(act) +mpp6 6 sysrst(out), spi(mosi), ptp(trig) +mpp7 7 gpo, pex(rsto), spi(cs), ptp(trig) +mpp8 8 gpio, twsi0(sda), uart0(rts), uart1(rts), ptp(clk), + mii(col), mii-1(rxerr), sata1(prsnt) +mpp9 9 gpio, twsi(sck), uart0(cts), uart1(cts), ptp(evreq), + mii(crs), sata0(prsnt) +mpp10 10 gpo, spi(sck), uart0(txd), ptp(trig), sata1(act) +mpp11 11 gpio, spi(miso), uart0(rxd), ptp(clk), ptp-1(evreq), + ptp-2(trig), sata0(act) +mpp12 12 gpo, sdio(clk) +mpp13 13 gpio, sdio(cmd), uart1(txd) +mpp14 14 gpio, sdio(d0), uart1(rxd), mii(col), sata1(prsnt) +mpp15 15 gpio, sdio(d1), uart0(rts), uart1(txd), sata0(act) +mpp16 16 gpio, sdio(d2), uart0(cts), uart1(rxd), mii(crs), + sata1(act) +mpp17 17 gpio, sdio(d3), sata0(prsnt) +mpp18 18 gpo, nand(io0) +mpp19 19 gpo, nand(io1) +mpp20 20 gpio, ge1(txd0), ts(mp0), tdm(tx0ql), audio(spdifi), + sata1(act) +mpp21 21 gpio, ge1(txd1), sata0(act), ts(mp1), tdm(rx0ql), + audio(spdifo) +mpp22 22 gpio, ge1(txd2), ts(mp2), tdm(tx2ql), audio(rmclk), + sata1(prsnt) +mpp23 23 gpio, ge1(txd3), sata0(prsnt), ts(mp3), tdm(rx2ql), + audio(bclk) +mpp24 24 gpio, ge1(rxd0), ts(mp4), tdm(spi-cs0), audio(sdo) +mpp25 25 gpio, ge1(rxd1), ts(mp5), tdm(spi-sck), audio(lrclk) +mpp26 26 gpio, ge1(rxd2), ts(mp6), tdm(spi-miso), audio(mclk) +mpp27 27 gpio, ge1(rxd3), ts(mp7), tdm(spi-mosi), audio(sdi) +mpp28 28 gpio, ge1(col), ts(mp8), tdm(int), audio(extclk) +mpp29 29 gpio, ge1(txclk), ts(mp9), tdm(rst) +mpp30 30 gpio, ge1(rxclk), ts(mp10), tdm(pclk) +mpp31 31 gpio, ge1(rxclk), ts(mp11), tdm(fs) +mpp32 32 gpio, ge1(txclko), ts(mp12), tdm(drx) +mpp33 33 gpo, ge1(txclk), tdm(drx) +mpp34 34 gpio, ge1(txen), tdm(spi-cs1) +mpp35 35 gpio, ge1(rxerr), sata0(act), mii(rxerr), tdm(tx0ql) + +* Marvell Kirkwood 88f6281 + +name pins functions +================================================================================ +mpp0 0 gpio, nand(io2), spi(cs) +mpp1 1 gpo, nand(io3), spi(mosi) +mpp2 2 gpo, nand(io4), spi(sck) +mpp3 3 gpo, nand(io5), spi(miso) +mpp4 4 gpio, nand(io6), uart0(rxd), ptp(clk), sata1(act) +mpp5 5 gpo, nand(io7), uart0(txd), ptp(trig), sata0(act) +mpp6 6 sysrst(out), spi(mosi), ptp(trig) +mpp7 7 gpo, pex(rsto), spi(cs), ptp(trig) +mpp8 8 gpio, twsi0(sda), uart0(rts), uart1(rts), ptp(clk), + mii(col), mii-1(rxerr), sata1(prsnt) +mpp9 9 gpio, twsi(sck), uart0(cts), uart1(cts), ptp(evreq), + mii(crs), sata0(prsnt) +mpp10 10 gpo, spi(sck), uart0(txd), ptp(trig), sata1(act) +mpp11 11 gpio, spi(miso), uart0(rxd), ptp(clk), ptp-1(evreq), + ptp-2(trig), sata0(act) +mpp12 12 gpio, sdio(clk) +mpp13 13 gpio, sdio(cmd), uart1(txd) +mpp14 14 gpio, sdio(d0), uart1(rxd), mii(col), sata1(prsnt) +mpp15 15 gpio, sdio(d1), uart0(rts), uart1(txd), sata0(act) +mpp16 16 gpio, sdio(d2), uart0(cts), uart1(rxd), mii(crs), + sata1(act) +mpp17 17 gpio, sdio(d3), sata0(prsnt) +mpp18 18 gpo, nand(io0) +mpp19 19 gpo, nand(io1) +mpp20 20 gpio, ge1(txd0), ts(mp0), tdm(tx0ql), audio(spdifi), + sata1(act) +mpp21 21 gpio, ge1(txd1), sata0(act), ts(mp1), tdm(rx0ql), + audio(spdifo) +mpp22 22 gpio, ge1(txd2), ts(mp2), tdm(tx2ql), audio(rmclk), + sata1(prsnt) +mpp23 23 gpio, ge1(txd3), sata0(prsnt), ts(mp3), tdm(rx2ql), + audio(bclk) +mpp24 24 gpio, ge1(rxd0), ts(mp4), tdm(spi-cs0), audio(sdo) +mpp25 25 gpio, ge1(rxd1), ts(mp5), tdm(spi-sck), audio(lrclk) +mpp26 26 gpio, ge1(rxd2), ts(mp6), tdm(spi-miso), audio(mclk) +mpp27 27 gpio, ge1(rxd3), ts(mp7), tdm(spi-mosi), audio(sdi) +mpp28 28 gpio, ge1(col), ts(mp8), tdm(int), audio(extclk) +mpp29 29 gpio, ge1(txclk), ts(mp9), tdm(rst) +mpp30 30 gpio, ge1(rxclk), ts(mp10), tdm(pclk) +mpp31 31 gpio, ge1(rxclk), ts(mp11), tdm(fs) +mpp32 32 gpio, ge1(txclko), ts(mp12), tdm(drx) +mpp33 33 gpo, ge1(txclk), tdm(drx) +mpp34 34 gpio, ge1(txen), tdm(spi-cs1), sata1(act) +mpp35 35 gpio, ge1(rxerr), sata0(act), mii(rxerr), tdm(tx0ql) +mpp36 36 gpio, ts(mp0), tdm(spi-cs1), audio(spdifi) +mpp37 37 gpio, ts(mp1), tdm(tx2ql), audio(spdifo) +mpp38 38 gpio, ts(mp2), tdm(rx2ql), audio(rmclk) +mpp39 39 gpio, ts(mp3), tdm(spi-cs0), audio(bclk) +mpp40 40 gpio, ts(mp4), tdm(spi-sck), audio(sdo) +mpp41 41 gpio, ts(mp5), tdm(spi-miso), audio(lrclk) +mpp42 42 gpio, ts(mp6), tdm(spi-mosi), audio(mclk) +mpp43 43 gpio, ts(mp7), tdm(int), audio(sdi) +mpp44 44 gpio, ts(mp8), tdm(rst), audio(extclk) +mpp45 45 gpio, ts(mp9), tdm(pclk) +mpp46 46 gpio, ts(mp10), tdm(fs) +mpp47 47 gpio, ts(mp11), tdm(drx) +mpp48 48 gpio, ts(mp12), tdm(dtx) +mpp49 49 gpio, ts(mp9), tdm(rx0ql), ptp(clk) + +* Marvell Kirkwood 88f6282 + +name pins functions +================================================================================ +mpp0 0 gpio, nand(io2), spi(cs) +mpp1 1 gpo, nand(io3), spi(mosi) +mpp2 2 gpo, nand(io4), spi(sck) +mpp3 3 gpo, nand(io5), spi(miso) +mpp4 4 gpio, nand(io6), uart0(rxd), sata1(act), lcd(hsync) +mpp5 5 gpo, nand(io7), uart0(txd), sata0(act), lcd(vsync) +mpp6 6 sysrst(out), spi(mosi) +mpp7 7 gpo, spi(cs), lcd(pwm) +mpp8 8 gpio, twsi0(sda), uart0(rts), uart1(rts), mii(col), + mii-1(rxerr), sata1(prsnt) +mpp9 9 gpio, twsi(sck), uart0(cts), uart1(cts), mii(crs), + sata0(prsnt) +mpp10 10 gpo, spi(sck), uart0(txd), sata1(act) +mpp11 11 gpio, spi(miso), uart0(rxd), sata0(act) +mpp12 12 gpo, sdio(clk), audio(spdifo), spi(mosi), twsi(sda) +mpp13 13 gpio, sdio(cmd), uart1(txd), audio(rmclk), lcd(pwm) +mpp14 14 gpio, sdio(d0), uart1(rxd), mii(col), sata1(prsnt), + audio(spdifi), audio-1(sdi) +mpp15 15 gpio, sdio(d1), uart0(rts), uart1(txd), sata0(act), + spi(cs) +mpp16 16 gpio, sdio(d2), uart0(cts), uart1(rxd), mii(crs), + sata1(act), lcd(extclk) +mpp17 17 gpio, sdio(d3), sata0(prsnt), sata1(act), twsi1(sck) +mpp18 18 gpo, nand(io0), pex(clkreq) +mpp19 19 gpo, nand(io1) +mpp20 20 gpio, ge1(txd0), ts(mp0), tdm(tx0ql), audio(spdifi), + sata1(act), lcd(d0) +mpp21 21 gpio, ge1(txd1), sata0(act), ts(mp1), tdm(rx0ql), + audio(spdifo), lcd(d1) +mpp22 22 gpio, ge1(txd2), ts(mp2), tdm(tx2ql), audio(rmclk), + sata1(prsnt), lcd(d2) +mpp23 23 gpio, ge1(txd3), sata0(prsnt), ts(mp3), tdm(rx2ql), + audio(bclk), lcd(d3) +mpp24 24 gpio, ge1(rxd0), ts(mp4), tdm(spi-cs0), audio(sdo), + lcd(d4) +mpp25 25 gpio, ge1(rxd1), ts(mp5), tdm(spi-sck), audio(lrclk), + lcd(d5) +mpp26 26 gpio, ge1(rxd2), ts(mp6), tdm(spi-miso), audio(mclk), + lcd(d6) +mpp27 27 gpio, ge1(rxd3), ts(mp7), tdm(spi-mosi), audio(sdi), + lcd(d7) +mpp28 28 gpio, ge1(col), ts(mp8), tdm(int), audio(extclk), + lcd(d8) +mpp29 29 gpio, ge1(txclk), ts(mp9), tdm(rst), lcd(d9) +mpp30 30 gpio, ge1(rxclk), ts(mp10), tdm(pclk), lcd(d10) +mpp31 31 gpio, ge1(rxclk), ts(mp11), tdm(fs), lcd(d11) +mpp32 32 gpio, ge1(txclko), ts(mp12), tdm(drx), lcd(d12) +mpp33 33 gpo, ge1(txclk), tdm(drx), lcd(d13) +mpp34 34 gpio, ge1(txen), tdm(spi-cs1), sata1(act), lcd(d14) +mpp35 35 gpio, ge1(rxerr), sata0(act), mii(rxerr), tdm(tx0ql), + lcd(d15) +mpp36 36 gpio, ts(mp0), tdm(spi-cs1), audio(spdifi), twsi1(sda) +mpp37 37 gpio, ts(mp1), tdm(tx2ql), audio(spdifo), twsi1(sck) +mpp38 38 gpio, ts(mp2), tdm(rx2ql), audio(rmclk), lcd(d18) +mpp39 39 gpio, ts(mp3), tdm(spi-cs0), audio(bclk), lcd(d19) +mpp40 40 gpio, ts(mp4), tdm(spi-sck), audio(sdo), lcd(d20) +mpp41 41 gpio, ts(mp5), tdm(spi-miso), audio(lrclk), lcd(d21) +mpp42 42 gpio, ts(mp6), tdm(spi-mosi), audio(mclk), lcd(d22) +mpp43 43 gpio, ts(mp7), tdm(int), audio(sdi), lcd(d23) +mpp44 44 gpio, ts(mp8), tdm(rst), audio(extclk), lcd(clk) +mpp45 45 gpio, ts(mp9), tdm(pclk), lcd(e) +mpp46 46 gpio, ts(mp10), tdm(fs), lcd(hsync) +mpp47 47 gpio, ts(mp11), tdm(drx), lcd(vsync) +mpp48 48 gpio, ts(mp12), tdm(dtx), lcd(d16) +mpp49 49 gpo, tdm(rx0ql), pex(clkreq), lcd(d17) diff --git a/Documentation/devicetree/bindings/pinctrl/marvell,mvebu-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/marvell,mvebu-pinctrl.txt new file mode 100644 index 000000000000..0a26c3aa4e6d --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/marvell,mvebu-pinctrl.txt @@ -0,0 +1,46 @@ +* Marvell SoC pinctrl core driver for mpp + +The pinctrl driver enables Marvell SoCs to configure the multi-purpose pins +(mpp) to a specific function. For each SoC family there is a SoC specific +driver using this core driver. + +Please refer to pinctrl-bindings.txt in this directory for details of the +common pinctrl bindings used by client devices, including the meaning of the +phrase "pin configuration node". + +A Marvell SoC pin configuration node is a node of a group of pins which can +be used for a specific device or function. Each node requires one or more +mpp pins or group of pins and a mpp function common to all pins. + +Required properties for pinctrl driver: +- compatible: "marvell,<soc>-pinctrl" + Please refer to each marvell,<soc>-pinctrl.txt binding doc for supported SoCs. + +Required properties for pin configuration node: +- marvell,pins: string array of mpp pins or group of pins to be muxed. +- marvell,function: string representing a function to mux to for all + marvell,pins given in this pin configuration node. The function has to be + common for all marvell,pins. Please refer to marvell,<soc>-pinctrl.txt for + valid pin/pin group names and available function names for each SoC. + +Examples: + +uart1: serial@12100 { + compatible = "ns16550a"; + reg = <0x12100 0x100>; + reg-shift = <2>; + interrupts = <7>; + + pinctrl-0 = <&pmx_uart1_sw>; + pinctrl-names = "default"; +}; + +pinctrl: pinctrl@d0200 { + compatible = "marvell,dove-pinctrl"; + reg = <0xd0200 0x20>; + + pmx_uart1_sw: pmx-uart1-sw { + marvell,pins = "mpp_uart1"; + marvell,function = "uart1"; + }; +}; diff --git a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt index 5187f0dd8b28..2c81e45f1374 100644 --- a/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt +++ b/Documentation/devicetree/bindings/pinctrl/pinctrl-single.txt @@ -14,10 +14,12 @@ Optional properties: - pinctrl-single,function-off : function off mode for disabled state if available and same for all registers; if not specified, disabling of pin functions is ignored +- pinctrl-single,bit-per-mux : boolean to indicate that one register controls + more than one pin -This driver assumes that there is only one register for each pin, -and uses the common pinctrl bindings as specified in the pinctrl-bindings.txt -document in this directory. +This driver assumes that there is only one register for each pin (unless the +pinctrl-single,bit-per-mux is set), and uses the common pinctrl bindings as +specified in the pinctrl-bindings.txt document in this directory. The pin configuration nodes for pinctrl-single are specified as pinctrl register offset and value pairs using pinctrl-single,pins. Only the bits @@ -31,6 +33,15 @@ device pinctrl register, and 0x118 contains the desired value of the pinctrl register. See the device example and static board pins example below for more information. +In case when one register changes more than one pin's mux the +pinctrl-single,bits need to be used which takes three parameters: + + pinctrl-single,bits = <0xdc 0x18, 0xff>; + +Where 0xdc is the offset from the pinctrl register base address for the +device pinctrl register, 0x18 is the desired value, and 0xff is the sub mask to +be used when applying this change to the register. + Example: /* SoC common file */ @@ -55,6 +66,15 @@ pmx_wkup: pinmux@4a31e040 { pinctrl-single,function-mask = <0xffff>; }; +control_devconf0: pinmux@48002274 { + compatible = "pinctrl-single"; + reg = <0x48002274 4>; /* Single register */ + #address-cells = <1>; + #size-cells = <0>; + pinctrl-single,bit-per-mux; + pinctrl-single,register-width = <32>; + pinctrl-single,function-mask = <0x5F>; +}; /* board specific .dts file */ @@ -87,6 +107,21 @@ pmx_wkup: pinmux@4a31e040 { }; }; +&control_devconf0 { + mcbsp1_pins: pinmux_mcbsp1_pins { + pinctrl-single,bits = < + 0x00 0x18 0x18 /* FSR/CLKR signal from FSX/CLKX pin */ + >; + }; + + mcbsp2_clks_pins: pinmux_mcbsp2_clks_pins { + pinctrl-single,bits = < + 0x00 0x40 0x40 /* McBSP2 CLKS from McBSP_CLKS pin */ + >; + }; + +}; + &uart2 { pinctrl-names = "default"; pinctrl-0 = <&uart2_pins>; diff --git a/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt new file mode 100644 index 000000000000..03dee50532f5 --- /dev/null +++ b/Documentation/devicetree/bindings/pinctrl/samsung-pinctrl.txt @@ -0,0 +1,196 @@ +Samsung GPIO and Pin Mux/Config controller + +Samsung's ARM based SoC's integrates a GPIO and Pin mux/config hardware +controller. It controls the input/output settings on the available pads/pins +and also provides ability to multiplex and configure the output of various +on-chip controllers onto these pads. + +Required Properties: +- compatible: should be one of the following. + - "samsung,pinctrl-exynos4210": for Exynos4210 compatible pin-controller. + - "samsung,pinctrl-exynos5250": for Exynos5250 compatible pin-controller. + +- reg: Base address of the pin controller hardware module and length of + the address space it occupies. + +- interrupts: interrupt specifier for the controller. The format and value of + the interrupt specifier depends on the interrupt parent for the controller. + +- Pin mux/config groups as child nodes: The pin mux (selecting pin function + mode) and pin config (pull up/down, driver strength) settings are represented + as child nodes of the pin-controller node. There should be atleast one + child node and there is no limit on the count of these child nodes. + + The child node should contain a list of pin(s) on which a particular pin + function selection or pin configuration (or both) have to applied. This + list of pins is specified using the property name "samsung,pins". There + should be atleast one pin specfied for this property and there is no upper + limit on the count of pins that can be specified. The pins are specified + using pin names which are derived from the hardware manual of the SoC. As + an example, the pins in GPA0 bank of the pin controller can be represented + as "gpa0-0", "gpa0-1", "gpa0-2" and so on. The names should be in lower case. + The format of the pin names should be (as per the hardware manual) + "[pin bank name]-[pin number within the bank]". + + The pin function selection that should be applied on the pins listed in the + child node is specified using the "samsung,pin-function" property. The value + of this property that should be applied to each of the pins listed in the + "samsung,pins" property should be picked from the hardware manual of the SoC + for the specified pin group. This property is optional in the child node if + no specific function selection is desired for the pins listed in the child + node. The value of this property is used as-is to program the pin-controller + function selector register of the pin-bank. + + The child node can also optionally specify one or more of the pin + configuration that should be applied on all the pins listed in the + "samsung,pins" property of the child node. The following pin configuration + properties are supported. + + - samsung,pin-pud: Pull up/down configuration. + - samsung,pin-drv: Drive strength configuration. + - samsung,pin-pud-pdn: Pull up/down configuration in power down mode. + - samsung,pin-drv-pdn: Drive strength configuration in power down mode. + + The values specified by these config properties should be derived from the + hardware manual and these values are programmed as-is into the pin + pull up/down and driver strength register of the pin-controller. + + Note: A child should include atleast a pin function selection property or + pin configuration property (one or more) or both. + + The client nodes that require a particular pin function selection and/or + pin configuration should use the bindings listed in the "pinctrl-bindings.txt" + file. + +External GPIO and Wakeup Interrupts: + +The controller supports two types of external interrupts over gpio. The first +is the external gpio interrupt and second is the external wakeup interrupts. +The difference between the two is that the external wakeup interrupts can be +used as system wakeup events. + +A. External GPIO Interrupts: For supporting external gpio interrupts, the + following properties should be specified in the pin-controller device node. + +- interrupt-controller: identifies the controller node as interrupt-parent. +- #interrupt-cells: the value of this property should be 2. + - First Cell: represents the external gpio interrupt number local to the + external gpio interrupt space of the controller. + - Second Cell: flags to identify the type of the interrupt + - 1 = rising edge triggered + - 2 = falling edge triggered + - 3 = rising and falling edge triggered + - 4 = high level triggered + - 8 = low level triggered + +B. External Wakeup Interrupts: For supporting external wakeup interrupts, a + child node representing the external wakeup interrupt controller should be + included in the pin-controller device node. This child node should include + the following properties. + + - compatible: identifies the type of the external wakeup interrupt controller + The possible values are: + - samsung,exynos4210-wakeup-eint: represents wakeup interrupt controller + found on Samsung Exynos4210 SoC. + - interrupt-parent: phandle of the interrupt parent to which the external + wakeup interrupts are forwarded to. + - interrupt-controller: identifies the node as interrupt-parent. + - #interrupt-cells: the value of this property should be 2 + - First Cell: represents the external wakeup interrupt number local to + the external wakeup interrupt space of the controller. + - Second Cell: flags to identify the type of the interrupt + - 1 = rising edge triggered + - 2 = falling edge triggered + - 3 = rising and falling edge triggered + - 4 = high level triggered + - 8 = low level triggered + +Aliases: + +All the pin controller nodes should be represented in the aliases node using +the following format 'pinctrl{n}' where n is a unique number for the alias. + +Example 1: A pin-controller node with pin groups. + + pinctrl_0: pinctrl@11400000 { + compatible = "samsung,pinctrl-exynos4210"; + reg = <0x11400000 0x1000>; + interrupts = <0 47 0>; + + uart0_data: uart0-data { + samsung,pins = "gpa0-0", "gpa0-1"; + samsung,pin-function = <2>; + samsung,pin-pud = <0>; + samsung,pin-drv = <0>; + }; + + uart0_fctl: uart0-fctl { + samsung,pins = "gpa0-2", "gpa0-3"; + samsung,pin-function = <2>; + samsung,pin-pud = <0>; + samsung,pin-drv = <0>; + }; + + uart1_data: uart1-data { + samsung,pins = "gpa0-4", "gpa0-5"; + samsung,pin-function = <2>; + samsung,pin-pud = <0>; + samsung,pin-drv = <0>; + }; + + uart1_fctl: uart1-fctl { + samsung,pins = "gpa0-6", "gpa0-7"; + samsung,pin-function = <2>; + samsung,pin-pud = <0>; + samsung,pin-drv = <0>; + }; + + i2c2_bus: i2c2-bus { + samsung,pins = "gpa0-6", "gpa0-7"; + samsung,pin-function = <3>; + samsung,pin-pud = <3>; + samsung,pin-drv = <0>; + }; + }; + +Example 2: A pin-controller node with external wakeup interrupt controller node. + + pinctrl_1: pinctrl@11000000 { + compatible = "samsung,pinctrl-exynos4210"; + reg = <0x11000000 0x1000>; + interrupts = <0 46 0>; + interrupt-controller; + #interrupt-cells = <2>; + + wakup_eint: wakeup-interrupt-controller { + compatible = "samsung,exynos4210-wakeup-eint"; + interrupt-parent = <&gic>; + interrupt-controller; + #interrupt-cells = <2>; + interrupts = <0 16 0>, <0 17 0>, <0 18 0>, <0 19 0>, + <0 20 0>, <0 21 0>, <0 22 0>, <0 23 0>, + <0 24 0>, <0 25 0>, <0 26 0>, <0 27 0>, + <0 28 0>, <0 29 0>, <0 30 0>, <0 31 0>, + <0 32 0>; + }; + }; + +Example 3: A uart client node that supports 'default' and 'flow-control' states. + + uart@13800000 { + compatible = "samsung,exynos4210-uart"; + reg = <0x13800000 0x100>; + interrupts = <0 52 0>; + pinctrl-names = "default", "flow-control; + pinctrl-0 = <&uart0_data>; + pinctrl-1 = <&uart0_data &uart0_fctl>; + }; + +Example 4: Set up the default pin state for uart controller. + + static int s3c24xx_serial_probe(struct platform_device *pdev) { + struct pinctrl *pinctrl; + ... + ... + pinctrl = devm_pinctrl_get_select_default(&pdev->dev); + } diff --git a/Documentation/devicetree/bindings/power/opp.txt b/Documentation/devicetree/bindings/power/opp.txt new file mode 100644 index 000000000000..74499e5033fc --- /dev/null +++ b/Documentation/devicetree/bindings/power/opp.txt @@ -0,0 +1,25 @@ +* Generic OPP Interface + +SoCs have a standard set of tuples consisting of frequency and +voltage pairs that the device will support per voltage domain. These +are called Operating Performance Points or OPPs. + +Properties: +- operating-points: An array of 2-tuples items, and each item consists + of frequency and voltage like <freq-kHz vol-uV>. + freq: clock frequency in kHz + vol: voltage in microvolt + +Examples: + +cpu@0 { + compatible = "arm,cortex-a9"; + reg = <0>; + next-level-cache = <&L2>; + operating-points = < + /* kHz uV */ + 792000 1100000 + 396000 950000 + 198000 850000 + >; +}; diff --git a/Documentation/devicetree/bindings/powerpc/fsl/ifc.txt b/Documentation/devicetree/bindings/powerpc/fsl/ifc.txt index 939a26d541f6..d5e370450ac0 100644 --- a/Documentation/devicetree/bindings/powerpc/fsl/ifc.txt +++ b/Documentation/devicetree/bindings/powerpc/fsl/ifc.txt @@ -12,9 +12,12 @@ Properties: - #size-cells : Either one or two, depending on how large each chipselect can be. - reg : Offset and length of the register set for the device -- interrupts : IFC has two interrupts. The first one is the "common" - interrupt(CM_EVTER_STAT), and second is the NAND interrupt - (NAND_EVTER_STAT). +- interrupts: IFC may have one or two interrupts. If two interrupt + specifiers are present, the first is the "common" + interrupt (CM_EVTER_STAT), and the second is the NAND + interrupt (NAND_EVTER_STAT). If there is only one, + that interrupt reports both types of event. + - ranges : Each range corresponds to a single chipselect, and covers the entire access window as configured. diff --git a/Documentation/devicetree/bindings/pwm/mxs-pwm.txt b/Documentation/devicetree/bindings/pwm/mxs-pwm.txt index b16f4a57d111..11963e4d6bc4 100644 --- a/Documentation/devicetree/bindings/pwm/mxs-pwm.txt +++ b/Documentation/devicetree/bindings/pwm/mxs-pwm.txt @@ -11,7 +11,7 @@ Example: pwm: pwm@80064000 { compatible = "fsl,imx28-pwm", "fsl,imx23-pwm"; - reg = <0x80064000 2000>; + reg = <0x80064000 0x2000>; #pwm-cells = <2>; fsl,pwm-number = <8>; }; diff --git a/Documentation/devicetree/bindings/regulator/88pm860x.txt b/Documentation/devicetree/bindings/regulator/88pm860x.txt new file mode 100644 index 000000000000..1267b3e1a2cc --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/88pm860x.txt @@ -0,0 +1,30 @@ +Marvell 88PM860x regulator + +Required properties: +- compatible: "marvell,88pm860x" +- reg: I2C slave address +- regulators: A node that houses a sub-node for each regulator within the + device. Each sub-node is identified using the regulator-compatible + property, with valid values listed below. + +Example: + + pmic: 88pm860x@34 { + compatible = "marvell,88pm860x"; + reg = <0x34>; + + regulators { + BUCK1 { + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1500000>; + regulator-boot-on; + regulator-always-on; + }; + BUCK3 { + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <3000000>; + regulator-boot-on; + regulator-always-on; + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/max8907.txt b/Documentation/devicetree/bindings/regulator/max8907.txt new file mode 100644 index 000000000000..371eccd1cd68 --- /dev/null +++ b/Documentation/devicetree/bindings/regulator/max8907.txt @@ -0,0 +1,69 @@ +MAX8907 regulator + +Required properties: +- compatible: "maxim,max8907" +- reg: I2C slave address +- interrupts: The interrupt output of the controller +- mbatt-supply: The input supply for MBATT, BBAT, SDBY, VRTC. +- in-v1-supply: The input supply for SD1. +- in-v2-supply: The input supply for SD2. +- in-v3-supply: The input supply for SD3. +- in1-supply: The input supply for LDO1. +... +- in20-supply: The input supply for LDO20. +- regulators: A node that houses a sub-node for each regulator within the + device. Each sub-node is identified using the node's name (or the deprecated + regulator-compatible property if present), with valid values listed below. + The content of each sub-node is defined by the standard binding for + regulators; see regulator.txt. + +Optional properties: +- maxim,system-power-controller: Boolean property indicating that the PMIC + controls the overall system power. + +The valid names for regulators are: + + sd1, sd2, sd3, ldo1, ldo2, ldo3, ldo4, ldo5, ldo6, ldo7, ldo8, ldo9, ldo10, + ldo11, ldo12, ldo13, ldo14, ldo15, ldo16, ldo17, ldo18, ldo19, ldo20, out5v, + out33v, bbat, sdby, vrtc. + +Example: + + max8907@3c { + compatible = "maxim,max8907"; + reg = <0x3c>; + interrupts = <0 86 0x4>; + + maxim,system-power-controller; + + mbatt-supply = <&some_reg>; + in-v1-supply = <&mbatt_reg>; + ... + in1-supply = <&mbatt_reg>; + ... + + regulators { + mbatt_reg: mbatt { + regulator-name = "vbat_pmu"; + regulator-min-microvolt = <5000000>; + regulator-max-microvolt = <5000000>; + regulator-always-on; + }; + + sd1 { + regulator-name = "nvvdd_sv1,vdd_cpu_pmu"; + regulator-min-microvolt = <1000000>; + regulator-max-microvolt = <1000000>; + regulator-always-on; + }; + + sd2 { + regulator-name = "nvvdd_sv2,vdd_core"; + regulator-min-microvolt = <1200000>; + regulator-max-microvolt = <1200000>; + regulator-always-on; + }; +... + }; + }; + }; diff --git a/Documentation/devicetree/bindings/regulator/regulator.txt b/Documentation/devicetree/bindings/regulator/regulator.txt index 66ece3f87bbc..ecfc6ccd67ef 100644 --- a/Documentation/devicetree/bindings/regulator/regulator.txt +++ b/Documentation/devicetree/bindings/regulator/regulator.txt @@ -11,10 +11,13 @@ Optional properties: - regulator-boot-on: bootloader/firmware enabled regulator - <name>-supply: phandle to the parent supply/regulator node - regulator-ramp-delay: ramp delay for regulator(in uV/uS) + +Deprecated properties: - regulator-compatible: If a regulator chip contains multiple regulators, and if the chip's binding contains a child node that describes each regulator, then this property indicates which regulator - this child node is intended to configure. + this child node is intended to configure. If this property is missing, + the node's name will be used instead. Example: diff --git a/Documentation/devicetree/bindings/regulator/tps65217.txt b/Documentation/devicetree/bindings/regulator/tps65217.txt index 0487e9675ba0..d316fb895daf 100644 --- a/Documentation/devicetree/bindings/regulator/tps65217.txt +++ b/Documentation/devicetree/bindings/regulator/tps65217.txt @@ -22,66 +22,49 @@ Example: compatible = "ti,tps65217"; regulators { - #address-cells = <1>; - #size-cells = <0>; - - dcdc1_reg: regulator@0 { - reg = <0>; - regulator-compatible = "dcdc1"; + dcdc1_reg: dcdc1 { regulator-min-microvolt = <900000>; regulator-max-microvolt = <1800000>; regulator-boot-on; regulator-always-on; }; - dcdc2_reg: regulator@1 { - reg = <1>; - regulator-compatible = "dcdc2"; + dcdc2_reg: dcdc2 { regulator-min-microvolt = <900000>; regulator-max-microvolt = <3300000>; regulator-boot-on; regulator-always-on; }; - dcdc3_reg: regulator@2 { - reg = <2>; - regulator-compatible = "dcdc3"; + dcdc3_reg: dcc3 { regulator-min-microvolt = <900000>; regulator-max-microvolt = <1500000>; regulator-boot-on; regulator-always-on; }; - ldo1_reg: regulator@3 { - reg = <3>; - regulator-compatible = "ldo1"; + ldo1_reg: ldo1 { regulator-min-microvolt = <1000000>; regulator-max-microvolt = <3300000>; regulator-boot-on; regulator-always-on; }; - ldo2_reg: regulator@4 { - reg = <4>; - regulator-compatible = "ldo2"; + ldo2_reg: ldo2 { regulator-min-microvolt = <900000>; regulator-max-microvolt = <3300000>; regulator-boot-on; regulator-always-on; }; - ldo3_reg: regulator@5 { - reg = <5>; - regulator-compatible = "ldo3"; + ldo3_reg: ldo3 { regulator-min-microvolt = <1800000>; regulator-max-microvolt = <3300000>; regulator-boot-on; regulator-always-on; }; - ldo4_reg: regulator@6 { - reg = <6>; - regulator-compatible = "ldo4"; + ldo4_reg: ldo4 { regulator-min-microvolt = <1800000>; regulator-max-microvolt = <3300000>; regulator-boot-on; diff --git a/Documentation/devicetree/bindings/regulator/tps6586x.txt b/Documentation/devicetree/bindings/regulator/tps6586x.txt index da80c2ae0915..8b40cac24d93 100644 --- a/Documentation/devicetree/bindings/regulator/tps6586x.txt +++ b/Documentation/devicetree/bindings/regulator/tps6586x.txt @@ -6,9 +6,13 @@ Required properties: - interrupts: the interrupt outputs of the controller - #gpio-cells: number of cells to describe a GPIO - gpio-controller: mark the device as a GPIO controller -- regulators: list of regulators provided by this controller, must have - property "regulator-compatible" to match their hardware counterparts: - sm[0-2], ldo[0-9] and ldo_rtc +- regulators: A node that houses a sub-node for each regulator within the + device. Each sub-node is identified using the node's name (or the deprecated + regulator-compatible property if present), with valid values listed below. + The content of each sub-node is defined by the standard binding for + regulators; see regulator.txt. + sys, sm[0-2], ldo[0-9] and ldo_rtc +- sys-supply: The input supply for SYS. - vin-sm0-supply: The input supply for the SM0. - vin-sm1-supply: The input supply for the SM1. - vin-sm2-supply: The input supply for the SM2. @@ -18,8 +22,15 @@ Required properties: - vinldo678-supply: The input supply for the LDO6, LDO7 and LDO8 - vinldo9-supply: The input supply for the LDO9 +Optional properties: +- ti,system-power-controller: Telling whether or not this pmic is controlling + the system power. + Each regulator is defined using the standard binding for regulators. +Note: LDO5 and LDO_RTC is supplied by SYS regulator internally and driver + take care of making proper parent child relationship. + Example: pmu: tps6586x@34 { @@ -30,6 +41,9 @@ Example: #gpio-cells = <2>; gpio-controller; + ti,system-power-controller; + + sys-supply = <&some_reg>; vin-sm0-supply = <&some_reg>; vin-sm1-supply = <&some_reg>; vin-sm2-supply = <&some_reg>; @@ -40,103 +54,80 @@ Example: vinldo9-supply = <...>; regulators { - #address-cells = <1>; - #size-cells = <0>; + sys_reg: sys { + regulator-name = "vdd_sys"; + regulator-boot-on; + regulator-always-on; + }; - sm0_reg: regulator@0 { - reg = <0>; - regulator-compatible = "sm0"; + sm0_reg: sm0 { regulator-min-microvolt = < 725000>; regulator-max-microvolt = <1500000>; regulator-boot-on; regulator-always-on; }; - sm1_reg: regulator@1 { - reg = <1>; - regulator-compatible = "sm1"; + sm1_reg: sm1 { regulator-min-microvolt = < 725000>; regulator-max-microvolt = <1500000>; regulator-boot-on; regulator-always-on; }; - sm2_reg: regulator@2 { - reg = <2>; - regulator-compatible = "sm2"; + sm2_reg: sm2 { regulator-min-microvolt = <3000000>; regulator-max-microvolt = <4550000>; regulator-boot-on; regulator-always-on; }; - ldo0_reg: regulator@3 { - reg = <3>; - regulator-compatible = "ldo0"; + ldo0_reg: ldo0 { regulator-name = "PCIE CLK"; regulator-min-microvolt = <3300000>; regulator-max-microvolt = <3300000>; }; - ldo1_reg: regulator@4 { - reg = <4>; - regulator-compatible = "ldo1"; + ldo1_reg: ldo1 { regulator-min-microvolt = < 725000>; regulator-max-microvolt = <1500000>; }; - ldo2_reg: regulator@5 { - reg = <5>; - regulator-compatible = "ldo2"; + ldo2_reg: ldo2 { regulator-min-microvolt = < 725000>; regulator-max-microvolt = <1500000>; }; - ldo3_reg: regulator@6 { - reg = <6>; - regulator-compatible = "ldo3"; + ldo3_reg: ldo3 { regulator-min-microvolt = <1250000>; regulator-max-microvolt = <3300000>; }; - ldo4_reg: regulator@7 { - reg = <7>; - regulator-compatible = "ldo4"; + ldo4_reg: ldo4 { regulator-min-microvolt = <1700000>; regulator-max-microvolt = <2475000>; }; - ldo5_reg: regulator@8 { - reg = <8>; - regulator-compatible = "ldo5"; + ldo5_reg: ldo5 { regulator-min-microvolt = <1250000>; regulator-max-microvolt = <3300000>; }; - ldo6_reg: regulator@9 { - reg = <9>; - regulator-compatible = "ldo6"; + ldo6_reg: ldo6 { regulator-min-microvolt = <1250000>; regulator-max-microvolt = <3300000>; }; - ldo7_reg: regulator@10 { - reg = <10>; - regulator-compatible = "ldo7"; + ldo7_reg: ldo7 { regulator-min-microvolt = <1250000>; regulator-max-microvolt = <3300000>; }; - ldo8_reg: regulator@11 { - reg = <11>; - regulator-compatible = "ldo8"; + ldo8_reg: ldo8 { regulator-min-microvolt = <1250000>; regulator-max-microvolt = <3300000>; }; - ldo9_reg: regulator@12 { - reg = <12>; - regulator-compatible = "ldo9"; + ldo9_reg: ldo9 { regulator-min-microvolt = <1250000>; regulator-max-microvolt = <3300000>; }; diff --git a/Documentation/devicetree/bindings/rtc/pxa-rtc.txt b/Documentation/devicetree/bindings/rtc/pxa-rtc.txt new file mode 100644 index 000000000000..8c6672a1b7d7 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/pxa-rtc.txt @@ -0,0 +1,14 @@ +* PXA RTC + +PXA specific RTC driver. + +Required properties: +- compatible : Should be "marvell,pxa-rtc" + +Examples: + +rtc@40900000 { + compatible = "marvell,pxa-rtc"; + reg = <0x40900000 0x3c>; + interrupts = <30 31>; +}; diff --git a/Documentation/devicetree/bindings/rtc/snvs-rtc.txt b/Documentation/devicetree/bindings/rtc/snvs-rtc.txt new file mode 100644 index 000000000000..fb61ed77ada3 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/snvs-rtc.txt @@ -0,0 +1 @@ +See Documentation/devicetree/bindings/crypto/fsl-sec4.txt for details. diff --git a/Documentation/devicetree/bindings/rtc/via,vt8500-rtc.txt b/Documentation/devicetree/bindings/rtc/via,vt8500-rtc.txt new file mode 100644 index 000000000000..3c0484c49582 --- /dev/null +++ b/Documentation/devicetree/bindings/rtc/via,vt8500-rtc.txt @@ -0,0 +1,15 @@ +VIA/Wondermedia VT8500 Realtime Clock Controller +----------------------------------------------------- + +Required properties: +- compatible : "via,vt8500-rtc" +- reg : Should contain 1 register ranges(address and length) +- interrupts : alarm interrupt + +Example: + + rtc@d8100000 { + compatible = "via,vt8500-rtc"; + reg = <0xd8100000 0x10000>; + interrupts = <48>; + }; diff --git a/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt new file mode 100644 index 000000000000..c58573b5b1a4 --- /dev/null +++ b/Documentation/devicetree/bindings/serial/fsl-imx-uart.txt @@ -0,0 +1,35 @@ +* Freescale i.MX UART controller + +Required properties: +- compatible : should be "fsl,imx21-uart" +- reg : Address and length of the register set for the device +- interrupts : Should contain UART interrupt number + +Optional properties: +- fsl,uart-has-rtscts: indicate that RTS/CTS signals are used + +Note: Each uart controller should have an alias correctly numbered +in "aliases" node. + +Example: + +- From imx51.dtsi: +aliases { + serial0 = &uart1; + serial1 = &uart2; + serial2 = &uart3; +}; + +uart1: serial@73fbc000 { + compatible = "fsl,imx51-uart", "fsl,imx21-uart"; + reg = <0x73fbc000 0x4000>; + interrupts = <31>; + status = "disabled"; +} + +- From imx51-babbage.dts: +uart1: serial@73fbc000 { + fsl,uart-has-rtscts; + status = "okay"; +}; + diff --git a/Documentation/devicetree/bindings/sound/cs4270.txt b/Documentation/devicetree/bindings/sound/cs4270.txt new file mode 100644 index 000000000000..6b222f9b8ef5 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cs4270.txt @@ -0,0 +1,21 @@ +CS4270 audio CODEC + +The driver for this device currently only supports I2C. + +Required properties: + + - compatible : "cirrus,cs4270" + + - reg : the I2C address of the device for I2C + +Optional properties: + + - reset-gpio : a GPIO spec for the reset pin. If specified, it will be + deasserted before communication to the codec starts. + +Example: + +codec: cs4270@48 { + compatible = "cirrus,cs4270"; + reg = <0x48>; +}; diff --git a/Documentation/devicetree/bindings/sound/cs4271.txt b/Documentation/devicetree/bindings/sound/cs4271.txt new file mode 100644 index 000000000000..c81b5fd5a5bc --- /dev/null +++ b/Documentation/devicetree/bindings/sound/cs4271.txt @@ -0,0 +1,36 @@ +Cirrus Logic CS4271 DT bindings + +This driver supports both the I2C and the SPI bus. + +Required properties: + + - compatible: "cirrus,cs4271" + +For required properties on SPI, please consult +Documentation/devicetree/bindings/spi/spi-bus.txt + +Required properties on I2C: + + - reg: the i2c address + + +Optional properties: + + - reset-gpio: a GPIO spec to define which pin is connected to the chip's + !RESET pin + +Examples: + + codec_i2c: cs4271@10 { + compatible = "cirrus,cs4271"; + reg = <0x10>; + reset-gpio = <&gpio 23 0>; + }; + + codec_spi: cs4271@0 { + compatible = "cirrus,cs4271"; + reg = <0x0>; + reset-gpio = <&gpio 23 0>; + spi-max-frequency = <6000000>; + }; + diff --git a/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt new file mode 100644 index 000000000000..374e145c2ef1 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/davinci-mcasp-audio.txt @@ -0,0 +1,45 @@ +Texas Instruments McASP controller + +Required properties: +- compatible : + "ti,dm646x-mcasp-audio" : for DM646x platforms + "ti,da830-mcasp-audio" : for both DA830 & DA850 platforms + "ti,omap2-mcasp-audio" : for OMAP2 platforms (TI81xx, AM33xx) + +- reg : Should contain McASP registers offset and length +- interrupts : Interrupt number for McASP +- op-mode : I2S/DIT ops mode. +- tdm-slots : Slots for TDM operation. +- num-serializer : Serializers used by McASP. +- serial-dir : A list of serializer pin mode. The list number should be equal + to "num-serializer" parameter. Each entry is a number indication + serializer pin direction. (0 - INACTIVE, 1 - TX, 2 - RX) + + +Optional properties: + +- ti,hwmods : Must be "mcasp<n>", n is controller instance starting 0 +- tx-num-evt : FIFO levels. +- rx-num-evt : FIFO levels. +- sram-size-playback : size of sram to be allocated during playback +- sram-size-capture : size of sram to be allocated during capture + +Example: + +mcasp0: mcasp0@1d00000 { + compatible = "ti,da830-mcasp-audio"; + #address-cells = <1>; + #size-cells = <0>; + reg = <0x100000 0x3000>; + interrupts = <82 83>; + op-mode = <0>; /* MCASP_IIS_MODE */ + tdm-slots = <2>; + num-serializer = <16>; + serial-dir = < + 0 0 0 0 /* 0: INACTIVE, 1: TX, 2: RX */ + 0 0 0 0 + 0 0 0 1 + 2 0 0 0 >; + tx-num-evt = <1>; + rx-num-evt = <1>; +}; diff --git a/Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt b/Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt new file mode 100644 index 000000000000..65dec876cb2d --- /dev/null +++ b/Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt @@ -0,0 +1,91 @@ +* Texas Instruments OMAP4+ and twl6040 based audio setups + +Required properties: +- compatible: "ti,abe-twl6040" +- ti,model: Name of the sound card ( for example "SDP4430") +- ti,mclk-freq: MCLK frequency for HPPLL operation +- ti,mcpdm: phandle for the McPDM node +- ti,twl6040: phandle for the twl6040 core node +- ti,audio-routing: List of connections between audio components. + Each entry is a pair of strings, the first being the connection's sink, + the second being the connection's source. + +Optional properties: +- ti,dmic: phandle for the OMAP dmic node if the machine have it connected +- ti,jack_detection: Need to be set to <1> if the board capable to detect jack + insertion, removal. + +Available audio endpoints for the audio-routing table: + +Board connectors: + * Headset Stereophone + * Earphone Spk + * Ext Spk + * Line Out + * Vibrator + * Headset Mic + * Main Handset Mic + * Sub Handset Mic + * Line In + * Digital Mic + +twl6040 pins: + * HSOL + * HSOR + * EP + * HFL + * HFR + * AUXL + * AUXR + * VIBRAL + * VIBRAR + * HSMIC + * MAINMIC + * SUBMIC + * AFML + * AFMR + + * Headset Mic Bias + * Main Mic Bias + * Digital Mic1 Bias + * Digital Mic2 Bias + +Digital mic pins: + * DMic + +Example: + +sound { + compatible = "ti,abe-twl6040"; + ti,model = "SDP4430"; + + ti,jack-detection = <1>; + ti,mclk-freq = <38400000>; + + ti,mcpdm = <&mcpdm>; + ti,dmic = <&dmic>; + + ti,twl6040 = <&twl6040>; + + /* Audio routing */ + ti,audio-routing = + "Headset Stereophone", "HSOL", + "Headset Stereophone", "HSOR", + "Earphone Spk", "EP", + "Ext Spk", "HFL", + "Ext Spk", "HFR", + "Line Out", "AUXL", + "Line Out", "AUXR", + "Vibrator", "VIBRAL", + "Vibrator", "VIBRAR", + "HSMIC", "Headset Mic", + "Headset Mic", "Headset Mic Bias", + "MAINMIC", "Main Handset Mic", + "Main Handset Mic", "Main Mic Bias", + "SUBMIC", "Sub Handset Mic", + "Sub Handset Mic", "Main Mic Bias", + "AFML", "Line In", + "AFMR", "Line In", + "DMic", "Digital Mic", + "Digital Mic", "Digital Mic1 Bias"; +}; diff --git a/Documentation/devicetree/bindings/sound/omap-mcbsp.txt b/Documentation/devicetree/bindings/sound/omap-mcbsp.txt new file mode 100644 index 000000000000..17cce4490456 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/omap-mcbsp.txt @@ -0,0 +1,37 @@ +* Texas Instruments OMAP2+ McBSP module + +Required properties: +- compatible: "ti,omap2420-mcbsp" for McBSP on OMAP2420 + "ti,omap2430-mcbsp" for McBSP on OMAP2430 + "ti,omap3-mcbsp" for McBSP on OMAP3 + "ti,omap4-mcbsp" for McBSP on OMAP4 and newer SoC +- reg: Register location and size, for OMAP4+ as an array: + <MPU access base address, size>, + <L3 interconnect address, size>; +- reg-names: Array of strings associated with the address space +- interrupts: Interrupt numbers for the McBSP port, as an array in case the + McBSP IP have more interrupt lines: + <OCP compliant irq>, + <TX irq>, + <RX irq>; +- interrupt-names: Array of strings associated with the interrupt numbers +- interrupt-parent: The parent interrupt controller +- ti,buffer-size: Size of the FIFO on the port (OMAP2430 and newer SoC) +- ti,hwmods: Name of the hwmod associated to the McBSP port + +Example: + +mcbsp2: mcbsp@49022000 { + compatible = "ti,omap3-mcbsp"; + reg = <0x49022000 0xff>, + <0x49028000 0xff>; + reg-names = "mpu", "sidetone"; + interrupts = <0 17 0x4>, /* OCP compliant interrupt */ + <0 62 0x4>, /* TX interrupt */ + <0 63 0x4>, /* RX interrupt */ + <0 4 0x4>; /* Sidetone */ + interrupt-names = "common", "tx", "rx", "sidetone"; + interrupt-parent = <&intc>; + ti,buffer-size = <1280>; + ti,hwmods = "mcbsp2"; +}; diff --git a/Documentation/devicetree/bindings/sound/omap-twl4030.txt b/Documentation/devicetree/bindings/sound/omap-twl4030.txt new file mode 100644 index 000000000000..6fae51c7f766 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/omap-twl4030.txt @@ -0,0 +1,17 @@ +* Texas Instruments SoC with twl4030 based audio setups + +Required properties: +- compatible: "ti,omap-twl4030" +- ti,model: Name of the sound card (for example "omap3beagle") +- ti,mcbsp: phandle for the McBSP node +- ti,codec: phandle for the twl4030 audio node + +Example: + +sound { + compatible = "ti,omap-twl4030"; + ti,model = "omap3beagle"; + + ti,mcbsp = <&mcbsp2>; + ti,codec = <&twl_audio>; +}; diff --git a/Documentation/devicetree/bindings/sound/tlv320aic3x.txt b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt new file mode 100644 index 000000000000..e7b98f41fa5f --- /dev/null +++ b/Documentation/devicetree/bindings/sound/tlv320aic3x.txt @@ -0,0 +1,20 @@ +Texas Instruments - tlv320aic3x Codec module + +The tlv320aic3x serial control bus communicates through I2C protocols + +Required properties: +- compatible - "string" - "ti,tlv320aic3x" +- reg - <int> - I2C slave address + + +Optional properties: + +- gpio-reset - gpio pin number used for codec reset +- ai3x-gpio-func - <array of 2 int> - AIC3X_GPIO1 & AIC3X_GPIO2 Functionality + +Example: + +tlv320aic3x: tlv320aic3x@1b { + compatible = "ti,tlv320aic3x"; + reg = <0x1b>; +}; diff --git a/Documentation/devicetree/bindings/sound/ux500-mop500.txt b/Documentation/devicetree/bindings/sound/ux500-mop500.txt new file mode 100644 index 000000000000..48e071c96b46 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ux500-mop500.txt @@ -0,0 +1,39 @@ +* MOP500 Audio Machine Driver + +This node is responsible for linking together all ux500 Audio Driver components. + +Required properties: + - compatible : "stericsson,snd-soc-mop500" + +Non-standard properties: + - stericsson,cpu-dai : Phandle to the CPU-side DAI + - stericsson,audio-codec : Phandle to the Audio CODEC + - stericsson,card-name : Over-ride default card name + +Example: + + sound { + compatible = "stericsson,snd-soc-mop500"; + + stericsson,cpu-dai = <&msp1 &msp3>; + stericsson,audio-codec = <&codec>; + }; + + msp1: msp@80124000 { + compatible = "stericsson,ux500-msp-i2s"; + reg = <0x80124000 0x1000>; + interrupts = <0 62 0x4>; + v-ape-supply = <&db8500_vape_reg>; + }; + + msp3: msp@80125000 { + compatible = "stericsson,ux500-msp-i2s"; + reg = <0x80125000 0x1000>; + interrupts = <0 62 0x4>; + v-ape-supply = <&db8500_vape_reg>; + }; + + codec: ab8500-codec { + compatible = "stericsson,ab8500-codec"; + stericsson,earpeice-cmv = <950>; /* Units in mV. */ + }; diff --git a/Documentation/devicetree/bindings/sound/ux500-msp.txt b/Documentation/devicetree/bindings/sound/ux500-msp.txt new file mode 100644 index 000000000000..99acd9c774e1 --- /dev/null +++ b/Documentation/devicetree/bindings/sound/ux500-msp.txt @@ -0,0 +1,43 @@ +* ux500 MSP (CPU-side Digital Audio Interface) + +Required properties: + - compatible :"stericsson,ux500-msp-i2s" + - reg : Physical base address and length of the device's registers. + +Optional properties: + - interrupts : The interrupt output from the device. + - interrupt-parent : The parent interrupt controller. + - <name>-supply : Phandle to the regulator <name> supply + +Example: + + sound { + compatible = "stericsson,snd-soc-mop500"; + + stericsson,platform-pcm-dma = <&pcm>; + stericsson,cpu-dai = <&msp1 &msp3>; + stericsson,audio-codec = <&codec>; + }; + + pcm: ux500-pcm { + compatible = "stericsson,ux500-pcm"; + }; + + msp1: msp@80124000 { + compatible = "stericsson,ux500-msp-i2s"; + reg = <0x80124000 0x1000>; + interrupts = <0 62 0x4>; + v-ape-supply = <&db8500_vape_reg>; + }; + + msp3: msp@80125000 { + compatible = "stericsson,ux500-msp-i2s"; + reg = <0x80125000 0x1000>; + interrupts = <0 62 0x4>; + v-ape-supply = <&db8500_vape_reg>; + }; + + codec: ab8500-codec { + compatible = "stericsson,ab8500-codec"; + stericsson,earpeice-cmv = <950>; /* Units in mV. */ + }; diff --git a/Documentation/devicetree/bindings/spi/mxs-spi.txt b/Documentation/devicetree/bindings/spi/mxs-spi.txt new file mode 100644 index 000000000000..e2e13957c2a4 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/mxs-spi.txt @@ -0,0 +1,22 @@ +* Freescale MX233/MX28 SSP/SPI + +Required properties: +- compatible: Should be "fsl,<soc>-spi", where soc is "imx23" or "imx28" +- reg: Offset and length of the register set for the device +- interrupts: Should contain SSP interrupts (error irq first, dma irq second) +- fsl,ssp-dma-channel: APBX DMA channel for the SSP + +Optional properties: +- clock-frequency : Input clock frequency to the SPI block in Hz. + Default is 160000000 Hz. + +Example: + +ssp0: ssp@80010000 { + #address-cells = <1>; + #size-cells = <0>; + compatible = "fsl,imx28-spi"; + reg = <0x80010000 0x2000>; + interrupts = <96 82>; + fsl,ssp-dma-channel = <0>; +}; diff --git a/Documentation/devicetree/bindings/spi/spi-bus.txt b/Documentation/devicetree/bindings/spi/spi-bus.txt index e782add2e457..d2c33d0f533e 100644 --- a/Documentation/devicetree/bindings/spi/spi-bus.txt +++ b/Documentation/devicetree/bindings/spi/spi-bus.txt @@ -21,6 +21,9 @@ assumption that board specific platform code will be used to manage chip selects. Individual drivers can define additional properties to support describing the chip select layout. +Optional property: +- num-cs : total number of chipselects + SPI slave nodes must be children of the SPI master node and can contain the following properties. - reg - (required) chip select address of device. diff --git a/Documentation/devicetree/bindings/spi/spi-gpio.txt b/Documentation/devicetree/bindings/spi/spi-gpio.txt new file mode 100644 index 000000000000..8a824be15754 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-gpio.txt @@ -0,0 +1,29 @@ +SPI-GPIO devicetree bindings + +Required properties: + + - compatible: should be set to "spi-gpio" + - #address-cells: should be set to <0x1> + - ranges + - gpio-sck: GPIO spec for the SCK line to use + - gpio-miso: GPIO spec for the MISO line to use + - gpio-mosi: GPIO spec for the MOSI line to use + - cs-gpios: GPIOs to use for chipselect lines + - num-chipselects: number of chipselect lines + +Example: + + spi { + compatible = "spi-gpio"; + #address-cells = <0x1>; + ranges; + + gpio-sck = <&gpio 95 0>; + gpio-miso = <&gpio 98 0>; + gpio-mosi = <&gpio 97 0>; + cs-gpios = <&gpio 125 0>; + num-chipselects = <1>; + + /* clients */ + }; + diff --git a/Documentation/devicetree/bindings/spi/spi-octeon.txt b/Documentation/devicetree/bindings/spi/spi-octeon.txt new file mode 100644 index 000000000000..431add192342 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-octeon.txt @@ -0,0 +1,33 @@ +Cavium, Inc. OCTEON SOC SPI master controller. + +Required properties: +- compatible : "cavium,octeon-3010-spi" +- reg : The register base for the controller. +- interrupts : One interrupt, used by the controller. +- #address-cells : <1>, as required by generic SPI binding. +- #size-cells : <0>, also as required by generic SPI binding. + +Child nodes as per the generic SPI binding. + +Example: + + spi@1070000001000 { + compatible = "cavium,octeon-3010-spi"; + reg = <0x10700 0x00001000 0x0 0x100>; + interrupts = <0 58>; + #address-cells = <1>; + #size-cells = <0>; + + eeprom@0 { + compatible = "st,m95256", "atmel,at25"; + reg = <0>; + spi-max-frequency = <5000000>; + spi-cpha; + spi-cpol; + + pagesize = <64>; + size = <32768>; + address-width = <16>; + }; + }; + diff --git a/Documentation/devicetree/bindings/spi/spi-sc18is602.txt b/Documentation/devicetree/bindings/spi/spi-sc18is602.txt new file mode 100644 index 000000000000..02f9033270a2 --- /dev/null +++ b/Documentation/devicetree/bindings/spi/spi-sc18is602.txt @@ -0,0 +1,23 @@ +NXP SC18IS602/SCIS603 + +Required properties: + - compatible : Should be one of + "nxp,sc18is602" + "nxp,sc18is602b" + "nxp,sc18is603" + - reg: I2C bus address + +Optional properties: + - clock-frequency : external oscillator clock frequency. If not + specified, the SC18IS602 default frequency (7372000) will be used. + +The clock-frequency property is relevant and needed only if the chip has an +external oscillator (SC18IS603). + +Example: + + sc18is603@28 { + compatible = "nxp,sc18is603"; + reg = <0x28>; + clock-frequency = <14744000>; + } diff --git a/Documentation/devicetree/bindings/spi/spi_pl022.txt b/Documentation/devicetree/bindings/spi/spi_pl022.txt index 306ec3ff3c0e..f158fd31cfda 100644 --- a/Documentation/devicetree/bindings/spi/spi_pl022.txt +++ b/Documentation/devicetree/bindings/spi/spi_pl022.txt @@ -6,7 +6,29 @@ Required properties: - interrupts : Should contain SPI controller interrupt Optional properties: +- num-cs : total number of chipselects - cs-gpios : should specify GPIOs used for chipselects. The gpios will be referred to as reg = <index> in the SPI child nodes. If unspecified, a single SPI device without a chip select can be used. +- pl022,autosuspend-delay : delay in ms following transfer completion before + the runtime power management system suspends the + device. A setting of 0 indicates no delay and the + device will be suspended immediately +- pl022,rt : indicates the controller should run the message pump with realtime + priority to minimise the transfer latency on the bus (boolean) + + +SPI slave nodes must be children of the SPI master node and can +contain the following properties. + +- pl022,interface : interface type: + 0: SPI + 1: Texas Instruments Synchronous Serial Frame Format + 2: Microwire (Half Duplex) +- pl022,com-mode : polling, interrupt or dma +- pl022,rx-level-trig : Rx FIFO watermark level +- pl022,tx-level-trig : Tx FIFO watermark level +- pl022,ctrl-len : Microwire interface: Control length +- pl022,wait-state : Microwire interface: Wait state +- pl022,duplex : Microwire interface: Full/Half duplex diff --git a/Documentation/devicetree/bindings/staging/iio/adc/mxs-lradc.txt b/Documentation/devicetree/bindings/staging/iio/adc/mxs-lradc.txt new file mode 100644 index 000000000000..801d58cb6d4d --- /dev/null +++ b/Documentation/devicetree/bindings/staging/iio/adc/mxs-lradc.txt @@ -0,0 +1,15 @@ +* Freescale i.MX28 LRADC device driver + +Required properties: +- compatible: Should be "fsl,imx28-lradc" +- reg: Address and length of the register set for the device +- interrupts: Should contain the LRADC interrupts + +Examples: + + lradc@80050000 { + compatible = "fsl,imx28-lradc"; + reg = <0x80050000 0x2000>; + interrupts = <10 14 15 16 17 18 19 + 20 21 22 23 24 25>; + }; diff --git a/Documentation/devicetree/bindings/staging/imx-drm/fsl-imx-drm.txt b/Documentation/devicetree/bindings/staging/imx-drm/fsl-imx-drm.txt new file mode 100644 index 000000000000..07654f0338b6 --- /dev/null +++ b/Documentation/devicetree/bindings/staging/imx-drm/fsl-imx-drm.txt @@ -0,0 +1,41 @@ +Freescale i.MX IPUv3 +==================== + +Required properties: +- compatible: Should be "fsl,<chip>-ipu" +- reg: should be register base and length as documented in the + datasheet +- interrupts: Should contain sync interrupt and error interrupt, + in this order. +- #crtc-cells: 1, See below + +example: + +ipu: ipu@18000000 { + #crtc-cells = <1>; + compatible = "fsl,imx53-ipu"; + reg = <0x18000000 0x080000000>; + interrupts = <11 10>; +}; + +Parallel display support +======================== + +Required properties: +- compatible: Should be "fsl,imx-parallel-display" +- crtc: the crtc this display is connected to, see below +Optional properties: +- interface_pix_fmt: How this display is connected to the + crtc. Currently supported types: "rgb24", "rgb565" +- edid: verbatim EDID data block describing attached display. +- ddc: phandle describing the i2c bus handling the display data + channel + +example: + +display@di0 { + compatible = "fsl,imx-parallel-display"; + edid = [edid-data]; + crtc = <&ipu 0>; + interface-pix-fmt = "rgb24"; +}; diff --git a/Documentation/devicetree/bindings/timer/brcm,bcm2835-system-timer.txt b/Documentation/devicetree/bindings/timer/brcm,bcm2835-system-timer.txt new file mode 100644 index 000000000000..2de21c2acf55 --- /dev/null +++ b/Documentation/devicetree/bindings/timer/brcm,bcm2835-system-timer.txt @@ -0,0 +1,22 @@ +BCM2835 System Timer + +The System Timer peripheral provides four 32-bit timer channels and a +single 64-bit free running counter. Each channel has an output compare +register, which is compared against the 32 least significant bits of the +free running counter values, and generates an interrupt. + +Required properties: + +- compatible : should be "brcm,bcm2835-system-timer.txt" +- reg : Specifies base physical address and size of the registers. +- interrupts : A list of 4 interrupt sinks; one per timer channel. +- clock-frequency : The frequency of the clock that drives the counter, in Hz. + +Example: + +timer { + compatible = "brcm,bcm2835-system-timer"; + reg = <0x7e003000 0x1000>; + interrupts = <1 0>, <1 1>, <1 2>, <1 3>; + clock-frequency = <1000000>; +}; diff --git a/Documentation/devicetree/bindings/tty/serial/nxp-lpc32xx-hsuart.txt b/Documentation/devicetree/bindings/tty/serial/nxp-lpc32xx-hsuart.txt new file mode 100644 index 000000000000..0d439dfc1aa5 --- /dev/null +++ b/Documentation/devicetree/bindings/tty/serial/nxp-lpc32xx-hsuart.txt @@ -0,0 +1,14 @@ +* NXP LPC32xx SoC High Speed UART + +Required properties: +- compatible: Should be "nxp,lpc3220-hsuart" +- reg: Should contain registers location and length +- interrupts: Should contain interrupt + +Example: + + uart1: serial@40014000 { + compatible = "nxp,lpc3220-hsuart"; + reg = <0x40014000 0x1000>; + interrupts = <26 0>; + }; diff --git a/Documentation/devicetree/bindings/tty/serial/of-serial.txt b/Documentation/devicetree/bindings/tty/serial/of-serial.txt index 0847fdeee11a..ba385f2e0ddc 100644 --- a/Documentation/devicetree/bindings/tty/serial/of-serial.txt +++ b/Documentation/devicetree/bindings/tty/serial/of-serial.txt @@ -25,6 +25,8 @@ Optional properties: accesses to the UART (e.g. TI davinci). - used-by-rtas : set to indicate that the port is in use by the OpenFirmware RTAS and should not be registered. +- no-loopback-test: set to indicate that the port does not implements loopback + test mode Example: diff --git a/Documentation/devicetree/bindings/tty/serial/via,vt8500-uart.txt b/Documentation/devicetree/bindings/tty/serial/via,vt8500-uart.txt new file mode 100644 index 000000000000..5feef1ef167d --- /dev/null +++ b/Documentation/devicetree/bindings/tty/serial/via,vt8500-uart.txt @@ -0,0 +1,17 @@ +VIA/Wondermedia VT8500 UART Controller +----------------------------------------------------- + +Required properties: +- compatible : "via,vt8500-uart" +- reg : Should contain 1 register ranges(address and length) +- interrupts : UART interrupt +- clocks : phandle to the uart source clock (usually a 24Mhz fixed clock) + +Example: + + uart@d8210000 { + compatible = "via,vt8500-uart"; + reg = <0xd8210000 0x1040>; + interrupts = <47>; + clocks = <&ref24>; + }; diff --git a/Documentation/devicetree/bindings/usb/am33xx-usb.txt b/Documentation/devicetree/bindings/usb/am33xx-usb.txt new file mode 100644 index 000000000000..ca8fa56e9f03 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/am33xx-usb.txt @@ -0,0 +1,14 @@ +AM33XX MUSB GLUE + - compatible : Should be "ti,musb-am33xx" + - ti,hwmods : must be "usb_otg_hs" + - multipoint : Should be "1" indicating the musb controller supports + multipoint. This is a MUSB configuration-specific setting. + - num_eps : Specifies the number of endpoints. This is also a + MUSB configuration-specific setting. Should be set to "16" + - ram_bits : Specifies the ram address size. Should be set to "12" + - port0_mode : Should be "3" to represent OTG. "1" signifies HOST and "2" + represents PERIPHERAL. + - port1_mode : Should be "1" to represent HOST. "3" signifies OTG and "2" + represents PERIPHERAL. + - power : Should be "250". This signifies the controller can supply upto + 500mA when operating in host mode. diff --git a/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt b/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt index 2c290418bb2d..5778b9c83bd8 100644 --- a/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt +++ b/Documentation/devicetree/bindings/usb/ci13xxx-imx.txt @@ -7,7 +7,10 @@ Required properties: Optional properties: - fsl,usbphy: phandler of usb phy that connects to the only one port +- fsl,usbmisc: phandler of non-core register device, with one argument + that indicate usb controller index - vbus-supply: regulator for vbus +- disable-over-current: disable over current detect Examples: usb@02184000 { /* USB OTG */ @@ -15,4 +18,6 @@ usb@02184000 { /* USB OTG */ reg = <0x02184000 0x200>; interrupts = <0 43 0x04>; fsl,usbphy = <&usbphy1>; + fsl,usbmisc = <&usbmisc 0>; + disable-over-current; }; diff --git a/Documentation/devicetree/bindings/usb/omap-usb.txt b/Documentation/devicetree/bindings/usb/omap-usb.txt new file mode 100644 index 000000000000..29a043ecda52 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/omap-usb.txt @@ -0,0 +1,33 @@ +OMAP GLUE + +OMAP MUSB GLUE + - compatible : Should be "ti,omap4-musb" or "ti,omap3-musb" + - ti,hwmods : must be "usb_otg_hs" + - multipoint : Should be "1" indicating the musb controller supports + multipoint. This is a MUSB configuration-specific setting. + - num_eps : Specifies the number of endpoints. This is also a + MUSB configuration-specific setting. Should be set to "16" + - ram_bits : Specifies the ram address size. Should be set to "12" + - interface_type : This is a board specific setting to describe the type of + interface between the controller and the phy. It should be "0" or "1" + specifying ULPI and UTMI respectively. + - mode : Should be "3" to represent OTG. "1" signifies HOST and "2" + represents PERIPHERAL. + - power : Should be "50". This signifies the controller can supply upto + 100mA when operating in host mode. + +SOC specific device node entry +usb_otg_hs: usb_otg_hs@4a0ab000 { + compatible = "ti,omap4-musb"; + ti,hwmods = "usb_otg_hs"; + multipoint = <1>; + num_eps = <16>; + ram_bits = <12>; +}; + +Board specific device node entry +&usb_otg_hs { + interface_type = <1>; + mode = <3>; + power = <50>; +}; diff --git a/Documentation/devicetree/bindings/usb/platform-uhci.txt b/Documentation/devicetree/bindings/usb/platform-uhci.txt new file mode 100644 index 000000000000..a4fb0719d157 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/platform-uhci.txt @@ -0,0 +1,15 @@ +Generic Platform UHCI Controller +----------------------------------------------------- + +Required properties: +- compatible : "platform-uhci" +- reg : Should contain 1 register ranges(address and length) +- interrupts : UHCI controller interrupt + +Example: + + uhci@d8007b00 { + compatible = "platform-uhci"; + reg = <0xd8007b00 0x200>; + interrupts = <43>; + }; diff --git a/Documentation/devicetree/bindings/usb/pxa-usb.txt b/Documentation/devicetree/bindings/usb/pxa-usb.txt new file mode 100644 index 000000000000..79729a948d5a --- /dev/null +++ b/Documentation/devicetree/bindings/usb/pxa-usb.txt @@ -0,0 +1,31 @@ +PXA USB controllers + +OHCI + +Required properties: + - compatible: Should be "marvell,pxa-ohci" for USB controllers + used in host mode. + +Optional properties: + - "marvell,enable-port1", "marvell,enable-port2", "marvell,enable-port3" + If present, enables the appropriate USB port of the controller. + - "marvell,port-mode" selects the mode of the ports: + 1 = PMM_NPS_MODE + 2 = PMM_GLOBAL_MODE + 3 = PMM_PERPORT_MODE + - "marvell,power-sense-low" - power sense pin is low-active. + - "marvell,power-control-low" - power control pin is low-active. + - "marvell,no-oc-protection" - disable over-current protection. + - "marvell,oc-mode-perport" - enable per-port over-current protection. + - "marvell,power_on_delay" Power On to Power Good time - in ms. + +Example: + + usb0: ohci@4c000000 { + compatible = "marvell,pxa-ohci", "usb-ohci"; + reg = <0x4c000000 0x100000>; + interrupts = <18>; + marvell,enable-port1; + marvell,port-mode = <2>; /* PMM_GLOBAL_MODE */ + }; + diff --git a/Documentation/devicetree/bindings/usb/twlxxxx-usb.txt b/Documentation/devicetree/bindings/usb/twlxxxx-usb.txt new file mode 100644 index 000000000000..36b9aede3f40 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/twlxxxx-usb.txt @@ -0,0 +1,40 @@ +USB COMPARATOR OF TWL CHIPS + +TWL6030 USB COMPARATOR + - compatible : Should be "ti,twl6030-usb" + - interrupts : Two interrupt numbers to the cpu should be specified. First + interrupt number is the otg interrupt number that raises ID interrupts when + the controller has to act as host and the second interrupt number is the + usb interrupt number that raises VBUS interrupts when the controller has to + act as device + - usb-supply : phandle to the regulator device tree node. It should be vusb + if it is twl6030 or ldousb if it is twl6025 subclass. + +twl6030-usb { + compatible = "ti,twl6030-usb"; + interrupts = < 4 10 >; +}; + +Board specific device node entry +&twl6030-usb { + usb-supply = <&vusb>; +}; + +TWL4030 USB PHY AND COMPARATOR + - compatible : Should be "ti,twl4030-usb" + - interrupts : The interrupt numbers to the cpu should be specified. First + interrupt number is the otg interrupt number that raises ID interrupts + and VBUS interrupts. The second interrupt number is optional. + - <supply-name>-supply : phandle to the regulator device tree node. + <supply-name> should be vusb1v5, vusb1v8 and vusb3v1 + - usb_mode : The mode used by the phy to connect to the controller. "1" + specifies "ULPI" mode and "2" specifies "CEA2011_3PIN" mode. + +twl4030-usb { + compatible = "ti,twl4030-usb"; + interrupts = < 10 4 >; + usb1v5-supply = <&vusb1v5>; + usb1v8-supply = <&vusb1v8>; + usb3v1-supply = <&vusb3v1>; + usb_mode = <1>; +}; diff --git a/Documentation/devicetree/bindings/usb/usb-phy.txt b/Documentation/devicetree/bindings/usb/usb-phy.txt new file mode 100644 index 000000000000..80d4148cb661 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usb-phy.txt @@ -0,0 +1,17 @@ +USB PHY + +OMAP USB2 PHY + +Required properties: + - compatible: Should be "ti,omap-usb2" + - reg : Address and length of the register set for the device. Also +add the address of control module dev conf register until a driver for +control module is added + +This is usually a subnode of ocp2scp to which it is connected. + +usb2phy@4a0ad080 { + compatible = "ti,omap-usb2"; + reg = <0x4a0ad080 0x58>, + <0x4a002300 0x4>; +}; diff --git a/Documentation/devicetree/bindings/usb/usbmisc-imx.txt b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt new file mode 100644 index 000000000000..97ce94e1a6cc --- /dev/null +++ b/Documentation/devicetree/bindings/usb/usbmisc-imx.txt @@ -0,0 +1,14 @@ +* Freescale i.MX non-core registers + +Required properties: +- #index-cells: Cells used to descibe usb controller index. Should be <1> +- compatible: Should be one of below: + "fsl,imx6q-usbmisc" for imx6q +- reg: Should contain registers location and length + +Examples: +usbmisc@02184800 { + #index-cells = <1>; + compatible = "fsl,imx6q-usbmisc"; + reg = <0x02184800 0x200>; +}; diff --git a/Documentation/devicetree/bindings/usb/via,vt8500-ehci.txt b/Documentation/devicetree/bindings/usb/via,vt8500-ehci.txt new file mode 100644 index 000000000000..17b3ad1d97e7 --- /dev/null +++ b/Documentation/devicetree/bindings/usb/via,vt8500-ehci.txt @@ -0,0 +1,15 @@ +VIA/Wondermedia VT8500 EHCI Controller +----------------------------------------------------- + +Required properties: +- compatible : "via,vt8500-ehci" +- reg : Should contain 1 register ranges(address and length) +- interrupts : ehci controller interrupt + +Example: + + ehci@d8007900 { + compatible = "via,vt8500-ehci"; + reg = <0xd8007900 0x200>; + interrupts = <43>; + }; diff --git a/Documentation/devicetree/bindings/usb/vt8500-ehci.txt b/Documentation/devicetree/bindings/usb/vt8500-ehci.txt new file mode 100644 index 000000000000..5fb8fd6e250c --- /dev/null +++ b/Documentation/devicetree/bindings/usb/vt8500-ehci.txt @@ -0,0 +1,12 @@ +VIA VT8500 and Wondermedia WM8xxx SoC USB controllers. + +Required properties: + - compatible: Should be "via,vt8500-ehci" or "wm,prizm-ehci". + - reg: Address range of the ehci registers. size should be 0x200 + - interrupts: Should contain the ehci interrupt. + +usb: ehci@D8007100 { + compatible = "wm,prizm-ehci", "usb-ehci"; + reg = <0xD8007100 0x200>; + interrupts = <1>; +}; diff --git a/Documentation/devicetree/bindings/vendor-prefixes.txt b/Documentation/devicetree/bindings/vendor-prefixes.txt index db4d3af3643c..9de2b9ff9d6e 100644 --- a/Documentation/devicetree/bindings/vendor-prefixes.txt +++ b/Documentation/devicetree/bindings/vendor-prefixes.txt @@ -10,6 +10,7 @@ apm Applied Micro Circuits Corporation (APM) arm ARM Ltd. atmel Atmel Corporation bosch Bosch Sensortec GmbH +brcm Broadcom Corporation cavium Cavium, Inc. chrp Common Hardware Reference Platform cortina Cortina Systems, Inc. @@ -47,5 +48,7 @@ sirf SiRF Technology, Inc. st STMicroelectronics stericsson ST-Ericsson ti Texas Instruments +via VIA Technologies, Inc. wlf Wolfson Microelectronics +wm Wondermedia Technologies, Inc. xlnx Xilinx diff --git a/Documentation/devicetree/bindings/video/backlight/88pm860x.txt b/Documentation/devicetree/bindings/video/backlight/88pm860x.txt new file mode 100644 index 000000000000..261df2799315 --- /dev/null +++ b/Documentation/devicetree/bindings/video/backlight/88pm860x.txt @@ -0,0 +1,15 @@ +88pm860x-backlight bindings + +Optional properties: + - marvell,88pm860x-iset: Current supplies on backlight device. + - marvell,88pm860x-pwm: PWM frequency on backlight device. + +Example: + + backlights { + backlight-0 { + marvell,88pm860x-iset = <4>; + marvell,88pm860x-pwm = <3>; + }; + backlight-2 { + }; diff --git a/Documentation/devicetree/bindings/video/via,vt8500-fb.txt b/Documentation/devicetree/bindings/video/via,vt8500-fb.txt new file mode 100644 index 000000000000..c870b6478ec8 --- /dev/null +++ b/Documentation/devicetree/bindings/video/via,vt8500-fb.txt @@ -0,0 +1,62 @@ +VIA VT8500 Framebuffer +----------------------------------------------------- + +Required properties: +- compatible : "via,vt8500-fb" +- reg : Should contain 1 register ranges(address and length) +- interrupts : framebuffer controller interrupt +- display: a phandle pointing to the display node + +Required nodes: +- display: a display node is required to initialize the lcd panel + This should be in the board dts. +- default-mode: a videomode within the display with timing parameters + as specified below. + +Example: + + fb@d800e400 { + compatible = "via,vt8500-fb"; + reg = <0xd800e400 0x400>; + interrupts = <12>; + display = <&display>; + default-mode = <&mode0>; + }; + +VIA VT8500 Display +----------------------------------------------------- +Required properties (as per of_videomode_helper): + + - hactive, vactive: Display resolution + - hfront-porch, hback-porch, hsync-len: Horizontal Display timing parameters + in pixels + vfront-porch, vback-porch, vsync-len: Vertical display timing parameters in + lines + - clock: displayclock in Hz + - bpp: lcd panel bit-depth. + <16> for RGB565, <32> for RGB888 + +Optional properties (as per of_videomode_helper): + - width-mm, height-mm: Display dimensions in mm + - hsync-active-high (bool): Hsync pulse is active high + - vsync-active-high (bool): Vsync pulse is active high + - interlaced (bool): This is an interlaced mode + - doublescan (bool): This is a doublescan mode + +Example: + display: display@0 { + modes { + mode0: mode@0 { + hactive = <800>; + vactive = <480>; + hback-porch = <88>; + hfront-porch = <40>; + hsync-len = <0>; + vback-porch = <32>; + vfront-porch = <11>; + vsync-len = <1>; + clock = <0>; /* unused but required */ + bpp = <16>; /* non-standard but required */ + }; + }; + }; diff --git a/Documentation/devicetree/bindings/video/wm,prizm-ge-rops.txt b/Documentation/devicetree/bindings/video/wm,prizm-ge-rops.txt new file mode 100644 index 000000000000..a850fa011f02 --- /dev/null +++ b/Documentation/devicetree/bindings/video/wm,prizm-ge-rops.txt @@ -0,0 +1,13 @@ +VIA/Wondermedia Graphics Engine Controller +----------------------------------------------------- + +Required properties: +- compatible : "wm,prizm-ge-rops" +- reg : Should contain 1 register ranges(address and length) + +Example: + + ge_rops@d8050400 { + compatible = "wm,prizm-ge-rops"; + reg = <0xd8050400 0x100>; + }; diff --git a/Documentation/devicetree/bindings/video/wm,wm8505-fb.txt b/Documentation/devicetree/bindings/video/wm,wm8505-fb.txt new file mode 100644 index 000000000000..3d325e1d11ee --- /dev/null +++ b/Documentation/devicetree/bindings/video/wm,wm8505-fb.txt @@ -0,0 +1,23 @@ +Wondermedia WM8505 Framebuffer +----------------------------------------------------- + +Required properties: +- compatible : "wm,wm8505-fb" +- reg : Should contain 1 register ranges(address and length) +- via,display: a phandle pointing to the display node + +Required nodes: +- display: a display node is required to initialize the lcd panel + This should be in the board dts. See definition in + Documentation/devicetree/bindings/video/via,vt8500-fb.txt +- default-mode: a videomode node as specified in + Documentation/devicetree/bindings/video/via,vt8500-fb.txt + +Example: + + fb@d8050800 { + compatible = "wm,wm8505-fb"; + reg = <0xd8050800 0x200>; + display = <&display>; + default-mode = <&mode0>; + }; diff --git a/Documentation/devicetree/bindings/w1/w1-gpio.txt b/Documentation/devicetree/bindings/w1/w1-gpio.txt new file mode 100644 index 000000000000..6e09c35d9f1a --- /dev/null +++ b/Documentation/devicetree/bindings/w1/w1-gpio.txt @@ -0,0 +1,22 @@ +w1-gpio devicetree bindings + +Required properties: + + - compatible: "w1-gpio" + - gpios: one or two GPIO specs: + - the first one is used as data I/O pin + - the second one is optional. If specified, it is used as + enable pin for an external pin pullup. + +Optional properties: + + - linux,open-drain: if specified, the data pin is considered in + open-drain mode. + +Examples: + + onewire@0 { + compatible = "w1-gpio"; + gpios = <&gpio 126 0>, <&gpio 105 0>; + }; + diff --git a/Documentation/dontdiff b/Documentation/dontdiff index 39462cf35cd4..74c25c8d8884 100644 --- a/Documentation/dontdiff +++ b/Documentation/dontdiff @@ -162,7 +162,6 @@ mach-types.h machtypes.h map map_hugetlb -maui_boot.h media mconf miboot* diff --git a/Documentation/dvb/README.dvb-usb b/Documentation/dvb/README.dvb-usb index c4d963a67d6f..8eb92264ee04 100644 --- a/Documentation/dvb/README.dvb-usb +++ b/Documentation/dvb/README.dvb-usb @@ -30,7 +30,7 @@ with the device via the bus. The connection between the DVB-API-functionality is done via callbacks, assigned in a static device-description (struct dvb_usb_device) each device-driver has to have. -For an example have a look in drivers/media/dvb/dvb-usb/vp7045*. +For an example have a look in drivers/media/usb/dvb-usb/vp7045*. Objective is to migrate all the usb-devices (dibusb, cinergyT2, maybe the ttusb; flexcop-usb already benefits from the generic flexcop-device) to use diff --git a/Documentation/dvb/get_dvb_firmware b/Documentation/dvb/get_dvb_firmware index 12d3952e83d5..32bc56b13b1c 100755 --- a/Documentation/dvb/get_dvb_firmware +++ b/Documentation/dvb/get_dvb_firmware @@ -116,7 +116,7 @@ sub tda10045 { sub tda10046 { my $sourcefile = "TT_PCI_2.19h_28_11_2006.zip"; - my $url = "http://www.tt-download.com/download/updates/219/$sourcefile"; + my $url = "http://technotrend.com.ua/download/software/219/$sourcefile"; my $hash = "6a7e1e2f2644b162ff0502367553c72d"; my $outfile = "dvb-fe-tda10046.fw"; my $tmpdir = tempdir(DIR => "/tmp", CLEANUP => 1); diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt deleted file mode 100644 index f4d8c7105fcd..000000000000 --- a/Documentation/feature-removal-schedule.txt +++ /dev/null @@ -1,639 +0,0 @@ -The following is a list of files and features that are going to be -removed in the kernel source tree. Every entry should contain what -exactly is going away, why it is happening, and who is going to be doing -the work. When the feature is removed from the kernel, it should also -be removed from this file. The suggested deprecation period is 3 releases. - ---------------------------- - -What: ddebug_query="query" boot cmdline param -When: v3.8 -Why: obsoleted by dyndbg="query" and module.dyndbg="query" -Who: Jim Cromie <jim.cromie@gmail.com>, Jason Baron <jbaron@redhat.com> - ---------------------------- - -What: /proc/sys/vm/nr_pdflush_threads -When: 2012 -Why: Since pdflush is deprecated, the interface exported in /proc/sys/vm/ - should be removed. -Who: Wanpeng Li <liwp@linux.vnet.ibm.com> - ---------------------------- - -What: CONFIG_APM_CPU_IDLE, and its ability to call APM BIOS in idle -When: 2012 -Why: This optional sub-feature of APM is of dubious reliability, - and ancient APM laptops are likely better served by calling HLT. - Deleting CONFIG_APM_CPU_IDLE allows x86 to stop exporting - the pm_idle function pointer to modules. -Who: Len Brown <len.brown@intel.com> - ----------------------------- - -What: x86_32 "no-hlt" cmdline param -When: 2012 -Why: remove a branch from idle path, simplify code used by everybody. - This option disabled the use of HLT in idle and machine_halt() - for hardware that was flakey 15-years ago. Today we have - "idle=poll" that removed HLT from idle, and so if such a machine - is still running the upstream kernel, "idle=poll" is likely sufficient. -Who: Len Brown <len.brown@intel.com> - ----------------------------- - -What: x86 "idle=mwait" cmdline param -When: 2012 -Why: simplify x86 idle code -Who: Len Brown <len.brown@intel.com> - ----------------------------- - -What: PRISM54 -When: 2.6.34 - -Why: prism54 FullMAC PCI / Cardbus devices used to be supported only by the - prism54 wireless driver. After Intersil stopped selling these - devices in preference for the newer more flexible SoftMAC devices - a SoftMAC device driver was required and prism54 did not support - them. The p54pci driver now exists and has been present in the kernel for - a while. This driver supports both SoftMAC devices and FullMAC devices. - The main difference between these devices was the amount of memory which - could be used for the firmware. The SoftMAC devices support a smaller - amount of memory. Because of this the SoftMAC firmware fits into FullMAC - devices's memory. p54pci supports not only PCI / Cardbus but also USB - and SPI. Since p54pci supports all devices prism54 supports - you will have a conflict. I'm not quite sure how distributions are - handling this conflict right now. prism54 was kept around due to - claims users may experience issues when using the SoftMAC driver. - Time has passed users have not reported issues. If you use prism54 - and for whatever reason you cannot use p54pci please let us know! - E-mail us at: linux-wireless@vger.kernel.org - - For more information see the p54 wiki page: - - http://wireless.kernel.org/en/users/Drivers/p54 - -Who: Luis R. Rodriguez <lrodriguez@atheros.com> - ---------------------------- - -What: The ieee80211_regdom module parameter -When: March 2010 / desktop catchup - -Why: This was inherited by the CONFIG_WIRELESS_OLD_REGULATORY code, - and currently serves as an option for users to define an - ISO / IEC 3166 alpha2 code for the country they are currently - present in. Although there are userspace API replacements for this - through nl80211 distributions haven't yet caught up with implementing - decent alternatives through standard GUIs. Although available as an - option through iw or wpa_supplicant its just a matter of time before - distributions pick up good GUI options for this. The ideal solution - would actually consist of intelligent designs which would do this for - the user automatically even when travelling through different countries. - Until then we leave this module parameter as a compromise. - - When userspace improves with reasonable widely-available alternatives for - this we will no longer need this module parameter. This entry hopes that - by the super-futuristically looking date of "March 2010" we will have - such replacements widely available. - -Who: Luis R. Rodriguez <lrodriguez@atheros.com> - ---------------------------- - -What: dev->power.power_state -When: July 2007 -Why: Broken design for runtime control over driver power states, confusing - driver-internal runtime power management with: mechanisms to support - system-wide sleep state transitions; event codes that distinguish - different phases of swsusp "sleep" transitions; and userspace policy - inputs. This framework was never widely used, and most attempts to - use it were broken. Drivers should instead be exposing domain-specific - interfaces either to kernel or to userspace. -Who: Pavel Machek <pavel@ucw.cz> - ---------------------------- - -What: /proc/<pid>/oom_adj -When: August 2012 -Why: /proc/<pid>/oom_adj allows userspace to influence the oom killer's - badness heuristic used to determine which task to kill when the kernel - is out of memory. - - The badness heuristic has since been rewritten since the introduction of - this tunable such that its meaning is deprecated. The value was - implemented as a bitshift on a score generated by the badness() - function that did not have any precise units of measure. With the - rewrite, the score is given as a proportion of available memory to the - task allocating pages, so using a bitshift which grows the score - exponentially is, thus, impossible to tune with fine granularity. - - A much more powerful interface, /proc/<pid>/oom_score_adj, was - introduced with the oom killer rewrite that allows users to increase or - decrease the badness score linearly. This interface will replace - /proc/<pid>/oom_adj. - - A warning will be emitted to the kernel log if an application uses this - deprecated interface. After it is printed once, future warnings will be - suppressed until the kernel is rebooted. - ---------------------------- - -What: remove EXPORT_SYMBOL(kernel_thread) -When: August 2006 -Files: arch/*/kernel/*_ksyms.c -Check: kernel_thread -Why: kernel_thread is a low-level implementation detail. Drivers should - use the <linux/kthread.h> API instead which shields them from - implementation details and provides a higherlevel interface that - prevents bugs and code duplication -Who: Christoph Hellwig <hch@lst.de> - ---------------------------- - -What: Unused EXPORT_SYMBOL/EXPORT_SYMBOL_GPL exports - (temporary transition config option provided until then) - The transition config option will also be removed at the same time. -When: before 2.6.19 -Why: Unused symbols are both increasing the size of the kernel binary - and are often a sign of "wrong API" -Who: Arjan van de Ven <arjan@linux.intel.com> - ---------------------------- - -What: PHYSDEVPATH, PHYSDEVBUS, PHYSDEVDRIVER in the uevent environment -When: October 2008 -Why: The stacking of class devices makes these values misleading and - inconsistent. - Class devices should not carry any of these properties, and bus - devices have SUBSYTEM and DRIVER as a replacement. -Who: Kay Sievers <kay.sievers@suse.de> - ---------------------------- - -What: ACPI procfs interface -When: July 2008 -Why: ACPI sysfs conversion should be finished by January 2008. - ACPI procfs interface will be removed in July 2008 so that - there is enough time for the user space to catch up. -Who: Zhang Rui <rui.zhang@intel.com> - ---------------------------- - -What: CONFIG_ACPI_PROCFS_POWER -When: 2.6.39 -Why: sysfs I/F for ACPI power devices, including AC and Battery, - has been working in upstream kernel since 2.6.24, Sep 2007. - In 2.6.37, we make the sysfs I/F always built in and this option - disabled by default. - Remove this option and the ACPI power procfs interface in 2.6.39. -Who: Zhang Rui <rui.zhang@intel.com> - ---------------------------- - -What: /proc/acpi/event -When: February 2008 -Why: /proc/acpi/event has been replaced by events via the input layer - and netlink since 2.6.23. -Who: Len Brown <len.brown@intel.com> - ---------------------------- - -What: i386/x86_64 bzImage symlinks -When: April 2010 - -Why: The i386/x86_64 merge provides a symlink to the old bzImage - location so not yet updated user space tools, e.g. package - scripts, do not break. -Who: Thomas Gleixner <tglx@linutronix.de> - ---------------------------- - -What: GPIO autorequest on gpio_direction_{input,output}() in gpiolib -When: February 2010 -Why: All callers should use explicit gpio_request()/gpio_free(). - The autorequest mechanism in gpiolib was provided mostly as a - migration aid for legacy GPIO interfaces (for SOC based GPIOs). - Those users have now largely migrated. Platforms implementing - the GPIO interfaces without using gpiolib will see no changes. -Who: David Brownell <dbrownell@users.sourceforge.net> ---------------------------- - -What: b43 support for firmware revision < 410 -When: The schedule was July 2008, but it was decided that we are going to keep the - code as long as there are no major maintanance headaches. - So it _could_ be removed _any_ time now, if it conflicts with something new. -Why: The support code for the old firmware hurts code readability/maintainability - and slightly hurts runtime performance. Bugfixes for the old firmware - are not provided by Broadcom anymore. -Who: Michael Buesch <m@bues.ch> - ---------------------------- - -What: Ability for non root users to shm_get hugetlb pages based on mlock - resource limits -When: 2.6.31 -Why: Non root users need to be part of /proc/sys/vm/hugetlb_shm_group or - have CAP_IPC_LOCK to be able to allocate shm segments backed by - huge pages. The mlock based rlimit check to allow shm hugetlb is - inconsistent with mmap based allocations. Hence it is being - deprecated. -Who: Ravikiran Thirumalai <kiran@scalex86.org> - ---------------------------- - -What: sysfs ui for changing p4-clockmod parameters -When: September 2009 -Why: See commits 129f8ae9b1b5be94517da76009ea956e89104ce8 and - e088e4c9cdb618675874becb91b2fd581ee707e6. - Removal is subject to fixing any remaining bugs in ACPI which may - cause the thermal throttling not to happen at the right time. -Who: Dave Jones <davej@redhat.com>, Matthew Garrett <mjg@redhat.com> - ------------------------------ - -What: fakephp and associated sysfs files in /sys/bus/pci/slots/ -When: 2011 -Why: In 2.6.27, the semantics of /sys/bus/pci/slots was redefined to - represent a machine's physical PCI slots. The change in semantics - had userspace implications, as the hotplug core no longer allowed - drivers to create multiple sysfs files per physical slot (required - for multi-function devices, e.g.). fakephp was seen as a developer's - tool only, and its interface changed. Too late, we learned that - there were some users of the fakephp interface. - - In 2.6.30, the original fakephp interface was restored. At the same - time, the PCI core gained the ability that fakephp provided, namely - function-level hot-remove and hot-add. - - Since the PCI core now provides the same functionality, exposed in: - - /sys/bus/pci/rescan - /sys/bus/pci/devices/.../remove - /sys/bus/pci/devices/.../rescan - - there is no functional reason to maintain fakephp as well. - - We will keep the existing module so that 'modprobe fakephp' will - present the old /sys/bus/pci/slots/... interface for compatibility, - but users are urged to migrate their applications to the API above. - - After a reasonable transition period, we will remove the legacy - fakephp interface. -Who: Alex Chiang <achiang@hp.com> - ---------------------------- - -What: CONFIG_RFKILL_INPUT -When: 2.6.33 -Why: Should be implemented in userspace, policy daemon. -Who: Johannes Berg <johannes@sipsolutions.net> - ----------------------------- - -What: sound-slot/service-* module aliases and related clutters in - sound/sound_core.c -When: August 2010 -Why: OSS sound_core grabs all legacy minors (0-255) of SOUND_MAJOR - (14) and requests modules using custom sound-slot/service-* - module aliases. The only benefit of doing this is allowing - use of custom module aliases which might as well be considered - a bug at this point. This preemptive claiming prevents - alternative OSS implementations. - - Till the feature is removed, the kernel will be requesting - both sound-slot/service-* and the standard char-major-* module - aliases and allow turning off the pre-claiming selectively via - CONFIG_SOUND_OSS_CORE_PRECLAIM and soundcore.preclaim_oss - kernel parameter. - - After the transition phase is complete, both the custom module - aliases and switches to disable it will go away. This removal - will also allow making ALSA OSS emulation independent of - sound_core. The dependency will be broken then too. -Who: Tejun Heo <tj@kernel.org> - ----------------------------- - -What: sysfs-class-rfkill state file -When: Feb 2014 -Files: net/rfkill/core.c -Why: Documented as obsolete since Feb 2010. This file is limited to 3 - states while the rfkill drivers can have 4 states. -Who: anybody or Florian Mickler <florian@mickler.org> - ----------------------------- - -What: sysfs-class-rfkill claim file -When: Feb 2012 -Files: net/rfkill/core.c -Why: It is not possible to claim an rfkill driver since 2007. This is - Documented as obsolete since Feb 2010. -Who: anybody or Florian Mickler <florian@mickler.org> - ----------------------------- - -What: iwlwifi 50XX module parameters -When: 3.0 -Why: The "..50" modules parameters were used to configure 5000 series and - up devices; different set of module parameters also available for 4965 - with same functionalities. Consolidate both set into single place - in drivers/net/wireless/iwlwifi/iwl-agn.c - -Who: Wey-Yi Guy <wey-yi.w.guy@intel.com> - ----------------------------- - -What: iwl4965 alias support -When: 3.0 -Why: Internal alias support has been present in module-init-tools for some - time, the MODULE_ALIAS("iwl4965") boilerplate aliases can be removed - with no impact. - -Who: Wey-Yi Guy <wey-yi.w.guy@intel.com> - ---------------------------- - -What: xt_NOTRACK -Files: net/netfilter/xt_NOTRACK.c -When: April 2011 -Why: Superseded by xt_CT -Who: Netfilter developer team <netfilter-devel@vger.kernel.org> - ----------------------------- - -What: IRQF_DISABLED -When: 2.6.36 -Why: The flag is a NOOP as we run interrupt handlers with interrupts disabled -Who: Thomas Gleixner <tglx@linutronix.de> - ----------------------------- - -What: PCI DMA unmap state API -When: August 2012 -Why: PCI DMA unmap state API (include/linux/pci-dma.h) was replaced - with DMA unmap state API (DMA unmap state API can be used for - any bus). -Who: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp> - ----------------------------- - -What: iwlwifi disable_hw_scan module parameters -When: 3.0 -Why: Hareware scan is the prefer method for iwlwifi devices for - scanning operation. Remove software scan support for all the - iwlwifi devices. - -Who: Wey-Yi Guy <wey-yi.w.guy@intel.com> - ----------------------------- - -What: Legacy, non-standard chassis intrusion detection interface. -When: June 2011 -Why: The adm9240, w83792d and w83793 hardware monitoring drivers have - legacy interfaces for chassis intrusion detection. A standard - interface has been added to each driver, so the legacy interface - can be removed. -Who: Jean Delvare <khali@linux-fr.org> - ----------------------------- - -What: i2c_driver.attach_adapter - i2c_driver.detach_adapter -When: September 2011 -Why: These legacy callbacks should no longer be used as i2c-core offers - a variety of preferable alternative ways to instantiate I2C devices. -Who: Jean Delvare <khali@linux-fr.org> - ----------------------------- - -What: Opening a radio device node will no longer automatically switch the - tuner mode from tv to radio. -When: 3.3 -Why: Just opening a V4L device should not change the state of the hardware - like that. It's very unexpected and against the V4L spec. Instead, you - switch to radio mode by calling VIDIOC_S_FREQUENCY. This is the second - and last step of the move to consistent handling of tv and radio tuners. -Who: Hans Verkuil <hans.verkuil@cisco.com> - ----------------------------- - -What: CONFIG_CFG80211_WEXT -When: as soon as distributions ship new wireless tools, ie. wpa_supplicant 1.0 - and NetworkManager/connman/etc. that are able to use nl80211 -Why: Wireless extensions are deprecated, and userland tools are moving to - using nl80211. New drivers are no longer using wireless extensions, - and while there might still be old drivers, both new drivers and new - userland no longer needs them and they can't be used for an feature - developed in the past couple of years. As such, compatibility with - wireless extensions in new drivers will be removed. -Who: Johannes Berg <johannes@sipsolutions.net> - ----------------------------- - -What: g_file_storage driver -When: 3.8 -Why: This driver has been superseded by g_mass_storage. -Who: Alan Stern <stern@rowland.harvard.edu> - ----------------------------- - -What: threeg and interface sysfs files in /sys/devices/platform/acer-wmi -When: 2012 -Why: In 3.0, we can now autodetect internal 3G device and already have - the threeg rfkill device. So, we plan to remove threeg sysfs support - for it's no longer necessary. - - We also plan to remove interface sysfs file that exposed which ACPI-WMI - interface that was used by acer-wmi driver. It will replaced by - information log when acer-wmi initial. -Who: Lee, Chun-Yi <jlee@novell.com> - ---------------------------- - -What: /sys/devices/platform/_UDC_/udc/_UDC_/is_dualspeed file and - is_dualspeed line in /sys/devices/platform/ci13xxx_*/udc/device file. -When: 3.8 -Why: The is_dualspeed file is superseded by maximum_speed in the same - directory and is_dualspeed line in device file is superseded by - max_speed line in the same file. - - The maximum_speed/max_speed specifies maximum speed supported by UDC. - To check if dualspeeed is supported, check if the value is >= 3. - Various possible speeds are defined in <linux/usb/ch9.h>. -Who: Michal Nazarewicz <mina86@mina86.com> - ----------------------------- - -What: The XFS nodelaylog mount option -When: 3.3 -Why: The delaylog mode that has been the default since 2.6.39 has proven - stable, and the old code is in the way of additional improvements in - the log code. -Who: Christoph Hellwig <hch@lst.de> - ----------------------------- - -What: iwlagn alias support -When: 3.5 -Why: The iwlagn module has been renamed iwlwifi. The alias will be around - for backward compatibility for several cycles and then dropped. -Who: Don Fry <donald.h.fry@intel.com> - ----------------------------- - -What: pci_scan_bus_parented() -When: 3.5 -Why: The pci_scan_bus_parented() interface creates a new root bus. The - bus is created with default resources (ioport_resource and - iomem_resource) that are always wrong, so we rely on arch code to - correct them later. Callers of pci_scan_bus_parented() should - convert to using pci_scan_root_bus() so they can supply a list of - bus resources when the bus is created. -Who: Bjorn Helgaas <bhelgaas@google.com> - ----------------------------- - -What: Low Performance USB Block driver ("CONFIG_BLK_DEV_UB") -When: 3.6 -Why: This driver provides support for USB storage devices like "USB - sticks". As of now, it is deactivated in Debian, Fedora and - Ubuntu. All current users can switch over to usb-storage - (CONFIG_USB_STORAGE) which only drawback is the additional SCSI - stack. -Who: Sebastian Andrzej Siewior <sebastian@breakpoint.cc> - ----------------------------- - -What: get_robust_list syscall -When: 2013 -Why: There appear to be no production users of the get_robust_list syscall, - and it runs the risk of leaking address locations, allowing the bypass - of ASLR. It was only ever intended for debugging, so it should be - removed. -Who: Kees Cook <keescook@chromium.org> - ----------------------------- - -What: Removing the pn544 raw driver. -When: 3.6 -Why: With the introduction of the NFC HCI and SHDL kernel layers, pn544.c - is being replaced by pn544_hci.c which is accessible through the netlink - and socket NFC APIs. Moreover, pn544.c is outdated and does not seem to - work properly with the latest Android stacks. - Having 2 drivers for the same hardware is confusing and as such we - should only keep the one following the kernel NFC APIs. -Who: Samuel Ortiz <sameo@linux.intel.com> - ----------------------------- - -What: setitimer accepts user NULL pointer (value) -When: 3.6 -Why: setitimer is not returning -EFAULT if user pointer is NULL. This - violates the spec. -Who: Sasikantha Babu <sasikanth.v19@gmail.com> - ----------------------------- - -What: remove bogus DV presets V4L2_DV_1080I29_97, V4L2_DV_1080I30 and - V4L2_DV_1080I25 -When: 3.6 -Why: These HDTV formats do not exist and were added by a confused mind - (that was me, to be precise...) -Who: Hans Verkuil <hans.verkuil@cisco.com> - ----------------------------- - -What: V4L2_CID_HCENTER, V4L2_CID_VCENTER V4L2 controls -When: 3.7 -Why: The V4L2_CID_VCENTER, V4L2_CID_HCENTER controls have been deprecated - for about 4 years and they are not used by any mainline driver. - There are newer controls (V4L2_CID_PAN*, V4L2_CID_TILT*) that provide - similar functionality. -Who: Sylwester Nawrocki <sylvester.nawrocki@gmail.com> - ----------------------------- - -What: cgroup option updates via remount -When: March 2013 -Why: Remount currently allows changing bound subsystems and - release_agent. Rebinding is hardly useful as it only works - when the hierarchy is empty and release_agent itself should be - replaced with conventional fsnotify. - ----------------------------- - -What: xt_recent rev 0 -When: 2013 -Who: Pablo Neira Ayuso <pablo@netfilter.org> -Files: net/netfilter/xt_recent.c - ----------------------------- - -What: KVM debugfs statistics -When: 2013 -Why: KVM tracepoints provide mostly equivalent information in a much more - flexible fashion. - ----------------------------- - -What: at91-mci driver ("CONFIG_MMC_AT91") -When: 3.8 -Why: There are two mci drivers: at91-mci and atmel-mci. The PDC support - was added to atmel-mci as a first step to support more chips. - Then at91-mci was kept only for old IP versions (on at91rm9200 and - at91sam9261). The support of these IP versions has just been added - to atmel-mci, so atmel-mci can be used for all chips. -Who: Ludovic Desroches <ludovic.desroches@atmel.com> - ----------------------------- - -What: net/wanrouter/ -When: June 2013 -Why: Unsupported/unmaintained/unused since 2.6 - ----------------------------- - -What: V4L2 selections API target rectangle and flags unification, the - following definitions will be removed: V4L2_SEL_TGT_CROP_ACTIVE, - V4L2_SEL_TGT_COMPOSE_ACTIVE, V4L2_SUBDEV_SEL_*, V4L2_SUBDEV_SEL_FLAG_* - in favor of common V4L2_SEL_TGT_* and V4L2_SEL_FLAG_* definitions. - For more details see include/linux/v4l2-common.h. -When: 3.8 -Why: The regular V4L2 selections and the subdev selection API originally - defined distinct names for the target rectangles and flags - V4L2_SEL_* - and V4L2_SUBDEV_SEL_*. Although, it turned out that the meaning of these - target rectangles is virtually identical and the APIs were consolidated - to use single set of names - V4L2_SEL_*. This didn't involve any ABI - changes. Alias definitions were created for the original ones to avoid - any instabilities in the user space interface. After few cycles these - backward compatibility definitions will be removed. -Who: Sylwester Nawrocki <sylvester.nawrocki@gmail.com> - ----------------------------- - -What: Using V4L2_CAP_VIDEO_CAPTURE and V4L2_CAP_VIDEO_OUTPUT flags - to indicate a V4L2 memory-to-memory device capability -When: 3.8 -Why: New drivers should use new V4L2_CAP_VIDEO_M2M capability flag - to indicate a V4L2 video memory-to-memory (M2M) device and - applications can now identify a M2M video device by checking - for V4L2_CAP_VIDEO_M2M, with VIDIOC_QUERYCAP ioctl. Using ORed - V4L2_CAP_VIDEO_CAPTURE and V4L2_CAP_VIDEO_OUTPUT flags for M2M - devices is ambiguous and may lead, for example, to identifying - a M2M device as a video capture or output device. -Who: Sylwester Nawrocki <s.nawrocki@samsung.com> - ----------------------------- - -What: OMAP private DMA implementation -When: 2013 -Why: We have a DMA engine implementation; all users should be updated - to use this rather than persisting with the old APIs. The old APIs - block merging the old DMA engine implementation into the DMA - engine driver. -Who: Russell King <linux@arm.linux.org.uk>, - Santosh Shilimkar <santosh.shilimkar@ti.com> - ----------------------------- diff --git a/Documentation/filesystems/debugfs.txt b/Documentation/filesystems/debugfs.txt index 7a34f827989c..3a863f692728 100644 --- a/Documentation/filesystems/debugfs.txt +++ b/Documentation/filesystems/debugfs.txt @@ -15,8 +15,8 @@ Debugfs is typically mounted with a command like: mount -t debugfs none /sys/kernel/debug (Or an equivalent /etc/fstab line). -The debugfs root directory is accessible by anyone by default. To -restrict access to the tree the "uid", "gid" and "mode" mount +The debugfs root directory is accessible only to the root user by +default. To change access to the tree the "uid", "gid" and "mode" mount options can be used. Note that the debugfs API is exported GPL-only to modules. diff --git a/Documentation/filesystems/ext4.txt b/Documentation/filesystems/ext4.txt index 1b7f9acbcbbe..104322bf378c 100644 --- a/Documentation/filesystems/ext4.txt +++ b/Documentation/filesystems/ext4.txt @@ -375,6 +375,16 @@ dioread_nolock locking. If the dioread_nolock option is specified Because of the restrictions this options comprises it is off by default (e.g. dioread_lock). +max_dir_size_kb=n This limits the size of directories so that any + attempt to expand them beyond the specified + limit in kilobytes will cause an ENOSPC error. + This is useful in memory constrained + environments, where a very large directory can + cause severe performance problems or even + provoke the Out Of Memory killer. (For example, + if there is only 512mb memory available, a 176mb + directory may seriously cramp the system's style.) + i_version Enable 64-bit inode version support. This option is off by default. diff --git a/Documentation/filesystems/jfs.txt b/Documentation/filesystems/jfs.txt index 26ebde77e821..f7433355394a 100644 --- a/Documentation/filesystems/jfs.txt +++ b/Documentation/filesystems/jfs.txt @@ -3,6 +3,7 @@ IBM's Journaled File System (JFS) for Linux JFS Homepage: http://jfs.sourceforge.net/ The following mount options are supported: +(*) == default iocharset=name Character set to use for converting from Unicode to ASCII. The default is to do no conversion. Use @@ -21,12 +22,12 @@ nointegrity Do not write to the journal. The primary use of this option from backup media. The integrity of the volume is not guaranteed if the system abnormally abends. -integrity Default. Commit metadata changes to the journal. Use this - option to remount a volume where the nointegrity option was +integrity(*) Commit metadata changes to the journal. Use this option to + remount a volume where the nointegrity option was previously specified in order to restore normal behavior. errors=continue Keep going on a filesystem error. -errors=remount-ro Default. Remount the filesystem read-only on an error. +errors=remount-ro(*) Remount the filesystem read-only on an error. errors=panic Panic and halt the machine if an error occurs. uid=value Override on-disk uid with specified value @@ -35,7 +36,17 @@ umask=value Override on-disk umask with specified octal value. For directories, the execute bit will be set if the corresponding read bit is set. -Please send bugs, comments, cards and letters to shaggy@linux.vnet.ibm.com. +discard=minlen This enables/disables the use of discard/TRIM commands. +discard The discard/TRIM commands are sent to the underlying +nodiscard(*) block device when blocks are freed. This is useful for SSD + devices and sparse/thinly-provisioned LUNs. The FITRIM ioctl + command is also available together with the nodiscard option. + The value of minlen specifies the minimum blockcount, when + a TRIM command to the block device is considered usefull. + When no value is given to the discard option, it defaults to + 64 blocks, which means 256KiB in JFS. + The minlen value of discard overrides the minlen value given + on an FITRIM ioctl(). The JFS mailing list can be subscribed to by using the link labeled "Mail list Subscribe" at our web page http://jfs.sourceforge.net/ diff --git a/Documentation/filesystems/nfs/nfsroot.txt b/Documentation/filesystems/nfs/nfsroot.txt index ffdd9d866ad7..2d66ed688125 100644 --- a/Documentation/filesystems/nfs/nfsroot.txt +++ b/Documentation/filesystems/nfs/nfsroot.txt @@ -78,7 +78,8 @@ nfsroot=[<server-ip>:]<root-dir>[,<nfs-options>] flags = hard, nointr, noposix, cto, ac -ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> +ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>: + <dns0-ip>:<dns1-ip> This parameter tells the kernel how to configure IP addresses of devices and also how to set up the IP routing table. It was originally called @@ -158,6 +159,13 @@ ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf> Default: any + <dns0-ip> IP address of first nameserver. + Value gets exported by /proc/net/pnp which is often linked + on embedded systems by /etc/resolv.conf. + + <dns1-ip> IP address of secound nameserver. + Same as above. + nfsrootdebug diff --git a/Documentation/filesystems/proc.txt b/Documentation/filesystems/proc.txt index fb0a6aeb936c..a1793d670cd0 100644 --- a/Documentation/filesystems/proc.txt +++ b/Documentation/filesystems/proc.txt @@ -33,7 +33,7 @@ Table of Contents 2 Modifying System Parameters 3 Per-Process Parameters - 3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj - Adjust the oom-killer + 3.1 /proc/<pid>/oom_score_adj - Adjust the oom-killer score 3.2 /proc/<pid>/oom_score - Display current oom-killer score 3.3 /proc/<pid>/io - Display the IO accounting fields @@ -1320,10 +1320,10 @@ of the kernel. CHAPTER 3: PER-PROCESS PARAMETERS ------------------------------------------------------------------------------ -3.1 /proc/<pid>/oom_adj & /proc/<pid>/oom_score_adj- Adjust the oom-killer score +3.1 /proc/<pid>/oom_score_adj- Adjust the oom-killer score -------------------------------------------------------------------------------- -These file can be used to adjust the badness heuristic used to select which +This file can be used to adjust the badness heuristic used to select which process gets killed in out of memory conditions. The badness heuristic assigns a value to each candidate task ranging from 0 @@ -1361,22 +1361,10 @@ same system, cpuset, mempolicy, or memory controller resources to use at least equivalent to discounting 50% of the task's allowed memory from being considered as scoring against the task. -For backwards compatibility with previous kernels, /proc/<pid>/oom_adj may also -be used to tune the badness score. Its acceptable values range from -16 -(OOM_ADJUST_MIN) to +15 (OOM_ADJUST_MAX) and a special value of -17 -(OOM_DISABLE) to disable oom killing entirely for that task. Its value is -scaled linearly with /proc/<pid>/oom_score_adj. - -Writing to /proc/<pid>/oom_score_adj or /proc/<pid>/oom_adj will change the -other with its scaled value. - The value of /proc/<pid>/oom_score_adj may be reduced no lower than the last value set by a CAP_SYS_RESOURCE process. To reduce the value any lower requires CAP_SYS_RESOURCE. -NOTICE: /proc/<pid>/oom_adj is deprecated and will be removed, please see -Documentation/feature-removal-schedule.txt. - Caveat: when a parent task is selected, the oom killer will sacrifice any first generation children with separate address spaces instead, if possible. This avoids servers and important system daemons from being killed and loses the @@ -1387,9 +1375,7 @@ minimal amount of work. ------------------------------------------------------------- This file can be used to check the current score used by the oom-killer is for -any given <pid>. Use it together with /proc/<pid>/oom_adj to tune which -process should be killed in an out-of-memory situation. - +any given <pid>. 3.3 /proc/<pid>/io - Display the IO accounting fields ------------------------------------------------------- diff --git a/Documentation/hid/hid-sensor.txt b/Documentation/hid/hid-sensor.txt new file mode 100755 index 000000000000..948b0989c433 --- /dev/null +++ b/Documentation/hid/hid-sensor.txt @@ -0,0 +1,140 @@ + +HID Sensors Framework +====================== +HID sensor framework provides necessary interfaces to implement sensor drivers, +which are connected to a sensor hub. The sensor hub is a HID device and it provides +a report descriptor conforming to HID 1.12 sensor usage tables. + +Description from the HID 1.12 "HID Sensor Usages" specification: +"Standardization of HID usages for sensors would allow (but not require) sensor +hardware vendors to provide a consistent Plug And Play interface at the USB boundary, +thereby enabling some operating systems to incorporate common device drivers that +could be reused between vendors, alleviating any need for the vendors to provide +the drivers themselves." + +This specification describes many usage IDs, which describe the type of sensor +and also the individual data fields. Each sensor can have variable number of +data fields. The length and order is specified in the report descriptor. For +example a part of report descriptor can look like: + + INPUT(1)[INPUT] + .. + Field(2) + Physical(0020.0073) + Usage(1) + 0020.045f + Logical Minimum(-32767) + Logical Maximum(32767) + Report Size(8) + Report Count(1) + Report Offset(16) + Flags(Variable Absolute) +.. +.. + +The report is indicating "sensor page (0x20)" contains an accelerometer-3D (0x73). +This accelerometer-3D has some fields. Here for example field 2 is motion intensity +(0x045f) with a logical minimum value of -32767 and logical maximum of 32767. The +order of fields and length of each field is important as the input event raw +data will use this format. + + +Implementation +================= + +This specification defines many different types of sensors with different sets of +data fields. It is difficult to have a common input event to user space applications, +for different sensors. For example an accelerometer can send X,Y and Z data, whereas +an ambient light sensor can send illumination data. +So the implementation has two parts: +- Core hid driver +- Individual sensor processing part (sensor drivers) + +Core driver +----------- +The core driver registers (hid-sensor-hub) registers as a HID driver. It parses +report descriptors and identifies all the sensors present. It adds an MFD device +with name HID-SENSOR-xxxx (where xxxx is usage id from the specification). +For example +HID-SENSOR-200073 is registered for an Accelerometer 3D driver. +So if any driver with this name is inserted, then the probe routine for that +function will be called. So an accelerometer processing driver can register +with this name and will be probed if there is an accelerometer-3D detected. + +The core driver provides a set of APIs which can be used by the processing +drivers to register and get events for that usage id. Also it provides parsing +functions, which get and set each input/feature/output report. + +Individual sensor processing part (sensor drivers) +----------- +The processing driver will use an interface provided by the core driver to parse +the report and get the indexes of the fields and also can get events. This driver +can use IIO interface to use the standard ABI defined for a type of sensor. + + +Core driver Interface +===================== + +Callback structure: +Each processing driver can use this structure to set some callbacks. + int (*suspend)(..): Callback when HID suspend is received + int (*resume)(..): Callback when HID resume is received + int (*capture_sample)(..): Capture a sample for one of its data fields + int (*send_event)(..): One complete event is received which can have + multiple data fields. + +Registration functions: +int sensor_hub_register_callback(struct hid_sensor_hub_device *hsdev, + u32 usage_id, + struct hid_sensor_hub_callbacks *usage_callback): + +Registers callbacks for an usage id. The callback functions are not allowed +to sleep. + + +int sensor_hub_remove_callback(struct hid_sensor_hub_device *hsdev, + u32 usage_id): + +Removes callbacks for an usage id. + + +Parsing function: +int sensor_hub_input_get_attribute_info(struct hid_sensor_hub_device *hsdev, + u8 type, + u32 usage_id, u32 attr_usage_id, + struct hid_sensor_hub_attribute_info *info); + +A processing driver can look for some field of interest and check if it exists +in a report descriptor. If it exists it will store necessary information +so that fields can be set or get individually. +These indexes avoid searching every time and getting field index to get or set. + + +Set Feature report +int sensor_hub_set_feature(struct hid_sensor_hub_device *hsdev, u32 report_id, + u32 field_index, s32 value); + +This interface is used to set a value for a field in feature report. For example +if there is a field report_interval, which is parsed by a call to +sensor_hub_input_get_attribute_info before, then it can directly set that individual +field. + + +int sensor_hub_get_feature(struct hid_sensor_hub_device *hsdev, u32 report_id, + u32 field_index, s32 *value); + +This interface is used to get a value for a field in input report. For example +if there is a field report_interval, which is parsed by a call to +sensor_hub_input_get_attribute_info before, then it can directly get that individual +field value. + + +int sensor_hub_input_attr_get_raw_value(struct hid_sensor_hub_device *hsdev, + u32 usage_id, + u32 attr_usage_id, u32 report_id); + +This is used to get a particular field value through input reports. For example +accelerometer wants to poll X axis value, then it can call this function with +the usage id of X axis. HID sensors can provide events, so this is not necessary +to poll for any field. If there is some new sample, the core driver will call +registered callback function to process the sample. diff --git a/Documentation/hwmon/adt7410 b/Documentation/hwmon/adt7410 new file mode 100644 index 000000000000..96004000dc2a --- /dev/null +++ b/Documentation/hwmon/adt7410 @@ -0,0 +1,51 @@ +Kernel driver adt7410 +===================== + +Supported chips: + * Analog Devices ADT7410 + Prefix: 'adt7410' + Addresses scanned: I2C 0x48 - 0x4B + Datasheet: Publicly available at the Analog Devices website + http://www.analog.com/static/imported-files/data_sheets/ADT7410.pdf + +Author: Hartmut Knaack <knaack.h@gmx.de> + +Description +----------- + +The ADT7410 is a temperature sensor with rated temperature range of -55°C to ++150°C. It has a high accuracy of +/-0.5°C and can be operated at a resolution +of 13 bits (0.0625°C) or 16 bits (0.0078°C). The sensor provides an INT pin to +indicate that a minimum or maximum temperature set point has been exceeded, as +well as a critical temperature (CT) pin to indicate that the critical +temperature set point has been exceeded. Both pins can be set up with a common +hysteresis of 0°C - 15°C and a fault queue, ranging from 1 to 4 events. Both +pins can individually set to be active-low or active-high, while the whole +device can either run in comparator mode or interrupt mode. The ADT7410 +supports continous temperature sampling, as well as sampling one temperature +value per second or even justget one sample on demand for power saving. +Besides, it can completely power down its ADC, if power management is +required. + +Configuration Notes +------------------- + +Since the device uses one hysteresis value, which is an offset to minimum, +maximum and critical temperature, it can only be set for temp#_max_hyst. +However, temp#_min_hyst and temp#_crit_hyst show their corresponding +hysteresis. +The device is set to 16 bit resolution and comparator mode. + +sysfs-Interface +--------------- + +temp#_input - temperature input +temp#_min - temperature minimum setpoint +temp#_max - temperature maximum setpoint +temp#_crit - critical temperature setpoint +temp#_min_hyst - hysteresis for temperature minimum (read-only) +temp#_max_hyst - hysteresis for temperature maximum (read/write) +temp#_crit_hyst - hysteresis for critical temperature (read-only) +temp#_min_alarm - temperature minimum alarm flag +temp#_max_alarm - temperature maximum alarm flag +temp#_crit_alarm - critical temperature alarm flag diff --git a/Documentation/hwmon/ina2xx b/Documentation/hwmon/ina2xx index f50a6cc27616..03444f9d833f 100644 --- a/Documentation/hwmon/ina2xx +++ b/Documentation/hwmon/ina2xx @@ -8,12 +8,24 @@ Supported chips: Datasheet: Publicly available at the Texas Instruments website http://www.ti.com/ + * Texas Instruments INA220 + Prefix: 'ina220' + Addresses: I2C 0x40 - 0x4f + Datasheet: Publicly available at the Texas Instruments website + http://www.ti.com/ + * Texas Instruments INA226 Prefix: 'ina226' Addresses: I2C 0x40 - 0x4f Datasheet: Publicly available at the Texas Instruments website http://www.ti.com/ + * Texas Instruments INA230 + Prefix: 'ina230' + Addresses: I2C 0x40 - 0x4f + Datasheet: Publicly available at the Texas Instruments website + http://www.ti.com/ + Author: Lothar Felten <l-felten@ti.com> Description @@ -23,7 +35,13 @@ The INA219 is a high-side current shunt and power monitor with an I2C interface. The INA219 monitors both shunt drop and supply voltage, with programmable conversion times and filtering. +The INA220 is a high or low side current shunt and power monitor with an I2C +interface. The INA220 monitors both shunt drop and supply voltage. + The INA226 is a current shunt and power monitor with an I2C interface. The INA226 monitors both a shunt voltage drop and bus supply voltage. +The INA230 is a high or low side current shunt and power monitor with an I2C +interface. The INA230 monitors both a shunt voltage drop and bus supply voltage. + The shunt value in micro-ohms can be set via platform data. diff --git a/Documentation/hwmon/lm70 b/Documentation/hwmon/lm70 index 0d240291e3cc..86d182942c51 100644 --- a/Documentation/hwmon/lm70 +++ b/Documentation/hwmon/lm70 @@ -6,6 +6,10 @@ Supported chips: Datasheet: http://www.national.com/pf/LM/LM70.html * Texas Instruments TMP121/TMP123 Information: http://focus.ti.com/docs/prod/folders/print/tmp121.html + * National Semiconductor LM71 + Datasheet: http://www.ti.com/product/LM71 + * National Semiconductor LM74 + Datasheet: http://www.ti.com/product/LM74 Author: Kaiwan N Billimoria <kaiwan@designergraphix.com> @@ -31,9 +35,11 @@ As a real (in-tree) example of this "SPI protocol driver" interfacing with a "SPI master controller driver", see drivers/spi/spi_lm70llp.c and its associated documentation. -The TMP121/TMP123 are very similar; main differences are 4 wire SPI inter- -face (read only) and 13-bit temperature data (0.0625 degrees celsius reso- -lution). +The LM74 and TMP121/TMP123 are very similar; main difference is 13-bit +temperature data (0.0625 degrees celsius resolution). + +The LM71 is also very similar; main difference is 14-bit temperature +data (0.03125 degrees celsius resolution). Thanks to --------- diff --git a/Documentation/hwmon/max197 b/Documentation/hwmon/max197 new file mode 100644 index 000000000000..8d89b9009df8 --- /dev/null +++ b/Documentation/hwmon/max197 @@ -0,0 +1,60 @@ +Maxim MAX197 driver +=================== + +Author: + * Vivien Didelot <vivien.didelot@savoirfairelinux.com> + +Supported chips: + * Maxim MAX197 + Prefix: 'max197' + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX197.pdf + + * Maxim MAX199 + Prefix: 'max199' + Datasheet: http://datasheets.maxim-ic.com/en/ds/MAX199.pdf + +Description +----------- + +The A/D converters MAX197, and MAX199 are both 8-Channel, Multi-Range, 5V, +12-Bit DAS with 8+4 Bus Interface and Fault Protection. + +The available ranges for the MAX197 are {0,-5V} to 5V, and {0,-10V} to 10V, +while they are {0,-2V} to 2V, and {0,-4V} to 4V on the MAX199. + +Platform data +------------- + +The MAX197 platform data (defined in linux/platform_data/max197.h) should be +filled with a pointer to a conversion function, defined like: + + int convert(u8 ctrl); + +ctrl is the control byte to write to start a new conversion. +On success, the function must return the 12-bit raw value read from the chip, +or a negative error code otherwise. + +Control byte format: + +Bit Name Description +7,6 PD1,PD0 Clock and Power-Down modes +5 ACQMOD Internal or External Controlled Acquisition +4 RNG Full-scale voltage magnitude at the input +3 BIP Unipolar or Bipolar conversion mode +2,1,0 A2,A1,A0 Channel + +Sysfs interface +--------------- + +* in[0-7]_input: The conversion value for the corresponding channel. + RO + +* in[0-7]_min: The lower limit (in mV) for the corresponding channel. + For the MAX197, it will be adjusted to -10000, -5000, or 0. + For the MAX199, it will be adjusted to -4000, -2000, or 0. + RW + +* in[0-7]_max: The higher limit (in mV) for the corresponding channel. + For the MAX197, it will be adjusted to 0, 5000, or 10000. + For the MAX199, it will be adjusted to 0, 2000, or 4000. + RW diff --git a/Documentation/hwmon/mcp3021 b/Documentation/hwmon/mcp3021 index 325fd87e81b2..74a6b72adf5f 100644 --- a/Documentation/hwmon/mcp3021 +++ b/Documentation/hwmon/mcp3021 @@ -5,18 +5,25 @@ Supported chips: * Microchip Technology MCP3021 Prefix: 'mcp3021' Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21805a.pdf + * Microchip Technology MCP3221 + Prefix: 'mcp3221' + Datasheet: http://ww1.microchip.com/downloads/en/DeviceDoc/21732c.pdf -Author: Mingkai Hu +Authors: + Mingkai Hu + Sven Schuchmann <schuchmann@schleissheimer.de> Description ----------- -This driver implements support for the Microchip Technology MCP3021 chip. +This driver implements support for the Microchip Technology MCP3021 and +MCP3221 chip. The Microchip Technology Inc. MCP3021 is a successive approximation A/D -converter (ADC) with 10-bit resolution. -This device provides one single-ended input with very low power consumption. -Communication to the MCP3021 is performed using a 2-wire I2C compatible -interface. Standard (100 kHz) and Fast (400 kHz) I2C modes are available. -The default I2C device address is 0x4d (contact the Microchip factory for -additional address options). +converter (ADC) with 10-bit resolution. The MCP3221 has 12-bit resolution. + +These devices provide one single-ended input with very low power consumption. +Communication to the MCP3021/MCP3221 is performed using a 2-wire I2C +compatible interface. Standard (100 kHz) and Fast (400 kHz) I2C modes are +available. The default I2C device address is 0x4d (contact the Microchip +factory for additional address options). diff --git a/Documentation/i2c/busses/i2c-viapro b/Documentation/i2c/busses/i2c-viapro index 2e758b0e9456..b88f91ae580e 100644 --- a/Documentation/i2c/busses/i2c-viapro +++ b/Documentation/i2c/busses/i2c-viapro @@ -20,7 +20,10 @@ Supported adapters: Datasheet: available on http://linux.via.com.tw * VIA Technologies, Inc. VX855/VX875 - Datasheet: Availability unknown + Datasheet: available on http://linux.via.com.tw + + * VIA Technologies, Inc. VX900 + Datasheet: available on http://linux.via.com.tw Authors: Kyösti Mälkki <kmalkki@cc.hut.fi>, @@ -57,6 +60,7 @@ Your lspci -n listing must show one of these : device 1106:8324 (CX700) device 1106:8353 (VX800/VX820) device 1106:8409 (VX855/VX875) + device 1106:8410 (VX900) If none of these show up, you should look in the BIOS for settings like enable ACPI / SMBus or even USB. diff --git a/Documentation/i2c/muxes/i2c-mux-gpio b/Documentation/i2c/muxes/i2c-mux-gpio index bd9b2299b739..d4d91a53fc39 100644 --- a/Documentation/i2c/muxes/i2c-mux-gpio +++ b/Documentation/i2c/muxes/i2c-mux-gpio @@ -63,3 +63,21 @@ static struct platform_device myboard_i2cmux = { .platform_data = &myboard_i2cmux_data, }, }; + +If you don't know the absolute GPIO pin numbers at registration time, +you can instead provide a chip name (.chip_name) and relative GPIO pin +numbers, and the i2c-gpio-mux driver will do the work for you, +including deferred probing if the GPIO chip isn't immediately +available. + +Device Registration +------------------- + +When registering your i2c-gpio-mux device, you should pass the number +of any GPIO pin it uses as the device ID. This guarantees that every +instance has a different ID. + +Alternatively, if you don't need a stable device name, you can simply +pass PLATFORM_DEVID_AUTO as the device ID, and the platform core will +assign a dynamic ID to your device. If you do not know the absolute +GPIO pin numbers at registration time, this is even the only option. diff --git a/Documentation/ia64/aliasing-test.c b/Documentation/ia64/aliasing-test.c index 5caa2af33207..62a190d45f38 100644 --- a/Documentation/ia64/aliasing-test.c +++ b/Documentation/ia64/aliasing-test.c @@ -132,6 +132,7 @@ static int read_rom(char *path) rc = write(fd, "1", 2); if (rc <= 0) { + close(fd); perror("write"); return -1; } diff --git a/Documentation/infiniband/ipoib.txt b/Documentation/infiniband/ipoib.txt index 64eeb55d0c09..f2cfe265e836 100644 --- a/Documentation/infiniband/ipoib.txt +++ b/Documentation/infiniband/ipoib.txt @@ -24,6 +24,9 @@ Partitions and P_Keys The P_Key for any interface is given by the "pkey" file, and the main interface for a subinterface is in "parent." + Child interface create/delete can also be done using IPoIB's + rtnl_link_ops, where childs created using either way behave the same. + Datagram vs Connected modes The IPoIB driver supports two modes of operation: datagram and diff --git a/Documentation/ioctl/ioctl-number.txt b/Documentation/ioctl/ioctl-number.txt index 849b771c5e03..2152b0e7237d 100644 --- a/Documentation/ioctl/ioctl-number.txt +++ b/Documentation/ioctl/ioctl-number.txt @@ -178,7 +178,6 @@ Code Seq#(hex) Include File Comments 'V' C0 linux/ivtv.h conflict! 'V' C0 media/davinci/vpfe_capture.h conflict! 'V' C0 media/si4713.h conflict! -'V' C0-CF drivers/media/video/mxb.h conflict! 'W' 00-1F linux/watchdog.h conflict! 'W' 00-1F linux/wanrouter.h conflict! 'W' 00-3F sound/asound.h conflict! @@ -204,8 +203,6 @@ Code Seq#(hex) Include File Comments 'c' A0-AF arch/x86/include/asm/msr.h conflict! 'd' 00-FF linux/char/drm/drm/h conflict! 'd' 02-40 pcmcia/ds.h conflict! -'d' 10-3F drivers/media/video/dabusb.h conflict! -'d' C0-CF drivers/media/video/saa7191.h conflict! 'd' F0-FF linux/digi1.h 'e' all linux/digi1.h conflict! 'e' 00-1F drivers/net/irda/irtty-sir.h conflict! @@ -267,9 +264,7 @@ Code Seq#(hex) Include File Comments 'v' 00-1F linux/ext2_fs.h conflict! 'v' 00-1F linux/fs.h conflict! 'v' 00-0F linux/sonypi.h conflict! -'v' C0-DF media/pwc-ioctl.h conflict! 'v' C0-FF linux/meye.h conflict! -'v' D0-DF drivers/media/video/cpia2/cpia2dev.h conflict! 'w' all CERN SCI driver 'y' 00-1F packet based user level communications <mailto:zapman@interlan.net> diff --git a/Documentation/kbuild/makefiles.txt b/Documentation/kbuild/makefiles.txt index ab0a984530d8..ec9ae6708691 100644 --- a/Documentation/kbuild/makefiles.txt +++ b/Documentation/kbuild/makefiles.txt @@ -45,7 +45,7 @@ This document describes the Linux kernel Makefiles. === 7 Kbuild syntax for exported headers --- 7.1 header-y - --- 7.2 objhdr-y + --- 7.2 genhdr-y --- 7.3 destination-y --- 7.4 generic-y @@ -1282,15 +1282,15 @@ See subsequent chapter for the syntax of the Kbuild file. Subdirectories are visited before their parent directories. - --- 7.2 objhdr-y + --- 7.2 genhdr-y - objhdr-y specifies generated files to be exported. + genhdr-y specifies generated files to be exported. Generated files are special as they need to be looked up in another directory when doing 'make O=...' builds. Example: #include/linux/Kbuild - objhdr-y += version.h + genhdr-y += version.h --- 7.3 destination-y diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index ad7e2e5088c1..f777fa96243d 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -1051,6 +1051,14 @@ bytes respectively. Such letter suffixes can also be entirely omitted. ihash_entries= [KNL] Set number of hash buckets for inode cache. + ima_appraise= [IMA] appraise integrity measurements + Format: { "off" | "enforce" | "fix" } + default: "enforce" + + ima_appraise_tcb [IMA] + The builtin appraise policy appraises all files + owned by uid=0. + ima_audit= [IMA] Format: { "0" | "1" } 0 -- integrity auditing messages. (Default) @@ -1350,6 +1358,9 @@ bytes respectively. Such letter suffixes can also be entirely omitted. * nohrst, nosrst, norst: suppress hard, soft and both resets. + * rstonce: only attempt one reset during + hot-unplug link recovery + * dump_id: dump IDENTIFY data. If there are multiple matching configurations changing @@ -1812,8 +1823,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. noexec=on: enable non-executable mappings (default) noexec=off: disable non-executable mappings + nosmap [X86] + Disable SMAP (Supervisor Mode Access Prevention) + even if it is supported by processor. + nosmep [X86] - Disable SMEP (Supervisor Mode Execution Protection) + Disable SMEP (Supervisor Mode Execution Prevention) even if it is supported by processor. noexec32 [X86-64] @@ -1833,6 +1848,12 @@ bytes respectively. Such letter suffixes can also be entirely omitted. and restore using xsave. The kernel will fallback to enabling legacy floating-point and sse state. + eagerfpu= [X86] + on enable eager fpu restore + off disable eager fpu restore + auto selects the default scheme, which automatically + enables eagerfpu restore for xsaveopt. + nohlt [BUGS=ARM,SH] Tells the kernel that the sleep(SH) or wfi(ARM) instruction doesn't work correctly and not to use it. This is also useful when using JTAG debugger. @@ -2385,6 +2406,17 @@ bytes respectively. Such letter suffixes can also be entirely omitted. rcutree.rcu_cpu_stall_timeout= [KNL,BOOT] Set timeout for RCU CPU stall warning messages. + rcutree.jiffies_till_first_fqs= [KNL,BOOT] + Set delay from grace-period initialization to + first attempt to force quiescent states. + Units are jiffies, minimum value is zero, + and maximum value is HZ. + + rcutree.jiffies_till_next_fqs= [KNL,BOOT] + Set delay between subsequent attempts to force + quiescent states. Units are jiffies, minimum + value is one, and maximum value is HZ. + rcutorture.fqs_duration= [KNL,BOOT] Set duration of force_quiescent_state bursts. @@ -2638,9 +2670,6 @@ bytes respectively. Such letter suffixes can also be entirely omitted. smart2= [HW] Format: <io1>[,<io2>[,...,<io8>]] - smp-alt-once [X86-32,SMP] On a hotplug CPU system, only - attempt to substitute SMP alternatives once at boot. - smsc-ircc2.nopnp [HW] Don't use PNP to discover SMC devices smsc-ircc2.ircc_cfg= [HW] Device configuration I/O port smsc-ircc2.ircc_sir= [HW] SIR base I/O port diff --git a/Documentation/kobject.txt b/Documentation/kobject.txt index 49578cf1aea5..c5182bb2c16c 100644 --- a/Documentation/kobject.txt +++ b/Documentation/kobject.txt @@ -284,9 +284,11 @@ instead, it is associated with the ktype. So let us introduce struct kobj_type: struct kobj_type { - void (*release)(struct kobject *); + void (*release)(struct kobject *kobj); const struct sysfs_ops *sysfs_ops; - struct attribute **default_attrs; + struct attribute **default_attrs; + const struct kobj_ns_type_operations *(*child_ns_type)(struct kobject *kobj); + const void *(*namespace)(struct kobject *kobj); }; This structure is used to describe a particular type of kobject (or, more diff --git a/Documentation/memory.txt b/Documentation/memory.txt deleted file mode 100644 index 802efe58647c..000000000000 --- a/Documentation/memory.txt +++ /dev/null @@ -1,33 +0,0 @@ -There are several classic problems related to memory on Linux -systems. - - 1) There are some motherboards that will not cache above - a certain quantity of memory. If you have one of these - motherboards, your system will be SLOWER, not faster - as you add more memory. Consider exchanging your - motherboard. - -All of these problems can be addressed with the "mem=XXXM" boot option -(where XXX is the size of RAM to use in megabytes). -It can also tell Linux to use less memory than is actually installed. -If you use "mem=" on a machine with PCI, consider using "memmap=" to avoid -physical address space collisions. - -See the documentation of your boot loader (LILO, grub, loadlin, etc.) about -how to pass options to the kernel. - -There are other memory problems which Linux cannot deal with. Random -corruption of memory is usually a sign of serious hardware trouble. -Try: - - * Reducing memory settings in the BIOS to the most conservative - timings. - - * Adding a cooling fan. - - * Not overclocking your CPU. - - * Having the memory tested in a memory tester or exchanged - with the vendor. Consider testing it with memtest86 yourself. - - * Exchanging your CPU, cache, or motherboard for one that works. diff --git a/Documentation/misc-devices/lis3lv02d b/Documentation/misc-devices/lis3lv02d index f1a4ec840f86..af815b9ba413 100644 --- a/Documentation/misc-devices/lis3lv02d +++ b/Documentation/misc-devices/lis3lv02d @@ -4,7 +4,8 @@ Kernel driver lis3lv02d Supported chips: * STMicroelectronics LIS3LV02DL, LIS3LV02DQ (12 bits precision) - * STMicroelectronics LIS302DL, LIS3L02DQ, LIS331DL (8 bits) + * STMicroelectronics LIS302DL, LIS3L02DQ, LIS331DL (8 bits) and + LIS331DLH (16 bits) Authors: Yan Burman <burman.yan@gmail.com> diff --git a/Documentation/networking/batman-adv.txt b/Documentation/networking/batman-adv.txt index 8f3ae4a6147e..a173d2a879f5 100644 --- a/Documentation/networking/batman-adv.txt +++ b/Documentation/networking/batman-adv.txt @@ -75,9 +75,10 @@ folder: There is a special folder for debugging information: -# ls /sys/kernel/debug/batman_adv/bat0/ -# bla_claim_table log socket transtable_local -# gateways originators transtable_global vis_data +# ls /sys/kernel/debug/batman_adv/bat0/ +# bla_backbone_table log transtable_global +# bla_claim_table originators transtable_local +# gateways socket vis_data Some of the files contain all sort of status information regard- ing the mesh network. For example, you can view the table of diff --git a/Documentation/networking/bonding.txt b/Documentation/networking/bonding.txt index 6b1c7110534e..10a015c384b8 100644 --- a/Documentation/networking/bonding.txt +++ b/Documentation/networking/bonding.txt @@ -752,12 +752,22 @@ xmit_hash_policy protocol information to generate the hash. Uses XOR of hardware MAC addresses and IP addresses to - generate the hash. The formula is + generate the hash. The IPv4 formula is (((source IP XOR dest IP) AND 0xffff) XOR ( source MAC XOR destination MAC )) modulo slave count + The IPv6 formula is + + hash = (source ip quad 2 XOR dest IP quad 2) XOR + (source ip quad 3 XOR dest IP quad 3) XOR + (source ip quad 4 XOR dest IP quad 4) + + (((hash >> 24) XOR (hash >> 16) XOR (hash >> 8) XOR hash) + XOR (source MAC XOR destination MAC)) + modulo slave count + This algorithm will place all traffic to a particular network peer on the same slave. For non-IP traffic, the formula is the same as for the layer2 transmit @@ -778,19 +788,29 @@ xmit_hash_policy slaves, although a single connection will not span multiple slaves. - The formula for unfragmented TCP and UDP packets is + The formula for unfragmented IPv4 TCP and UDP packets is ((source port XOR dest port) XOR ((source IP XOR dest IP) AND 0xffff) modulo slave count - For fragmented TCP or UDP packets and all other IP - protocol traffic, the source and destination port + The formula for unfragmented IPv6 TCP and UDP packets is + + hash = (source port XOR dest port) XOR + ((source ip quad 2 XOR dest IP quad 2) XOR + (source ip quad 3 XOR dest IP quad 3) XOR + (source ip quad 4 XOR dest IP quad 4)) + + ((hash >> 24) XOR (hash >> 16) XOR (hash >> 8) XOR hash) + modulo slave count + + For fragmented TCP or UDP packets and all other IPv4 and + IPv6 protocol traffic, the source and destination port information is omitted. For non-IP traffic, the formula is the same as for the layer2 transmit hash policy. - This policy is intended to mimic the behavior of + The IPv4 policy is intended to mimic the behavior of certain switches, notably Cisco switches with PFC2 as well as some Foundry and IBM products. diff --git a/Documentation/networking/ip-sysctl.txt b/Documentation/networking/ip-sysctl.txt index ca447b35b833..c7fc10724948 100644 --- a/Documentation/networking/ip-sysctl.txt +++ b/Documentation/networking/ip-sysctl.txt @@ -439,7 +439,9 @@ tcp_stdurg - BOOLEAN tcp_synack_retries - INTEGER Number of times SYNACKs for a passive TCP connection attempt will be retransmitted. Should not be higher than 255. Default value - is 5, which corresponds to ~180seconds. + is 5, which corresponds to 31seconds till the last retransmission + with the current initial RTO of 1second. With this the final timeout + for a passive TCP connection will happen after 63seconds. tcp_syncookies - BOOLEAN Only valid when the kernel was compiled with CONFIG_SYNCOOKIES @@ -465,20 +467,37 @@ tcp_syncookies - BOOLEAN tcp_fastopen - INTEGER Enable TCP Fast Open feature (draft-ietf-tcpm-fastopen) to send data in the opening SYN packet. To use this feature, the client application - must not use connect(). Instead, it should use sendmsg() or sendto() - with MSG_FASTOPEN flag which performs a TCP handshake automatically. - - The values (bitmap) are: - 1: Enables sending data in the opening SYN on the client - 5: Enables sending data in the opening SYN on the client regardless - of cookie availability. + must use sendmsg() or sendto() with MSG_FASTOPEN flag rather than + connect() to perform a TCP handshake automatically. + + The values (bitmap) are + 1: Enables sending data in the opening SYN on the client. + 2: Enables TCP Fast Open on the server side, i.e., allowing data in + a SYN packet to be accepted and passed to the application before + 3-way hand shake finishes. + 4: Send data in the opening SYN regardless of cookie availability and + without a cookie option. + 0x100: Accept SYN data w/o validating the cookie. + 0x200: Accept data-in-SYN w/o any cookie option present. + 0x400/0x800: Enable Fast Open on all listeners regardless of the + TCP_FASTOPEN socket option. The two different flags designate two + different ways of setting max_qlen without the TCP_FASTOPEN socket + option. Default: 0 + Note that the client & server side Fast Open flags (1 and 2 + respectively) must be also enabled before the rest of flags can take + effect. + + See include/net/tcp.h and the code for more details. + tcp_syn_retries - INTEGER Number of times initial SYNs for an active TCP connection attempt will be retransmitted. Should not be higher than 255. Default value - is 5, which corresponds to ~180seconds. + is 6, which corresponds to 63seconds till the last restransmission + with the current initial RTO of 1second. With this the final timeout + for an active TCP connection attempt will happen after 127seconds. tcp_timestamps - BOOLEAN Enable timestamps as defined in RFC1323. diff --git a/Documentation/networking/stmmac.txt b/Documentation/networking/stmmac.txt index c676b9cedbd0..ef9ee71b4d7f 100644 --- a/Documentation/networking/stmmac.txt +++ b/Documentation/networking/stmmac.txt @@ -173,7 +173,6 @@ Where: For MDIO bus The we have: struct stmmac_mdio_bus_data { - int bus_id; int (*phy_reset)(void *priv); unsigned int phy_mask; int *irqs; @@ -181,7 +180,6 @@ For MDIO bus The we have: }; Where: - o bus_id: bus identifier; o phy_reset: hook to reset the phy device attached to the bus. o phy_mask: phy mask passed when register the MDIO bus within the driver. o irqs: list of IRQs, one per PHY. @@ -230,9 +228,6 @@ there are two MAC cores: one MAC is for MDIO Bus/PHY emulation with fixed_link support. static struct stmmac_mdio_bus_data stmmac1_mdio_bus = { - .bus_id = 1, - | - |-> phy device on the bus_id 1 .phy_reset = phy_reset; | |-> function to provide the phy_reset on this board diff --git a/Documentation/networking/vxlan.txt b/Documentation/networking/vxlan.txt new file mode 100644 index 000000000000..5b34b762d7d5 --- /dev/null +++ b/Documentation/networking/vxlan.txt @@ -0,0 +1,47 @@ +Virtual eXtensible Local Area Networking documentation +====================================================== + +The VXLAN protocol is a tunnelling protocol that is designed to +solve the problem of limited number of available VLAN's (4096). +With VXLAN identifier is expanded to 24 bits. + +It is a draft RFC standard, that is implemented by Cisco Nexus, +Vmware and Brocade. The protocol runs over UDP using a single +destination port (still not standardized by IANA). +This document describes the Linux kernel tunnel device, +there is also an implantation of VXLAN for Openvswitch. + +Unlike most tunnels, a VXLAN is a 1 to N network, not just point +to point. A VXLAN device can either dynamically learn the IP address +of the other end, in a manner similar to a learning bridge, or the +forwarding entries can be configured statically. + +The management of vxlan is done in a similar fashion to it's +too closest neighbors GRE and VLAN. Configuring VXLAN requires +the version of iproute2 that matches the kernel release +where VXLAN was first merged upstream. + +1. Create vxlan device + # ip li add vxlan0 type vxlan id 42 group 239.1.1.1 dev eth1 + +This creates a new device (vxlan0). The device uses the +the multicast group 239.1.1.1 over eth1 to handle packets where +no entry is in the forwarding table. + +2. Delete vxlan device + # ip link delete vxlan0 + +3. Show vxlan info + # ip -d show vxlan0 + +It is possible to create, destroy and display the vxlan +forwarding table using the new bridge command. + +1. Create forwarding table entry + # bridge fdb add to 00:17:42:8a:b4:05 dst 192.19.0.2 dev vxlan0 + +2. Delete forwarding table entry + # bridge fdb delete 00:17:42:8a:b4:05 + +3. Show forwarding table + # bridge fdb show dev vxlan0 diff --git a/Documentation/pinctrl.txt b/Documentation/pinctrl.txt index 1479aca23744..3b4ee5328868 100644 --- a/Documentation/pinctrl.txt +++ b/Documentation/pinctrl.txt @@ -289,6 +289,11 @@ Interaction with the GPIO subsystem The GPIO drivers may want to perform operations of various types on the same physical pins that are also registered as pin controller pins. +First and foremost, the two subsystems can be used as completely orthogonal, +see the section named "pin control requests from drivers" and +"drivers needing both pin control and GPIOs" below for details. But in some +situations a cross-subsystem mapping between pins and GPIOs is needed. + Since the pin controller subsystem have its pinspace local to the pin controller we need a mapping so that the pin control subsystem can figure out which pin controller handles control of a certain GPIO pin. Since a single @@ -359,6 +364,7 @@ will get an pin number into its handled number range. Further it is also passed the range ID value, so that the pin controller knows which range it should deal with. + PINMUX interfaces ================= @@ -960,8 +966,8 @@ all get selected, and they all get enabled and disable simultaneously by the pinmux core. -Pinmux requests from drivers -============================ +Pin control requests from drivers +================================= Generally it is discouraged to let individual drivers get and enable pin control. So if possible, handle the pin control in platform code or some other @@ -969,6 +975,11 @@ place where you have access to all the affected struct device * pointers. In some cases where a driver needs to e.g. switch between different mux mappings at runtime this is not possible. +A typical case is if a driver needs to switch bias of pins from normal +operation and going to sleep, moving from the PINCTRL_STATE_DEFAULT to +PINCTRL_STATE_SLEEP at runtime, re-biasing or even re-muxing pins to save +current in sleep mode. + A driver may request a certain control state to be activated, usually just the default state like this: @@ -1058,6 +1069,51 @@ registered. Thus make sure that the error path in your driver gracefully cleans up and is ready to retry the probing later in the startup process. +Drivers needing both pin control and GPIOs +========================================== + +Again, it is discouraged to let drivers lookup and select pin control states +themselves, but again sometimes this is unavoidable. + +So say that your driver is fetching its resources like this: + +#include <linux/pinctrl/consumer.h> +#include <linux/gpio.h> + +struct pinctrl *pinctrl; +int gpio; + +pinctrl = devm_pinctrl_get_select_default(&dev); +gpio = devm_gpio_request(&dev, 14, "foo"); + +Here we first request a certain pin state and then request GPIO 14 to be +used. If you're using the subsystems orthogonally like this, you should +nominally always get your pinctrl handle and select the desired pinctrl +state BEFORE requesting the GPIO. This is a semantic convention to avoid +situations that can be electrically unpleasant, you will certainly want to +mux in and bias pins in a certain way before the GPIO subsystems starts to +deal with them. + +The above can be hidden: using pinctrl hogs, the pin control driver may be +setting up the config and muxing for the pins when it is probing, +nevertheless orthogonal to the GPIO subsystem. + +But there are also situations where it makes sense for the GPIO subsystem +to communicate directly with with the pinctrl subsystem, using the latter +as a back-end. This is when the GPIO driver may call out to the functions +described in the section "Pin control interaction with the GPIO subsystem" +above. This only involves per-pin multiplexing, and will be completely +hidden behind the gpio_*() function namespace. In this case, the driver +need not interact with the pin control subsystem at all. + +If a pin control driver and a GPIO driver is dealing with the same pins +and the use cases involve multiplexing, you MUST implement the pin controller +as a back-end for the GPIO driver like this, unless your hardware design +is such that the GPIO controller can override the pin controller's +multiplexing state through hardware without the need to interact with the +pin control system. + + System pin control hogging ========================== diff --git a/Documentation/power/power_supply_class.txt b/Documentation/power/power_supply_class.txt index 2f0ddc15b5ac..9c647bd7c5a9 100644 --- a/Documentation/power/power_supply_class.txt +++ b/Documentation/power/power_supply_class.txt @@ -81,6 +81,9 @@ This defines trickle and fast charges. For batteries that are already charged or discharging, 'n/a' can be displayed (or 'unknown', if the status is not known). +AUTHENTIC - indicates the power supply (battery or charger) connected +to the platform is authentic(1) or non authentic(0). + HEALTH - represents health of the battery, values corresponds to POWER_SUPPLY_HEALTH_*, defined in battery.h. @@ -113,8 +116,12 @@ be negative; there is no empty or full value. It is only useful for relative, time-based measurements. CONSTANT_CHARGE_CURRENT - constant charge current programmed by charger. +CONSTANT_CHARGE_CURRENT_MAX - maximum charge current supported by the +power supply object. CONSTANT_CHARGE_VOLTAGE - constant charge voltage programmed by charger. +CONSTANT_CHARGE_VOLTAGE_MAX - maximum charge voltage supported by the +power supply object. ENERGY_FULL, ENERGY_EMPTY - same as above but for energy. diff --git a/Documentation/power/swsusp.txt b/Documentation/power/swsusp.txt index 92341b84250d..0b4b63e7e9b6 100644 --- a/Documentation/power/swsusp.txt +++ b/Documentation/power/swsusp.txt @@ -53,7 +53,7 @@ before suspend (it is limited to 500 MB by default). Article about goals and implementation of Software Suspend for Linux ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Author: Gábor Kuti +Author: Gábor Kuti Last revised: 2003-10-20 by Pavel Machek Idea and goals to achieve diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt index 7561d7ed8e11..8ffb274367c7 100644 --- a/Documentation/printk-formats.txt +++ b/Documentation/printk-formats.txt @@ -69,6 +69,7 @@ MAC/FDDI addresses: %pMR 05:04:03:02:01:00 %pMF 00-01-02-03-04-05 %pm 000102030405 + %pmR 050403020100 For printing 6-byte MAC/FDDI addresses in hex notation. The 'M' and 'm' specifiers result in a printed address with ('M') or without ('m') byte diff --git a/Documentation/prio_tree.txt b/Documentation/prio_tree.txt deleted file mode 100644 index 3aa68f9a117b..000000000000 --- a/Documentation/prio_tree.txt +++ /dev/null @@ -1,107 +0,0 @@ -The prio_tree.c code indexes vmas using 3 different indexes: - * heap_index = vm_pgoff + vm_size_in_pages : end_vm_pgoff - * radix_index = vm_pgoff : start_vm_pgoff - * size_index = vm_size_in_pages - -A regular radix-priority-search-tree indexes vmas using only heap_index and -radix_index. The conditions for indexing are: - * ->heap_index >= ->left->heap_index && - ->heap_index >= ->right->heap_index - * if (->heap_index == ->left->heap_index) - then ->radix_index < ->left->radix_index; - * if (->heap_index == ->right->heap_index) - then ->radix_index < ->right->radix_index; - * nodes are hashed to left or right subtree using radix_index - similar to a pure binary radix tree. - -A regular radix-priority-search-tree helps to store and query -intervals (vmas). However, a regular radix-priority-search-tree is only -suitable for storing vmas with different radix indices (vm_pgoff). - -Therefore, the prio_tree.c extends the regular radix-priority-search-tree -to handle many vmas with the same vm_pgoff. Such vmas are handled in -2 different ways: 1) All vmas with the same radix _and_ heap indices are -linked using vm_set.list, 2) if there are many vmas with the same radix -index, but different heap indices and if the regular radix-priority-search -tree cannot index them all, we build an overflow-sub-tree that indexes such -vmas using heap and size indices instead of heap and radix indices. For -example, in the figure below some vmas with vm_pgoff = 0 (zero) are -indexed by regular radix-priority-search-tree whereas others are pushed -into an overflow-subtree. Note that all vmas in an overflow-sub-tree have -the same vm_pgoff (radix_index) and if necessary we build different -overflow-sub-trees to handle each possible radix_index. For example, -in figure we have 3 overflow-sub-trees corresponding to radix indices -0, 2, and 4. - -In the final tree the first few (prio_tree_root->index_bits) levels -are indexed using heap and radix indices whereas the overflow-sub-trees below -those levels (i.e. levels prio_tree_root->index_bits + 1 and higher) are -indexed using heap and size indices. In overflow-sub-trees the size_index -is used for hashing the nodes to appropriate places. - -Now, an example prio_tree: - - vmas are represented [radix_index, size_index, heap_index] - i.e., [start_vm_pgoff, vm_size_in_pages, end_vm_pgoff] - -level prio_tree_root->index_bits = 3 ------ - _ - 0 [0,7,7] | - / \ | - ------------------ ------------ | Regular - / \ | radix priority - 1 [1,6,7] [4,3,7] | search tree - / \ / \ | - ------- ----- ------ ----- | heap-and-radix - / \ / \ | indexed - 2 [0,6,6] [2,5,7] [5,2,7] [6,1,7] | - / \ / \ / \ / \ | - 3 [0,5,5] [1,5,6] [2,4,6] [3,4,7] [4,2,6] [5,1,6] [6,0,6] [7,0,7] | - / / / _ - / / / _ - 4 [0,4,4] [2,3,5] [4,1,5] | - / / / | - 5 [0,3,3] [2,2,4] [4,0,4] | Overflow-sub-trees - / / | - 6 [0,2,2] [2,1,3] | heap-and-size - / / | indexed - 7 [0,1,1] [2,0,2] | - / | - 8 [0,0,0] | - _ - -Note that we use prio_tree_root->index_bits to optimize the height -of the heap-and-radix indexed tree. Since prio_tree_root->index_bits is -set according to the maximum end_vm_pgoff mapped, we are sure that all -bits (in vm_pgoff) above prio_tree_root->index_bits are 0 (zero). Therefore, -we only use the first prio_tree_root->index_bits as radix_index. -Whenever index_bits is increased in prio_tree_expand, we shuffle the tree -to make sure that the first prio_tree_root->index_bits levels of the tree -is indexed properly using heap and radix indices. - -We do not optimize the height of overflow-sub-trees using index_bits. -The reason is: there can be many such overflow-sub-trees and all of -them have to be suffled whenever the index_bits increases. This may involve -walking the whole prio_tree in prio_tree_insert->prio_tree_expand code -path which is not desirable. Hence, we do not optimize the height of the -heap-and-size indexed overflow-sub-trees using prio_tree->index_bits. -Instead the overflow sub-trees are indexed using full BITS_PER_LONG bits -of size_index. This may lead to skewed sub-trees because most of the -higher significant bits of the size_index are likely to be 0 (zero). In -the example above, all 3 overflow-sub-trees are skewed. This may marginally -affect the performance. However, processes rarely map many vmas with the -same start_vm_pgoff but different end_vm_pgoffs. Therefore, we normally -do not require overflow-sub-trees to index all vmas. - -From the above discussion it is clear that the maximum height of -a prio_tree can be prio_tree_root->index_bits + BITS_PER_LONG. -However, in most of the common cases we do not need overflow-sub-trees, -so the tree height in the common cases will be prio_tree_root->index_bits. - -It is fair to mention here that the prio_tree_root->index_bits -is increased on demand, however, the index_bits is not decreased when -vmas are removed from the prio_tree. That's tricky to do. Hence, it's -left as a home work problem. - - diff --git a/Documentation/ramoops.txt b/Documentation/ramoops.txt index 197ad59ab9bf..69b3cac4749d 100644 --- a/Documentation/ramoops.txt +++ b/Documentation/ramoops.txt @@ -102,9 +102,7 @@ related hangs. The functions call chain log is stored in a "ftrace-ramoops" file. Here is an example of usage: # mount -t debugfs debugfs /sys/kernel/debug/ - # cd /sys/kernel/debug/tracing - # echo function > current_tracer - # echo 1 > options/func_pstore + # echo 1 > /sys/kernel/debug/pstore/record_ftrace # reboot -f [...] # mount -t pstore pstore /mnt/ diff --git a/Documentation/rbtree.txt b/Documentation/rbtree.txt index 8d32d85a5234..61b6c48871a0 100644 --- a/Documentation/rbtree.txt +++ b/Documentation/rbtree.txt @@ -193,24 +193,55 @@ Example: Support for Augmented rbtrees ----------------------------- -Augmented rbtree is an rbtree with "some" additional data stored in each node. -This data can be used to augment some new functionality to rbtree. -Augmented rbtree is an optional feature built on top of basic rbtree -infrastructure. An rbtree user who wants this feature will have to call the -augmentation functions with the user provided augmentation callback -when inserting and erasing nodes. - -On insertion, the user must call rb_augment_insert() once the new node is in -place. This will cause the augmentation function callback to be called for -each node between the new node and the root which has been affected by the -insertion. - -When erasing a node, the user must call rb_augment_erase_begin() first to -retrieve the deepest node on the rebalance path. Then, after erasing the -original node, the user must call rb_augment_erase_end() with the deepest -node found earlier. This will cause the augmentation function to be called -for each affected node between the deepest node and the root. - +Augmented rbtree is an rbtree with "some" additional data stored in +each node, where the additional data for node N must be a function of +the contents of all nodes in the subtree rooted at N. This data can +be used to augment some new functionality to rbtree. Augmented rbtree +is an optional feature built on top of basic rbtree infrastructure. +An rbtree user who wants this feature will have to call the augmentation +functions with the user provided augmentation callback when inserting +and erasing nodes. + +C files implementing augmented rbtree manipulation must include +<linux/rbtree_augmented.h> instead of <linus/rbtree.h>. Note that +linux/rbtree_augmented.h exposes some rbtree implementations details +you are not expected to rely on; please stick to the documented APIs +there and do not include <linux/rbtree_augmented.h> from header files +either so as to minimize chances of your users accidentally relying on +such implementation details. + +On insertion, the user must update the augmented information on the path +leading to the inserted node, then call rb_link_node() as usual and +rb_augment_inserted() instead of the usual rb_insert_color() call. +If rb_augment_inserted() rebalances the rbtree, it will callback into +a user provided function to update the augmented information on the +affected subtrees. + +When erasing a node, the user must call rb_erase_augmented() instead of +rb_erase(). rb_erase_augmented() calls back into user provided functions +to updated the augmented information on affected subtrees. + +In both cases, the callbacks are provided through struct rb_augment_callbacks. +3 callbacks must be defined: + +- A propagation callback, which updates the augmented value for a given + node and its ancestors, up to a given stop point (or NULL to update + all the way to the root). + +- A copy callback, which copies the augmented value for a given subtree + to a newly assigned subtree root. + +- A tree rotation callback, which copies the augmented value for a given + subtree to a newly assigned subtree root AND recomputes the augmented + information for the former subtree root. + +The compiled code for rb_erase_augmented() may inline the propagation and +copy callbacks, which results in a large function, so each augmented rbtree +user should have a single rb_erase_augmented() call site in order to limit +compiled code size. + + +Sample usage: Interval tree is an example of augmented rb tree. Reference - "Introduction to Algorithms" by Cormen, Leiserson, Rivest and Stein. @@ -230,26 +261,132 @@ and its immediate children. And this will be used in O(log n) lookup for lowest match (lowest start address among all possible matches) with something like: -find_lowest_match(lo, hi, node) +struct interval_tree_node * +interval_tree_first_match(struct rb_root *root, + unsigned long start, unsigned long last) { - lowest_match = NULL; - while (node) { - if (max_hi(node->left) > lo) { - // Lowest overlap if any must be on left side - node = node->left; - } else if (overlap(lo, hi, node)) { - lowest_match = node; - break; - } else if (lo > node->lo) { - // Lowest overlap if any must be on right side - node = node->right; - } else { - break; + struct interval_tree_node *node; + + if (!root->rb_node) + return NULL; + node = rb_entry(root->rb_node, struct interval_tree_node, rb); + + while (true) { + if (node->rb.rb_left) { + struct interval_tree_node *left = + rb_entry(node->rb.rb_left, + struct interval_tree_node, rb); + if (left->__subtree_last >= start) { + /* + * Some nodes in left subtree satisfy Cond2. + * Iterate to find the leftmost such node N. + * If it also satisfies Cond1, that's the match + * we are looking for. Otherwise, there is no + * matching interval as nodes to the right of N + * can't satisfy Cond1 either. + */ + node = left; + continue; + } } + if (node->start <= last) { /* Cond1 */ + if (node->last >= start) /* Cond2 */ + return node; /* node is leftmost match */ + if (node->rb.rb_right) { + node = rb_entry(node->rb.rb_right, + struct interval_tree_node, rb); + if (node->__subtree_last >= start) + continue; + } + } + return NULL; /* No match */ + } +} + +Insertion/removal are defined using the following augmented callbacks: + +static inline unsigned long +compute_subtree_last(struct interval_tree_node *node) +{ + unsigned long max = node->last, subtree_last; + if (node->rb.rb_left) { + subtree_last = rb_entry(node->rb.rb_left, + struct interval_tree_node, rb)->__subtree_last; + if (max < subtree_last) + max = subtree_last; + } + if (node->rb.rb_right) { + subtree_last = rb_entry(node->rb.rb_right, + struct interval_tree_node, rb)->__subtree_last; + if (max < subtree_last) + max = subtree_last; + } + return max; +} + +static void augment_propagate(struct rb_node *rb, struct rb_node *stop) +{ + while (rb != stop) { + struct interval_tree_node *node = + rb_entry(rb, struct interval_tree_node, rb); + unsigned long subtree_last = compute_subtree_last(node); + if (node->__subtree_last == subtree_last) + break; + node->__subtree_last = subtree_last; + rb = rb_parent(&node->rb); } - return lowest_match; } -Finding exact match will be to first find lowest match and then to follow -successor nodes looking for exact match, until the start of a node is beyond -the hi value we are looking for. +static void augment_copy(struct rb_node *rb_old, struct rb_node *rb_new) +{ + struct interval_tree_node *old = + rb_entry(rb_old, struct interval_tree_node, rb); + struct interval_tree_node *new = + rb_entry(rb_new, struct interval_tree_node, rb); + + new->__subtree_last = old->__subtree_last; +} + +static void augment_rotate(struct rb_node *rb_old, struct rb_node *rb_new) +{ + struct interval_tree_node *old = + rb_entry(rb_old, struct interval_tree_node, rb); + struct interval_tree_node *new = + rb_entry(rb_new, struct interval_tree_node, rb); + + new->__subtree_last = old->__subtree_last; + old->__subtree_last = compute_subtree_last(old); +} + +static const struct rb_augment_callbacks augment_callbacks = { + augment_propagate, augment_copy, augment_rotate +}; + +void interval_tree_insert(struct interval_tree_node *node, + struct rb_root *root) +{ + struct rb_node **link = &root->rb_node, *rb_parent = NULL; + unsigned long start = node->start, last = node->last; + struct interval_tree_node *parent; + + while (*link) { + rb_parent = *link; + parent = rb_entry(rb_parent, struct interval_tree_node, rb); + if (parent->__subtree_last < last) + parent->__subtree_last = last; + if (start < parent->start) + link = &parent->rb.rb_left; + else + link = &parent->rb.rb_right; + } + + node->__subtree_last = last; + rb_link_node(&node->rb, rb_parent, link); + rb_insert_augmented(&node->rb, root, &augment_callbacks); +} + +void interval_tree_remove(struct interval_tree_node *node, + struct rb_root *root) +{ + rb_erase_augmented(&node->rb, root, &augment_callbacks); +} diff --git a/Documentation/remoteproc.txt b/Documentation/remoteproc.txt index 23a09b884bc7..e6469fdcf89a 100644 --- a/Documentation/remoteproc.txt +++ b/Documentation/remoteproc.txt @@ -129,6 +129,13 @@ int dummy_rproc_example(struct rproc *my_rproc) Returns 0 on success and -EINVAL if @rproc isn't valid. + void rproc_report_crash(struct rproc *rproc, enum rproc_crash_type type) + - Report a crash in a remoteproc + This function must be called every time a crash is detected by the + platform specific rproc implementation. This should not be called from a + non-remoteproc driver. This function can be called from atomic/interrupt + context. + 5. Implementation callbacks These callbacks should be provided by platform-specific remoteproc diff --git a/Documentation/rtc.txt b/Documentation/rtc.txt index 250160469d83..32aa4002de4a 100644 --- a/Documentation/rtc.txt +++ b/Documentation/rtc.txt @@ -119,8 +119,9 @@ three different userspace interfaces: * /sys/class/rtc/rtcN ... sysfs attributes support readonly access to some RTC attributes. - * /proc/driver/rtc ... the first RTC (rtc0) may expose itself - using a procfs interface. More information is (currently) shown + * /proc/driver/rtc ... the system clock RTC may expose itself + using a procfs interface. If there is no RTC for the system clock, + rtc0 is used by default. More information is (currently) shown here than through sysfs. The RTC Class framework supports a wide variety of RTCs, ranging from those diff --git a/Documentation/scheduler/sched-arch.txt b/Documentation/scheduler/sched-arch.txt index 28aa1075e291..b1b8587b86f0 100644 --- a/Documentation/scheduler/sched-arch.txt +++ b/Documentation/scheduler/sched-arch.txt @@ -17,16 +17,6 @@ you must `#define __ARCH_WANT_UNLOCKED_CTXSW` in a header file Unlocked context switches introduce only a very minor performance penalty to the core scheduler implementation in the CONFIG_SMP case. -2. Interrupt status -By default, the switch_to arch function is called with interrupts -disabled. Interrupts may be enabled over the call if it is likely to -introduce a significant interrupt latency by adding the line -`#define __ARCH_WANT_INTERRUPTS_ON_CTXSW` in the same place as for -unlocked context switches. This define also implies -`__ARCH_WANT_UNLOCKED_CTXSW`. See arch/arm/include/asm/system.h for an -example. - - CPU idle ======== Your cpu_idle routines need to obey the following rules: diff --git a/Documentation/scsi/ChangeLog.megaraid_sas b/Documentation/scsi/ChangeLog.megaraid_sas index 80441ab608e4..3a3079411a3d 100644 --- a/Documentation/scsi/ChangeLog.megaraid_sas +++ b/Documentation/scsi/ChangeLog.megaraid_sas @@ -1,3 +1,13 @@ +Release Date : Tue. Jun 17, 2012 17:00:00 PST 2012 - + (emaild-id:megaraidlinux@lsi.com) + Adam Radford/Kashyap Desai +Current Version : 00.00.06.18-rc1 +Old Version : 00.00.06.15-rc1 + 1. Fix Copyright dates. + 2. Add throttlequeuedepth module parameter. + 3. Add resetwaittime module parameter. + 4. Move poll_aen_lock initializer. +------------------------------------------------------------------------------- Release Date : Mon. Mar 19, 2012 17:00:00 PST 2012 - (emaild-id:megaraidlinux@lsi.com) Adam Radford diff --git a/Documentation/scsi/LICENSE.qla2xxx b/Documentation/scsi/LICENSE.qla2xxx index ce0fdf349a81..27a91cf43d6d 100644 --- a/Documentation/scsi/LICENSE.qla2xxx +++ b/Documentation/scsi/LICENSE.qla2xxx @@ -1,4 +1,4 @@ -Copyright (c) 2003-2011 QLogic Corporation +Copyright (c) 2003-2012 QLogic Corporation QLogic Linux FC-FCoE Driver This program includes a device driver for Linux 3.x. diff --git a/Documentation/scsi/LICENSE.qla4xxx b/Documentation/scsi/LICENSE.qla4xxx index ab899591ecb7..78c169f0d7c6 100644 --- a/Documentation/scsi/LICENSE.qla4xxx +++ b/Documentation/scsi/LICENSE.qla4xxx @@ -1,4 +1,4 @@ -Copyright (c) 2003-2011 QLogic Corporation +Copyright (c) 2003-2012 QLogic Corporation QLogic Linux iSCSI Driver This program includes a device driver for Linux 3.x. diff --git a/Documentation/scsi/st.txt b/Documentation/scsi/st.txt index 685bf3582abe..f346abbdd6ff 100644 --- a/Documentation/scsi/st.txt +++ b/Documentation/scsi/st.txt @@ -112,10 +112,8 @@ attempted). MINOR NUMBERS -The tape driver currently supports 128 drives by default. This number -can be increased by editing st.h and recompiling the driver if -necessary. The upper limit is 2^17 drives if 4 modes for each drive -are used. +The tape driver currently supports up to 2^17 drives if 4 modes for +each drive are used. The minor numbers consist of the following bit fields: diff --git a/Documentation/security/Smack.txt b/Documentation/security/Smack.txt index a416479b8a1c..8a177e4b6e21 100644 --- a/Documentation/security/Smack.txt +++ b/Documentation/security/Smack.txt @@ -28,12 +28,11 @@ Smack kernels use the CIPSO IP option. Some network configurations are intolerant of IP options and can impede access to systems that use them as Smack does. -The current git repositories for Smack user space are: +The current git repository for Smack user space is: - git@gitorious.org:meego-platform-security/smackutil.git - git@gitorious.org:meego-platform-security/libsmack.git + git://github.com/smack-team/smack.git -These should make and install on most modern distributions. +This should make and install on most modern distributions. There are three commands included in smackutil: smackload - properly formats data for writing to /smack/load @@ -194,6 +193,9 @@ onlycap these capabilities are effective at for processes with any label. The value is set by writing the desired label to the file or cleared by writing "-" to the file. +revoke-subject + Writing a Smack label here sets the access to '-' for all access + rules with that subject label. You can add access rules in /etc/smack/accesses. They take the form: diff --git a/Documentation/serial/00-INDEX b/Documentation/serial/00-INDEX index e09468ad3cb1..f7b0c7dc25ef 100644 --- a/Documentation/serial/00-INDEX +++ b/Documentation/serial/00-INDEX @@ -2,8 +2,6 @@ - this file. README.cycladesZ - info on Cyclades-Z firmware loading. -computone.txt - - info on Computone Intelliport II/Plus Multiport Serial Driver. digiepca.txt - info on Digi Intl. {PC,PCI,EISA}Xx and Xem series cards. hayes-esp.txt diff --git a/Documentation/serial/computone.txt b/Documentation/serial/computone.txt deleted file mode 100644 index a6a1158ea2ba..000000000000 --- a/Documentation/serial/computone.txt +++ /dev/null @@ -1,520 +0,0 @@ -NOTE: This is an unmaintained driver. It is not guaranteed to work due to -changes made in the tty layer in 2.6. If you wish to take over maintenance of -this driver, contact Michael Warfield <mhw@wittsend.com>. - -Changelog: ----------- -11-01-2001: Original Document - -10-29-2004: Minor misspelling & format fix, update status of driver. - James Nelson <james4765@gmail.com> - -Computone Intelliport II/Plus Multiport Serial Driver ------------------------------------------------------ - -Release Notes For Linux Kernel 2.2 and higher. -These notes are for the drivers which have already been integrated into the -kernel and have been tested on Linux kernels 2.0, 2.2, 2.3, and 2.4. - -Version: 1.2.14 -Date: 11/01/2001 -Historical Author: Andrew Manison <amanison@america.net> -Primary Author: Doug McNash - -This file assumes that you are using the Computone drivers which are -integrated into the kernel sources. For updating the drivers or installing -drivers into kernels which do not already have Computone drivers, please -refer to the instructions in the README.computone file in the driver patch. - - -1. INTRODUCTION - -This driver supports the entire family of Intelliport II/Plus controllers -with the exception of the MicroChannel controllers. It does not support -products previous to the Intelliport II. - -This driver was developed on the v2.0.x Linux tree and has been tested up -to v2.4.14; it will probably not work with earlier v1.X kernels,. - - -2. QUICK INSTALLATION - -Hardware - If you have an ISA card, find a free interrupt and io port. - List those in use with `cat /proc/interrupts` and - `cat /proc/ioports`. Set the card dip switches to a free - address. You may need to configure your BIOS to reserve an - irq for an ISA card. PCI and EISA parameters are set - automagically. Insert card into computer with the power off - before or after drivers installation. - - Note the hardware address from the Computone ISA cards installed into - the system. These are required for editing ip2.c or editing - /etc/modprobe.d/*.conf, or for specification on the modprobe - command line. - - Note that the /etc/modules.conf should be used for older (pre-2.6) - kernels. - -Software - - -Module installation: - -a) Determine free irq/address to use if any (configure BIOS if need be) -b) Run "make config" or "make menuconfig" or "make xconfig" - Select (m) module for CONFIG_COMPUTONE under character - devices. CONFIG_PCI and CONFIG_MODULES also may need to be set. -c) Set address on ISA cards then: - edit /usr/src/linux/drivers/char/ip2.c if needed - or - edit config file in /etc/modprobe.d/ if needed (module). - or both to match this setting. -d) Run "make modules" -e) Run "make modules_install" -f) Run "/sbin/depmod -a" -g) install driver using `modprobe ip2 <options>` (options listed below) -h) run ip2mkdev (either the script below or the binary version) - - -Kernel installation: - -a) Determine free irq/address to use if any (configure BIOS if need be) -b) Run "make config" or "make menuconfig" or "make xconfig" - Select (y) kernel for CONFIG_COMPUTONE under character - devices. CONFIG_PCI may need to be set if you have PCI bus. -c) Set address on ISA cards then: - edit /usr/src/linux/drivers/char/ip2.c - (Optional - may be specified on kernel command line now) -d) Run "make zImage" or whatever target you prefer. -e) mv /usr/src/linux/arch/x86/boot/zImage to /boot. -f) Add new config for this kernel into /etc/lilo.conf, run "lilo" - or copy to a floppy disk and boot from that floppy disk. -g) Reboot using this kernel -h) run ip2mkdev (either the script below or the binary version) - -Kernel command line options: - -When compiling the driver into the kernel, io and irq may be -compiled into the driver by editing ip2.c and setting the values for -io and irq in the appropriate array. An alternative is to specify -a command line parameter to the kernel at boot up. - - ip2=io0,irq0,io1,irq1,io2,irq2,io3,irq3 - -Note that this order is very different from the specifications for the -modload parameters which have separate IRQ and IO specifiers. - -The io port also selects PCI (1) and EISA (2) boards. - - io=0 No board - io=1 PCI board - io=2 EISA board - else ISA board io address - -You only need to specify the boards which are present. - - Examples: - - 2 PCI boards: - - ip2=1,0,1,0 - - 1 ISA board at 0x310 irq 5: - - ip2=0x310,5 - -This can be added to and "append" option in lilo.conf similar to this: - - append="ip2=1,0,1,0" - - -3. INSTALLATION - -Previously, the driver sources were packaged with a set of patch files -to update the character drivers' makefile and configuration file, and other -kernel source files. A build script (ip2build) was included which applies -the patches if needed, and build any utilities needed. -What you receive may be a single patch file in conventional kernel -patch format build script. That form can also be applied by -running patch -p1 < ThePatchFile. Otherwise run ip2build. - -The driver can be installed as a module (recommended) or built into the -kernel. This is selected as for other drivers through the `make config` -command from the root of the Linux source tree. If the driver is built -into the kernel you will need to edit the file ip2.c to match the boards -you are installing. See that file for instructions. If the driver is -installed as a module the configuration can also be specified on the -modprobe command line as follows: - - modprobe ip2 irq=irq1,irq2,irq3,irq4 io=addr1,addr2,addr3,addr4 - -where irqnum is one of the valid Intelliport II interrupts (3,4,5,7,10,11, -12,15) and addr1-4 are the base addresses for up to four controllers. If -the irqs are not specified the driver uses the default in ip2.c (which -selects polled mode). If no base addresses are specified the defaults in -ip2.c are used. If you are autoloading the driver module with kerneld or -kmod the base addresses and interrupt number must also be set in ip2.c -and recompile or just insert and options line in /etc/modprobe.d/*.conf or both. -The options line is equivalent to the command line and takes precedence over -what is in ip2.c. - -config sample to put /etc/modprobe.d/*.conf: - options ip2 io=1,0x328 irq=1,10 - alias char-major-71 ip2 - alias char-major-72 ip2 - alias char-major-73 ip2 - -The equivalent in ip2.c: - -static int io[IP2_MAX_BOARDS]= { 1, 0x328, 0, 0 }; -static int irq[IP2_MAX_BOARDS] = { 1, 10, -1, -1 }; - -The equivalent for the kernel command line (in lilo.conf): - - append="ip2=1,1,0x328,10" - - -Note: Both io and irq should be updated to reflect YOUR system. An "io" - address of 1 or 2 indicates a PCI or EISA card in the board table. - The PCI or EISA irq will be assigned automatically. - -Specifying an invalid or in-use irq will default the driver into -running in polled mode for that card. If all irq entries are 0 then -all cards will operate in polled mode. - -If you select the driver as part of the kernel run : - - make zlilo (or whatever you do to create a bootable kernel) - -If you selected a module run : - - make modules && make modules_install - -The utility ip2mkdev (see 5 and 7 below) creates all the device nodes -required by the driver. For a device to be created it must be configured -in the driver and the board must be installed. Only devices corresponding -to real IntelliPort II ports are created. With multiple boards and expansion -boxes this will leave gaps in the sequence of device names. ip2mkdev uses -Linux tty naming conventions: ttyF0 - ttyF255 for normal devices, and -cuf0 - cuf255 for callout devices. - - -4. USING THE DRIVERS - -As noted above, the driver implements the ports in accordance with Linux -conventions, and the devices should be interchangeable with the standard -serial devices. (This is a key point for problem reporting: please make -sure that what you are trying do works on the ttySx/cuax ports first; then -tell us what went wrong with the ip2 ports!) - -Higher speeds can be obtained using the setserial utility which remaps -38,400 bps (extb) to 57,600 bps, 115,200 bps, or a custom speed. -Intelliport II installations using the PowerPort expansion module can -use the custom speed setting to select the highest speeds: 153,600 bps, -230,400 bps, 307,200 bps, 460,800bps and 921,600 bps. The base for -custom baud rate configuration is fixed at 921,600 for cards/expansion -modules with ST654's and 115200 for those with Cirrus CD1400's. This -corresponds to the maximum bit rates those chips are capable. -For example if the baud base is 921600 and the baud divisor is 18 then -the custom rate is 921600/18 = 51200 bps. See the setserial man page for -complete details. Of course if stty accepts the higher rates now you can -use that as well as the standard ioctls(). - - -5. ip2mkdev and assorted utilities... - -Several utilities, including the source for a binary ip2mkdev utility are -available under .../drivers/char/ip2. These can be build by changing to -that directory and typing "make" after the kernel has be built. If you do -not wish to compile the binary utilities, the shell script below can be -cut out and run as "ip2mkdev" to create the necessary device files. To -use the ip2mkdev script, you must have procfs enabled and the proc file -system mounted on /proc. - - -6. NOTES - -This is a release version of the driver, but it is impossible to test it -in all configurations of Linux. If there is any anomalous behaviour that -does not match the standard serial port's behaviour please let us know. - - -7. ip2mkdev shell script - -Previously, this script was simply attached here. It is now attached as a -shar archive to make it easier to extract the script from the documentation. -To create the ip2mkdev shell script change to a convenient directory (/tmp -works just fine) and run the following command: - - unshar Documentation/serial/computone.txt - (This file) - -You should now have a file ip2mkdev in your current working directory with -permissions set to execute. Running that script with then create the -necessary devices for the Computone boards, interfaces, and ports which -are present on you system at the time it is run. - - -#!/bin/sh -# This is a shell archive (produced by GNU sharutils 4.2.1). -# To extract the files from this archive, save it to some FILE, remove -# everything before the `!/bin/sh' line above, then type `sh FILE'. -# -# Made on 2001-10-29 10:32 EST by <mhw@alcove.wittsend.com>. -# Source directory was `/home2/src/tmp'. -# -# Existing files will *not* be overwritten unless `-c' is specified. -# -# This shar contains: -# length mode name -# ------ ---------- ------------------------------------------ -# 4251 -rwxr-xr-x ip2mkdev -# -save_IFS="${IFS}" -IFS="${IFS}:" -gettext_dir=FAILED -locale_dir=FAILED -first_param="$1" -for dir in $PATH -do - if test "$gettext_dir" = FAILED && test -f $dir/gettext \ - && ($dir/gettext --version >/dev/null 2>&1) - then - set `$dir/gettext --version 2>&1` - if test "$3" = GNU - then - gettext_dir=$dir - fi - fi - if test "$locale_dir" = FAILED && test -f $dir/shar \ - && ($dir/shar --print-text-domain-dir >/dev/null 2>&1) - then - locale_dir=`$dir/shar --print-text-domain-dir` - fi -done -IFS="$save_IFS" -if test "$locale_dir" = FAILED || test "$gettext_dir" = FAILED -then - echo=echo -else - TEXTDOMAINDIR=$locale_dir - export TEXTDOMAINDIR - TEXTDOMAIN=sharutils - export TEXTDOMAIN - echo="$gettext_dir/gettext -s" -fi -if touch -am -t 200112312359.59 $$.touch >/dev/null 2>&1 && test ! -f 200112312359.59 -a -f $$.touch; then - shar_touch='touch -am -t $1$2$3$4$5$6.$7 "$8"' -elif touch -am 123123592001.59 $$.touch >/dev/null 2>&1 && test ! -f 123123592001.59 -a ! -f 123123592001.5 -a -f $$.touch; then - shar_touch='touch -am $3$4$5$6$1$2.$7 "$8"' -elif touch -am 1231235901 $$.touch >/dev/null 2>&1 && test ! -f 1231235901 -a -f $$.touch; then - shar_touch='touch -am $3$4$5$6$2 "$8"' -else - shar_touch=: - echo - $echo 'WARNING: not restoring timestamps. Consider getting and' - $echo "installing GNU \`touch', distributed in GNU File Utilities..." - echo -fi -rm -f 200112312359.59 123123592001.59 123123592001.5 1231235901 $$.touch -# -if mkdir _sh17581; then - $echo 'x -' 'creating lock directory' -else - $echo 'failed to create lock directory' - exit 1 -fi -# ============= ip2mkdev ============== -if test -f 'ip2mkdev' && test "$first_param" != -c; then - $echo 'x -' SKIPPING 'ip2mkdev' '(file already exists)' -else - $echo 'x -' extracting 'ip2mkdev' '(text)' - sed 's/^X//' << 'SHAR_EOF' > 'ip2mkdev' && -#!/bin/sh - -# -# ip2mkdev -# -# Make or remove devices as needed for Computone Intelliport drivers -# -# First rule! If the dev file exists and you need it, don't mess -# with it. That prevents us from screwing up open ttys, ownership -# and permissions on a running system! -# -# This script will NOT remove devices that no longer exist if their -# board or interface box has been removed. If you want to get rid -# of them, you can manually do an "rm -f /dev/ttyF* /dev/cuaf*" -# before running this script. Running this script will then recreate -# all the valid devices. -# -# Michael H. Warfield -# /\/\|=mhw=|\/\/ -# mhw@wittsend.com -# -# Updated 10/29/2000 for version 1.2.13 naming convention -# under devfs. /\/\|=mhw=|\/\/ -# -# Updated 03/09/2000 for devfs support in ip2 drivers. /\/\|=mhw=|\/\/ -# -X -if test -d /dev/ip2 ; then -# This is devfs mode... We don't do anything except create symlinks -# from the real devices to the old names! -X cd /dev -X echo "Creating symbolic links to devfs devices" -X for i in `ls ip2` ; do -X if test ! -L ip2$i ; then -X # Remove it incase it wasn't a symlink (old device) -X rm -f ip2$i -X ln -s ip2/$i ip2$i -X fi -X done -X for i in `( cd tts ; ls F* )` ; do -X if test ! -L tty$i ; then -X # Remove it incase it wasn't a symlink (old device) -X rm -f tty$i -X ln -s tts/$i tty$i -X fi -X done -X for i in `( cd cua ; ls F* )` ; do -X DEVNUMBER=`expr $i : 'F\(.*\)'` -X if test ! -L cuf$DEVNUMBER ; then -X # Remove it incase it wasn't a symlink (old device) -X rm -f cuf$DEVNUMBER -X ln -s cua/$i cuf$DEVNUMBER -X fi -X done -X exit 0 -fi -X -if test ! -f /proc/tty/drivers -then -X echo "\ -Unable to check driver status. -Make sure proc file system is mounted." -X -X exit 255 -fi -X -if test ! -f /proc/tty/driver/ip2 -then -X echo "\ -Unable to locate ip2 proc file. -Attempting to load driver" -X -X if /sbin/insmod ip2 -X then -X if test ! -f /proc/tty/driver/ip2 -X then -X echo "\ -Unable to locate ip2 proc file after loading driver. -Driver initialization failure or driver version error. -" -X exit 255 -X fi -X else -X echo "Unable to load ip2 driver." -X exit 255 -X fi -fi -X -# Ok... So we got the driver loaded and we can locate the procfs files. -# Next we need our major numbers. -X -TTYMAJOR=`sed -e '/^ip2/!d' -e '/\/dev\/tt/!d' -e 's/.*tt[^ ]*[ ]*\([0-9]*\)[ ]*.*/\1/' < /proc/tty/drivers` -CUAMAJOR=`sed -e '/^ip2/!d' -e '/\/dev\/cu/!d' -e 's/.*cu[^ ]*[ ]*\([0-9]*\)[ ]*.*/\1/' < /proc/tty/drivers` -BRDMAJOR=`sed -e '/^Driver: /!d' -e 's/.*IMajor=\([0-9]*\)[ ]*.*/\1/' < /proc/tty/driver/ip2` -X -echo "\ -TTYMAJOR = $TTYMAJOR -CUAMAJOR = $CUAMAJOR -BRDMAJOR = $BRDMAJOR -" -X -# Ok... Now we should know our major numbers, if appropriate... -# Now we need our boards and start the device loops. -X -grep '^Board [0-9]:' /proc/tty/driver/ip2 | while read token number type alltherest -do -X # The test for blank "type" will catch the stats lead-in lines -X # if they exist in the file -X if test "$type" = "vacant" -o "$type" = "Vacant" -o "$type" = "" -X then -X continue -X fi -X -X BOARDNO=`expr "$number" : '\([0-9]\):'` -X PORTS=`expr "$alltherest" : '.*ports=\([0-9]*\)' | tr ',' ' '` -X MINORS=`expr "$alltherest" : '.*minors=\([0-9,]*\)' | tr ',' ' '` -X -X if test "$BOARDNO" = "" -o "$PORTS" = "" -X then -# This may be a bug. We should at least get this much information -X echo "Unable to process board line" -X continue -X fi -X -X if test "$MINORS" = "" -X then -# Silently skip this one. This board seems to have no boxes -X continue -X fi -X -X echo "board $BOARDNO: $type ports = $PORTS; port numbers = $MINORS" -X -X if test "$BRDMAJOR" != "" -X then -X BRDMINOR=`expr $BOARDNO \* 4` -X STSMINOR=`expr $BRDMINOR + 1` -X if test ! -c /dev/ip2ipl$BOARDNO ; then -X mknod /dev/ip2ipl$BOARDNO c $BRDMAJOR $BRDMINOR -X fi -X if test ! -c /dev/ip2stat$BOARDNO ; then -X mknod /dev/ip2stat$BOARDNO c $BRDMAJOR $STSMINOR -X fi -X fi -X -X if test "$TTYMAJOR" != "" -X then -X PORTNO=$BOARDBASE -X -X for PORTNO in $MINORS -X do -X if test ! -c /dev/ttyF$PORTNO ; then -X # We got the hardware but no device - make it -X mknod /dev/ttyF$PORTNO c $TTYMAJOR $PORTNO -X fi -X done -X fi -X -X if test "$CUAMAJOR" != "" -X then -X PORTNO=$BOARDBASE -X -X for PORTNO in $MINORS -X do -X if test ! -c /dev/cuf$PORTNO ; then -X # We got the hardware but no device - make it -X mknod /dev/cuf$PORTNO c $CUAMAJOR $PORTNO -X fi -X done -X fi -done -X -Xexit 0 -SHAR_EOF - (set 20 01 10 29 10 32 01 'ip2mkdev'; eval "$shar_touch") && - chmod 0755 'ip2mkdev' || - $echo 'restore of' 'ip2mkdev' 'failed' - if ( md5sum --help 2>&1 | grep 'sage: md5sum \[' ) >/dev/null 2>&1 \ - && ( md5sum --version 2>&1 | grep -v 'textutils 1.12' ) >/dev/null; then - md5sum -c << SHAR_EOF >/dev/null 2>&1 \ - || $echo 'ip2mkdev:' 'MD5 check failed' -cb5717134509f38bad9fde6b1f79b4a4 ip2mkdev -SHAR_EOF - else - shar_count="`LC_ALL= LC_CTYPE= LANG= wc -c < 'ip2mkdev'`" - test 4251 -eq "$shar_count" || - $echo 'ip2mkdev:' 'original size' '4251,' 'current size' "$shar_count!" - fi -fi -rm -fr _sh17581 -exit 0 diff --git a/Documentation/smsc_ece1099.txt b/Documentation/smsc_ece1099.txt new file mode 100644 index 000000000000..6b492e82b43d --- /dev/null +++ b/Documentation/smsc_ece1099.txt @@ -0,0 +1,56 @@ +What is smsc-ece1099? +---------------------- + +The ECE1099 is a 40-Pin 3.3V Keyboard Scan Expansion +or GPIO Expansion device. The device supports a keyboard +scan matrix of 23x8. The device is connected to a Master +via the SMSC BC-Link interface or via the SMBus. +Keypad scan Input(KSI) and Keypad Scan Output(KSO) signals +are multiplexed with GPIOs. + +Interrupt generation +-------------------- + +Interrupts can be generated by an edge detection on a GPIO +pin or an edge detection on one of the bus interface pins. +Interrupts can also be detected on the keyboard scan interface. +The bus interrupt pin (BC_INT# or SMBUS_INT#) is asserted if +any bit in one of the Interrupt Status registers is 1 and +the corresponding Interrupt Mask bit is also 1. + +In order for software to determine which device is the source +of an interrupt, it should first read the Group Interrupt Status Register +to determine which Status register group is a source for the interrupt. +Software should read both the Status register and the associated Mask register, +then AND the two values together. Bits that are 1 in the result of the AND +are active interrupts. Software clears an interrupt by writing a 1 to the +corresponding bit in the Status register. + +Communication Protocol +---------------------- + +- SMbus slave Interface + The host processor communicates with the ECE1099 device + through a series of read/write registers via the SMBus + interface. SMBus is a serial communication protocol between + a computer host and its peripheral devices. The SMBus data + rate is 10KHz minimum to 400 KHz maximum + +- Slave Bus Interface + The ECE1099 device SMBus implementation is a subset of the + SMBus interface to the host. The device is a slave-only SMBus device. + The implementation in the device is a subset of SMBus since it + only supports four protocols. + + The Write Byte, Read Byte, Send Byte, and Receive Byte protocols are the + only valid SMBus protocols for the device. + +- BC-LinkTM Interface + The BC-Link is a proprietary bus that allows communication + between a Master device and a Companion device. The Master + device uses this serial bus to read and write registers + located on the Companion device. The bus comprises three signals, + BC_CLK, BC_DAT and BC_INT#. The Master device always provides the + clock, BC_CLK, and the Companion device is the source for an + independent asynchronous interrupt signal, BC_INT#. The ECE1099 + supports BC-Link speeds up to 24MHz. diff --git a/Documentation/sound/alsa/ALSA-Configuration.txt b/Documentation/sound/alsa/ALSA-Configuration.txt index 4e4d0bc9816f..d90d8ec2853d 100644 --- a/Documentation/sound/alsa/ALSA-Configuration.txt +++ b/Documentation/sound/alsa/ALSA-Configuration.txt @@ -860,8 +860,14 @@ Prior to version 0.9.0rc4 options had a 'snd_' prefix. This was removed. [Multiple options for each card instance] model - force the model name - position_fix - Fix DMA pointer (0 = auto, 1 = use LPIB, 2 = POSBUF, - 3 = VIACOMBO, 4 = COMBO) + position_fix - Fix DMA pointer + -1 = system default: choose appropriate one per controller + hardware + 0 = auto: falls back to LPIB when POSBUF doesn't work + 1 = use LPIB + 2 = POSBUF: use position buffer + 3 = VIACOMBO: VIA-specific workaround for capture + 4 = COMBO: use LPIB for playback, auto for capture stream probe_mask - Bitmask to probe codecs (default = -1, meaning all slots) When the bit 8 (0x100) is set, the lower 8 bits are used as the "fixed" codec slots; i.e. the driver probes the diff --git a/Documentation/sound/alsa/Channel-Mapping-API.txt b/Documentation/sound/alsa/Channel-Mapping-API.txt new file mode 100644 index 000000000000..3c43d1a4ca0e --- /dev/null +++ b/Documentation/sound/alsa/Channel-Mapping-API.txt @@ -0,0 +1,153 @@ +ALSA PCM channel-mapping API +============================ + Takashi Iwai <tiwai@suse.de> + +GENERAL +------- + +The channel mapping API allows user to query the possible channel maps +and the current channel map, also optionally to modify the channel map +of the current stream. + +A channel map is an array of position for each PCM channel. +Typically, a stereo PCM stream has a channel map of + { front_left, front_right } +while a 4.0 surround PCM stream has a channel map of + { front left, front right, rear left, rear right }. + +The problem, so far, was that we had no standard channel map +explicitly, and applications had no way to know which channel +corresponds to which (speaker) position. Thus, applications applied +wrong channels for 5.1 outputs, and you hear suddenly strange sound +from rear. Or, some devices secretly assume that center/LFE is the +third/fourth channels while others that C/LFE as 5th/6th channels. + +Also, some devices such as HDMI are configurable for different speaker +positions even with the same number of total channels. However, there +was no way to specify this because of lack of channel map +specification. These are the main motivations for the new channel +mapping API. + + +DESIGN +------ + +Actually, "the channel mapping API" doesn't introduce anything new in +the kernel/user-space ABI perspective. It uses only the existing +control element features. + +As a ground design, each PCM substream may contain a control element +providing the channel mapping information and configuration. This +element is specified by: + iface = SNDRV_CTL_ELEM_IFACE_PCM + name = "Playback Channel Map" or "Capture Channel Map" + device = the same device number for the assigned PCM substream + index = the same index number for the assigned PCM substream + +Note the name is different depending on the PCM substream direction. + +Each control element provides at least the TLV read operation and the +read operation. Optionally, the write operation can be provided to +allow user to change the channel map dynamically. + +* TLV + +The TLV operation gives the list of available channel +maps. A list item of a channel map is usually a TLV of + type data-bytes ch0 ch1 ch2... +where type is the TLV type value, the second argument is the total +bytes (not the numbers) of channel values, and the rest are the +position value for each channel. + +As a TLV type, either SNDRV_CTL_TLVT_CHMAP_FIXED, +SNDRV_CTL_TLV_CHMAP_VAR or SNDRV_CTL_TLVT_CHMAP_PAIRED can be used. +The _FIXED type is for a channel map with the fixed channel position +while the latter two are for flexible channel positions. _VAR type is +for a channel map where all channels are freely swappable and _PAIRED +type is where pair-wise channels are swappable. For example, when you +have {FL/FR/RL/RR} channel map, _PAIRED type would allow you to swap +only {RL/RR/FL/FR} while _VAR type would allow even swapping FL and +RR. + +These new TLV types are defined in sound/tlv.h. + +The available channel position values are defined in sound/asound.h, +here is a cut: + +/* channel positions */ +enum { + SNDRV_CHMAP_UNKNOWN = 0, + SNDRV_CHMAP_NA, /* N/A, silent */ + SNDRV_CHMAP_MONO, /* mono stream */ + /* this follows the alsa-lib mixer channel value + 3 */ + SNDRV_CHMAP_FL, /* front left */ + SNDRV_CHMAP_FR, /* front right */ + SNDRV_CHMAP_RL, /* rear left */ + SNDRV_CHMAP_RR, /* rear right */ + SNDRV_CHMAP_FC, /* front center */ + SNDRV_CHMAP_LFE, /* LFE */ + SNDRV_CHMAP_SL, /* side left */ + SNDRV_CHMAP_SR, /* side right */ + SNDRV_CHMAP_RC, /* rear center */ + /* new definitions */ + SNDRV_CHMAP_FLC, /* front left center */ + SNDRV_CHMAP_FRC, /* front right center */ + SNDRV_CHMAP_RLC, /* rear left center */ + SNDRV_CHMAP_RRC, /* rear right center */ + SNDRV_CHMAP_FLW, /* front left wide */ + SNDRV_CHMAP_FRW, /* front right wide */ + SNDRV_CHMAP_FLH, /* front left high */ + SNDRV_CHMAP_FCH, /* front center high */ + SNDRV_CHMAP_FRH, /* front right high */ + SNDRV_CHMAP_TC, /* top center */ + SNDRV_CHMAP_TFL, /* top front left */ + SNDRV_CHMAP_TFR, /* top front right */ + SNDRV_CHMAP_TFC, /* top front center */ + SNDRV_CHMAP_TRL, /* top rear left */ + SNDRV_CHMAP_TRR, /* top rear right */ + SNDRV_CHMAP_TRC, /* top rear center */ + SNDRV_CHMAP_LAST = SNDRV_CHMAP_TRC, +}; + +When a PCM stream can provide more than one channel map, you can +provide multiple channel maps in a TLV container type. The TLV data +to be returned will contain such as: + SNDRV_CTL_TLVT_CONTAINER 96 + SNDRV_CTL_TLVT_CHMAP_FIXED 4 SNDRV_CHMAP_FC + SNDRV_CTL_TLVT_CHMAP_FIXED 8 SNDRV_CHMAP_FL SNDRV_CHMAP_FR + SNDRV_CTL_TLVT_CHMAP_FIXED 16 NDRV_CHMAP_FL SNDRV_CHMAP_FR \ + SNDRV_CHMAP_RL SNDRV_CHMAP_RR + +The channel position is provided in LSB 16bits. The upper bits are +used for bit flags. + +#define SNDRV_CHMAP_POSITION_MASK 0xffff +#define SNDRV_CHMAP_PHASE_INVERSE (0x01 << 16) +#define SNDRV_CHMAP_DRIVER_SPEC (0x02 << 16) + +SNDRV_CHMAP_PHASE_INVERSE indicates the channel is phase inverted, +(thus summing left and right channels would result in almost silence). +Some digital mic devices have this. + +When SNDRV_CHMAP_DRIVER_SPEC is set, all the channel position values +don't follow the standard definition above but driver-specific. + +* READ OPERATION + +The control read operation is for providing the current channel map of +the given stream. The control element returns an integer array +containing the position of each channel. + +When this is performed before the number of the channel is specified +(i.e. hw_params is set), it should return all channels set to +UNKNOWN. + +* WRITE OPERATION + +The control write operation is optional, and only for devices that can +change the channel configuration on the fly, such as HDMI. User needs +to pass an integer value containing the valid channel positions for +all channels of the assigned PCM substream. + +This operation is allowed only at PCM PREPARED state. When called in +other states, it shall return an error. diff --git a/Documentation/sound/alsa/HD-Audio-Models.txt b/Documentation/sound/alsa/HD-Audio-Models.txt index a92bba816843..16dfe57f1731 100644 --- a/Documentation/sound/alsa/HD-Audio-Models.txt +++ b/Documentation/sound/alsa/HD-Audio-Models.txt @@ -74,7 +74,8 @@ CMI9880 AD1882 / AD1882A ================ - 3stack 3-stack mode (default) + 3stack 3-stack mode + 3stack-automute 3-stack with automute front HP (default) 6stack 6-stack mode AD1884A / AD1883 / AD1984A / AD1984B diff --git a/Documentation/spi/ep93xx_spi b/Documentation/spi/ep93xx_spi index d8eb01c15db1..832ddce6e5fb 100644 --- a/Documentation/spi/ep93xx_spi +++ b/Documentation/spi/ep93xx_spi @@ -26,7 +26,7 @@ arch/arm/mach-ep93xx/ts72xx.c: #include <linux/gpio.h> #include <linux/spi/spi.h> -#include <mach/ep93xx_spi.h> +#include <linux/platform_data/spi-ep93xx.h> /* this is our GPIO line used for chip select */ #define MMC_CHIP_SELECT_GPIO EP93XX_GPIO_LINE_EGPIO9 diff --git a/Documentation/spi/spi-sc18is602 b/Documentation/spi/spi-sc18is602 new file mode 100644 index 000000000000..a45702865a38 --- /dev/null +++ b/Documentation/spi/spi-sc18is602 @@ -0,0 +1,36 @@ +Kernel driver spi-sc18is602 +=========================== + +Supported chips: + * NXP SI18IS602/602B/603 + Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf + +Author: + Guenter Roeck <linux@roeck-us.net> + + +Description +----------- + +This driver provides connects a NXP SC18IS602/603 I2C-bus to SPI bridge to the +kernel's SPI core subsystem. + +The driver does not probe for supported chips, since the SI18IS602/603 does not +support Chip ID registers. You will have to instantiate the devices explicitly. +Please see Documentation/i2c/instantiating-devices for details. + + +Usage Notes +----------- + +This driver requires the I2C adapter driver to support raw I2C messages. I2C +adapter drivers which can only handle the SMBus protocol are not supported. + +The maximum SPI message size supported by SC18IS602/603 is 200 bytes. Attempts +to initiate longer transfers will fail with -EINVAL. EEPROM read operations and +similar large accesses have to be split into multiple chunks of no more than +200 bytes per SPI message (128 bytes of data per message is recommended). This +means that programs such as "cp" or "od", which automatically use large block +sizes to access a device, can not be used directly to read data from EEPROM. +Programs such as dd, where the block size can be specified, should be used +instead. diff --git a/Documentation/sysctl/kernel.txt b/Documentation/sysctl/kernel.txt index 6d78841fd416..2907ba6c3607 100644 --- a/Documentation/sysctl/kernel.txt +++ b/Documentation/sysctl/kernel.txt @@ -181,6 +181,8 @@ core_pattern is used to specify a core dumpfile pattern name. %p pid %u uid %g gid + %d dump mode, matches PR_SET_DUMPABLE and + /proc/sys/fs/suid_dumpable %s signal number %t UNIX time of dump %h hostname diff --git a/Documentation/trace/kprobetrace.txt b/Documentation/trace/kprobetrace.txt index d0d0bb9e3e25..d68ea5fc812b 100644 --- a/Documentation/trace/kprobetrace.txt +++ b/Documentation/trace/kprobetrace.txt @@ -12,7 +12,7 @@ kprobes can probe (this means, all functions body except for __kprobes functions). Unlike the Tracepoint based event, this can be added and removed dynamically, on the fly. -To enable this feature, build your kernel with CONFIG_KPROBE_TRACING=y. +To enable this feature, build your kernel with CONFIG_KPROBE_EVENT=y. Similar to the events tracer, this doesn't need to be activated via current_tracer. Instead of that, add probe points via diff --git a/Documentation/usb/persist.txt b/Documentation/usb/persist.txt index 074b159b77c2..35d70eda9ad6 100644 --- a/Documentation/usb/persist.txt +++ b/Documentation/usb/persist.txt @@ -155,6 +155,9 @@ If the kernel gets fooled in this way, it's almost certain to cause data corruption and to crash your system. You'll have no one to blame but yourself. +For those devices with avoid_reset_quirk attribute being set, persist +maybe fail because they may morph after reset. + YOU HAVE BEEN WARNED! USE AT YOUR OWN RISK! That having been said, most of the time there shouldn't be any trouble diff --git a/Documentation/vfio.txt b/Documentation/vfio.txt index 0cb6685c8029..8eda3635a17d 100644 --- a/Documentation/vfio.txt +++ b/Documentation/vfio.txt @@ -133,7 +133,7 @@ character devices for this group: $ lspci -n -s 0000:06:0d.0 06:0d.0 0401: 1102:0002 (rev 08) # echo 0000:06:0d.0 > /sys/bus/pci/devices/0000:06:0d.0/driver/unbind -# echo 1102 0002 > /sys/bus/pci/drivers/vfio/new_id +# echo 1102 0002 > /sys/bus/pci/drivers/vfio-pci/new_id Now we need to look at what other devices are in the group to free it for use by VFIO: diff --git a/Documentation/video4linux/CARDLIST.cx23885 b/Documentation/video4linux/CARDLIST.cx23885 index 652aecd13199..1299b5e82d7f 100644 --- a/Documentation/video4linux/CARDLIST.cx23885 +++ b/Documentation/video4linux/CARDLIST.cx23885 @@ -35,3 +35,4 @@ 34 -> TerraTec Cinergy T PCIe Dual [153b:117e] 35 -> TeVii S471 [d471:9022] 36 -> Hauppauge WinTV-HVR1255 [0070:2259] + 37 -> Prof Revolution DVB-S2 8000 [8000:3034] diff --git a/Documentation/video4linux/CQcam.txt b/Documentation/video4linux/CQcam.txt index 6e680fec1e9c..0b69e4ee8e31 100644 --- a/Documentation/video4linux/CQcam.txt +++ b/Documentation/video4linux/CQcam.txt @@ -18,7 +18,7 @@ Table of Contents 1.0 Introduction - The file ../../drivers/media/video/c-qcam.c is a device driver for + The file ../../drivers/media/parport/c-qcam.c is a device driver for the Logitech (nee Connectix) parallel port interface color CCD camera. This is a fairly inexpensive device for capturing images. Logitech does not currently provide information for developers, but many people diff --git a/Documentation/video4linux/README.davinci-vpbe b/Documentation/video4linux/README.davinci-vpbe index 7a460b0685bb..dc9a297f49c3 100644 --- a/Documentation/video4linux/README.davinci-vpbe +++ b/Documentation/video4linux/README.davinci-vpbe @@ -5,22 +5,22 @@ File partitioning ----------------- V4L2 display device driver - drivers/media/video/davinci/vpbe_display.c - drivers/media/video/davinci/vpbe_display.h + drivers/media/platform/davinci/vpbe_display.c + drivers/media/platform/davinci/vpbe_display.h VPBE display controller - drivers/media/video/davinci/vpbe.c - drivers/media/video/davinci/vpbe.h + drivers/media/platform/davinci/vpbe.c + drivers/media/platform/davinci/vpbe.h VPBE venc sub device driver - drivers/media/video/davinci/vpbe_venc.c - drivers/media/video/davinci/vpbe_venc.h - drivers/media/video/davinci/vpbe_venc_regs.h + drivers/media/platform/davinci/vpbe_venc.c + drivers/media/platform/davinci/vpbe_venc.h + drivers/media/platform/davinci/vpbe_venc_regs.h VPBE osd driver - drivers/media/video/davinci/vpbe_osd.c - drivers/media/video/davinci/vpbe_osd.h - drivers/media/video/davinci/vpbe_osd_regs.h + drivers/media/platform/davinci/vpbe_osd.c + drivers/media/platform/davinci/vpbe_osd.h + drivers/media/platform/davinci/vpbe_osd_regs.h Functional partitioning ----------------------- diff --git a/Documentation/video4linux/fimc.txt b/Documentation/video4linux/fimc.txt index eb049708f3e4..fd02d9a4930a 100644 --- a/Documentation/video4linux/fimc.txt +++ b/Documentation/video4linux/fimc.txt @@ -10,7 +10,7 @@ data from LCD controller (FIMD) through the SoC internal writeback data path. There are multiple FIMC instances in the SoCs (up to 4), having slightly different capabilities, like pixel alignment constraints, rotator availability, LCD writeback support, etc. The driver is located at -drivers/media/video/s5p-fimc directory. +drivers/media/platform/s5p-fimc directory. 1. Supported SoCs ================= @@ -36,21 +36,21 @@ Not currently supported: ===================== - media device driver - drivers/media/video/s5p-fimc/fimc-mdevice.[ch] + drivers/media/platform/s5p-fimc/fimc-mdevice.[ch] - camera capture video device driver - drivers/media/video/s5p-fimc/fimc-capture.c + drivers/media/platform/s5p-fimc/fimc-capture.c - MIPI-CSI2 receiver subdev - drivers/media/video/s5p-fimc/mipi-csis.[ch] + drivers/media/platform/s5p-fimc/mipi-csis.[ch] - video post-processor (mem-to-mem) - drivers/media/video/s5p-fimc/fimc-core.c + drivers/media/platform/s5p-fimc/fimc-core.c - common files - drivers/media/video/s5p-fimc/fimc-core.h - drivers/media/video/s5p-fimc/fimc-reg.h - drivers/media/video/s5p-fimc/regs-fimc.h + drivers/media/platform/s5p-fimc/fimc-core.h + drivers/media/platform/s5p-fimc/fimc-reg.h + drivers/media/platform/s5p-fimc/regs-fimc.h 4. User space interfaces ======================== diff --git a/Documentation/video4linux/omap3isp.txt b/Documentation/video4linux/omap3isp.txt index 5dd1439b61fd..b9a9f83b1587 100644 --- a/Documentation/video4linux/omap3isp.txt +++ b/Documentation/video4linux/omap3isp.txt @@ -12,7 +12,7 @@ Introduction ============ This file documents the Texas Instruments OMAP 3 Image Signal Processor (ISP) -driver located under drivers/media/video/omap3isp. The original driver was +driver located under drivers/media/platform/omap3isp. The original driver was written by Texas Instruments but since that it has been rewritten (twice) at Nokia. diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt index 43da22b89728..54270df99d5c 100644 --- a/Documentation/video4linux/v4l2-controls.txt +++ b/Documentation/video4linux/v4l2-controls.txt @@ -594,7 +594,11 @@ handler and finally add the first handler to the second. For example: v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_MUTE, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...); v4l2_ctrl_new_std(&video_ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...); - v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler); + v4l2_ctrl_add_handler(&video_ctrl_handler, &radio_ctrl_handler, NULL); + +The last argument to v4l2_ctrl_add_handler() is a filter function that allows +you to filter which controls will be added. Set it to NULL if you want to add +all controls. Or you can add specific controls to a handler: diff --git a/Documentation/video4linux/v4l2-framework.txt b/Documentation/video4linux/v4l2-framework.txt index 89318be6c1d2..32bfe926e8d7 100644 --- a/Documentation/video4linux/v4l2-framework.txt +++ b/Documentation/video4linux/v4l2-framework.txt @@ -583,11 +583,19 @@ You should also set these fields: - name: set to something descriptive and unique. +- vfl_dir: set this to VFL_DIR_RX for capture devices (VFL_DIR_RX has value 0, + so this is normally already the default), set to VFL_DIR_TX for output + devices and VFL_DIR_M2M for mem2mem (codec) devices. + - fops: set to the v4l2_file_operations struct. - ioctl_ops: if you use the v4l2_ioctl_ops to simplify ioctl maintenance (highly recommended to use this and it might become compulsory in the - future!), then set this to your v4l2_ioctl_ops struct. + future!), then set this to your v4l2_ioctl_ops struct. The vfl_type and + vfl_dir fields are used to disable ops that do not match the type/dir + combination. E.g. VBI ops are disabled for non-VBI nodes, and output ops + are disabled for a capture device. This makes it possible to provide + just one v4l2_ioctl_ops struct for both vbi and video nodes. - lock: leave to NULL if you want to do all the locking in the driver. Otherwise you give it a pointer to a struct mutex_lock and before the @@ -1054,4 +1062,4 @@ The first event type in the class is reserved for future use, so the first available event type is 'class base + 1'. An example on how the V4L2 events may be used can be found in the OMAP -3 ISP driver (drivers/media/video/omap3isp). +3 ISP driver (drivers/media/platform/omap3isp). diff --git a/Documentation/video4linux/videobuf b/Documentation/video4linux/videobuf index 1d00d7f15b8f..3ffe9e960b6f 100644 --- a/Documentation/video4linux/videobuf +++ b/Documentation/video4linux/videobuf @@ -349,7 +349,7 @@ again. Developers who are interested in more information can go into the relevant header files; there are a few low-level functions declared there which have not been talked about here. Also worthwhile is the vivi driver -(drivers/media/video/vivi.c), which is maintained as an example of how V4L2 +(drivers/media/platform/vivi.c), which is maintained as an example of how V4L2 drivers should be written. Vivi only uses the vmalloc() API, but it's good enough to get started with. Note also that all of these calls are exported GPL-only, so they will not be available to non-GPL kernel modules. diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index bf33aaa4c59f..f6ec3a92e621 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -857,7 +857,8 @@ struct kvm_userspace_memory_region { }; /* for kvm_memory_region::flags */ -#define KVM_MEM_LOG_DIRTY_PAGES 1UL +#define KVM_MEM_LOG_DIRTY_PAGES (1UL << 0) +#define KVM_MEM_READONLY (1UL << 1) This ioctl allows the user to create or modify a guest physical memory slot. When changing an existing slot, it may be moved in the guest @@ -873,14 +874,17 @@ It is recommended that the lower 21 bits of guest_phys_addr and userspace_addr be identical. This allows large pages in the guest to be backed by large pages in the host. -The flags field supports just one flag, KVM_MEM_LOG_DIRTY_PAGES, which -instructs kvm to keep track of writes to memory within the slot. See -the KVM_GET_DIRTY_LOG ioctl. +The flags field supports two flag, KVM_MEM_LOG_DIRTY_PAGES, which instructs +kvm to keep track of writes to memory within the slot. See KVM_GET_DIRTY_LOG +ioctl. The KVM_CAP_READONLY_MEM capability indicates the availability of the +KVM_MEM_READONLY flag. When this flag is set for a memory region, KVM only +allows read accesses. Writes will be posted to userspace as KVM_EXIT_MMIO +exits. -When the KVM_CAP_SYNC_MMU capability, changes in the backing of the memory -region are automatically reflected into the guest. For example, an mmap() -that affects the region will be made visible immediately. Another example -is madvise(MADV_DROP). +When the KVM_CAP_SYNC_MMU capability is available, changes in the backing of +the memory region are automatically reflected into the guest. For example, an +mmap() that affects the region will be made visible immediately. Another +example is madvise(MADV_DROP). It is recommended to use this API instead of the KVM_SET_MEMORY_REGION ioctl. The KVM_SET_MEMORY_REGION does not allow fine grained control over memory @@ -1946,6 +1950,19 @@ the guest using the specified gsi pin. The irqfd is removed using the KVM_IRQFD_FLAG_DEASSIGN flag, specifying both kvm_irqfd.fd and kvm_irqfd.gsi. +With KVM_CAP_IRQFD_RESAMPLE, KVM_IRQFD supports a de-assert and notify +mechanism allowing emulation of level-triggered, irqfd-based +interrupts. When KVM_IRQFD_FLAG_RESAMPLE is set the user must pass an +additional eventfd in the kvm_irqfd.resamplefd field. When operating +in resample mode, posting of an interrupt through kvm_irq.fd asserts +the specified gsi in the irqchip. When the irqchip is resampled, such +as from an EOI, the gsi is de-asserted and the user is notifed via +kvm_irqfd.resamplefd. It is the user's responsibility to re-queue +the interrupt if the device making use of it still requires service. +Note that closing the resamplefd is not sufficient to disable the +irqfd. The KVM_IRQFD_FLAG_RESAMPLE is only necessary on assignment +and need not be specified with KVM_IRQFD_FLAG_DEASSIGN. + 4.76 KVM_PPC_ALLOCATE_HTAB Capability: KVM_CAP_PPC_ALLOC_HTAB diff --git a/Documentation/virtual/kvm/hypercalls.txt b/Documentation/virtual/kvm/hypercalls.txt new file mode 100644 index 000000000000..ea113b5d87a4 --- /dev/null +++ b/Documentation/virtual/kvm/hypercalls.txt @@ -0,0 +1,66 @@ +Linux KVM Hypercall: +=================== +X86: + KVM Hypercalls have a three-byte sequence of either the vmcall or the vmmcall + instruction. The hypervisor can replace it with instructions that are + guaranteed to be supported. + + Up to four arguments may be passed in rbx, rcx, rdx, and rsi respectively. + The hypercall number should be placed in rax and the return value will be + placed in rax. No other registers will be clobbered unless explicitly stated + by the particular hypercall. + +S390: + R2-R7 are used for parameters 1-6. In addition, R1 is used for hypercall + number. The return value is written to R2. + + S390 uses diagnose instruction as hypercall (0x500) along with hypercall + number in R1. + + PowerPC: + It uses R3-R10 and hypercall number in R11. R4-R11 are used as output registers. + Return value is placed in R3. + + KVM hypercalls uses 4 byte opcode, that are patched with 'hypercall-instructions' + property inside the device tree's /hypervisor node. + For more information refer to Documentation/virtual/kvm/ppc-pv.txt + +KVM Hypercalls Documentation +=========================== +The template for each hypercall is: +1. Hypercall name. +2. Architecture(s) +3. Status (deprecated, obsolete, active) +4. Purpose + +1. KVM_HC_VAPIC_POLL_IRQ +------------------------ +Architecture: x86 +Status: active +Purpose: Trigger guest exit so that the host can check for pending +interrupts on reentry. + +2. KVM_HC_MMU_OP +------------------------ +Architecture: x86 +Status: deprecated. +Purpose: Support MMU operations such as writing to PTE, +flushing TLB, release PT. + +3. KVM_HC_FEATURES +------------------------ +Architecture: PPC +Status: active +Purpose: Expose hypercall availability to the guest. On x86 platforms, cpuid +used to enumerate which hypercalls are available. On PPC, either device tree +based lookup ( which is also what EPAPR dictates) OR KVM specific enumeration +mechanism (which is this hypercall) can be used. + +4. KVM_HC_PPC_MAP_MAGIC_PAGE +------------------------ +Architecture: PPC +Status: active +Purpose: To enable communication between the hypervisor and guest there is a +shared page that contains parts of supervisor visible register state. +The guest can map this shared page to access its supervisor register through +memory using this hypercall. diff --git a/Documentation/virtual/kvm/msr.txt b/Documentation/virtual/kvm/msr.txt index 730471048583..6d470ae7b073 100644 --- a/Documentation/virtual/kvm/msr.txt +++ b/Documentation/virtual/kvm/msr.txt @@ -34,9 +34,12 @@ MSR_KVM_WALL_CLOCK_NEW: 0x4b564d00 time information and check that they are both equal and even. An odd version indicates an in-progress update. - sec: number of seconds for wallclock. + sec: number of seconds for wallclock at time of boot. - nsec: number of nanoseconds for wallclock. + nsec: number of nanoseconds for wallclock at time of boot. + + In order to get the current wallclock time, the system_time from + MSR_KVM_SYSTEM_TIME_NEW needs to be added. Note that although MSRs are per-CPU entities, the effect of this particular MSR is global. @@ -82,20 +85,25 @@ MSR_KVM_SYSTEM_TIME_NEW: 0x4b564d01 time at the time this structure was last updated. Unit is nanoseconds. - tsc_to_system_mul: a function of the tsc frequency. One has - to multiply any tsc-related quantity by this value to get - a value in nanoseconds, besides dividing by 2^tsc_shift + tsc_to_system_mul: multiplier to be used when converting + tsc-related quantity to nanoseconds - tsc_shift: cycle to nanosecond divider, as a power of two, to - allow for shift rights. One has to shift right any tsc-related - quantity by this value to get a value in nanoseconds, besides - multiplying by tsc_to_system_mul. + tsc_shift: shift to be used when converting tsc-related + quantity to nanoseconds. This shift will ensure that + multiplication with tsc_to_system_mul does not overflow. + A positive value denotes a left shift, a negative value + a right shift. - With this information, guests can derive per-CPU time by - doing: + The conversion from tsc to nanoseconds involves an additional + right shift by 32 bits. With this information, guests can + derive per-CPU time by doing: time = (current_tsc - tsc_timestamp) - time = (time * tsc_to_system_mul) >> tsc_shift + if (tsc_shift >= 0) + time <<= tsc_shift; + else + time >>= -tsc_shift; + time = (time * tsc_to_system_mul) >> 32 time = time + system_time flags: bits in this field indicate extended capabilities diff --git a/Documentation/virtual/kvm/ppc-pv.txt b/Documentation/virtual/kvm/ppc-pv.txt index 4911cf95c67e..4cd076febb02 100644 --- a/Documentation/virtual/kvm/ppc-pv.txt +++ b/Documentation/virtual/kvm/ppc-pv.txt @@ -174,3 +174,25 @@ following: That way we can inject an arbitrary amount of code as replacement for a single instruction. This allows us to check for pending interrupts when setting EE=1 for example. + +Hypercall ABIs in KVM on PowerPC +================================= +1) KVM hypercalls (ePAPR) + +These are ePAPR compliant hypercall implementation (mentioned above). Even +generic hypercalls are implemented here, like the ePAPR idle hcall. These are +available on all targets. + +2) PAPR hypercalls + +PAPR hypercalls are needed to run server PowerPC PAPR guests (-M pseries in QEMU). +These are the same hypercalls that pHyp, the POWER hypervisor implements. Some of +them are handled in the kernel, some are handled in user space. This is only +available on book3s_64. + +3) OSI hypercalls + +Mac-on-Linux is another user of KVM on PowerPC, which has its own hypercall (long +before KVM). This is supported to maintain compatibility. All these hypercalls get +forwarded to user space. This is only useful on book3s_32, but can be used with +book3s_64 as well. diff --git a/Documentation/virtual/uml/UserModeLinux-HOWTO.txt b/Documentation/virtual/uml/UserModeLinux-HOWTO.txt index 77dfecf4e2d6..a5f8436753e7 100644 --- a/Documentation/virtual/uml/UserModeLinux-HOWTO.txt +++ b/Documentation/virtual/uml/UserModeLinux-HOWTO.txt @@ -3591,7 +3591,7 @@ Looking at the source shows that the fault happened during a call to - copy_to_user to copy the data into the kernel: + copy_from_user to copy the data into the kernel: 107 count -= chars; diff --git a/Documentation/vm/unevictable-lru.txt b/Documentation/vm/unevictable-lru.txt index fa206cccf89f..a68db7692ee8 100644 --- a/Documentation/vm/unevictable-lru.txt +++ b/Documentation/vm/unevictable-lru.txt @@ -197,12 +197,8 @@ the pages are also "rescued" from the unevictable list in the process of freeing them. page_evictable() also checks for mlocked pages by testing an additional page -flag, PG_mlocked (as wrapped by PageMlocked()). If the page is NOT mlocked, -and a non-NULL VMA is supplied, page_evictable() will check whether the VMA is -VM_LOCKED via is_mlocked_vma(). is_mlocked_vma() will SetPageMlocked() and -update the appropriate statistics if the vma is VM_LOCKED. This method allows -efficient "culling" of pages in the fault path that are being faulted in to -VM_LOCKED VMAs. +flag, PG_mlocked (as wrapped by PageMlocked()), which is set when a page is +faulted into a VM_LOCKED vma, or found in a vma being VM_LOCKED. VMSCAN'S HANDLING OF UNEVICTABLE PAGES @@ -371,8 +367,8 @@ mlock_fixup() filters several classes of "special" VMAs: mlock_fixup() will call make_pages_present() in the hugetlbfs VMA range to allocate the huge pages and populate the ptes. -3) VMAs with VM_DONTEXPAND or VM_RESERVED are generally userspace mappings of - kernel pages, such as the VDSO page, relay channel pages, etc. These pages +3) VMAs with VM_DONTEXPAND are generally userspace mappings of kernel pages, + such as the VDSO page, relay channel pages, etc. These pages are inherently unevictable and are not managed on the LRU lists. mlock_fixup() treats these VMAs the same as hugetlbfs VMAs. It calls make_pages_present() to populate the ptes. @@ -651,7 +647,7 @@ PAGE RECLAIM IN shrink_*_list() ------------------------------- shrink_active_list() culls any obviously unevictable pages - i.e. -!page_evictable(page, NULL) - diverting these to the unevictable list. +!page_evictable(page) - diverting these to the unevictable list. However, shrink_active_list() only sees unevictable pages that made it onto the active/inactive lru lists. Note that these pages do not have PageUnevictable set - otherwise they would be on the unevictable list and shrink_active_list diff --git a/Documentation/x86/x86_64/boot-options.txt b/Documentation/x86/x86_64/boot-options.txt index c54b4f503e2a..de38429beb71 100644 --- a/Documentation/x86/x86_64/boot-options.txt +++ b/Documentation/x86/x86_64/boot-options.txt @@ -50,6 +50,13 @@ Machine check monarchtimeout: Sets the time in us to wait for other CPUs on machine checks. 0 to disable. + mce=bios_cmci_threshold + Don't overwrite the bios-set CMCI threshold. This boot option + prevents Linux from overwriting the CMCI threshold set by the + bios. Without this option, Linux always sets the CMCI + threshold to 1. Enabling this may make memory predictive failure + analysis less effective if the bios sets thresholds for memory + errors since we will not see details for all errors. nomce (for compatibility with i386): same as mce=off diff --git a/Documentation/zh_CN/arm/Booting b/Documentation/zh_CN/arm/Booting new file mode 100644 index 000000000000..6158a64df80c --- /dev/null +++ b/Documentation/zh_CN/arm/Booting @@ -0,0 +1,175 @@ +Chinese translated version of Documentation/arm/Booting + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Russell King <linux@arm.linux.org.uk> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/arm/Booting 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 + +英文版维护者： Russell King <linux@arm.linux.org.uk> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + +以下为正文 +--------------------------------------------------------------------- + + 启动 ARM Linux + ============== + +作者：Russell King +日期：2002年5月18日 + +以下文档适用于 2.4.18-rmk6 及以上版本。 + +为了启动 ARM Linux，你需要一个引导装载程序（boot loader）， +它是一个在主内核启动前运行的一个小程序。引导装载程序需要初始化各种 +设备，并最终调用 Linux 内核，将信息传递给内核。 + +从本质上讲，引导装载程序应提供（至少）以下功能： + +1、设置和初始化 RAM。 +2、初始化一个串口。 +3、检测机器的类型（machine type）。 +4、设置内核标签列表（tagged list）。 +5、调用内核映像。 + + +1、设置和初始化 RAM +------------------- + +现有的引导加载程序: 强制 +新开发的引导加载程序: 强制 + +引导装载程序应该找到并初始化系统中所有内核用于保持系统变量数据的 RAM。 +这个操作的执行是设备依赖的。（它可能使用内部算法来自动定位和计算所有 +RAM，或可能使用对这个设备已知的 RAM 信息，还可能使用任何引导装载程序 +设计者想到的匹配方法。） + + +2、初始化一个串口 +----------------------------- + +现有的引导加载程序: 可选、建议 +新开发的引导加载程序: 可选、建议 + +引导加载程序应该初始化并使能一个目标板上的串口。这允许内核串口驱动 +自动检测哪个串口用于内核控制台。(一般用于调试或与目标板通信。) + +作为替代方案，引导加载程序也可以通过标签列表传递相关的'console=' +选项给内核以指定某个串口，而串口数据格式的选项在以下文档中描述： + + Documentation/kernel-parameters.txt。 + + +3、检测机器类型 +-------------------------- + +现有的引导加载程序: 可选 +新开发的引导加载程序: 强制 + +引导加载程序应该通过某些方式检测自身所处的机器类型。这是一个硬件 +代码或通过查看所连接的硬件用某些算法得到，这些超出了本文档的范围。 +引导加载程序最终必须能提供一个 MACH_TYPE_xxx 值给内核。 +(详见 linux/arch/arm/tools/mach-types )。 + +4、设置启动数据 +------------------ + +现有的引导加载程序: 可选、强烈建议 +新开发的引导加载程序: 强制 + +引导加载程序必须提供标签列表或者 dtb 映像以传递配置数据给内核。启动 +数据的物理地址通过寄存器 r2 传递给内核。 + +4a、设置内核标签列表 +-------------------------------- + +bootloader 必须创建和初始化内核标签列表。一个有效的标签列表以 +ATAG_CORE 标签开始，并以 ATAG_NONE 标签结束。ATAG_CORE 标签可以是 +空的，也可以是非空。一个空 ATAG_CORE 标签其 size 域设置为 +‘2’(0x00000002)。ATAG_NONE 标签的 size 域必须设置为零。 + +在列表中可以保存任意数量的标签。对于一个重复的标签是追加到之前标签 +所携带的信息之后，还是会覆盖原来的信息，是未定义的。某些标签的行为 +是前者，其他是后者。 + +bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 +因此，最小的标签列表如下所示： + + +-----------+ +基地址 -> | ATAG_CORE | | + +-----------+ | + | ATAG_MEM | | 地址增长方向 + +-----------+ | + | ATAG_NONE | | + +-----------+ v + +标签列表应该保存在系统的 RAM 中。 + +标签列表必须置于内核自解压和 initrd'bootp' 程序都不会覆盖的内存区。 +建议放在 RAM 的头 16KiB 中。 + +4b、设置设备树 +------------------------- + +bootloader 必须以 64bit 地址对齐的形式加载一个设备树映像(dtb)到系统 +RAM 中，并用启动数据初始化它。dtb 格式在文档 +Documentation/devicetree/booting-without-of.txt 中。内核将会在 +dtb 物理地址处查找 dtb 魔数值（0xd00dfeed），以确定 dtb 是否已经代替 +标签列表被传递进来。 + +bootloader 必须传递一个系统内存的位置和最小值，以及根文件系统位置。 +dtb 必须置于内核自解压不会覆盖的内存区。建议将其放置于 RAM 的头 16KiB +中。但是不可将其放置于“0”物理地址处，因为内核认为：r2 中为 0，意味着 +没有标签列表和 dtb 传递过来。 + +5、调用内核映像 +--------------------------- + +现有的引导加载程序: 强制 +新开发的引导加载程序: 强制 + +调用内核映像 zImage 有两个选择。如果 zImge 保存在 flash 中，且是为了 +在 flash 中直接运行而被正确链接的。这样引导加载程序就可以在 flash 中 +直接调用 zImage。 + +zImage 也可以被放在系统 RAM（任意位置）中被调用。注意：内核使用映像 +基地址的前 16KB RAM 空间来保存页表。建议将映像置于 RAM 的 32KB 处。 + +对于以上任意一种情况，都必须符合以下启动状态： + +- 停止所有 DMA 设备，这样内存数据就不会因为虚假网络包或磁盘数据而被破坏。 + 这可能可以节省你许多的调试时间。 + +- CPU 寄存器配置 + r0 = 0， + r1 = （在上面 3 中获取的）机器类型码。 + r2 = 标签列表在系统 RAM 中的物理地址，或 + 设备树块(dtb)在系统 RAM 中的物理地址 + +- CPU 模式 + 所有形式的中断必须被禁止 (IRQs 和 FIQs) + CPU 必须处于 SVC 模式。(对于 Angel 调试有特例存在) + +- 缓存，MMUs + MMU 必须关闭。 + 指令缓存开启或关闭都可以。 + 数据缓存必须关闭。 + +- 引导加载程序应该通过直接跳转到内核映像的第一条指令来调用内核映像。 + + 对于支持 ARM 指令集的 CPU，跳入内核入口时必须处在 ARM 状态，即使 + 对于 Thumb-2 内核也是如此。 + + 对于仅支持 Thumb 指令集的 CPU，比如 Cortex-M 系列的 CPU，跳入 + 内核入口时必须处于 Thumb 状态。 diff --git a/Documentation/zh_CN/basic_profiling.txt b/Documentation/zh_CN/basic_profiling.txt new file mode 100644 index 000000000000..1e6bf0bdf8f5 --- /dev/null +++ b/Documentation/zh_CN/basic_profiling.txt @@ -0,0 +1,71 @@ +Chinese translated version of Documentation/basic_profiling + +If you have any comment or update to the content, please post to LKML directly. +However, if you have problem communicating in English you can also ask the +Chinese maintainer for help. Contact the Chinese maintainer, if this +translation is outdated or there is problem with translation. + +Chinese maintainer: Liang Xie <xieliang@xiaomi.com> +--------------------------------------------------------------------- +Documentation/basic_profiling的中文翻译 + +如果想评论或更新本文的内容，请直接发信到LKML。如果你使用英文交流有困难的话，也可 +以向中文版维护者求助。如果本翻译更新不及时或者翻译存在问题，请联系中文版维护者。 + +中文版维护者： 谢良 Liang Xie <xieliang007@gmail.com> +中文版翻译者： 谢良 Liang Xie <xieliang007@gmail.com> +中文版校译者： +以下为正文 +--------------------------------------------------------------------- + +下面这些说明指令都是非常基础的，如果你想进一步了解请阅读相关专业文档：） +请不要再在本文档增加新的内容，但可以修复文档中的错误：）(mbligh@aracnet.com) +感谢John Levon，Dave Hansen等在撰写时的帮助 + +<test> 用于表示要测量的目标 +请先确保您已经有正确的System.map / vmlinux配置！ + +对于linux系统来说，配置vmlinuz最容易的方法可能就是使用“make install”，然后修改 +/sbin/installkernel将vmlinux拷贝到/boot目录，而System.map通常是默认安装好的 + +Readprofile +----------- +2.6系列内核需要版本相对较新的readprofile，比如util-linux 2.12a中包含的，可以从: + +http://www.kernel.org/pub/linux/utils/util-linux/ 下载 + +大部分linux发行版已经包含了. + +启用readprofile需要在kernel启动命令行增加”profile=2“ + +clear readprofile -r + <test> +dump output readprofile -m /boot/System.map > captured_profile + +Oprofile +-------- + +从http://oprofile.sourceforge.net/获取源代码（请参考Changes以获取匹配的版本） +在kernel启动命令行增加“idle=poll” + +配置CONFIG_PROFILING=y和CONFIG_OPROFILE=y然后重启进入新kernel + +./configure --with-kernel-support +make install + +想得到好的测量结果，请确保启用了本地APIC特性。如果opreport显示有0Hz CPU， +说明APIC特性没有开启。另外注意idle=poll选项可能有损性能。 + +One time setup: + opcontrol --setup --vmlinux=/boot/vmlinux + +clear opcontrol --reset +start opcontrol --start + <test> +stop opcontrol --stop +dump output opreport > output_file + +如果只看kernel相关的报告结果，请运行命令 opreport -l /boot/vmlinux > output_file + +通过reset选项可以清理过期统计数据，相当于重启的效果。 + diff --git a/Documentation/zh_CN/filesystems/sysfs.txt b/Documentation/zh_CN/filesystems/sysfs.txt new file mode 100644 index 000000000000..e230eaa33122 --- /dev/null +++ b/Documentation/zh_CN/filesystems/sysfs.txt @@ -0,0 +1,372 @@ +Chinese translated version of Documentation/filesystems/sysfs.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Patrick Mochel <mochel@osdl.org> + Mike Murphy <mamurph@cs.clemson.edu> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/filesystems/sysfs.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Patrick Mochel <mochel@osdl.org> + Mike Murphy <mamurph@cs.clemson.edu> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +sysfs - 用于导出内核对象(kobject)的文件系统 + +Patrick Mochel <mochel@osdl.org> +Mike Murphy <mamurph@cs.clemson.edu> + +修订: 16 August 2011 +原始版本: 10 January 2003 + + +sysfs 简介: +~~~~~~~~~~ + +sysfs 是一个最初基于 ramfs 且位于内存的文件系统。它提供导出内核 +数据结构及其属性，以及它们之间的关联到用户空间的方法。 + +sysfs 始终与 kobject 的底层结构紧密相关。请阅读 +Documentation/kobject.txt 文档以获得更多关于 kobject 接口的 +信息。 + + +使用 sysfs +~~~~~~~~~~~ + +只要内核配置中定义了 CONFIG_SYSFS ，sysfs 总是被编译进内核。你可 +通过以下命令挂载它: + + mount -t sysfs sysfs /sys + + +创建目录 +~~~~~~~~ + +任何 kobject 在系统中注册，就会有一个目录在 sysfs 中被创建。这个 +目录是作为该 kobject 的父对象所在目录的子目录创建的，以准确地传递 +内核的对象层次到用户空间。sysfs 中的顶层目录代表着内核对象层次的 +共同祖先；例如：某些对象属于某个子系统。 + +Sysfs 在与其目录关联的 sysfs_dirent 对象中内部保存一个指向实现 +目录的 kobject 的指针。以前，这个 kobject 指针被 sysfs 直接用于 +kobject 文件打开和关闭的引用计数。而现在的 sysfs 实现中，kobject +引用计数只能通过 sysfs_schedule_callback() 函数直接修改。 + + +属性 +~~~~ + +kobject 的属性可在文件系统中以普通文件的形式导出。Sysfs 为属性定义 +了面向文件 I/O 操作的方法，以提供对内核属性的读写。 + + +属性应为 ASCII 码文本文件。以一个文件只存储一个属性值为宜。但一个 +文件只包含一个属性值可能影响效率，所以一个包含相同数据类型的属性值 +数组也被广泛地接受。 + +混合类型、表达多行数据以及一些怪异的数据格式会遭到强烈反对。这样做是 +很丢脸的,而且其代码会在未通知作者的情况下被重写。 + + +一个简单的属性结构定义如下: + +struct attribute { + char * name; + struct module *owner; + umode_t mode; +}; + + +int sysfs_create_file(struct kobject * kobj, const struct attribute * attr); +void sysfs_remove_file(struct kobject * kobj, const struct attribute * attr); + + +一个单独的属性结构并不包含读写其属性值的方法。子系统最好为增删特定 +对象类型的属性定义自己的属性结构体和封装函数。 + +例如:驱动程序模型定义的 device_attribute 结构体如下: + +struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); +}; + +int device_create_file(struct device *, const struct device_attribute *); +void device_remove_file(struct device *, const struct device_attribute *); + +为了定义设备属性，同时定义了一下辅助宏: + +#define DEVICE_ATTR(_name, _mode, _show, _store) \ +struct device_attribute dev_attr_##_name = __ATTR(_name, _mode, _show, _store) + +例如:声明 + +static DEVICE_ATTR(foo, S_IWUSR | S_IRUGO, show_foo, store_foo); + +等同于如下代码： + +static struct device_attribute dev_attr_foo = { + .attr = { + .name = "foo", + .mode = S_IWUSR | S_IRUGO, + .show = show_foo, + .store = store_foo, + }, +}; + + +子系统特有的回调函数 +~~~~~~~~~~~~~~~~~~~ + +当一个子系统定义一个新的属性类型时，必须实现一系列的 sysfs 操作， +以帮助读写调用实现属性所有者的显示和储存方法。 + +struct sysfs_ops { + ssize_t (*show)(struct kobject *, struct attribute *, char *); + ssize_t (*store)(struct kobject *, struct attribute *, const char *, size_t); +}; + +[子系统应已经定义了一个 struct kobj_type 结构体作为这个类型的 +描述符，并在此保存 sysfs_ops 的指针。更多的信息参见 kobject 的 +文档] + +sysfs 会为这个类型调用适当的方法。当一个文件被读写时，这个方法会 +将一般的kobject 和 attribute 结构体指针转换为适当的指针类型后 +调用相关联的函数。 + + +示例: + +#define to_dev(obj) container_of(obj, struct device, kobj) +#define to_dev_attr(_attr) container_of(_attr, struct device_attribute, attr) + +static ssize_t dev_attr_show(struct kobject *kobj, struct attribute *attr, + char *buf) +{ + struct device_attribute *dev_attr = to_dev_attr(attr); + struct device *dev = to_dev(kobj); + ssize_t ret = -EIO; + + if (dev_attr->show) + ret = dev_attr->show(dev, dev_attr, buf); + if (ret >= (ssize_t)PAGE_SIZE) { + print_symbol("dev_attr_show: %s returned bad count\n", + (unsigned long)dev_attr->show); + } + return ret; +} + + + +读写属性数据 +~~~~~~~~~~~~ + +在声明属性时，必须指定 show() 或 store() 方法，以实现属性的 +读或写。这些方法的类型应该和以下的设备属性定义一样简单。 + +ssize_t (*show)(struct device *dev, struct device_attribute *attr, char *buf); +ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); + +也就是说,他们应只以一个处理对象、一个属性和一个缓冲指针作为参数。 + +sysfs 会分配一个大小为 (PAGE_SIZE) 的缓冲区并传递给这个方法。 +Sysfs 将会为每次读写操作调用一次这个方法。这使得这些方法在执行时 +会出现以下的行为: + +- 在读方面（read(2)），show() 方法应该填充整个缓冲区。回想属性 + 应只导出了一个属性值或是一个同类型属性值的数组，所以这个代价将 + 不会不太高。 + + 这使得用户空间可以局部地读和任意的向前搜索整个文件。如果用户空间 + 向后搜索到零或使用‘0’偏移执行一个pread(2)操作，show()方法将 + 再次被调用，以重新填充缓存。 + +- 在写方面（write(2)），sysfs 希望在第一次写操作时得到整个缓冲区。 + 之后 Sysfs 传递整个缓冲区给 store() 方法。 + + 当要写 sysfs 文件时，用户空间进程应首先读取整个文件，修该想要 + 改变的值，然后回写整个缓冲区。 + + 在读写属性值时，属性方法的执行应操作相同的缓冲区。 + +注记: + +- 写操作导致的 show() 方法重载，会忽略当前文件位置。 + +- 缓冲区应总是 PAGE_SIZE 大小。对于i386，这个值为4096。 + +- show() 方法应该返回写入缓冲区的字节数，也就是 snprintf()的 + 返回值。 + +- show() 应始终使用 snprintf()。 + +- store() 应返回缓冲区的已用字节数。如果整个缓存都已填满，只需返回 + count 参数。 + +- show() 或 store() 可以返回错误值。当得到一个非法值，必须返回一个 + 错误值。 + +- 一个传递给方法的对象将会通过 sysfs 调用对象内嵌的引用计数固定在 + 内存中。尽管如此，对象代表的物理实体(如设备)可能已不存在。如有必要， + 应该实现一个检测机制。 + +一个简单的(未经实验证实的)设备属性实现如下： + +static ssize_t show_name(struct device *dev, struct device_attribute *attr, + char *buf) +{ + return scnprintf(buf, PAGE_SIZE, "%s\n", dev->name); +} + +static ssize_t store_name(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count) +{ + snprintf(dev->name, sizeof(dev->name), "%.*s", + (int)min(count, sizeof(dev->name) - 1), buf); + return count; +} + +static DEVICE_ATTR(name, S_IRUGO, show_name, store_name); + + +（注意：真正的实现不允许用户空间设置设备名。） + +顶层目录布局 +~~~~~~~~~~~~ + +sysfs 目录的安排显示了内核数据结构之间的关系。 + +顶层 sysfs 目录如下: + +block/ +bus/ +class/ +dev/ +devices/ +firmware/ +net/ +fs/ + +devices/ 包含了一个设备树的文件系统表示。他直接映射了内部的内核 +设备树，反映了设备的层次结构。 + +bus/ 包含了内核中各种总线类型的平面目录布局。每个总线目录包含两个 +子目录: + + devices/ + drivers/ + +devices/ 包含了系统中出现的每个设备的符号链接，他们指向 root/ 下的 +设备目录。 + +drivers/ 包含了每个已为特定总线上的设备而挂载的驱动程序的目录(这里 +假定驱动没有跨越多个总线类型)。 + +fs/ 包含了一个为文件系统设立的目录。现在每个想要导出属性的文件系统必须 +在 fs/ 下创建自己的层次结构(参见Documentation/filesystems/fuse.txt)。 + +dev/ 包含两个子目录： char/ 和 block/。在这两个子目录中，有以 +<major>:<minor> 格式命名的符号链接。这些符号链接指向 sysfs 目录 +中相应的设备。/sys/dev 提供一个通过一个 stat(2) 操作结果，查找 +设备 sysfs 接口快捷的方法。 + +更多有关 driver-model 的特性信息可以在 Documentation/driver-model/ +中找到。 + + +TODO: 完成这一节。 + + +当前接口 +~~~~~~~~ + +以下的接口层普遍存在于当前的sysfs中: + +- 设备 (include/linux/device.h) +---------------------------------- +结构体: + +struct device_attribute { + struct attribute attr; + ssize_t (*show)(struct device *dev, struct device_attribute *attr, + char *buf); + ssize_t (*store)(struct device *dev, struct device_attribute *attr, + const char *buf, size_t count); +}; + +声明: + +DEVICE_ATTR(_name, _mode, _show, _store); + +增/删属性: + +int device_create_file(struct device *dev, const struct device_attribute * attr); +void device_remove_file(struct device *dev, const struct device_attribute * attr); + + +- 总线驱动程序 (include/linux/device.h) +-------------------------------------- +结构体: + +struct bus_attribute { + struct attribute attr; + ssize_t (*show)(struct bus_type *, char * buf); + ssize_t (*store)(struct bus_type *, const char * buf, size_t count); +}; + +声明: + +BUS_ATTR(_name, _mode, _show, _store) + +增/删属性: + +int bus_create_file(struct bus_type *, struct bus_attribute *); +void bus_remove_file(struct bus_type *, struct bus_attribute *); + + +- 设备驱动程序 (include/linux/device.h) +----------------------------------------- + +结构体: + +struct driver_attribute { + struct attribute attr; + ssize_t (*show)(struct device_driver *, char * buf); + ssize_t (*store)(struct device_driver *, const char * buf, + size_t count); +}; + +声明: + +DRIVER_ATTR(_name, _mode, _show, _store) + +增/删属性： + +int driver_create_file(struct device_driver *, const struct driver_attribute *); +void driver_remove_file(struct device_driver *, const struct driver_attribute *); + + +文档 +~~~~ + +sysfs 目录结构以及其中包含的属性定义了一个内核与用户空间之间的 ABI。 +对于任何 ABI，其自身的稳定和适当的文档是非常重要的。所有新的 sysfs +属性必须在 Documentation/ABI 中有文档。详见 Documentation/ABI/README。 diff --git a/Documentation/zh_CN/gpio.txt b/Documentation/zh_CN/gpio.txt new file mode 100644 index 000000000000..4fa7b4e6f856 --- /dev/null +++ b/Documentation/zh_CN/gpio.txt @@ -0,0 +1,658 @@ +Chinese translated version of Documentation/gpio.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Grant Likely <grant.likely@secretlab.ca> + Linus Walleij <linus.walleij@linaro.org> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/gpio.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Grant Likely <grant.likely@secretlab.ca> + Linus Walleij <linus.walleij@linaro.org> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +GPIO 接口 + +本文档提供了一个在Linux下访问GPIO的公约概述。 + +这些函数以 gpio_* 作为前缀。其他的函数不允许使用这样的前缀或相关的 +__gpio_* 前缀。 + + +什么是GPIO? +========== +"通用输入/输出口"(GPIO)是一个灵活的由软件控制的数字信号。他们可 +由多种芯片提供,且对于从事嵌入式和定制硬件的 Linux 开发者来说是 +比较熟悉。每个GPIO 都代表一个连接到特定引脚或球栅阵列(BGA)封装中 +“球珠”的一个位。电路板原理图显示了 GPIO 与外部硬件的连接关系。 +驱动可以编写成通用代码，以使板级启动代码可传递引脚配置数据给驱动。 + +片上系统 (SOC) 处理器对 GPIO 有很大的依赖。在某些情况下,每个 +非专用引脚都可配置为 GPIO,且大多数芯片都最少有一些 GPIO。 +可编程逻辑器件(类似 FPGA) 可以方便地提供 GPIO。像电源管理和 +音频编解码器这样的多功能芯片经常留有一些这样的引脚来帮助那些引脚 +匮乏的 SOC。同时还有通过 I2C 或 SPI 串行总线连接的“GPIO扩展器” +芯片。大多数 PC 的南桥有一些拥有 GPIO 能力的引脚 (只有BIOS +固件才知道如何使用他们)。 + +GPIO 的实际功能因系统而异。通常用法有: + + - 输出值可写 (高电平=1，低电平=0)。一些芯片也有如何驱动这些值的选项, + 例如只允许输出一个值、支持“线与”及其他取值类似的模式(值得注意的是 + “开漏”信号) + + - 输入值可读(1、0)。一些芯片支持引脚在配置为“输出”时回读，这对于类似 + “线与”的情况(以支持双向信号)是非常有用的。GPIO 控制器可能有输入 + 去毛刺/消抖逻辑,这有时需要软件控制。 + + - 输入通常可作为 IRQ 信号,一般是沿触发,但有时是电平触发。这样的 IRQ + 可能配置为系统唤醒事件,以将系统从低功耗状态下唤醒。 + + - 通常一个 GPIO 根据不同产品电路板的需求,可以配置为输入或输出,也有仅 + 支持单向的。 + + - 大部分 GPIO 可以在持有自旋锁时访问,但是通常由串行总线扩展的 GPIO + 不允许持有自旋锁。但某些系统也支持这种类型。 + +对于给定的电路板,每个 GPIO 都用于某个特定的目的,如监控 MMC/SD 卡的 +插入/移除、检测卡的写保护状态、驱动 LED、配置收发器、模拟串行总线、 +复位硬件看门狗、感知开关状态等等。 + + +GPIO 公约 +========= +注意,这个叫做“公约”，因为这不是强制性的，不遵循这个公约是无伤大雅的， +因为此时可移植性并不重要。GPIO 常用于板级特定的电路逻辑,甚至可能 +随着电路板的版本而改变，且不可能在不同走线的电路板上使用。仅有在少数 +功能上才具有可移植性，其他功能是平台特定。这也是由于“胶合”的逻辑造成的。 + +此外，这不需要任何的执行框架，只是一个接口。某个平台可能通过一个简单地 +访问芯片寄存器的内联函数来实现它，其他平台可能通过委托一系列不同的GPIO +控制器的抽象函数来实现它。(有一些可选的代码能支持这种策略的实现,本文档 +后面会介绍，但作为 GPIO 接口的客户端驱动程序必须与它的实现无关。) + +也就是说,如果在他们的平台上支持这个公约，驱动应尽可能的使用它。平台 +必须在 Kconfig 中声明对 GENERIC_GPIO的支持 (布尔型 true)，并提供 +一个 <asm/gpio.h> 文件。那些调用标准 GPIO 函数的驱动应该在 Kconfig +入口中声明依赖GENERIC_GPIO。当驱动包含文件: + + #include <linux/gpio.h> + +则 GPIO 函数是可用,无论是“真实代码”还是经优化过的语句。如果你遵守 +这个公约，当你的代码完成后，对其他的开发者来说会更容易看懂和维护。 + +注意，这些操作包含所用平台的 I/O 屏障代码，驱动无须显式地调用他们。 + + +标识 GPIO +--------- +GPIO 是通过无符号整型来标识的,范围是 0 到 MAX_INT。保留“负”数 +用于其他目的,例如标识信号“在这个板子上不可用”或指示错误。未接触底层 +硬件的代码会忽略这些整数。 + +平台会定义这些整数的用法,且通常使用 #define 来定义 GPIO，这样 +板级特定的启动代码可以直接关联相应的原理图。相对来说，驱动应该仅使用 +启动代码传递过来的 GPIO 编号，使用 platform_data 保存板级特定 +引脚配置数据 (同时还有其他须要的板级特定数据)，避免可能出现的问题。 + +例如一个平台使用编号 32-159 来标识 GPIO,而在另一个平台使用编号0-63 +标识一组 GPIO 控制器,64-79标识另一类 GPIO 控制器,且在一个含有 +FPGA 的特定板子上使用 80-95。编号不一定要连续,那些平台中，也可以 +使用编号2000-2063来标识一个 I2C 接口的 GPIO 扩展器中的 GPIO。 + +如果你要初始化一个带有无效 GPIO 编号的结构体,可以使用一些负编码 +(如"-EINVAL")，那将使其永远不会是有效。来测试这样一个结构体中的编号 +是否关联一个 GPIO，你可使用以下断言: + + int gpio_is_valid(int number); + +如果编号不存在，则请求和释放 GPIO 的函数将拒绝执行相关操作(见下文)。 +其他编号也可能被拒绝,比如一个编号可能存在，但暂时在给定的电路上不可用。 + +一个平台是否支持多个 GPIO 控制器为平台特定的实现问题，就像是否可以 +在 GPIO 编号空间中有“空洞”和是否可以在运行时添加新的控制器一样。 +这些问题会影响其他事情，包括相邻的 GPIO 编号是否存在等。 + +使用 GPIO +--------- +对于一个 GPIO，系统应该做的第一件事情就是通过 gpio_request() +函数分配它，见下文。 + +接下来是设置I/O方向，这通常是在板级启动代码中为所使用的 GPIO 设置 +platform_device 时完成。 + + /* 设置为输入或输出, 返回 0 或负的错误代码 */ + int gpio_direction_input(unsigned gpio); + int gpio_direction_output(unsigned gpio, int value); + +返回值为零代表成功，否则返回一个负的错误代码。这个返回值需要检查，因为 +get/set(获取/设置)函数调用没法返回错误,且有可能是配置错误。通常， +你应该在进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO，在板子 +启动的早期、进程启动前使用他们也是可以的。 + +对于作为输出的 GPIO，为其提供初始输出值，对于避免在系统启动期间出现 +信号毛刺是很有帮助的。 + +为了与传统的 GPIO 接口兼容, 在设置一个 GPIO 方向时，如果它还未被申请， +则隐含了申请那个 GPIO 的操作(见下文)。这种兼容性正在从可选的 gpiolib +框架中移除。 + +如果这个 GPIO 编码不存在，或者特定的 GPIO 不能用于那种模式，则方向 +设置可能失败。依赖启动固件来正确地设置方向通常是一个坏主意，因为它可能 +除了启动Linux，并没有做更多的验证工作。(同理, 板子的启动代码可能需要 +将这个复用的引脚设置为 GPIO，并正确地配置上拉/下拉电阻。) + + +访问自旋锁安全的 GPIO +------------------- +大多数 GPIO 控制器可以通过内存读/写指令来访问。这些指令不会休眠,可以 +安全地在硬(非线程)中断例程和类似的上下文中完成。 + +对于那些用 gpio_cansleep()测试总是返回失败的 GPIO(见下文)，使用 +以下的函数访问: + + /* GPIO 输入:返回零或非零 */ + int gpio_get_value(unsigned gpio); + + /* GPIO 输出 */ + void gpio_set_value(unsigned gpio, int value); + +GPIO值是布尔值，零表示低电平，非零表示高电平。当读取一个输出引脚的值时， +返回值应该是引脚上的值。这个值不总是和输出值相符，因为存在开漏输出信号和 +输出延迟问题。 + +以上的 get/set 函数无错误返回值，因为之前 gpio_direction_*()应已检查过 +其是否为“无效GPIO”。此外，还需要注意的是并不是所有平台都可以从输出引脚 +中读取数据，对于不能读取的引脚应总返回零。另外，对那些在原子上下文中无法 +安全访问的 GPIO (译者注：因为访问可能导致休眠)使用这些函数是不合适的 +(见下文)。 + +在 GPIO 编号(还有输出、值)为常数的情况下,鼓励通过平台特定的实现来优化 +这两个函数来访问 GPIO 值。这种情况(读写一个硬件寄存器)下只需要几条指令 +是很正常的,且无须自旋锁。这种优化函数比起那些在子程序上花费许多指令的 +函数可以使得模拟接口(译者注:例如 GPIO 模拟 I2C、1-wire 或 SPI)的 +应用(在空间和时间上都)更具效率。 + + +访问可能休眠的 GPIO +----------------- +某些 GPIO 控制器必须通过基于总线(如 I2C 或 SPI)的消息访问。读或写这些 +GPIO 值的命令需要等待其信息排到队首才发送命令，再获得其反馈。期间需要 +休眠，这不能在 IRQ 例程(中断上下文)中执行。 + +支持此类 GPIO 的平台通过以下函数返回非零值来区分出这种 GPIO。(此函数需要 +一个之前通过 gpio_request 分配到的有效 GPIO 编号): + + int gpio_cansleep(unsigned gpio); + +为了访问这种 GPIO,内核定义了一套不同的函数: + + /* GPIO 输入:返回零或非零 ,可能会休眠 */ + int gpio_get_value_cansleep(unsigned gpio); + + /* GPIO 输出,可能会休眠 */ + void gpio_set_value_cansleep(unsigned gpio, int value); + + +访问这样的 GPIO 需要一个允许休眠的上下文，例如线程 IRQ 处理例程，并用以上的 +访问函数替换那些没有 cansleep()后缀的自旋锁安全访问函数。 + +除了这些访问函数可能休眠，且它们操作的 GPIO 不能在硬件 IRQ 处理例程中访问的 +事实，这些处理例程实际上和自旋锁安全的函数是一样的。 + +** 除此之外 ** 调用设置和配置此类 GPIO 的函数也必须在允许休眠的上下文中， +因为它们可能也需要访问 GPIO 控制器芯片: (这些设置函数通常在板级启动代码或者 +驱动探测/断开代码中，所以这是一个容易满足的约束条件。) + + gpio_direction_input() + gpio_direction_output() + gpio_request() + +## gpio_request_one() +## gpio_request_array() +## gpio_free_array() + + gpio_free() + gpio_set_debounce() + + + +声明和释放 GPIO +---------------------------- +为了有助于捕获系统配置错误,定义了两个函数。 + + /* 申请 GPIO, 返回 0 或负的错误代码. + * 非空标签可能有助于诊断. + */ + int gpio_request(unsigned gpio, const char *label); + + /* 释放之前声明的 GPIO */ + void gpio_free(unsigned gpio); + +将无效的 GPIO 编码传递给 gpio_request()会导致失败，申请一个已使用这个 +函数声明过的 GPIO 也会失败。gpio_request()的返回值必须检查。你应该在 +进程上下文中调用这些函数。然而,对于自旋锁安全的 GPIO,在板子启动的早期、 +进入进程之前是可以申请的。 + +这个函数完成两个基本的目标。一是标识那些实际上已作为 GPIO 使用的信号线， +这样便于更好地诊断;系统可能需要服务几百个可用的 GPIO，但是对于任何一个 +给定的电路板通常只有一些被使用。另一个目的是捕获冲突，查明错误:如两个或 +更多驱动错误地认为他们已经独占了某个信号线,或是错误地认为移除一个管理着 +某个已激活信号的驱动是安全的。也就是说，申请 GPIO 的作用类似一种锁机制。 + +某些平台可能也使用 GPIO 作为电源管理激活信号(例如通过关闭未使用芯片区和 +简单地关闭未使用时钟)。 + +对于 GPIO 使用 pinctrl 子系统已知的引脚，子系统应该被告知其使用情况； +一个 gpiolib 驱动的 .request()操作应调用 pinctrl_request_gpio()， +而 gpiolib 驱动的 .free()操作应调用 pinctrl_free_gpio()。pinctrl +子系统允许 pinctrl_request_gpio()在某个引脚或引脚组以复用形式“属于” +一个设备时都成功返回。 + +任何须将 GPIO 信号导向适当引脚的引脚复用硬件的编程应该发生在 GPIO +驱动的 .direction_input()或 .direction_output()函数中，以及 +任何输出 GPIO 值的设置之后。这样可使从引脚特殊功能到 GPIO 的转换 +不会在引脚产生毛刺波形。有时当用一个 GPIO 实现其信号驱动一个非 GPIO +硬件模块的解决方案时，就需要这种机制。 + +某些平台允许部分或所有 GPIO 信号使用不同的引脚。类似的，GPIO 或引脚的 +其他方面也需要配置，如上拉/下拉。平台软件应该在对这些 GPIO 调用 +gpio_request()前将这类细节配置好，例如使用 pinctrl 子系统的映射表， +使得 GPIO 的用户无须关注这些细节。 + +还有一个值得注意的是在释放 GPIO 前，你必须停止使用它。 + + +注意:申请一个 GPIO 并没有以任何方式配置它，只不过标识那个 GPIO 处于使用 +状态。必须有另外的代码来处理引脚配置(如控制 GPIO 使用的引脚、上拉/下拉)。 +考虑到大多数情况下声明 GPIO 之后就会立即配置它们,所以定义了以下三个辅助函数: + + /* 申请一个 GPIO 信号, 同时通过特定的'flags'初始化配置, + * 其他和 gpio_request()的参数和返回值相同 + * + */ + int gpio_request_one(unsigned gpio, unsigned long flags, const char *label); + + /* 在单个函数中申请多个 GPIO + */ + int gpio_request_array(struct gpio *array, size_t num); + + /* 在单个函数中释放多个 GPIO + */ + void gpio_free_array(struct gpio *array, size_t num); + +这里 'flags' 当前定义可指定以下属性: + + * GPIOF_DIR_IN - 配置方向为输入 + * GPIOF_DIR_OUT - 配置方向为输出 + + * GPIOF_INIT_LOW - 在作为输出时,初始值为低电平 + * GPIOF_INIT_HIGH - 在作为输出时,初始值为高电平 + * GPIOF_OPEN_DRAIN - gpio引脚为开漏信号 + * GPIOF_OPEN_SOURCE - gpio引脚为源极开路信号 + + * GPIOF_EXPORT_DIR_FIXED - 将 gpio 导出到 sysfs，并保持方向 + * GPIOF_EXPORT_DIR_CHANGEABLE - 同样是导出, 但允许改变方向 + +因为 GPIOF_INIT_* 仅有在配置为输出的时候才存在,所以有效的组合为: + + * GPIOF_IN - 配置为输入 + * GPIOF_OUT_INIT_LOW - 配置为输出,并初始化为低电平 + * GPIOF_OUT_INIT_HIGH - 配置为输出,并初始化为高电平 + +当设置 flag 为 GPIOF_OPEN_DRAIN 时，则假设引脚是开漏信号。这样的引脚 +将不会在输出模式下置1。这样的引脚需要连接上拉电阻。通过使能这个标志，gpio库 +将会在被要求输出模式下置1时将引脚变为输入状态来使引脚置高。引脚在输出模式下 +通过置0使其输出低电平。 + +当设置 flag 为 GPIOF_OPEN_SOURCE 时，则假设引脚为源极开路信号。这样的引脚 +将不会在输出模式下置0。这样的引脚需要连接下拉电阻。通过使能这个标志，gpio库 +将会在被要求输出模式下置0时将引脚变为输入状态来使引脚置低。引脚在输出模式下 +通过置1使其输出高电平。 + +将来这些标志可能扩展到支持更多的属性。 + +更进一步,为了更简单地声明/释放多个 GPIO,'struct gpio'被引进来封装所有 +这三个领域: + + struct gpio { + unsigned gpio; + unsigned long flags; + const char *label; + }; + +一个典型的用例: + + static struct gpio leds_gpios[] = { + { 32, GPIOF_OUT_INIT_HIGH, "Power LED" }, /* 默认开启 */ + { 33, GPIOF_OUT_INIT_LOW, "Green LED" }, /* 默认关闭 */ + { 34, GPIOF_OUT_INIT_LOW, "Red LED" }, /* 默认关闭 */ + { 35, GPIOF_OUT_INIT_LOW, "Blue LED" }, /* 默认关闭 */ + { ... }, + }; + + err = gpio_request_one(31, GPIOF_IN, "Reset Button"); + if (err) + ... + + err = gpio_request_array(leds_gpios, ARRAY_SIZE(leds_gpios)); + if (err) + ... + + gpio_free_array(leds_gpios, ARRAY_SIZE(leds_gpios)); + + +GPIO 映射到 IRQ +-------------------- +GPIO 编号是无符号整数;IRQ 编号也是。这些构成了两个逻辑上不同的命名空间 +(GPIO 0 不一定使用 IRQ 0)。你可以通过以下函数在它们之间实现映射: + + /* 映射 GPIO 编号到 IRQ 编号 */ + int gpio_to_irq(unsigned gpio); + + /* 映射 IRQ 编号到 GPIO 编号 (尽量避免使用) */ + int irq_to_gpio(unsigned irq); + +它们的返回值为对应命名空间的相关编号，或是负的错误代码(如果无法映射)。 +(例如,某些 GPIO 无法做为 IRQ 使用。)以下的编号错误是未经检测的:使用一个 +未通过 gpio_direction_input()配置为输入的 GPIO 编号，或者使用一个 +并非来源于gpio_to_irq()的 IRQ 编号。 + +这两个映射函数可能会在信号编号的加减计算过程上花些时间。它们不可休眠。 + +gpio_to_irq()返回的非错误值可以传递给 request_irq()或者 free_irq()。 +它们通常通过板级特定的初始化代码存放到平台设备的 IRQ 资源中。注意:IRQ +触发选项是 IRQ 接口的一部分，如 IRQF_TRIGGER_FALLING，系统唤醒能力 +也是如此。 + +irq_to_gpio()返回的非错误值大多数通常可以被 gpio_get_value()所使用， +比如在 IRQ 是沿触发时初始化或更新驱动状态。注意某些平台不支持反映射,所以 +你应该尽量避免使用它。 + + +模拟开漏信号 +---------------------------- +有时在只有低电平信号作为实际驱动结果(译者注:多个输出连接于一点，逻辑电平 +结果为所有输出的逻辑与)的时候,共享的信号线需要使用“开漏”信号。(该术语 +适用于 CMOS 管；而 TTL 用“集电极开路”。)一个上拉电阻使信号为高电平。这 +有时被称为“线与”。实际上，从负逻辑(低电平为真)的角度来看，这是一个“线或”。 + +一个开漏信号的常见例子是共享的低电平使能 IRQ 信号线。此外,有时双向数据总线 +信号也使用漏极开路信号。 + +某些 GPIO 控制器直接支持开漏输出，还有许多不支持。当你需要开漏信号，但 +硬件又不直接支持的时候，一个常用的方法是用任何即可作输入也可作输出的 GPIO +引脚来模拟: + + LOW: gpio_direction_output(gpio, 0) ... 这代码驱动信号并覆盖 + 上拉配置。 + + HIGH: gpio_direction_input(gpio) ... 这代码关闭输出,所以上拉电阻 + (或其他的一些器件)控制了信号。 + +如果你将信号线“驱动”为高电平，但是 gpio_get_value(gpio)报告了一个 +低电平(在适当的上升时间后)，你就可以知道是其他的一些组件将共享信号线拉低了。 +这不一定是错误的。一个常见的例子就是 I2C 时钟的延长：一个需要较慢时钟的 +从设备延迟 SCK 的上升沿，而 I2C 主设备相应地调整其信号传输速率。 + + +这些公约忽略了什么? +================ +这些公约忽略的最大一件事就是引脚复用，因为这属于高度芯片特定的属性且 +没有可移植性。某个平台可能不需要明确的复用信息；有的对于任意给定的引脚 +可能只有两个功能选项；有的可能每个引脚有八个功能选项；有的可能可以将 +几个引脚中的任何一个作为给定的 GPIO。(是的，这些例子都来自于当前运行 +Linux 的系统。) + +在某些系统中,与引脚复用相关的是配置和使能集成的上、下拉模式。并不是所有 +平台都支持这种模式,或者不会以相同的方式来支持这种模式；且任何给定的电路板 +可能使用外置的上拉(或下拉)电阻,这时芯片上的就不应该使用。(当一个电路需要 +5kOhm 的拉动电阻,芯片上的 100 kOhm 电阻就不能做到。)同样的，驱动能力 +(2 mA vs 20 mA)和电压(1.8V vs 3.3V)是平台特定问题,就像模型一样在 +可配置引脚和 GPIO 之间(没)有一一对应的关系。 + +还有其他一些系统特定的机制没有在这里指出，例如上述的输入去毛刺和线与输出 +选项。硬件可能支持批量读或写 GPIO，但是那一般是配置相关的：对于处于同一 +块区(bank)的GPIO。(GPIO 通常以 16 或 32 个组成一个区块，一个给定的 +片上系统一般有几个这样的区块。)某些系统可以通过输出 GPIO 触发 IRQ， +或者从并非以 GPIO 管理的引脚取值。这些机制的相关代码没有必要具有可移植性。 + +当前，动态定义 GPIO 并不是标准的，例如作为配置一个带有某些 GPIO 扩展器的 +附加电路板的副作用。 + +GPIO 实现者的框架 (可选) +===================== +前面提到了，有一个可选的实现框架，让平台使用相同的编程接口，更加简单地支持 +不同种类的 GPIO 控制器。这个框架称为"gpiolib"。 + +作为一个辅助调试功能，如果 debugfs 可用，就会有一个 /sys/kernel/debug/gpio +文件。通过这个框架，它可以列出所有注册的控制器,以及当前正在使用中的 GPIO +的状态。 + + +控制器驱动: gpio_chip +------------------- +在框架中每个 GPIO 控制器都包装为一个 "struct gpio_chip"，他包含了 +该类型的每个控制器的常用信息: + + - 设置 GPIO 方向的方法 + - 用于访问 GPIO 值的方法 + - 告知调用其方法是否可能休眠的标志 + - 可选的 debugfs 信息导出方法 (显示类似上拉配置一样的额外状态) + - 诊断标签 + +也包含了来自 device.platform_data 的每个实例的数据：它第一个 GPIO 的 +编号和它可用的 GPIO 的数量。 + +实现 gpio_chip 的代码应支持多控制器实例，这可能使用驱动模型。那些代码要 +配置每个 gpio_chip，并发起gpiochip_add()。卸载一个 GPIO 控制器很少见， +但在必要的时候可以使用 gpiochip_remove()。 + +大部分 gpio_chip 是一个实例特定结构体的一部分，而并不将 GPIO 接口单独 +暴露出来,比如编址、电源管理等。类似编解码器这样的芯片会有复杂的非 GPIO +状态。 + +任何一个 debugfs 信息导出方法通常应该忽略还未申请作为 GPIO 的信号线。 +他们可以使用 gpiochip_is_requested()测试，当这个 GPIO 已经申请过了 +就返回相关的标签，否则返回 NULL。 + + +平台支持 +------- +为了支持这个框架，一个平台的 Kconfig 文件将会 "select"(选择) +ARCH_REQUIRE_GPIOLIB 或 ARCH_WANT_OPTIONAL_GPIOLIB，并让它的 +<asm/gpio.h> 包含 <asm-generic/gpio.h>，同时定义三个方法: +gpio_get_value()、gpio_set_value()和 gpio_cansleep()。 + +它也应提供一个 ARCH_NR_GPIOS 的定义值，这样可以更好地反映该平台 GPIO +的实际数量,节省静态表的空间。(这个定义值应该包含片上系统内建 GPIO 和 +GPIO 扩展器中的数据。) + +ARCH_REQUIRE_GPIOLIB 意味着 gpiolib 核心在这个构架中将总是编译进内核。 + +ARCH_WANT_OPTIONAL_GPIOLIB 意味着 gpiolib 核心默认关闭,且用户可以 +使能它,并将其编译进内核(可选)。 + +如果这些选项都没被选择,该平台就不通过 GPIO-lib 支持 GPIO,且代码不可以 +被用户使能。 + +以下这些方法的实现可以直接使用框架代码,并总是通过 gpio_chip 调度: + + #define gpio_get_value __gpio_get_value + #define gpio_set_value __gpio_set_value + #define gpio_cansleep __gpio_cansleep + +这些定义可以用更理想的实现方法替代，那就是使用经过逻辑优化的内联函数来访问 +基于特定片上系统的 GPIO。例如,若引用的 GPIO (寄存器位偏移)是常量“12”， +读取或设置它可能只需少则两或三个指令，且不会休眠。当这样的优化无法实现时， +那些函数必须使用框架提供的代码，那就至少要几十条指令才可以实现。对于用 GPIO +模拟的 I/O 接口, 如此精简指令是很有意义的。 + +对于片上系统，平台特定代码为片上 GPIO 每个区(bank)定义并注册 gpio_chip +实例。那些 GPIO 应该根据芯片厂商的文档进行编码/标签,并直接和电路板原理图 +对应。他们应该开始于零并终止于平台特定的限制。这些 GPIO(代码)通常从 +arch_initcall()或者更早的地方集成进平台初始化代码，使这些 GPIO 总是可用， +且他们通常可以作为 IRQ 使用。 + +板级支持 +------- +对于外部 GPIO 控制器(例如 I2C 或 SPI 扩展器、专用芯片、多功能器件、FPGA +或 CPLD)，大多数常用板级特定代码都可以注册控制器设备，并保证他们的驱动知道 +gpiochip_add()所使用的 GPIO 编号。他们的起始编号通常跟在平台特定的 GPIO +编号之后。 + +例如板级启动代码应该创建结构体指明芯片公开的 GPIO 范围，并使用 platform_data +将其传递给每个 GPIO 扩展器芯片。然后芯片驱动中的 probe()例程可以将这个 +数据传递给 gpiochip_add()。 + +初始化顺序很重要。例如，如果一个设备依赖基于 I2C 的(扩展)GPIO，那么它的 +probe()例程就应该在那个 GPIO 有效以后才可以被调用。这意味着设备应该在 +GPIO 可以工作之后才可被注册。解决这类依赖的的一种方法是让这种 gpio_chip +控制器向板级特定代码提供 setup()和 teardown()回调函数。一旦所有必须的 +资源可用之后，这些板级特定的回调函数将会注册设备，并可以在这些 GPIO 控制器 +设备变成无效时移除它们。 + + +用户空间的 Sysfs 接口(可选) +======================== +使用“gpiolib”实现框架的平台可以选择配置一个 GPIO 的 sysfs 用户接口。 +这不同于 debugfs 接口，因为它提供的是对 GPIO方向和值的控制，而不只显示 +一个GPIO 的状态摘要。此外,它可以出现在没有调试支持的产品级系统中。 + +例如，通过适当的系统硬件文档，用户空间可以知道 GIOP #23 控制 Flash +存储器的写保护(用于保护其中 Bootloader 分区)。产品的系统升级可能需要 +临时解除这个保护：首先导入一个 GPIO，改变其输出状态，然后在重新使能写保护 +前升级代码。通常情况下,GPIO #23 是不会被触及的，并且内核也不需要知道他。 + +根据适当的硬件文档，某些系统的用户空间 GPIO 可以用于确定系统配置数据， +这些数据是标准内核不知道的。在某些任务中，简单的用户空间 GPIO 驱动可能是 +系统真正需要的。 + +注意：标准内核驱动中已经存在通用的“LED 和按键”GPIO 任务，分别是: +"leds-gpio" 和 "gpio_keys"。请使用这些来替代直接访问 GPIO，因为集成在 +内核框架中的这类驱动比你在用户空间的代码更好。 + + +Sysfs 中的路径 +-------------- +在/sys/class/gpio 中有 3 类入口: + + - 用于在用户空间控制 GPIO 的控制接口; + + - GPIOs 本身;以及 + + - GPIO 控制器 ("gpio_chip" 实例)。 + +除了这些标准的文件,还包含“device”符号链接。 + +控制接口是只写的: + + /sys/class/gpio/ + + "export" ... 用户空间可以通过写其编号到这个文件，要求内核导出 + 一个 GPIO 的控制到用户空间。 + + 例如: 如果内核代码没有申请 GPIO #19,"echo 19 > export" + 将会为 GPIO #19 创建一个 "gpio19" 节点。 + + "unexport" ... 导出到用户空间的逆操作。 + + 例如: "echo 19 > unexport" 将会移除使用"export"文件导出的 + "gpio19" 节点。 + +GPIO 信号的路径类似 /sys/class/gpio/gpio42/ (对于 GPIO #42 来说)， +并有如下的读/写属性: + + /sys/class/gpio/gpioN/ + + "direction" ... 读取得到 "in" 或 "out"。这个值通常运行写入。 + 写入"out" 时,其引脚的默认输出为低电平。为了确保无故障运行， + "low" 或 "high" 的电平值应该写入 GPIO 的配置，作为初始输出值。 + + 注意:如果内核不支持改变 GPIO 的方向，或者在导出时内核代码没有 + 明确允许用户空间可以重新配置 GPIO 方向，那么这个属性将不存在。 + + "value" ... 读取得到 0 (低电平) 或 1 (高电平)。如果 GPIO 配置为 + 输出,这个值允许写操作。任何非零值都以高电平看待。 + + 如果引脚可以配置为中断信号，且如果已经配置了产生中断的模式 + （见"edge"的描述），你可以对这个文件使用轮询操作(poll(2))， + 且轮询操作会在任何中断触发时返回。如果你使用轮询操作(poll(2))， + 请在 events 中设置 POLLPRI 和 POLLERR。如果你使用轮询操作 + (select(2))，请在 exceptfds 设置你期望的文件描述符。在 + 轮询操作(poll(2))返回之后，既可以通过 lseek(2)操作读取 + sysfs 文件的开始部分，也可以关闭这个文件并重新打开它来读取数据。 + + "edge" ... 读取得到“none”、“rising”、“falling”或者“both”。 + 将这些字符串写入这个文件可以选择沿触发模式，会使得轮询操作 + (select(2))在"value"文件中返回。 + + 这个文件仅有在这个引脚可以配置为可产生中断输入引脚时，才存在。 + + "active_low" ... 读取得到 0 (假) 或 1 (真)。写入任何非零值可以 + 翻转这个属性的(读写)值。已存在或之后通过"edge"属性设置了"rising" + 和 "falling" 沿触发模式的轮询操作(poll(2))将会遵循这个设置。 + +GPIO 控制器的路径类似 /sys/class/gpio/gpiochip42/ (对于从#42 GPIO +开始实现控制的控制器),并有着以下只读属性: + + /sys/class/gpio/gpiochipN/ + + "base" ... 与以上的 N 相同,代表此芯片管理的第一个 GPIO 的编号 + + "label" ... 用于诊断 (并不总是只有唯一值) + + "ngpio" ... 此控制器所管理的 GPIO 数量(而 GPIO 编号从 N 到 + N + ngpio - 1) + +大多数情况下,电路板的文档应当标明每个 GPIO 的使用目的。但是那些编号并不总是 +固定的,例如在扩展卡上的 GPIO会根据所使用的主板或所在堆叠架构中其他的板子而 +有所不同。在这种情况下,你可能需要使用 gpiochip 节点(尽可能地结合电路图)来 +确定给定信号所用的 GPIO 编号。 + + +从内核代码中导出 +------------- +内核代码可以明确地管理那些已通过 gpio_request()申请的 GPIO 的导出: + + /* 导出 GPIO 到用户空间 */ + int gpio_export(unsigned gpio, bool direction_may_change); + + /* gpio_export()的逆操作 */ + void gpio_unexport(); + + /* 创建一个 sysfs 连接到已导出的 GPIO 节点 */ + int gpio_export_link(struct device *dev, const char *name, + unsigned gpio) + + /* 改变 sysfs 中的一个 GPIO 节点的极性 */ + int gpio_sysfs_set_active_low(unsigned gpio, int value); + +在一个内核驱动申请一个 GPIO 之后，它可以通过 gpio_export()使其在 sysfs +接口中可见。该驱动可以控制信号方向是否可修改。这有助于防止用户空间代码无意间 +破坏重要的系统状态。 + +这个明确的导出有助于(通过使某些实验更容易来)调试，也可以提供一个始终存在的接口， +与文档配合作为板级支持包的一部分。 + +在 GPIO 被导出之后，gpio_export_link()允许在 sysfs 文件系统的任何地方 +创建一个到这个 GPIO sysfs 节点的符号链接。这样驱动就可以通过一个描述性的 +名字，在 sysfs 中他们所拥有的设备下提供一个(到这个 GPIO sysfs 节点的)接口。 + +驱动可以使用 gpio_sysfs_set_active_low() 来在用户空间隐藏电路板之间 +GPIO 线的极性差异。这个仅对 sysfs 接口起作用。极性的改变可以在 gpio_export() +前后进行,且之前使能的轮询操作(poll(2))支持(上升或下降沿)将会被重新配置来遵循 +这个设置。 diff --git a/Documentation/zh_CN/video4linux/omap3isp.txt b/Documentation/zh_CN/video4linux/omap3isp.txt new file mode 100644 index 000000000000..67ffbf352ae0 --- /dev/null +++ b/Documentation/zh_CN/video4linux/omap3isp.txt @@ -0,0 +1,277 @@ +Chinese translated version of Documentation/video4linux/omap3isp.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/video4linux/omap3isp.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +OMAP 3 图像信号处理器 (ISP) 驱动 + +Copyright (C) 2010 Nokia Corporation +Copyright (C) 2009 Texas Instruments, Inc. + +联系人: Laurent Pinchart <laurent.pinchart@ideasonboard.com> + Sakari Ailus <sakari.ailus@iki.fi> + David Cohen <dacohen@gmail.com> + + +介绍 +=== + +本文档介绍了由 drivers/media/video/omap3isp 加载的德州仪器 +（TI）OMAP 3 图像信号处理器 (ISP) 驱动。原始驱动由德州仪器（TI） +编写，但此后由诺基亚重写了两次。 + +驱动已在以下 OMAP 3 系列的芯片中成功使用： + + 3430 + 3530 + 3630 + +驱动实现了 V4L2、媒体控制器和 v4l2_subdev 接口。支持内核中使用 +v4l2_subdev 接口的传感器、镜头和闪光灯驱动。 + + +拆分为子设备 +========== + +OMAP 3 ISP 被拆分为 V4L2 子设备，ISP中的每个模块都由一个子设备 +来表示。每个子设备向用户空间提供一个 V4L2 子设备接口。 + + OMAP3 ISP CCP2 + OMAP3 ISP CSI2a + OMAP3 ISP CCDC + OMAP3 ISP preview + OMAP3 ISP resizer + OMAP3 ISP AEWB + OMAP3 ISP AF + OMAP3 ISP histogram + +ISP 中每个可能的连接都通过一个链接嵌入到媒体控制器接口中。详见例程 [2]。 + + +控制 OMAP 3 ISP +============== + +通常，对 OMAP 3 ISP 的配置会在下一帧起始时生效。在传感器垂直消隐期间， +模块变为空闲时完成配置。在内存到内存的操作中，视频管道一次处理一帧。 +应用配置应在帧间完成。 + +ISP 中的所有模块，除 CSI-2 和 （可能存在的）CCP2 接收器外，都必须 +接收完整的帧数据。因此，传感器必须保证从不发送部分帧数据给ISP。 + +Autoidle（自动空闲）功能至少在 3430 的 ISP 模块中确实存在一些问题。 +当 omap3isp 模块参数 autoidle 非零时，autoidle（自动空闲）功能 +仅在 3630 中启用了。 + + +事件机制 +====== + +OMAP 3 ISP 驱动在 CCDC 和统计（AEWB、AF 和 直方图）子设备中支持 +V4L2 事件机制接口。 + +CCDC 子设备通过 HS_VS 中断，处理 V4L2_EVENT_FRAME_SYNC 类型 +事件，用于告知帧起始。早期版本的驱动则使用 V4L2_EVENT_OMAP3ISP_HS_VS。 +当在 CCDC 模块中接收到起始帧的第一行时，会准确地触发事件。这个事件 +可以在 CCDC 子设备中“订阅”。 + +（当使用并行接口时，必须注意正确地配置 VS 信号极性。而当使用串行接收时 +这个会自动校正。） + +每个统计子设备都可以产生事件。每当一个统计缓冲区可由用户空间应用程序 +通过 VIDIOC_OMAP3ISP_STAT_REQ IOCTL 操作获取时，就会产生一个 +事件。当前存在以下事件： + + V4L2_EVENT_OMAP3ISP_AEWB + V4L2_EVENT_OMAP3ISP_AF + V4L2_EVENT_OMAP3ISP_HIST + +这些 ioctl 的事件数据类型为 struct omap3isp_stat_event_status +结构体。如果出现计算错误的统计，也同样会产生一个事件，但没有相关的统计 +数据缓冲区。这种情况下 omap3isp_stat_event_status.buf_err 会被 +设置为非零值。 + + +私有 IOCTL +========== + +OMAP 3 ISP 驱动支持标准的 V4L2 IOCTL 以及可能存在且实用的控制。但 +ISP 提供的许多功能都不在标准 IOCTL 之列，例如 gamma（伽马）表和统计 +数据采集配置等。 + +通常，会有一个私有 ioctl 用于配置每个包含硬件依赖功能的模块。 + +支持以下私有 IOCTL： + + VIDIOC_OMAP3ISP_CCDC_CFG + VIDIOC_OMAP3ISP_PRV_CFG + VIDIOC_OMAP3ISP_AEWB_CFG + VIDIOC_OMAP3ISP_HIST_CFG + VIDIOC_OMAP3ISP_AF_CFG + VIDIOC_OMAP3ISP_STAT_REQ + VIDIOC_OMAP3ISP_STAT_EN + +在 include/linux/omap3isp.h 中描述了这些 ioctl 使用的参数结构体。 +与特定 ISP 模块相关的 ISP 自身的详细功能在技术参考手册 (TRMs)中有 +描述，详见文档结尾。 + +虽然在不使用任何私有 IOCTL 的情况下使用 ISP 驱动是可能的，但这样无法 +获得最佳的图像质量。AEWB、AF 和 直方图（译者注：一般用于自动曝光和增益 +控制，以及图像均衡等）模块无法在未使用适当的私有 IOCTL 配置的情况下使用。 + + +CCDC 和 preview（预览）模块 IOCTL +=============================== + +VIDIOC_OMAP3ISP_CCDC_CFG 和 VIDIOC_OMAP3ISP_PRV_CFG IOCTL +被分别用于配置、启用和禁用 CCDC 和 preview（预览）模块的功能。在它们 +所控制的模块中，两个 IOCTL 控制多种功能。VIDIOC_OMAP3ISP_CCDC_CFG IOCTL +接受一个指向 omap3isp_ccdc_update_config 结构体的指针作为它的参数。 +同样的，VIDIOC_OMAP3ISP_PRV_CFG 接受一个指向 omap3isp_prev_update_config +结构体的指针。以上两个结构体定义位于 [1]。 + +这些结构体中的 update 域标识是否针对指定的功能更新配置，而 flag 域 +则标识是启用还是禁用此功能。 + +update 和 flag 位接受以下掩码值。CCDC 和 preview（预览）模块的 +每个单独功能都与一个 flag 关联（禁用或启用；在结构体中 flag 域的 +一部分）和一个指向功能配置数据的指针。 + +对于 VIDIOC_OMAP3ISP_CCDC_CFG，下面列出了 update 和 flag 域 +中的有效值。 这些值可能会在同一个 IOCTL 调用中配置多个功能。 + + OMAP3ISP_CCDC_ALAW + OMAP3ISP_CCDC_LPF + OMAP3ISP_CCDC_BLCLAMP + OMAP3ISP_CCDC_BCOMP + OMAP3ISP_CCDC_FPC + OMAP3ISP_CCDC_CULL + OMAP3ISP_CCDC_CONFIG_LSC + OMAP3ISP_CCDC_TBL_LSC + +针对 VIDIOC_OMAP3ISP_PRV_CFG 的相应值如下： + + OMAP3ISP_PREV_LUMAENH + OMAP3ISP_PREV_INVALAW + OMAP3ISP_PREV_HRZ_MED + OMAP3ISP_PREV_CFA + OMAP3ISP_PREV_CHROMA_SUPP + OMAP3ISP_PREV_WB + OMAP3ISP_PREV_BLKADJ + OMAP3ISP_PREV_RGB2RGB + OMAP3ISP_PREV_COLOR_CONV + OMAP3ISP_PREV_YC_LIMIT + OMAP3ISP_PREV_DEFECT_COR + OMAP3ISP_PREV_GAMMABYPASS + OMAP3ISP_PREV_DRK_FRM_CAPTURE + OMAP3ISP_PREV_DRK_FRM_SUBTRACT + OMAP3ISP_PREV_LENS_SHADING + OMAP3ISP_PREV_NF + OMAP3ISP_PREV_GAMMA + +在启用某个功能的时候，相关的配置数据指针不可为 NULL。在禁用某个功能时， +配置数据指针会被忽略。 + + +统计模块 IOCTL +============= + +统计子设备相较于其他子设备提供了更多动态配置选项。在图像处理流水线处于 +工作状态时，它们可以被启用、禁用和重配。 + +统计模块总是从 CCDC 中获取输入的图像数据（由于直方图内存读取未实现）。 +统计数据可由用户通过统计子设备节点使用私有 IOCTL 获取。 + +AEWB、AF 和 直方图子设备提供的私有 IOCTL 极大程度上反应了 ISP 硬件 +提供的寄存器级接口。有些方面纯粹和驱动程序的实现相关，这些将在下面讨论。 + +VIDIOC_OMAP3ISP_STAT_EN +----------------------- + +这个私有 IOCTL 启用/禁用 一个统计模块。如果这个申请在视频流启动前完成， +它将在视频流水线开始工作时生效。如果视频流水线已经处于工作状态了，它将在 +CCDC 变为空闲时生效。 + +VIDIOC_OMAP3ISP_AEWB_CFG, VIDIOC_OMAP3ISP_HIST_CFG and VIDIOC_OMAP3ISP_AF_CFG +----------------------------------------------------------------------------- + +这些 IOCTL 用于配置模块。它们要求用户应用程序对硬件有深入的认识。对 +大多数域的解释可以在 OMAP 的 TRM 中找到。以下两个域对于以上所有的 +私有 IOCTL 配置都很常见，由于他们没有在 TRM 中提及，故需要对其有 +更好的认识。 + +omap3isp_[h3a_af/h3a_aewb/hist]_config.buf_size: + +模块在内部处理自身缓冲。对模块数据输出所必需的缓存大小依赖于已申请的配置。 +虽然驱动支持在视频流工作时重新配置，但对于所需缓存量大于模块启用时内部 +所分配数量的情况，则不支持重新配置。在这种情况下将返回 -EBUSY。为了避免 +此类状况，无论是禁用/重配/启用模块，还是第一次配置时申请必须的缓存大小， +都应在模块禁用的情况下进行。 + +内部缓冲分配的大小需综合考虑所申请配置的最小缓存量以及 buf_size 域中 +所设的值。如果 buf_size 域在[minimum（最小值）, maximum（最大值）] +缓冲大小范围之外，则应该将其调整到其范围中。驱动则会选择最大值。正确的 +buf_size 值将回写到用户应用程序中。 + +omap3isp_[h3a_af/h3a_aewb/hist]_config.config_counter: + +由于配置并未在申请之后同步生效，驱动必须提供一个跟踪这类信息的方法， +以提供更准确的数据。在一个配置被申请之后，返回到用户空间应用程序的 +config_counter 是一个与其配置相关的唯一值。当用户应用程序接收到 +一个缓冲可用或一个新的缓冲申请事件时，这个 config_counter 用于 +一个缓冲数据和一个配置的匹配。 + +VIDIOC_OMAP3ISP_STAT_REQ +------------------------ + +将内部缓冲队列中最早的数据发送到用户空间，然后丢弃此缓冲区。 +omap3isp_stat_data.frame_number 域与视频缓冲的 field_count +域相匹配。 + + +技术参考手册 (TRMs) 和其他文档 +========================== + +OMAP 3430 TRM: +<URL:http://focus.ti.com/pdfs/wtbu/OMAP34xx_ES3.1.x_PUBLIC_TRM_vZM.zip> +参考于 2011-03-05. + +OMAP 35xx TRM: +<URL:http://www.ti.com/litv/pdf/spruf98o> 参考于 2011-03-05. + +OMAP 3630 TRM: +<URL:http://focus.ti.com/pdfs/wtbu/OMAP36xx_ES1.x_PUBLIC_TRM_vQ.zip> +参考于 2011-03-05. + +DM 3730 TRM: +<URL:http://www.ti.com/litv/pdf/sprugn4h> 参考于 2011-03-06. + + +参考资料 +======= + +[1] include/linux/omap3isp.h + +[2] http://git.ideasonboard.org/?p=media-ctl.git;a=summary diff --git a/Documentation/zh_CN/video4linux/v4l2-framework.txt b/Documentation/zh_CN/video4linux/v4l2-framework.txt new file mode 100644 index 000000000000..3e74f13af426 --- /dev/null +++ b/Documentation/zh_CN/video4linux/v4l2-framework.txt @@ -0,0 +1,983 @@ +Chinese translated version of Documentation/video4linux/v4l2-framework.txt + +If you have any comment or update to the content, please contact the +original document maintainer directly. However, if you have a problem +communicating in English you can also ask the Chinese maintainer for +help. Contact the Chinese maintainer if this translation is outdated +or if there is a problem with the translation. + +Maintainer: Mauro Carvalho Chehab <mchehab@infradead.org> +Chinese maintainer: Fu Wei <tekkamanninja@gmail.com> +--------------------------------------------------------------------- +Documentation/video4linux/v4l2-framework.txt 的中文翻译 + +如果想评论或更新本文的内容，请直接联系原文档的维护者。如果你使用英文 +交流有困难的话，也可以向中文版维护者求助。如果本翻译更新不及时或者翻 +译存在问题，请联系中文版维护者。 +英文版维护者： Mauro Carvalho Chehab <mchehab@infradead.org> +中文版维护者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版翻译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> +中文版校译者： 傅炜 Fu Wei <tekkamanninja@gmail.com> + + +以下为正文 +--------------------------------------------------------------------- +V4L2 驱动框架概览 +============== + +本文档描述 V4L2 框架所提供的各种结构和它们之间的关系。 + + +介绍 +---- + +大部分现代 V4L2 设备由多个 IC 组成，在 /dev 下导出多个设备节点， +并同时创建非 V4L2 设备（如 DVB、ALSA、FB、I2C 和红外输入设备）。 +由于这种硬件的复杂性，V4L2 驱动也变得非常复杂。 + +尤其是 V4L2 必须支持 IC 实现音视频的多路复用和编解码，这就更增加了其 +复杂性。通常这些 IC 通过一个或多个 I2C 总线连接到主桥驱动器，但也可 +使用其他总线。这些设备称为“子设备”。 + +长期以来，这个框架仅限于通过 video_device 结构体创建 V4L 设备节点， +并使用 video_buf 处理视频缓冲（注：本文不讨论 video_buf 框架）。 + +这意味着所有驱动必须自己设置设备实例并连接到子设备。其中一部分要正确地 +完成是比较复杂的，使得许多驱动都没有正确地实现。 + +由于框架的缺失，有很多通用代码都不可重复利用。 + +因此，这个框架构建所有驱动都需要的基本结构块，而统一的框架将使通用代码 +创建成实用函数并在所有驱动中共享变得更加容易。 + + +驱动结构 +------- + +所有 V4L2 驱动都有如下结构： + +1) 每个设备实例的结构体--包含其设备状态。 + +2) 初始化和控制子设备的方法（如果有）。 + +3) 创建 V4L2 设备节点 (/dev/videoX、/dev/vbiX 和 /dev/radioX) + 并跟踪设备节点的特定数据。 + +4) 特定文件句柄结构体--包含每个文件句柄的数据。 + +5) 视频缓冲处理。 + +以下是它们的初略关系图： + + device instances（设备实例） + | + +-sub-device instances（子设备实例） + | + \-V4L2 device nodes（V4L2 设备节点） + | + \-filehandle instances（文件句柄实例） + + +框架结构 +------- + +该框架非常类似驱动结构：它有一个 v4l2_device 结构用于保存设备 +实例的数据；一个 v4l2_subdev 结构体代表子设备实例；video_device +结构体保存 V4L2 设备节点的数据；将来 v4l2_fh 结构体将跟踪文件句柄 +实例（暂未尚未实现）。 + +V4L2 框架也可与媒体框架整合（可选的）。如果驱动设置了 v4l2_device +结构体的 mdev 域，子设备和视频节点的入口将自动出现在媒体框架中。 + + +v4l2_device 结构体 +---------------- + +每个设备实例都通过 v4l2_device (v4l2-device.h)结构体来表示。 +简单设备可以仅分配这个结构体，但在大多数情况下，都会将这个结构体 +嵌入到一个更大的结构体中。 + +你必须注册这个设备实例： + + v4l2_device_register(struct device *dev, struct v4l2_device *v4l2_dev); + +注册操作将会初始化 v4l2_device 结构体。如果 dev->driver_data 域 +为 NULL，就将其指向 v4l2_dev。 + +需要与媒体框架整合的驱动必须手动设置 dev->driver_data，指向包含 +v4l2_device 结构体实例的驱动特定设备结构体。这可以在注册 V4L2 设备 +实例前通过 dev_set_drvdata() 函数完成。同时必须设置 v4l2_device +结构体的 mdev 域，指向适当的初始化并注册过的 media_device 实例。 + +如果 v4l2_dev->name 为空，则它将被设置为从 dev 中衍生出的值（为了 +更加精确，形式为驱动名后跟 bus_id）。如果你在调用 v4l2_device_register +前已经设置好了，则不会被修改。如果 dev 为 NULL，则你*必须*在调用 +v4l2_device_register 前设置 v4l2_dev->name。 + +你可以基于驱动名和驱动的全局 atomic_t 类型的实例编号，通过 +v4l2_device_set_name() 设置 name。这样会生成类似 ivtv0、ivtv1 等 +名字。若驱动名以数字结尾，则会在编号和驱动名间插入一个破折号，如： +cx18-0、cx18-1 等。此函数返回实例编号。 + +第一个 “dev” 参数通常是一个指向 pci_dev、usb_interface 或 +platform_device 的指针。很少使其为 NULL，除非是一个ISA设备或者 +当一个设备创建了多个 PCI 设备，使得 v4l2_dev 无法与一个特定的父设备 +关联。 + +你也可以提供一个 notify() 回调，使子设备可以调用它实现事件通知。 +但这个设置与子设备相关。子设备支持的任何通知必须在 +include/media/<subdevice>.h 中定义一个消息头。 + +注销 v4l2_device 使用如下函数： + + v4l2_device_unregister(struct v4l2_device *v4l2_dev); + +如果 dev->driver_data 域指向 v4l2_dev，将会被重置为 NULL。注销同时 +会自动从设备中注销所有子设备。 + +如果你有一个热插拔设备（如USB设备），则当断开发生时，父设备将无效。 +由于 v4l2_device 有一个指向父设备的指针必须被清除，同时标志父设备 +已消失，所以必须调用以下函数： + + v4l2_device_disconnect(struct v4l2_device *v4l2_dev); + +这个函数并*不*注销子设备，因此你依然要调用 v4l2_device_unregister() +函数。如果你的驱动器并非热插拔的，就没有必要调用 v4l2_device_disconnect()。 + +有时你需要遍历所有被特定驱动注册的设备。这通常发生在多个设备驱动使用 +同一个硬件的情况下。如：ivtvfb 驱动是一个使用 ivtv 硬件的帧缓冲驱动， +同时 alsa 驱动也使用此硬件。 + +你可以使用如下例程遍历所有注册的设备： + +static int callback(struct device *dev, void *p) +{ + struct v4l2_device *v4l2_dev = dev_get_drvdata(dev); + + /* 测试这个设备是否已经初始化 */ + if (v4l2_dev == NULL) + return 0; + ... + return 0; +} + +int iterate(void *p) +{ + struct device_driver *drv; + int err; + + /* 在PCI 总线上查找ivtv驱动。 + pci_bus_type是全局的. 对于USB总线使用usb_bus_type。 */ + drv = driver_find("ivtv", &pci_bus_type); + /* 遍历所有的ivtv设备实例 */ + err = driver_for_each_device(drv, NULL, p, callback); + put_driver(drv); + return err; +} + +有时你需要一个设备实例的运行计数。这个通常用于映射一个设备实例到一个 +模块选择数组的索引。 + +推荐方法如下： + +static atomic_t drv_instance = ATOMIC_INIT(0); + +static int __devinit drv_probe(struct pci_dev *pdev, + const struct pci_device_id *pci_id) +{ + ... + state->instance = atomic_inc_return(&drv_instance) - 1; +} + +如果你有多个设备节点，对于热插拔设备，知道何时注销 v4l2_device 结构体 +就比较困难。为此 v4l2_device 有引用计数支持。当调用 video_register_device +时增加引用计数，而设备节点释放时减小引用计数。当引用计数为零，则 +v4l2_device 的release() 回调将被执行。你就可以在此时做最后的清理工作。 + +如果创建了其他设备节点（比如 ALSA），则你可以通过以下函数手动增减 +引用计数： + +void v4l2_device_get(struct v4l2_device *v4l2_dev); + +或: + +int v4l2_device_put(struct v4l2_device *v4l2_dev); + +由于引用技术初始化为 1 ，你也需要在 disconnect() 回调（对于 USB 设备）中 +调用 v4l2_device_put，或者 remove() 回调（例如对于 PCI 设备），否则 +引用计数将永远不会为 0 。 + +v4l2_subdev结构体 +------------------ + +许多驱动需要与子设备通信。这些设备可以完成各种任务，但通常他们负责 +音视频复用和编解码。如网络摄像头的子设备通常是传感器和摄像头控制器。 + +这些一般为 I2C 接口设备，但并不一定都是。为了给驱动提供调用子设备的 +统一接口，v4l2_subdev 结构体（v4l2-subdev.h）产生了。 + +每个子设备驱动都必须有一个 v4l2_subdev 结构体。这个结构体可以单独 +代表一个简单的子设备，也可以嵌入到一个更大的结构体中，与更多设备状态 +信息保存在一起。通常有一个下级设备结构体（比如：i2c_client）包含了 +内核创建的设备数据。建议使用 v4l2_set_subdevdata() 将这个结构体的 +指针保存在 v4l2_subdev 的私有数据域(dev_priv)中。这使得通过 v4l2_subdev +找到实际的低层总线特定设备数据变得容易。 + +你同时需要一个从低层结构体获取 v4l2_subdev 指针的方法。对于常用的 +i2c_client 结构体，i2c_set_clientdata() 函数可用于保存一个 v4l2_subdev +指针；对于其他总线你可能需要使用其他相关函数。 + +桥驱动中也应保存每个子设备的私有数据，比如一个指向特定桥的各设备私有 +数据的指针。为此 v4l2_subdev 结构体提供主机私有数据域(host_priv)， +并可通过 v4l2_get_subdev_hostdata() 和 v4l2_set_subdev_hostdata() +访问。 + +从总线桥驱动的视角，驱动加载子设备模块并以某种方式获得 v4l2_subdev +结构体指针。对于 i2c 总线设备相对简单：调用 i2c_get_clientdata()。 +对于其他总线也需要做类似的操作。针对 I2C 总线上的子设备辅助函数帮你 +完成了大部分复杂的工作。 + +每个 v4l2_subdev 都包含子设备驱动需要实现的函数指针（如果对此设备 +不适用，可为NULL）。由于子设备可完成许多不同的工作，而在一个庞大的 +函数指针结构体中通常仅有少数有用的函数实现其功能肯定不合适。所以， +函数指针根据其实现的功能被分类，每一类都有自己的函数指针结构体。 + +顶层函数指针结构体包含了指向各类函数指针结构体的指针，如果子设备驱动 +不支持该类函数中的任何一个功能，则指向该类结构体的指针为NULL。 + +这些结构体定义如下： + +struct v4l2_subdev_core_ops { + int (*g_chip_ident)(struct v4l2_subdev *sd, struct v4l2_dbg_chip_ident *chip); + int (*log_status)(struct v4l2_subdev *sd); + int (*init)(struct v4l2_subdev *sd, u32 val); + ... +}; + +struct v4l2_subdev_tuner_ops { + ... +}; + +struct v4l2_subdev_audio_ops { + ... +}; + +struct v4l2_subdev_video_ops { + ... +}; + +struct v4l2_subdev_pad_ops { + ... +}; + +struct v4l2_subdev_ops { + const struct v4l2_subdev_core_ops *core; + const struct v4l2_subdev_tuner_ops *tuner; + const struct v4l2_subdev_audio_ops *audio; + const struct v4l2_subdev_video_ops *video; + const struct v4l2_subdev_pad_ops *video; +}; + +其中 core（核心）函数集通常可用于所有子设备，其他类别的实现依赖于 +子设备。如视频设备可能不支持音频操作函数，反之亦然。 + +这样的设置在限制了函数指针数量的同时，还使增加新的操作函数和分类 +变得较为容易。 + +子设备驱动可使用如下函数初始化 v4l2_subdev 结构体： + + v4l2_subdev_init(sd, &ops); + +然后，你必须用一个唯一的名字初始化 subdev->name，并初始化模块的 +owner 域。若使用 i2c 辅助函数，这些都会帮你处理好。 + +若需同媒体框架整合，你必须调用 media_entity_init() 初始化 v4l2_subdev +结构体中的 media_entity 结构体（entity 域）： + + struct media_pad *pads = &my_sd->pads; + int err; + + err = media_entity_init(&sd->entity, npads, pads, 0); + +pads 数组必须预先初始化。无须手动设置 media_entity 的 type 和 +name 域，但如有必要，revision 域必须初始化。 + +当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。 + +在子设备被注销之后，不要忘记清理 media_entity 结构体： + + media_entity_cleanup(&sd->entity); + +如果子设备驱动趋向于处理视频并整合进了媒体框架，必须使用 v4l2_subdev_pad_ops +替代 v4l2_subdev_video_ops 实现格式相关的功能。 + +这种情况下，子设备驱动应该设置 link_validate 域，以提供它自身的链接 +验证函数。链接验证函数应对管道（两端链接的都是 V4L2 子设备）中的每个 +链接调用。驱动还要负责验证子设备和视频节点间格式配置的正确性。 + +如果 link_validate 操作没有设置，默认的 v4l2_subdev_link_validate_default() +函数将会被调用。这个函数保证宽、高和媒体总线像素格式在链接的收发两端 +都一致。子设备驱动除了它们自己的检测外，也可以自由使用这个函数以执行 +上面提到的检查。 + +设备（桥）驱动程序必须向 v4l2_device 注册 v4l2_subdev： + + int err = v4l2_device_register_subdev(v4l2_dev, sd); + +如果子设备模块在它注册前消失，这个操作可能失败。在这个函数成功返回后， +subdev->dev 域就指向了 v4l2_device。 + +如果 v4l2_device 父设备的 mdev 域为非 NULL 值，则子设备实体将被自动 +注册为媒体设备。 + +注销子设备则可用如下函数： + + v4l2_device_unregister_subdev(sd); + +此后，子设备模块就可卸载，且 sd->dev == NULL。 + +注册之设备后，可通过以下方式直接调用其操作函数： + + err = sd->ops->core->g_chip_ident(sd, &chip); + +但使用如下宏会比较容易且合适： + + err = v4l2_subdev_call(sd, core, g_chip_ident, &chip); + +这个宏将会做 NULL 指针检查，如果 subdev 为 NULL，则返回-ENODEV；如果 +subdev->core 或 subdev->core->g_chip_ident 为 NULL，则返回 -ENOIOCTLCMD； +否则将返回 subdev->ops->core->g_chip_ident ops 调用的实际结果。 + +有时也可能同时调用所有或一系列子设备的某个操作函数： + + v4l2_device_call_all(v4l2_dev, 0, core, g_chip_ident, &chip); + +任何不支持此操作的子设备都会被跳过，并忽略错误返回值。但如果你需要 +检查出错码，则可使用如下函数： + + err = v4l2_device_call_until_err(v4l2_dev, 0, core, g_chip_ident, &chip); + +除 -ENOIOCTLCMD 外的任何错误都会跳出循环并返回错误值。如果（除 -ENOIOCTLCMD +外）没有错误发生，则返回 0。 + +对于以上两个函数的第二个参数为组 ID。如果为 0，则所有子设备都会执行 +这个操作。如果为非 0 值，则只有那些组 ID 匹配的子设备才会执行此操作。 +在桥驱动注册一个子设备前，可以设置 sd->grp_id 为任何期望值（默认值为 +0）。这个值属于桥驱动，且子设备驱动将不会修改和使用它。 + +组 ID 赋予了桥驱动更多对于如何调用回调的控制。例如，电路板上有多个 +音频芯片，每个都有改变音量的能力。但当用户想要改变音量的时候，通常 +只有一个会被实际使用。你可以对这样的子设备设置组 ID 为（例如 AUDIO_CONTROLLER） +并在调用 v4l2_device_call_all() 时指定它为组 ID 值。这就保证了只有 +需要的子设备才会执行这个回调。 + +如果子设备需要通知它的 v4l2_device 父设备一个事件，可以调用 +v4l2_subdev_notify(sd, notification, arg)。这个宏检查是否有一个 +notify() 回调被注册，如果没有，返回 -ENODEV。否则返回 notify() 调用 +结果。 + +使用 v4l2_subdev 的好处在于它是一个通用结构体，且不包含任何底层硬件 +信息。所有驱动可以包含多个 I2C 总线的子设备，但也有子设备是通过 GPIO +控制。这个区别仅在配置设备时有关系，一旦子设备注册完成，对于 v4l2 +子系统来说就完全透明了。 + + +V4L2 子设备用户空间API +-------------------- + +除了通过 v4l2_subdev_ops 结构导出的内核 API，V4L2 子设备也可以直接 +通过用户空间应用程序来控制。 + +可以在 /dev 中创建名为 v4l-subdevX 设备节点，以通过其直接访问子设备。 +如果子设备支持用户空间直接配置，必须在注册前设置 V4L2_SUBDEV_FL_HAS_DEVNODE +标志。 + +注册子设备之后， v4l2_device 驱动会通过调用 v4l2_device_register_subdev_nodes() +函数为所有已注册并设置了 V4L2_SUBDEV_FL_HAS_DEVNODE 的子设备创建 +设备节点。这些设备节点会在子设备注销时自动删除。 + +这些设备节点处理 V4L2 API 的一个子集。 + +VIDIOC_QUERYCTRL +VIDIOC_QUERYMENU +VIDIOC_G_CTRL +VIDIOC_S_CTRL +VIDIOC_G_EXT_CTRLS +VIDIOC_S_EXT_CTRLS +VIDIOC_TRY_EXT_CTRLS + + 这些 ioctls 控制与 V4L2 中定义的一致。他们行为相同，唯一的 + 不同是他们只处理子设备的控制实现。根据驱动程序，这些控制也 + 可以通过一个（或多个） V4L2 设备节点访问。 + +VIDIOC_DQEVENT +VIDIOC_SUBSCRIBE_EVENT +VIDIOC_UNSUBSCRIBE_EVENT + + 这些 ioctls 事件与 V4L2 中定义的一致。他们行为相同，唯一的 + 不同是他们只处理子设备产生的事件。根据驱动程序，这些事件也 + 可以通过一个（或多个） V4L2 设备节点上报。 + + 要使用事件通知的子设备驱动，在注册子设备前必须在 v4l2_subdev::flags + 中设置 V4L2_SUBDEV_USES_EVENTS 并在 v4l2_subdev::nevents + 中初始化事件队列深度。注册完成后，事件会在 v4l2_subdev::devnode + 设备节点中像通常一样被排队。 + + 为正确支持事件机制，poll() 文件操作也应被实现。 + +私有 ioctls + + 不在以上列表中的所有 ioctls 会通过 core::ioctl 操作直接传递 + 给子设备驱动。 + + +I2C 子设备驱动 +------------- + +由于这些驱动很常见，所以内特提供了特定的辅助函数(v4l2-common.h)让这些 +设备的使用更加容易。 + +添加 v4l2_subdev 支持的推荐方法是让 I2C 驱动将 v4l2_subdev 结构体 +嵌入到为每个 I2C 设备实例创建的状态结构体中。而最简单的设备没有状态 +结构体，此时可以直接创建一个 v4l2_subdev 结构体。 + +一个典型的状态结构体如下所示（‘chipname’用芯片名代替）： + +struct chipname_state { + struct v4l2_subdev sd; + ... /* 附加的状态域*/ +}; + +初始化 v4l2_subdev 结构体的方法如下： + + v4l2_i2c_subdev_init(&state->sd, client, subdev_ops); + +这个函数将填充 v4l2_subdev 结构体中的所有域，并保证 v4l2_subdev 和 +i2c_client 都指向彼此。 + +同时，你也应该为从 v4l2_subdev 指针找到 chipname_state 结构体指针 +添加一个辅助内联函数。 + +static inline struct chipname_state *to_state(struct v4l2_subdev *sd) +{ + return container_of(sd, struct chipname_state, sd); +} + +使用以下函数可以通过 v4l2_subdev 结构体指针获得 i2c_client 结构体 +指针： + + struct i2c_client *client = v4l2_get_subdevdata(sd); + +而以下函数则相反，通过 i2c_client 结构体指针获得 v4l2_subdev 结构体 +指针： + + struct v4l2_subdev *sd = i2c_get_clientdata(client); + +当 remove()函数被调用前，必须保证先调用 v4l2_device_unregister_subdev(sd)。 +此操作将会从桥驱动中注销子设备。即使子设备没有注册，调用此函数也是 +安全的。 + +必须这样做的原因是：当桥驱动注销 i2c 适配器时，remove()回调函数 +会被那个适配器上的 i2c 设备调用。此后，相应的 v4l2_subdev 结构体 +就不存在了，所有它们必须先被注销。在 remove()回调函数中调用 +v4l2_device_unregister_subdev(sd)，可以保证执行总是正确的。 + + +桥驱动也有一些辅组函数可用： + +struct v4l2_subdev *sd = v4l2_i2c_new_subdev(v4l2_dev, adapter, + "module_foo", "chipid", 0x36, NULL); + +这个函数会加载给定的模块（如果没有模块需要加载，可以为 NULL）， +并用给定的 i2c 适配器结构体指针（i2c_adapter）和 器件地址（chip/address） +作为参数调用 i2c_new_device()。如果一切顺利，则就在 v4l2_device +中注册了子设备。 + +你也可以利用 v4l2_i2c_new_subdev()的最后一个参数，传递一个可能的 +I2C 地址数组，让函数自动探测。这些探测地址只有在前一个参数为 0 的 +情况下使用。非零参数意味着你知道准确的 i2c 地址，所以此时无须进行 +探测。 + +如果出错，两个函数都返回 NULL。 + +注意：传递给 v4l2_i2c_new_subdev()的 chipid 通常与模块名一致。 +它允许你指定一个芯片的变体，比如“saa7114”或“saa7115”。一般通过 +i2c 驱动自动探测。chipid 的使用是在今后需要深入了解的事情。这个与 +i2c 驱动不同，较容易混淆。要知道支持哪些芯片变体，你可以查阅 i2c +驱动代码的 i2c_device_id 表，上面列出了所有可能支持的芯片。 + +还有两个辅助函数： + +v4l2_i2c_new_subdev_cfg：这个函数添加新的 irq 和 platform_data +参数，并有‘addr’和‘probed_addrs’参数：如果 addr 非零，则被使用 +（不探测变体），否则 probed_addrs 中的地址将用于自动探测。 + +例如：以下代码将会探测地址（0x10）： + +struct v4l2_subdev *sd = v4l2_i2c_new_subdev_cfg(v4l2_dev, adapter, + "module_foo", "chipid", 0, NULL, 0, I2C_ADDRS(0x10)); + +v4l2_i2c_new_subdev_board 使用一个 i2c_board_info 结构体，将其 +替代 irq、platform_data 和 add r参数传递给 i2c 驱动。 + +如果子设备支持 s_config 核心操作，这个操作会在子设备配置好之后以 irq 和 +platform_data 为参数调用。早期的 v4l2_i2c_new_(probed_)subdev 函数 +同样也会调用 s_config，但仅在 irq 为 0 且 platform_data 为 NULL 时。 + +video_device结构体 +----------------- + +在 /dev 目录下的实际设备节点根据 video_device 结构体(v4l2-dev.h) +创建。此结构体既可以动态分配也可以嵌入到一个更大的结构体中。 + +动态分配方法如下： + + struct video_device *vdev = video_device_alloc(); + + if (vdev == NULL) + return -ENOMEM; + + vdev->release = video_device_release; + +如果将其嵌入到一个大结构体中，则必须自己实现 release()回调。 + + struct video_device *vdev = &my_vdev->vdev; + + vdev->release = my_vdev_release; + +release()回调必须被设置，且在最后一个 video_device 用户退出之后 +被调用。 + +默认的 video_device_release()回调只是调用 kfree 来释放之前分配的 +内存。 + +你应该设置这些域： + +- v4l2_dev: 设置为 v4l2_device 父设备。 + +- name: 设置为唯一的描述性设备名。 + +- fops: 设置为已有的 v4l2_file_operations 结构体。 + +- ioctl_ops: 如果你使用v4l2_ioctl_ops 来简化 ioctl 的维护 + (强烈建议使用，且将来可能变为强制性的!)，然后设置你自己的 + v4l2_ioctl_ops 结构体. + +- lock: 如果你要在驱动中实现所有的锁操作，则设为 NULL 。否则 + 就要设置一个指向 struct mutex_lock 结构体的指针，这个锁将 + 在 unlocked_ioctl 文件操作被调用前由内核获得，并在调用返回后 + 释放。详见下一节。 + +- prio: 保持对优先级的跟踪。用于实现 VIDIOC_G/S_PRIORITY。如果 + 设置为 NULL，则会使用 v4l2_device 中的 v4l2_prio_state 结构体。 + 如果要对每个设备节点（组）实现独立的优先级，可以将其指向自己 + 实现的 v4l2_prio_state 结构体。 + +- parent: 仅在使用 NULL 作为父设备结构体参数注册 v4l2_device 时 + 设置此参数。只有在一个硬件设备包含多一个 PCI 设备，共享同一个 + v4l2_device 核心时才会发生。 + + cx88 驱动就是一个例子：一个 v4l2_device 结构体核心，被一个裸的 + 视频 PCI 设备(cx8800)和一个 MPEG PCI 设备(cx8802)共用。由于 + v4l2_device 无法与特定的 PCI 设备关联，所有没有设置父设备。但当 + video_device 配置后，就知道使用哪个父 PCI 设备了。 + +- flags：可选。如果你要让框架处理设置 VIDIOC_G/S_PRIORITY ioctls， + 请设置 V4L2_FL_USE_FH_PRIO。这要求你使用 v4l2_fh 结构体。 + 一旦所有驱动使用了核心的优先级处理，最终这个标志将消失。但现在它 + 必须被显式设置。 + +如果你使用 v4l2_ioctl_ops，则应该在 v4l2_file_operations 结构体中 +设置 .unlocked_ioctl 指向 video_ioctl2。 + +请勿使用 .ioctl！它已被废弃，今后将消失。 + +某些情况下你要告诉核心：你在 v4l2_ioctl_ops 指定的某个函数应被忽略。 +你可以在 video_device_register 被调用前通过以下函数标记这个 ioctls。 + +void v4l2_disable_ioctl(struct video_device *vdev, unsigned int cmd); + +基于外部因素（例如某个板卡已被使用），在不创建新结构体的情况下，你想 +要关闭 v4l2_ioctl_ops 中某个特性往往需要这个机制。 + +v4l2_file_operations 结构体是 file_operations 的一个子集。其主要 +区别在于：因 inode 参数从未被使用，它将被忽略。 + +如果需要与媒体框架整合，你必须通过调用 media_entity_init() 初始化 +嵌入在 video_device 结构体中的 media_entity（entity 域）结构体： + + struct media_pad *pad = &my_vdev->pad; + int err; + + err = media_entity_init(&vdev->entity, 1, pad, 0); + +pads 数组必须预先初始化。没有必要手动设置 media_entity 的 type 和 +name 域。 + +当（任何）子设备节点被打开/关闭，对 entity 的引用将被自动获取/释放。 + +v4l2_file_operations 与锁 +-------------------------- + +你可以在 video_device 结构体中设置一个指向 mutex_lock 的指针。通常 +这既可是一个顶层互斥锁也可为设备节点自身的互斥锁。默认情况下，此锁 +用于 unlocked_ioctl，但为了使用 ioctls 你通过以下函数可禁用锁定： + + void v4l2_disable_ioctl_locking(struct video_device *vdev, unsigned int cmd); + +例如: v4l2_disable_ioctl_locking(vdev, VIDIOC_DQBUF); + +你必须在注册 video_device 前调用这个函数。 + +特别是对于 USB 驱动程序，某些命令（如设置控制）需要很长的时间，可能 +需要自行为缓冲区队列的 ioctls 实现锁定。 + +如果你需要更细粒度的锁，你必须设置 mutex_lock 为 NULL，并完全自己实现 +锁机制。 + +这完全由驱动开发者决定使用何种方法。然而，如果你的驱动存在长延时操作 +（例如，改变 USB 摄像头的曝光时间可能需要较长时间），而你又想让用户 +在等待长延时操作完成期间做其他的事，则你最好自己实现锁机制。 + +如果指定一个锁，则所有 ioctl 操作将在这个锁的作用下串行执行。如果你 +使用 videobuf，则必须将同一个锁传递给 videobuf 队列初始化函数；如 +videobuf 必须等待一帧的到达，则可临时解锁并在这之后重新上锁。如果驱动 +也在代码执行期间等待，则可做同样的工作（临时解锁，再上锁）让其他进程 +可以在第一个进程阻塞时访问设备节点。 + +在使用 videobuf2 的情况下，必须实现 wait_prepare 和 wait_finish 回调 +在适当的时候解锁/加锁。进一步来说，如果你在 video_device 结构体中使用 +锁，则必须在 wait_prepare 和 wait_finish 中对这个互斥锁进行解锁/加锁。 + +热插拔的断开实现也必须在调用 v4l2_device_disconnect 前获得锁。 + +video_device注册 +--------------- + +接下来你需要注册视频设备：这会为你创建一个字符设备。 + + err = video_register_device(vdev, VFL_TYPE_GRABBER, -1); + if (err) { + video_device_release(vdev); /* or kfree(my_vdev); */ + return err; + } + +如果 v4l2_device 父设备的 mdev 域为非 NULL 值，视频设备实体将自动 +注册为媒体设备。 + +注册哪种设备是根据类型（type）参数。存在以下类型： + +VFL_TYPE_GRABBER: 用于视频输入/输出设备的 videoX +VFL_TYPE_VBI: 用于垂直消隐数据的 vbiX (例如，隐藏式字幕，图文电视) +VFL_TYPE_RADIO: 用于广播调谐器的 radioX + +最后一个参数让你确定一个所控制设备的设备节点号数量(例如 videoX 中的 X)。 +通常你可以传入-1，让 v4l2 框架自己选择第一个空闲的编号。但是有时用户 +需要选择一个特定的节点号。驱动允许用户通过驱动模块参数选择一个特定的 +设备节点号是很普遍的。这个编号将会传递给这个函数，且 video_register_device +将会试图选择这个设备节点号。如果这个编号被占用，下一个空闲的设备节点 +编号将被选中，并向内核日志中发送一个警告信息。 + +另一个使用场景是当驱动创建多个设备时。这种情况下，对不同的视频设备在 +编号上使用不同的范围是很有用的。例如，视频捕获设备从 0 开始，视频 +输出设备从 16 开始。所以你可以使用最后一个参数来指定设备节点号最小值， +而 v4l2 框架会试图选择第一个的空闲编号（等于或大于你提供的编号）。 +如果失败，则它会就选择第一个空闲的编号。 + +由于这种情况下，你会忽略无法选择特定设备节点号的警告，则可调用 +video_register_device_no_warn() 函数避免警告信息的产生。 + +只要设备节点被创建，一些属性也会同时创建。在 /sys/class/video4linux +目录中你会找到这些设备。例如进入其中的 video0 目录，你会看到‘name’和 +‘index’属性。‘name’属性值就是 video_device 结构体中的‘name’域。 + +‘index’属性值就是设备节点的索引值：每次调用 video_register_device()， +索引值都递增 1 。第一个视频设备节点总是从索引值 0 开始。 + +用户可以设置 udev 规则，利用索引属性生成花哨的设备名（例如：用‘mpegX’ +代表 MPEG 视频捕获设备节点）。 + +在设备成功注册后，就可以使用这些域： + +- vfl_type: 传递给 video_register_device 的设备类型。 +- minor: 已指派的次设备号。 +- num: 设备节点编号 (例如 videoX 中的 X)。 +- index: 设备索引号。 + +如果注册失败，你必须调用 video_device_release() 来释放已分配的 +video_device 结构体；如果 video_device 是嵌入在自己创建的结构体中， +你也必须释放它。vdev->release() 回调不会在注册失败之后被调用， +你也不应试图在注册失败后注销设备。 + + +video_device 注销 +---------------- + +当视频设备节点已被移除，不论是卸载驱动还是USB设备断开，你都应注销 +它们： + + video_unregister_device(vdev); + +这个操作将从 sysfs 中移除设备节点（导致 udev 将其从 /dev 中移除）。 + +video_unregister_device() 返回之后，就无法完成打开操作。尽管如此， +USB 设备的情况则不同，某些应用程序可能依然打开着其中一个已注销设备 +节点。所以在注销之后，所有文件操作（当然除了 release ）也应返回错误值。 + +当最后一个视频设备节点的用户退出，则 vdev->release() 回调会被调用， +并且你可以做最后的清理操作。 + +不要忘记清理与视频设备相关的媒体入口（如果被初始化过）： + + media_entity_cleanup(&vdev->entity); + +这可以在 release 回调中完成。 + + +video_device 辅助函数 +--------------------- + +一些有用的辅助函数如下： + +- file/video_device 私有数据 + +你可以用以下函数在 video_device 结构体中设置/获取驱动私有数据： + +void *video_get_drvdata(struct video_device *vdev); +void video_set_drvdata(struct video_device *vdev, void *data); + +注意：在调用 video_register_device() 前执行 video_set_drvdata() +是安全的。 + +而以下函数： + +struct video_device *video_devdata(struct file *file); + +返回 file 结构体中拥有的的 video_device 指针。 + +video_drvdata 辅助函数结合了 video_get_drvdata 和 video_devdata +的功能： + +void *video_drvdata(struct file *file); + +你可以使用如下代码从 video_device 结构体中获取 v4l2_device 结构体 +指针： + +struct v4l2_device *v4l2_dev = vdev->v4l2_dev; + +- 设备节点名 + +video_device 设备节点在内核中的名称可以通过以下函数获得 + +const char *video_device_node_name(struct video_device *vdev); + +这个名字被用户空间工具（例如 udev）作为提示信息使用。应尽可能使用 +此功能，而非访问 video_device::num 和 video_device::minor 域。 + + +视频缓冲辅助函数 +--------------- + +v4l2 核心 API 提供了一个处理视频缓冲的标准方法(称为“videobuf”)。 +这些方法使驱动可以通过统一的方式实现 read()、mmap() 和 overlay()。 +目前在设备上支持视频缓冲的方法有分散/聚集 DMA(videobuf-dma-sg)、 +线性 DMA(videobuf-dma-contig)以及大多用于 USB 设备的用 vmalloc +分配的缓冲(videobuf-vmalloc)。 + +请参阅 Documentation/video4linux/videobuf，以获得更多关于 videobuf +层的使用信息。 + +v4l2_fh 结构体 +------------- + +v4l2_fh 结构体提供一个保存用于 V4L2 框架的文件句柄特定数据的简单方法。 +如果 video_device 的 flag 设置了 V4L2_FL_USE_FH_PRIO 标志，新驱动 +必须使用 v4l2_fh 结构体，因为它也用于实现优先级处理（VIDIOC_G/S_PRIORITY）。 + +v4l2_fh 的用户（位于 V4l2 框架中，并非驱动）可通过测试 +video_device->flags 中的 V4L2_FL_USES_V4L2_FH 位得知驱动是否使用 +v4l2_fh 作为他的 file->private_data 指针。这个位会在调用 v4l2_fh_init() +时被设置。 + +v4l2_fh 结构体作为驱动自身文件句柄结构体的一部分被分配，且驱动在 +其打开函数中将 file->private_data 指向它。 + +在许多情况下，v4l2_fh 结构体会嵌入到一个更大的结构体中。这钟情况下， +应该在 open() 中调用 v4l2_fh_init+v4l2_fh_add，并在 release() 中 +调用 v4l2_fh_del+v4l2_fh_exit。 + +驱动可以通过使用 container_of 宏提取他们自己的文件句柄结构体。例如： + +struct my_fh { + int blah; + struct v4l2_fh fh; +}; + +... + +int my_open(struct file *file) +{ + struct my_fh *my_fh; + struct video_device *vfd; + int ret; + + ... + + my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL); + + ... + + v4l2_fh_init(&my_fh->fh, vfd); + + ... + + file->private_data = &my_fh->fh; + v4l2_fh_add(&my_fh->fh); + return 0; +} + +int my_release(struct file *file) +{ + struct v4l2_fh *fh = file->private_data; + struct my_fh *my_fh = container_of(fh, struct my_fh, fh); + + ... + v4l2_fh_del(&my_fh->fh); + v4l2_fh_exit(&my_fh->fh); + kfree(my_fh); + return 0; +} + +以下是 v4l2_fh 函数使用的简介： + +void v4l2_fh_init(struct v4l2_fh *fh, struct video_device *vdev) + + 初始化文件句柄。这*必须*在驱动的 v4l2_file_operations->open() + 函数中执行。 + +void v4l2_fh_add(struct v4l2_fh *fh) + + 添加一个 v4l2_fh 到 video_device 文件句柄列表。一旦文件句柄 + 初始化完成就必须调用。 + +void v4l2_fh_del(struct v4l2_fh *fh) + + 从 video_device() 中解除文件句柄的关联。文件句柄的退出函数也 + 将被调用。 + +void v4l2_fh_exit(struct v4l2_fh *fh) + + 清理文件句柄。在清理完 v4l2_fh 后，相关内存会被释放。 + + +如果 v4l2_fh 不是嵌入在其他结构体中的，则可以用这些辅助函数： + +int v4l2_fh_open(struct file *filp) + + 分配一个 v4l2_fh 结构体空间，初始化并将其添加到 file 结构体相关的 + video_device 结构体中。 + +int v4l2_fh_release(struct file *filp) + + 从 file 结构体相关的 video_device 结构体中删除 v4l2_fh ，清理 + v4l2_fh 并释放空间。 + +这两个函数可以插入到 v4l2_file_operation 的 open() 和 release() +操作中。 + + +某些驱动需要在第一个文件句柄打开和最后一个文件句柄关闭的时候做些 +工作。所以加入了两个辅助函数以检查 v4l2_fh 结构体是否是相关设备 +节点打开的唯一文件句柄。 + +int v4l2_fh_is_singular(struct v4l2_fh *fh) + + 如果此文件句柄是唯一打开的文件句柄，则返回 1 ，否则返回 0 。 + +int v4l2_fh_is_singular_file(struct file *filp) + + 功能相同，但通过 filp->private_data 调用 v4l2_fh_is_singular。 + + +V4L2 事件机制 +----------- + +V4L2 事件机制提供了一个通用的方法将事件传递到用户空间。驱动必须使用 +v4l2_fh 才能支持 V4L2 事件机制。 + + +事件通过一个类型和选择 ID 来定义。ID 对应一个 V4L2 对象，例如 +一个控制 ID。如果未使用，则 ID 为 0。 + +当用户订阅一个事件，驱动会为此分配一些 kevent 结构体。所以每个 +事件组（类型、ID）都会有自己的一套 kevent 结构体。这保证了如果 +一个驱动短时间内产生了许多同类事件，不会覆盖其他类型的事件。 + +但如果你收到的事件数量大于同类事件 kevent 的保存数量，则最早的 +事件将被丢弃，并加入新事件。 + +此外，v4l2_subscribed_event 结构体内部有可供驱动设置的 merge() 和 +replace() 回调，这些回调会在新事件产生且没有多余空间的时候被调用。 +replace() 回调让你可以将早期事件的净荷替换为新事件的净荷，将早期 +净荷的相关数据合并到替换进来的新净荷中。当该类型的事件仅分配了一个 +kevent 结构体时，它将被调用。merge() 回调让你可以合并最早的事件净荷 +到在它之后的那个事件净荷中。当该类型的事件分配了两个或更多 kevent +结构体时，它将被调用。 + +这种方法不会有状态信息丢失，只会导致中间步骤信息丢失。 + + +关于 replace/merge 回调的一个不错的例子在 v4l2-event.c 中：用于 +控制事件的 ctrls_replace() 和 ctrls_merge() 回调。 + +注意：这些回调可以在中断上下文中调用，所以它们必须尽快完成并退出。 + +有用的函数： + +void v4l2_event_queue(struct video_device *vdev, const struct v4l2_event *ev) + + 将事件加入视频设备的队列。驱动仅负责填充 type 和 data 域。 + 其他域由 V4L2 填充。 + +int v4l2_event_subscribe(struct v4l2_fh *fh, + struct v4l2_event_subscription *sub, unsigned elems, + const struct v4l2_subscribed_event_ops *ops) + + video_device->ioctl_ops->vidioc_subscribe_event 必须检测驱动能 + 产生特定 id 的事件。然后调用 v4l2_event_subscribe() 来订阅该事件。 + + elems 参数是该事件的队列大小。若为 0，V4L2 框架将会（根据事件类型） + 填充默认值。 + + ops 参数允许驱动指定一系列回调： + * add: 当添加一个新监听者时调用（重复订阅同一个事件，此回调 + 仅被执行一次）。 + * del: 当一个监听者停止监听时调用。 + * replace: 用‘新’事件替换‘早期‘事件。 + * merge: 将‘早期‘事件合并到‘新’事件中。 + 这四个调用都是可选的，如果不想指定任何回调，则 ops 可为 NULL。 + +int v4l2_event_unsubscribe(struct v4l2_fh *fh, + struct v4l2_event_subscription *sub) + + v4l2_ioctl_ops 结构体中的 vidioc_unsubscribe_event 回调函数。 + 驱动程序可以直接使用 v4l2_event_unsubscribe() 实现退订事件过程。 + + 特殊的 V4L2_EVENT_ALL 类型，可用于退订所有事件。驱动可能在特殊 + 情况下需要做此操作。 + +int v4l2_event_pending(struct v4l2_fh *fh) + + 返回未决事件的数量。有助于实现轮询（poll）操作。 + +事件通过 poll 系统调用传递到用户空间。驱动可用 +v4l2_fh->wait (wait_queue_head_t 类型)作为参数调用 poll_wait()。 + +事件分为标准事件和私有事件。新的标准事件必须使用可用的最小事件类型 +编号。驱动必须从他们本类型的编号起始处分配事件。类型的编号起始为 +V4L2_EVENT_PRIVATE_START + n * 1000 ，其中 n 为可用最小编号。每个 +类型中的第一个事件类型编号是为以后的使用保留的，所以第一个可用事件 +类型编号是‘class base + 1’。 + +V4L2 事件机制的使用实例可以在 OMAP3 ISP 的驱动 +(drivers/media/video/omap3isp)中找到。 |