diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget | 12 | ||||
| -rw-r--r-- | Documentation/DocBook/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/lirc_device_interface.xml | 16 | ||||
| -rw-r--r-- | Documentation/DocBook/v4l/pixfmt-packed-rgb.xml | 78 | ||||
| -rw-r--r-- | Documentation/feature-removal-schedule.txt | 8 | ||||
| -rw-r--r-- | Documentation/filesystems/Locking | 22 | ||||
| -rw-r--r-- | Documentation/filesystems/porting | 45 | ||||
| -rw-r--r-- | Documentation/kernel-parameters.txt | 3 | ||||
| -rw-r--r-- | Documentation/usb/ehci.txt | 2 | ||||
| -rw-r--r-- | Documentation/usb/gadget_multi.txt | 150 | ||||
| -rw-r--r-- | Documentation/usb/gadget_serial.txt | 87 | ||||
| -rw-r--r-- | Documentation/usb/hotplug.txt | 4 | ||||
| -rw-r--r-- | Documentation/usb/linux-cdc-acm.inf | 107 | ||||
| -rw-r--r-- | Documentation/usb/linux.inf | 228 | ||||
| -rw-r--r-- | Documentation/video4linux/v4l2-controls.txt | 648 |
15 files changed, 1132 insertions, 280 deletions
diff --git a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget index 34034027b13c..d548eaac230a 100644 --- a/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget +++ b/Documentation/ABI/testing/sysfs-devices-platform-_UDC_-gadget @@ -7,3 +7,15 @@ Description: 0 -> resumed (_UDC_ is the name of the USB Device Controller driver) + +What: /sys/devices/platform/_UDC_/gadget/gadget-lunX/nofua +Date: July 2010 +Contact: Andy Shevchenko <andy.shevchenko@gmail.com> +Description: + Show or set the reaction on the FUA (Force Unit Access) bit in + the SCSI WRITE(10,12) commands when a gadget in USB Mass + Storage mode. + + Possible values are: + 1 -> ignore the FUA flag + 0 -> obey the FUA flag diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index c7e5dc7e8cb3..4b603c5c3cc1 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -45,7 +45,7 @@ PDF := $(patsubst %.xml, %.pdf, $(BOOKS)) pdfdocs: $(PDF) HTML := $(sort $(patsubst %.xml, %.html, $(BOOKS))) -htmldocs: $(HTML) +htmldocs: $(HTML) xmldoclinks $(call build_main_index) $(call build_images) diff --git a/Documentation/DocBook/v4l/lirc_device_interface.xml b/Documentation/DocBook/v4l/lirc_device_interface.xml index 0413234023d4..68134c0ab4d1 100644 --- a/Documentation/DocBook/v4l/lirc_device_interface.xml +++ b/Documentation/DocBook/v4l/lirc_device_interface.xml @@ -229,6 +229,22 @@ on working with the default settings initially.</para> and LIRC_SETUP_END. Drivers can also choose to ignore these ioctls.</para> </listitem> </varlistentry> + <varlistentry> + <term>LIRC_SET_WIDEBAND_RECEIVER</term> + <listitem> + <para>Some receivers are equipped with special wide band receiver which is intended + to be used to learn output of existing remote. + Calling that ioctl with (1) will enable it, and with (0) disable it. + This might be useful of receivers that have otherwise narrow band receiver + that prevents them to be used with some remotes. + Wide band receiver might also be more precise + On the other hand its disadvantage it usually reduced range of reception. + Note: wide band receiver might be implictly enabled if you enable + carrier reports. In that case it will be disabled as soon as you disable + carrier reports. Trying to disable wide band receiver while carrier + reports are active will do nothing.</para> + </listitem> + </varlistentry> </variablelist> </section> diff --git a/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml index d2dd697a81d8..26e879231088 100644 --- a/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml +++ b/Documentation/DocBook/v4l/pixfmt-packed-rgb.xml @@ -240,6 +240,45 @@ colorspace <constant>V4L2_COLORSPACE_SRGB</constant>.</para> <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> + <row id="V4L2-PIX-FMT-BGR666"> + <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry> + <entry>'BGRH'</entry> + <entry></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> <row id="V4L2-PIX-FMT-BGR24"> <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> <entry>'BGR3'</entry> @@ -700,6 +739,45 @@ defined in error. Drivers may interpret them as in <xref <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> + <row id="V4L2-PIX-FMT-BGR666"> + <entry><constant>V4L2_PIX_FMT_BGR666</constant></entry> + <entry>'BGRH'</entry> + <entry></entry> + <entry>b<subscript>5</subscript></entry> + <entry>b<subscript>4</subscript></entry> + <entry>b<subscript>3</subscript></entry> + <entry>b<subscript>2</subscript></entry> + <entry>b<subscript>1</subscript></entry> + <entry>b<subscript>0</subscript></entry> + <entry>g<subscript>5</subscript></entry> + <entry>g<subscript>4</subscript></entry> + <entry></entry> + <entry>g<subscript>3</subscript></entry> + <entry>g<subscript>2</subscript></entry> + <entry>g<subscript>1</subscript></entry> + <entry>g<subscript>0</subscript></entry> + <entry>r<subscript>5</subscript></entry> + <entry>r<subscript>4</subscript></entry> + <entry>r<subscript>3</subscript></entry> + <entry>r<subscript>2</subscript></entry> + <entry></entry> + <entry>r<subscript>1</subscript></entry> + <entry>r<subscript>0</subscript></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + <entry></entry> + </row> <row><!-- id="V4L2-PIX-FMT-BGR24" --> <entry><constant>V4L2_PIX_FMT_BGR24</constant></entry> <entry>'BGR3'</entry> diff --git a/Documentation/feature-removal-schedule.txt b/Documentation/feature-removal-schedule.txt index 56cee4727b1a..b16cbe4152ea 100644 --- a/Documentation/feature-removal-schedule.txt +++ b/Documentation/feature-removal-schedule.txt @@ -360,14 +360,6 @@ When: 2.6.33 Why: Should be implemented in userspace, policy daemon. Who: Johannes Berg <johannes@sipsolutions.net> ---------------------------- - -What: CONFIG_INOTIFY -When: 2.6.33 -Why: last user (audit) will be converted to the newer more generic - and more easily maintained fsnotify subsystem -Who: Eric Paris <eparis@redhat.com> - ---------------------------- What: sound-slot/service-* module aliases and related clutters in diff --git a/Documentation/filesystems/Locking b/Documentation/filesystems/Locking index 96d4293607ec..bbcc15651a21 100644 --- a/Documentation/filesystems/Locking +++ b/Documentation/filesystems/Locking @@ -92,8 +92,8 @@ prototypes: void (*destroy_inode)(struct inode *); void (*dirty_inode) (struct inode *); int (*write_inode) (struct inode *, int); - void (*drop_inode) (struct inode *); - void (*delete_inode) (struct inode *); + int (*drop_inode) (struct inode *); + void (*evict_inode) (struct inode *); void (*put_super) (struct super_block *); void (*write_super) (struct super_block *); int (*sync_fs)(struct super_block *sb, int wait); @@ -101,14 +101,13 @@ prototypes: int (*unfreeze_fs) (struct super_block *); int (*statfs) (struct dentry *, struct kstatfs *); int (*remount_fs) (struct super_block *, int *, char *); - void (*clear_inode) (struct inode *); void (*umount_begin) (struct super_block *); int (*show_options)(struct seq_file *, struct vfsmount *); ssize_t (*quota_read)(struct super_block *, int, char *, size_t, loff_t); ssize_t (*quota_write)(struct super_block *, int, const char *, size_t, loff_t); locking rules: - All may block. + All may block [not true, see below] None have BKL s_umount alloc_inode: @@ -116,22 +115,25 @@ destroy_inode: dirty_inode: (must not sleep) write_inode: drop_inode: !!!inode_lock!!! -delete_inode: +evict_inode: put_super: write write_super: read sync_fs: read freeze_fs: read unfreeze_fs: read -statfs: no -remount_fs: maybe (see below) -clear_inode: +statfs: maybe(read) (see below) +remount_fs: write umount_begin: no show_options: no (namespace_sem) quota_read: no (see below) quota_write: no (see below) -->remount_fs() will have the s_umount exclusive lock if it's already mounted. -When called from get_sb_single, it does NOT have the s_umount lock. +->statfs() has s_umount (shared) when called by ustat(2) (native or +compat), but that's an accident of bad API; s_umount is used to pin +the superblock down when we only have dev_t given us by userland to +identify the superblock. Everything else (statfs(), fstatfs(), etc.) +doesn't hold it when calling ->statfs() - superblock is pinned down +by resolving the pathname passed to syscall. ->quota_read() and ->quota_write() functions are both guaranteed to be the only ones operating on the quota file by the quota code (via dqio_sem) (unless an admin really wants to screw up something and diff --git a/Documentation/filesystems/porting b/Documentation/filesystems/porting index a7e9746ee7ea..b12c89538680 100644 --- a/Documentation/filesystems/porting +++ b/Documentation/filesystems/porting @@ -273,3 +273,48 @@ it's safe to remove it. If you don't need it, remove it. deliberate; as soon as struct block_device * is propagated in a reasonable way by that code fixing will become trivial; until then nothing can be done. + +[mandatory] + + block truncatation on error exit from ->write_begin, and ->direct_IO +moved from generic methods (block_write_begin, cont_write_begin, +nobh_write_begin, blockdev_direct_IO*) to callers. Take a look at +ext2_write_failed and callers for an example. + +[mandatory] + + ->truncate is going away. The whole truncate sequence needs to be +implemented in ->setattr, which is now mandatory for filesystems +implementing on-disk size changes. Start with a copy of the old inode_setattr +and vmtruncate, and the reorder the vmtruncate + foofs_vmtruncate sequence to +be in order of zeroing blocks using block_truncate_page or similar helpers, +size update and on finally on-disk truncation which should not fail. +inode_change_ok now includes the size checks for ATTR_SIZE and must be called +in the beginning of ->setattr unconditionally. + +[mandatory] + + ->clear_inode() and ->delete_inode() are gone; ->evict_inode() should +be used instead. It gets called whenever the inode is evicted, whether it has +remaining links or not. Caller does *not* evict the pagecache or inode-associated +metadata buffers; getting rid of those is responsibility of method, as it had +been for ->delete_inode(). + ->drop_inode() returns int now; it's called on final iput() with inode_lock +held and it returns true if filesystems wants the inode to be dropped. As before, +generic_drop_inode() is still the default and it's been updated appropriately. +generic_delete_inode() is also alive and it consists simply of return 1. Note that +all actual eviction work is done by caller after ->drop_inode() returns. + clear_inode() is gone; use end_writeback() instead. As before, it must +be called exactly once on each call of ->evict_inode() (as it used to be for +each call of ->delete_inode()). Unlike before, if you are using inode-associated +metadata buffers (i.e. mark_buffer_dirty_inode()), it's your responsibility to +call invalidate_inode_buffers() before end_writeback(). + No async writeback (and thus no calls of ->write_inode()) will happen +after end_writeback() returns, so actions that should not overlap with ->write_inode() +(e.g. freeing on-disk inode if i_nlink is 0) ought to be done after that call. + + NOTE: checking i_nlink in the beginning of ->write_inode() and bailing out +if it's zero is not *and* *never* *had* *been* enough. Final unlink() and iput() +may happen while the inode is in the middle of ->write_inode(); e.g. if you blindly +free the on-disk inode, you may end up doing that while ->write_inode() is writing +to it. diff --git a/Documentation/kernel-parameters.txt b/Documentation/kernel-parameters.txt index 44f6b19c50bb..d529b1363e95 100644 --- a/Documentation/kernel-parameters.txt +++ b/Documentation/kernel-parameters.txt @@ -681,8 +681,11 @@ and is between 256 and 4096 characters. It is defined in the file earlycon= [KNL] Output early console device and options. uart[8250],io,<addr>[,options] uart[8250],mmio,<addr>[,options] + uart[8250],mmio32,<addr>[,options] Start an early, polled-mode console on the 8250/16550 UART at the specified I/O port or MMIO address. + MMIO inter-register address stride is either 8bit (mmio) + or 32bit (mmio32). The options are the same as for ttyS, above. earlyprintk= [X86,SH,BLACKFIN] diff --git a/Documentation/usb/ehci.txt b/Documentation/usb/ehci.txt index 1536b7e75134..9dcafa7d930d 100644 --- a/Documentation/usb/ehci.txt +++ b/Documentation/usb/ehci.txt @@ -9,7 +9,7 @@ compatible with the USB 1.1 standard. It defines three transfer speeds: - "Low Speed" 1.5 Mbit/sec USB 1.1 only addressed full speed and low speed. High speed devices -can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds. +can be used on USB 1.1 systems, but they slow down to USB 1.1 speeds. USB 1.1 devices may also be used on USB 2.0 systems. When plugged into an EHCI controller, they are given to a USB 1.1 "companion" diff --git a/Documentation/usb/gadget_multi.txt b/Documentation/usb/gadget_multi.txt new file mode 100644 index 000000000000..80f4ef0eb75b --- /dev/null +++ b/Documentation/usb/gadget_multi.txt @@ -0,0 +1,150 @@ + -*- org -*- + +* Overview + +The Multifunction Composite Gadget (or g_multi) is a composite gadget +that makes extensive use of the composite framework to provide +a... multifunction gadget. + +In it's standard configuration it provides a single USB configuration +with RNDIS[1] (that is Ethernet), USB CDC[2] ACM (that is serial) and +USB Mass Storage functions. + +A CDC ECM (Ethernet) function may be turned on via a Kconfig option +and RNDIS can be turned off. If they are both enabled the gadget will +have two configurations -- one with RNDIS and another with CDC ECM[3]. + +Please not that if you use non-standard configuration (that is enable +CDC ECM) you may need to change vendor and/or product ID. + +* Host drivers + +To make use of the gadget one needs to make it work on host side -- +without that there's no hope of achieving anything with the gadget. +As one might expect, things one need to do very from system to system. + +** Linux host drivers + +Since the gadget uses standard composite framework and appears as such +to Linux host it does not need any additional drivers on Linux host +side. All the functions are handled by respective drivers developed +for them. + +This is also true for two configuration set-up with RNDIS +configuration being the first one. Linux host will use the second +configuration with CDC ECM which should work better under Linux. + +** Windows host drivers + +For the gadget two work under Windows two conditions have to be met: + +*** Detecting as composite gadget + +First of all, Windows need to detect the gadget as an USB composite +gadget which on its own have some conditions[4]. If they are met, +Windows lets USB Generic Parent Driver[5] handle the device which then +tries to much drivers for each individual interface (sort of, don't +get into too many details). + +The good news is: you do not have to worry about most of the +conditions! + +The only thing to worry is that the gadget has to have a single +configuration so a dual RNDIS and CDC ECM gadget won't work unless you +create a proper INF -- and of course, if you do submit it! + +*** Installing drivers for each function + +The other, trickier thing is making Windows install drivers for each +individual function. + +For mass storage it is trivial since Windows detect it's an interface +implementing USB Mass Storage class and selects appropriate driver. + +Things are harder with RDNIS and CDC ACM. + +**** RNDIS + +To make Windows select RNDIS drivers for the first function in the +gadget, one needs to use the [[file:linux.inf]] file provided with this +document. It "attaches" Window's RNDIS driver to the first interface +of the gadget. + +Please note, that while testing we encountered some issues[6] when +RNDIS was not the first interface. You do not need to worry abut it +unless you are trying to develop your own gadget in which case watch +out for this bug. + +**** CDC ACM + +Similarly, [[file:linux-cdc-acm.inf]] is provided for CDC ACM. + +**** Customising the gadget + +If you intend to hack the g_multi gadget be advised that rearranging +functions will obviously change interface numbers for each of the +functionality. As an effect provided INFs won't work since they have +interface numbers hard-coded in them (it's not hard to change those +though[7]). + +This also means, that after experimenting with g_multi and changing +provided functions one should change gadget's vendor and/or product ID +so there will be no collision with other customised gadgets or the +original gadget. + +Failing to comply may cause brain damage after wondering for hours why +things don't work as intended before realising Windows have cached +some drivers information (changing USB port may sometimes help plus +you might try using USBDeview[8] to remove the phantom device). + +**** INF testing + +Provided INF files have been tested on Windows XP SP3, Windows Vista +and Windows 7, all 32-bit versions. It should work on 64-bit versions +as well. It most likely won't work on Windows prior to Windows XP +SP2. + +** Other systems + +At this moment, drivers for any other systems have not been tested. +Knowing how MacOS is based on BSD and BSD is an Open Source it is +believed that it should (read: "I have no idea whether it will") work +out-of-the-box. + +For more exotic systems I have even less to say... + +Any testing and drivers *are* *welcome*! + +* Authors + +This document has been written by Michal Nazarewicz +([[mailto:mina86@mina86.com]]). INF files have been hacked with +support of Marek Szyprowski ([[mailto:m.szyprowski@samsung.com]]) and +Xiaofan Chen ([[mailto:xiaofanc@gmail.com]]) basing on the MS RNDIS +template[9], Microchip's CDC ACM INF file and David Brownell's +([[mailto:dbrownell@users.sourceforge.net]]) original INF files. + +* Footnotes + +[1] Remote Network Driver Interface Specification, +[[http://msdn.microsoft.com/en-us/library/ee484414.aspx]]. + +[2] Communications Device Class Abstract Control Model, spec for this +and other USB classes can be found at +[[http://www.usb.org/developers/devclass_docs/]]. + +[3] CDC Ethernet Control Model. + +[4] [[http://msdn.microsoft.com/en-us/library/ff537109(v=VS.85).aspx]] + +[5] [[http://msdn.microsoft.com/en-us/library/ff539234(v=VS.85).aspx]] + +[6] To put it in some other nice words, Windows failed to respond to +any user input. + +[7] You may find [[http://www.cygnal.org/ubb/Forum9/HTML/001050.html]] +useful. + +[8] http://www.nirsoft.net/utils/usb_devices_view.html + +[9] [[http://msdn.microsoft.com/en-us/library/ff570620.aspx]] diff --git a/Documentation/usb/gadget_serial.txt b/Documentation/usb/gadget_serial.txt index eac7df94d8e3..61e67f6a20a0 100644 --- a/Documentation/usb/gadget_serial.txt +++ b/Documentation/usb/gadget_serial.txt @@ -151,88 +151,23 @@ instructions below to install the host side driver. Installing the Windows Host ACM Driver -------------------------------------- -To use the Windows ACM driver you must have the files "gserial.inf" -and "usbser.sys" together in a folder on the Windows machine. - -The "gserial.inf" file is given here. - --------------------- CUT HERE -------------------- -[Version] -Signature="$Windows NT$" -Class=Ports -ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} -Provider=%LINUX% -DriverVer=08/17/2004,0.0.2.0 -; Copyright (C) 2004 Al Borchers (alborchers@steinerpoint.com) - -[Manufacturer] -%LINUX%=GSerialDeviceList - -[GSerialDeviceList] -%GSERIAL%=GSerialInstall, USB\VID_0525&PID_A4A7 - -[DestinationDirs] -DefaultDestDir=10,System32\Drivers - -[GSerialInstall] -CopyFiles=GSerialCopyFiles -AddReg=GSerialAddReg - -[GSerialCopyFiles] -usbser.sys - -[GSerialAddReg] -HKR,,DevLoader,,*ntkern -HKR,,NTMPDriver,,usbser.sys -HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" - -[GSerialInstall.Services] -AddService = usbser,0x0002,GSerialService - -[GSerialService] -DisplayName = %GSERIAL_DISPLAY_NAME% -ServiceType = 1 ; SERVICE_KERNEL_DRIVER -StartType = 3 ; SERVICE_DEMAND_START -ErrorControl = 1 ; SERVICE_ERROR_NORMAL -ServiceBinary = %10%\System32\Drivers\usbser.sys -LoadOrderGroup = Base - -[Strings] -LINUX = "Linux" -GSERIAL = "Gadget Serial" -GSERIAL_DISPLAY_NAME = "USB Gadget Serial Driver" --------------------- CUT HERE -------------------- - -The "usbser.sys" file comes with various versions of Windows. -For example, it can be found on Windows XP typically in - - C:\WINDOWS\Driver Cache\i386\driver.cab - -Or it can be found on the Windows 98SE CD in the "win98" folder -in the "DRIVER11.CAB" through "DRIVER20.CAB" cab files. You will -need the DOS "expand" program, the Cygwin "cabextract" program, or -a similar program to unpack these cab files and extract "usbser.sys". - -For example, to extract "usbser.sys" into the current directory -on Windows XP, open a DOS window and run a command like - - expand C:\WINDOWS\Driver~1\i386\driver.cab -F:usbser.sys . - -(Thanks to Nishant Kamat for pointing out this DOS command.) +To use the Windows ACM driver you must have the "linux-cdc-acm.inf" +file (provided along this document) which supports all recent versions +of Windows. When the gadget serial driver is loaded and the USB device connected to the Windows host with a USB cable, Windows should recognize the gadget serial device and ask for a driver. Tell Windows to find the -driver in the folder that contains "gserial.inf" and "usbser.sys". +driver in the folder that contains the "linux-cdc-acm.inf" file. For example, on Windows XP, when the gadget serial device is first plugged in, the "Found New Hardware Wizard" starts up. Select -"Install from a list or specific location (Advanced)", then on -the next screen select "Include this location in the search" and -enter the path or browse to the folder containing "gserial.inf" and -"usbser.sys". Windows will complain that the Gadget Serial driver -has not passed Windows Logo testing, but select "Continue anyway" -and finish the driver installation. +"Install from a list or specific location (Advanced)", then on the +next screen select "Include this location in the search" and enter the +path or browse to the folder containing the "linux-cdc-acm.inf" file. +Windows will complain that the Gadget Serial driver has not passed +Windows Logo testing, but select "Continue anyway" and finish the +driver installation. On Windows XP, in the "Device Manager" (under "Control Panel", "System", "Hardware") expand the "Ports (COM & LPT)" entry and you @@ -345,5 +280,3 @@ you should be able to send data back and forth between the gadget side and host side systems. Anything you type on the terminal window on the gadget side should appear in the terminal window on the host side and vice versa. - - diff --git a/Documentation/usb/hotplug.txt b/Documentation/usb/hotplug.txt index f53170665f37..4c945716a660 100644 --- a/Documentation/usb/hotplug.txt +++ b/Documentation/usb/hotplug.txt @@ -10,7 +10,7 @@ immediately usable. That means the system must do many things, including: - Bind a driver to that device. Bus frameworks do that using a device driver's probe() routine. - + - Tell other subsystems to configure the new device. Print queues may need to be enabled, networks brought up, disk partitions mounted, and so on. In some cases these will @@ -84,7 +84,7 @@ USB MODUTILS SUPPORT Current versions of module-init-tools will create a "modules.usbmap" file which contains the entries from each driver's MODULE_DEVICE_TABLE. Such files can be used by various user mode policy agents to make sure all the -right driver modules get loaded, either at boot time or later. +right driver modules get loaded, either at boot time or later. See <linux/usb.h> for full information about such table entries; or look at existing drivers. Each table entry describes one or more criteria to diff --git a/Documentation/usb/linux-cdc-acm.inf b/Documentation/usb/linux-cdc-acm.inf new file mode 100644 index 000000000000..612e7220fb29 --- /dev/null +++ b/Documentation/usb/linux-cdc-acm.inf @@ -0,0 +1,107 @@ +; Windows USB CDC ACM Setup File + +; Based on INF template which was: +; Copyright (c) 2000 Microsoft Corporation +; Copyright (c) 2007 Microchip Technology Inc. +; likely to be covered by the MLPL as found at: +; <http://msdn.microsoft.com/en-us/cc300389.aspx#MLPL>. +; For use only on Windows operating systems. + +[Version] +Signature="$Windows NT$" +Class=Ports +ClassGuid={4D36E978-E325-11CE-BFC1-08002BE10318} +Provider=%Linux% +DriverVer=11/15/2007,5.1.2600.0 + +[Manufacturer] +%Linux%=DeviceList, NTamd64 + +[DestinationDirs] +DefaultDestDir=12 + + +;------------------------------------------------------------------------------ +; Windows 2000/XP/Vista-32bit Sections +;------------------------------------------------------------------------------ + +[DriverInstall.nt] +include=mdmcpq.inf +CopyFiles=DriverCopyFiles.nt +AddReg=DriverInstall.nt.AddReg + +[DriverCopyFiles.nt] +usbser.sys,,,0x20 + +[DriverInstall.nt.AddReg] +HKR,,DevLoader,,*ntkern +HKR,,NTMPDriver,,USBSER.sys +HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" + +[DriverInstall.nt.Services] +AddService=usbser, 0x00000002, DriverService.nt + +[DriverService.nt] +DisplayName=%SERVICE% +ServiceType=1 +StartType=3 +ErrorControl=1 +ServiceBinary=%12%\USBSER.sys + +;------------------------------------------------------------------------------ +; Vista-64bit Sections +;------------------------------------------------------------------------------ + +[DriverInstall.NTamd64] +include=mdmcpq.inf +CopyFiles=DriverCopyFiles.NTamd64 +AddReg=DriverInstall.NTamd64.AddReg + +[DriverCopyFiles.NTamd64] +USBSER.sys,,,0x20 + +[DriverInstall.NTamd64.AddReg] +HKR,,DevLoader,,*ntkern +HKR,,NTMPDriver,,USBSER.sys +HKR,,EnumPropPages32,,"MsPorts.dll,SerialPortPropPageProvider" + +[DriverInstall.NTamd64.Services] +AddService=usbser, 0x00000002, DriverService.NTamd64 + +[DriverService.NTamd64] +DisplayName=%SERVICE% +ServiceType=1 +StartType=3 +ErrorControl=1 +ServiceBinary=%12%\USBSER.sys + + +;------------------------------------------------------------------------------ +; Vendor and Product ID Definitions +;------------------------------------------------------------------------------ +; When developing your USB device, the VID and PID used in the PC side +; application program and the firmware on the microcontroller must match. +; Modify the below line to use your VID and PID. Use the format as shown +; below. +; Note: One INF file can be used for multiple devices with different +; VID and PIDs. For each supported device, append +; ",USB\VID_xxxx&PID_yyyy" to the end of the line. +;------------------------------------------------------------------------------ +[SourceDisksFiles] +[SourceDisksNames] +[DeviceList] +%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02 + +[DeviceList.NTamd64] +%DESCRIPTION%=DriverInstall, USB\VID_0525&PID_A4A7, USB\VID_0525&PID_A4AB&MI_02 + + +;------------------------------------------------------------------------------ +; String Definitions +;------------------------------------------------------------------------------ +;Modify these strings to customize your device +;------------------------------------------------------------------------------ +[Strings] +Linux = "Linux Developer Community" +DESCRIPTION = "Gadget Serial" +SERVICE = "USB RS-232 Emulation Driver" diff --git a/Documentation/usb/linux.inf b/Documentation/usb/linux.inf index af71d87d9e94..4dee95851224 100644 --- a/Documentation/usb/linux.inf +++ b/Documentation/usb/linux.inf @@ -1,200 +1,66 @@ -; MS-Windows driver config matching some basic modes of the -; Linux-USB Ethernet/RNDIS gadget firmware: -; -; - RNDIS plus CDC Ethernet ... this may be familiar as a DOCSIS -; cable modem profile, and supports most non-Microsoft USB hosts -; -; - RNDIS plus CDC Subset ... used by hardware that incapable of -; full CDC Ethernet support. -; -; Microsoft only directly supports RNDIS drivers, and bundled them into XP. -; The Microsoft "Remote NDIS USB Driver Kit" is currently found at: -; http://www.microsoft.com/whdc/device/network/ndis/rmndis.mspx - +; Based on template INF file found at +; <http://msdn.microsoft.com/en-us/library/ff570620.aspx> +; which was: +; Copyright (c) Microsoft Corporation +; and released under the MLPL as found at: +; <http://msdn.microsoft.com/en-us/cc300389.aspx#MLPL>. +; For use only on Windows operating systems. [Version] -Signature = "$CHICAGO$" +Signature = "$Windows NT$" Class = Net ClassGUID = {4d36e972-e325-11ce-bfc1-08002be10318} Provider = %Linux% -Compatible = 1 -MillenniumPreferred = .ME -DriverVer = 03/30/2004,0.0.0.0 -; catalog file would be used by WHQL -;CatalogFile = Linux.cat +DriverVer = 06/21/2006,6.0.6000.16384 [Manufacturer] -%Linux% = LinuxDevices,NT.5.1 +%Linux% = LinuxDevices,NTx86,NTamd64,NTia64 + +; Decoration for x86 architecture +[LinuxDevices.NTx86] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 -[LinuxDevices] -; NetChip IDs, used by both firmware modes -%LinuxDevice% = RNDIS, USB\VID_0525&PID_a4a2 +; Decoration for x64 architecture +[LinuxDevices.NTamd64] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 -[LinuxDevices.NT.5.1] -%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2 +; Decoration for ia64 architecture +[LinuxDevices.NTia64] +%LinuxDevice% = RNDIS.NT.5.1, USB\VID_0525&PID_a4a2, USB\VID_0525&PID_a4ab&MI_00 +;@@@ This is the common setting for setup [ControlFlags] ExcludeFromSelect=* -; Windows 98, Windows 98 Second Edition specific sections -------- - -[RNDIS] -DeviceID = usb8023 -MaxInstance = 512 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_98, RNDIS_AddReg_Common - -[RNDIS_AddReg_98] -HKR, , DevLoader, 0, *ndis -HKR, , DeviceVxDs, 0, usb8023.sys -HKR, NDIS, LogDriverName, 0, "usb8023" -HKR, NDIS, MajorNdisVersion, 1, 5 -HKR, NDIS, MinorNdisVersion, 1, 0 -HKR, Ndi\Interfaces, DefUpper, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, DefLower, 0, "ethernet" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" -HKR, Ndi\Install, ndis3, 0, "RNDIS_Install_98" -HKR, Ndi\Install, ndis4, 0, "RNDIS_Install_98" -HKR, Ndi\Install, ndis5, 0, "RNDIS_Install_98" -HKR, Ndi, DeviceId, 0, "USB\VID_0525&PID_a4a2" - -[RNDIS_Install_98] -CopyFiles=RNDIS_CopyFiles_98 - -[RNDIS_CopyFiles_98] -usb8023.sys, usb8023w.sys, , 0 -rndismp.sys, rndismpw.sys, , 0 - -; Windows Millennium Edition specific sections -------------------- - -[RNDIS.ME] -DeviceID = usb8023 -MaxInstance = 512 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_ME, RNDIS_AddReg_Common -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 - -[RNDIS_AddReg_ME] -HKR, , DevLoader, 0, *ndis -HKR, , DeviceVxDs, 0, usb8023.sys -HKR, NDIS, LogDriverName, 0, "usb8023" -HKR, NDIS, MajorNdisVersion, 1, 5 -HKR, NDIS, MinorNdisVersion, 1, 0 -HKR, Ndi\Interfaces, DefUpper, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, DefLower, 0, "ethernet" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis3,ndis4,ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" -HKR, Ndi\Install, ndis3, 0, "RNDIS_Install_ME" -HKR, Ndi\Install, ndis4, 0, "RNDIS_Install_ME" -HKR, Ndi\Install, ndis5, 0, "RNDIS_Install_ME" -HKR, Ndi, DeviceId, 0, "USB\VID_0525&PID_a4a2" - -[RNDIS_Install_ME] -CopyFiles=RNDIS_CopyFiles_ME - -[RNDIS_CopyFiles_ME] -usb8023.sys, usb8023m.sys, , 0 -rndismp.sys, rndismpm.sys, , 0 - -; Windows 2000 specific sections --------------------------------- - -[RNDIS.NT] -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_NT, RNDIS_AddReg_Common -CopyFiles = RNDIS_CopyFiles_NT - -[RNDIS.NT.Services] -AddService = USB_RNDIS, 2, RNDIS_ServiceInst_NT, RNDIS_EventLog - -[RNDIS_CopyFiles_NT] -; no rename of files on Windows 2000, use the 'k' names as is -usb8023k.sys, , , 0 -rndismpk.sys, , , 0 - -[RNDIS_ServiceInst_NT] -DisplayName = %ServiceDisplayName% -ServiceType = 1 -StartType = 3 -ErrorControl = 1 -ServiceBinary = %12%\usb8023k.sys -LoadOrderGroup = NDIS -AddReg = RNDIS_WMI_AddReg_NT - -[RNDIS_WMI_AddReg_NT] -HKR, , MofImagePath, 0x00020000, "System32\drivers\rndismpk.sys" - -; Windows XP specific sections ----------------------------------- - +; DDInstall section +; References the in-build Netrndis.inf [RNDIS.NT.5.1] -Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI -BusType = 15 -DriverVer = 03/30/2004,0.0.0.0 -AddReg = RNDIS_AddReg_NT, RNDIS_AddReg_Common -; no copyfiles - the files are already in place - +Characteristics = 0x84 ; NCF_PHYSICAL + NCF_HAS_UI +BusType = 15 +; NEVER REMOVE THE FOLLOWING REFERENCE FOR NETRNDIS.INF +include = netrndis.inf +needs = Usb_Rndis.ndi +AddReg = Rndis_AddReg_Vista + +; DDInstal.Services section [RNDIS.NT.5.1.Services] -AddService = USB_RNDIS, 2, RNDIS_ServiceInst_51, RNDIS_EventLog - -[RNDIS_ServiceInst_51] -DisplayName = %ServiceDisplayName% -ServiceType = 1 -StartType = 3 -ErrorControl = 1 -ServiceBinary = %12%\usb8023.sys -LoadOrderGroup = NDIS -AddReg = RNDIS_WMI_AddReg_51 - -[RNDIS_WMI_AddReg_51] -HKR, , MofImagePath, 0x00020000, "System32\drivers\rndismp.sys" - -; Windows 2000 and Windows XP common sections -------------------- - -[RNDIS_AddReg_NT] -HKR, Ndi, Service, 0, "USB_RNDIS" -HKR, Ndi\Interfaces, UpperRange, 0, "ndis5" -HKR, Ndi\Interfaces, LowerRange, 0, "ethernet" - -[RNDIS_EventLog] -AddReg = RNDIS_EventLog_AddReg - -[RNDIS_EventLog_AddReg] -HKR, , EventMessageFile, 0x00020000, "%%SystemRoot%%\System32\netevent.dll" -HKR, , TypesSupported, 0x00010001, 7 - -; Common Sections ------------------------------------------------- - -[RNDIS_AddReg_Common] -HKR, NDI\params\NetworkAddress, ParamDesc, 0, %NetworkAddress% -HKR, NDI\params\NetworkAddress, type, 0, "edit" -HKR, NDI\params\NetworkAddress, LimitText, 0, "12" -HKR, NDI\params\NetworkAddress, UpperCase, 0, "1" -HKR, NDI\params\NetworkAddress, default, 0, " " -HKR, NDI\params\NetworkAddress, optional, 0, "1" - -[SourceDisksNames] -1=%SourceDisk%,,1 - -[SourceDisksFiles] -usb8023m.sys=1 -rndismpm.sys=1 -usb8023w.sys=1 -rndismpw.sys=1 -usb8023k.sys=1 -rndismpk.sys=1 - -[DestinationDirs] -RNDIS_CopyFiles_98 = 10, system32/drivers -RNDIS_CopyFiles_ME = 10, system32/drivers -RNDIS_CopyFiles_NT = 12 +include = netrndis.inf +needs = Usb_Rndis.ndi.Services + +; Optional registry settings. You can modify as needed. +[RNDIS_AddReg_Vista] +HKR, NDI\params\VistaProperty, ParamDesc, 0, %Vista_Property% +HKR, NDI\params\VistaProperty, type, 0, "edit" +HKR, NDI\params\VistaProperty, LimitText, 0, "12" +HKR, NDI\params\VistaProperty, UpperCase, 0, "1" +HKR, NDI\params\VistaProperty, default, 0, " " +HKR, NDI\params\VistaProperty, optional, 0, "1" + +; No sys copyfiles - the sys files are already in-build +; (part of the operating system). +; We do not support XP SP1-, 2003 SP1-, ME, 9x. [Strings] -ServiceDisplayName = "USB Remote NDIS Network Device Driver" -NetworkAddress = "Network Address" Linux = "Linux Developer Community" LinuxDevice = "Linux USB Ethernet/RNDIS Gadget" -SourceDisk = "Ethernet/RNDIS Gadget Driver Install Disk" - +Vista_Property = "Optional Vista Property" diff --git a/Documentation/video4linux/v4l2-controls.txt b/Documentation/video4linux/v4l2-controls.txt new file mode 100644 index 000000000000..8773778d23fc --- /dev/null +++ b/Documentation/video4linux/v4l2-controls.txt @@ -0,0 +1,648 @@ +Introduction +============ + +The V4L2 control API seems simple enough, but quickly becomes very hard to +implement correctly in drivers. But much of the code needed to handle controls +is actually not driver specific and can be moved to the V4L core framework. + +After all, the only part that a driver developer is interested in is: + +1) How do I add a control? +2) How do I set the control's value? (i.e. s_ctrl) + +And occasionally: + +3) How do I get the control's value? (i.e. g_volatile_ctrl) +4) How do I validate the user's proposed control value? (i.e. try_ctrl) + +All the rest is something that can be done centrally. + +The control framework was created in order to implement all the rules of the +V4L2 specification with respect to controls in a central place. And to make +life as easy as possible for the driver developer. + +Note that the control framework relies on the presence of a struct v4l2_device +for V4L2 drivers and struct v4l2_subdev for sub-device drivers. + + +Objects in the framework +======================== + +There are two main objects: + +The v4l2_ctrl object describes the control properties and keeps track of the +control's value (both the current value and the proposed new value). + +v4l2_ctrl_handler is the object that keeps track of controls. It maintains a +list of v4l2_ctrl objects that it owns and another list of references to +controls, possibly to controls owned by other handlers. + + +Basic usage for V4L2 and sub-device drivers +=========================================== + +1) Prepare the driver: + +1.1) Add the handler to your driver's top-level struct: + + struct foo_dev { + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; + + struct foo_dev *foo; + +1.2) Initialize the handler: + + v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); + + The second argument is a hint telling the function how many controls this + handler is expected to handle. It will allocate a hashtable based on this + information. It is a hint only. + +1.3) Hook the control handler into the driver: + +1.3.1) For V4L2 drivers do this: + + struct foo_dev { + ... + struct v4l2_device v4l2_dev; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; + + foo->v4l2_dev.ctrl_handler = &foo->ctrl_handler; + + Where foo->v4l2_dev is of type struct v4l2_device. + + Finally, remove all control functions from your v4l2_ioctl_ops: + vidioc_queryctrl, vidioc_querymenu, vidioc_g_ctrl, vidioc_s_ctrl, + vidioc_g_ext_ctrls, vidioc_try_ext_ctrls and vidioc_s_ext_ctrls. + Those are now no longer needed. + +1.3.2) For sub-device drivers do this: + + struct foo_dev { + ... + struct v4l2_subdev sd; + ... + struct v4l2_ctrl_handler ctrl_handler; + ... + }; + + foo->sd.ctrl_handler = &foo->ctrl_handler; + + Where foo->sd is of type struct v4l2_subdev. + + And set all core control ops in your struct v4l2_subdev_core_ops to these + helpers: + + .queryctrl = v4l2_subdev_queryctrl, + .querymenu = v4l2_subdev_querymenu, + .g_ctrl = v4l2_subdev_g_ctrl, + .s_ctrl = v4l2_subdev_s_ctrl, + .g_ext_ctrls = v4l2_subdev_g_ext_ctrls, + .try_ext_ctrls = v4l2_subdev_try_ext_ctrls, + .s_ext_ctrls = v4l2_subdev_s_ext_ctrls, + + Note: this is a temporary solution only. Once all V4L2 drivers that depend + on subdev drivers are converted to the control framework these helpers will + no longer be needed. + +1.4) Clean up the handler at the end: + + v4l2_ctrl_handler_free(&foo->ctrl_handler); + + +2) Add controls: + +You add non-menu controls by calling v4l2_ctrl_new_std: + + struct v4l2_ctrl *v4l2_ctrl_new_std(struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, + u32 id, s32 min, s32 max, u32 step, s32 def); + +Menu controls are added by calling v4l2_ctrl_new_std_menu: + + struct v4l2_ctrl *v4l2_ctrl_new_std_menu(struct v4l2_ctrl_handler *hdl, + const struct v4l2_ctrl_ops *ops, + u32 id, s32 max, s32 skip_mask, s32 def); + +These functions are typically called right after the v4l2_ctrl_handler_init: + + v4l2_ctrl_handler_init(&foo->ctrl_handler, nr_of_controls); + v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_BRIGHTNESS, 0, 255, 1, 128); + v4l2_ctrl_new_std(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_CONTRAST, 0, 255, 1, 128); + v4l2_ctrl_new_std_menu(&foo->ctrl_handler, &foo_ctrl_ops, + V4L2_CID_POWER_LINE_FREQUENCY, + V4L2_CID_POWER_LINE_FREQUENCY_60HZ, 0, + V4L2_CID_POWER_LINE_FREQUENCY_DISABLED); + ... + if (foo->ctrl_handler.error) { + int err = foo->ctrl_handler.error; + + v4l2_ctrl_handler_free(&foo->ctrl_handler); + return err; + } + +The v4l2_ctrl_new_std function returns the v4l2_ctrl pointer to the new +control, but if you do not need to access the pointer outside the control ops, +then there is no need to store it. + +The v4l2_ctrl_new_std function will fill in most fields based on the control +ID except for the min, max, step and default values. These are passed in the +last four arguments. These values are driver specific while control attributes +like type, name, flags are all global. The control's current value will be set +to the default value. + +The v4l2_ctrl_new_std_menu function is very similar but it is used for menu +controls. There is no min argument since that is always 0 for menu controls, +and instead of a step there is a skip_mask argument: if bit X is 1, then menu +item X is skipped. + +Note that if something fails, the function will return NULL or an error and +set ctrl_handler->error to the error code. If ctrl_handler->error was already +set, then it will just return and do nothing. This is also true for +v4l2_ctrl_handler_init if it cannot allocate the internal data structure. + +This makes it easy to init the handler and just add all controls and only check +the error code at the end. Saves a lot of repetitive error checking. + +It is recommended to add controls in ascending control ID order: it will be +a bit faster that way. + +3) Optionally force initial control setup: + + v4l2_ctrl_handler_setup(&foo->ctrl_handler); + +This will call s_ctrl for all controls unconditionally. Effectively this +initializes the hardware to the default control values. It is recommended +that you do this as this ensures that both the internal data structures and +the hardware are in sync. + +4) Finally: implement the v4l2_ctrl_ops + + static const struct v4l2_ctrl_ops foo_ctrl_ops = { + .s_ctrl = foo_s_ctrl, + }; + +Usually all you need is s_ctrl: + + static int foo_s_ctrl(struct v4l2_ctrl *ctrl) + { + struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler); + + switch (ctrl->id) { + case V4L2_CID_BRIGHTNESS: + write_reg(0x123, ctrl->val); + break; + case V4L2_CID_CONTRAST: + write_reg(0x456, ctrl->val); + break; + } + return 0; + } + +The control ops are called with the v4l2_ctrl pointer as argument. +The new control value has already been validated, so all you need to do is +to actually update the hardware registers. + +You're done! And this is sufficient for most of the drivers we have. No need +to do any validation of control values, or implement QUERYCTRL/QUERYMENU. And +G/S_CTRL as well as G/TRY/S_EXT_CTRLS are automatically supported. + + +============================================================================== + +The remainder of this document deals with more advanced topics and scenarios. +In practice the basic usage as described above is sufficient for most drivers. + +=============================================================================== + + +Inheriting Controls +=================== + +When a sub-device is registered with a V4L2 driver by calling +v4l2_device_register_subdev() and the ctrl_handler fields of both v4l2_subdev +and v4l2_device are set, then the controls of the subdev will become +automatically available in the V4L2 driver as well. If the subdev driver +contains controls that already exist in the V4L2 driver, then those will be +skipped (so a V4L2 driver can always override a subdev control). + +What happens here is that v4l2_device_register_subdev() calls +v4l2_ctrl_add_handler() adding the controls of the subdev to the controls +of v4l2_device. + + +Accessing Control Values +======================== + +The v4l2_ctrl struct contains these two unions: + + /* The current control value. */ + union { + s32 val; + s64 val64; + char *string; + } cur; + + /* The new control value. */ + union { + s32 val; + s64 val64; + char *string; + }; + +Within the control ops you can freely use these. The val and val64 speak for +themselves. The string pointers point to character buffers of length +ctrl->maximum + 1, and are always 0-terminated. + +In most cases 'cur' contains the current cached control value. When you create +a new control this value is made identical to the default value. After calling +v4l2_ctrl_handler_setup() this value is passed to the hardware. It is generally +a good idea to call this function. + +Whenever a new value is set that new value is automatically cached. This means +that most drivers do not need to implement the g_volatile_ctrl() op. The +exception is for controls that return a volatile register such as a signal +strength read-out that changes continuously. In that case you will need to +implement g_volatile_ctrl like this: + + static int foo_g_volatile_ctrl(struct v4l2_ctrl *ctrl) + { + switch (ctrl->id) { + case V4L2_CID_BRIGHTNESS: + ctrl->cur.val = read_reg(0x123); + break; + } + } + +The 'new value' union is not used in g_volatile_ctrl. In general controls +that need to implement g_volatile_ctrl are read-only controls. + +To mark a control as volatile you have to set the is_volatile flag: + + ctrl = v4l2_ctrl_new_std(&sd->ctrl_handler, ...); + if (ctrl) + ctrl->is_volatile = 1; + +For try/s_ctrl the new values (i.e. as passed by the user) are filled in and +you can modify them in try_ctrl or set them in s_ctrl. The 'cur' union +contains the current value, which you can use (but not change!) as well. + +If s_ctrl returns 0 (OK), then the control framework will copy the new final +values to the 'cur' union. + +While in g_volatile/s/try_ctrl you can access the value of all controls owned +by the same handler since the handler's lock is held. If you need to access +the value of controls owned by other handlers, then you have to be very careful +not to introduce deadlocks. + +Outside of the control ops you have to go through to helper functions to get +or set a single control value safely in your driver: + + s32 v4l2_ctrl_g_ctrl(struct v4l2_ctrl *ctrl); + int v4l2_ctrl_s_ctrl(struct v4l2_ctrl *ctrl, s32 val); + +These functions go through the control framework just as VIDIOC_G/S_CTRL ioctls +do. Don't use these inside the control ops g_volatile/s/try_ctrl, though, that +will result in a deadlock since these helpers lock the handler as well. + +You can also take the handler lock yourself: + + mutex_lock(&state->ctrl_handler.lock); + printk(KERN_INFO "String value is '%s'\n", ctrl1->cur.string); + printk(KERN_INFO "Integer value is '%s'\n", ctrl2->cur.val); + mutex_unlock(&state->ctrl_handler.lock); + + +Menu Controls +============= + +The v4l2_ctrl struct contains this union: + + union { + u32 step; + u32 menu_skip_mask; + }; + +For menu controls menu_skip_mask is used. What it does is that it allows you +to easily exclude certain menu items. This is used in the VIDIOC_QUERYMENU +implementation where you can return -EINVAL if a certain menu item is not +present. Note that VIDIOC_QUERYCTRL always returns a step value of 1 for +menu controls. + +A good example is the MPEG Audio Layer II Bitrate menu control where the +menu is a list of standardized possible bitrates. But in practice hardware +implementations will only support a subset of those. By setting the skip +mask you can tell the framework which menu items should be skipped. Setting +it to 0 means that all menu items are supported. + +You set this mask either through the v4l2_ctrl_config struct for a custom +control, or by calling v4l2_ctrl_new_std_menu(). + + +Custom Controls +=============== + +Driver specific controls can be created using v4l2_ctrl_new_custom(): + + static const struct v4l2_ctrl_config ctrl_filter = { + .ops = &ctrl_custom_ops, + .id = V4L2_CID_MPEG_CX2341X_VIDEO_SPATIAL_FILTER, + .name = "Spatial Filter", + .type = V4L2_CTRL_TYPE_INTEGER, + .flags = V4L2_CTRL_FLAG_SLIDER, + .max = 15, + .step = 1, + }; + + ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_filter, NULL); + +The last argument is the priv pointer which can be set to driver-specific +private data. + +The v4l2_ctrl_config struct also has fields to set the is_private and is_volatile +flags. + +If the name field is not set, then the framework will assume this is a standard +control and will fill in the name, type and flags fields accordingly. + + +Active and Grabbed Controls +=========================== + +If you get more complex relationships between controls, then you may have to +activate and deactivate controls. For example, if the Chroma AGC control is +on, then the Chroma Gain control is inactive. That is, you may set it, but +the value will not be used by the hardware as long as the automatic gain +control is on. Typically user interfaces can disable such input fields. + +You can set the 'active' status using v4l2_ctrl_activate(). By default all +controls are active. Note that the framework does not check for this flag. +It is meant purely for GUIs. The function is typically called from within +s_ctrl. + +The other flag is the 'grabbed' flag. A grabbed control means that you cannot +change it because it is in use by some resource. Typical examples are MPEG +bitrate controls that cannot be changed while capturing is in progress. + +If a control is set to 'grabbed' using v4l2_ctrl_grab(), then the framework +will return -EBUSY if an attempt is made to set this control. The +v4l2_ctrl_grab() function is typically called from the driver when it +starts or stops streaming. + + +Control Clusters +================ + +By default all controls are independent from the others. But in more +complex scenarios you can get dependencies from one control to another. +In that case you need to 'cluster' them: + + struct foo { + struct v4l2_ctrl_handler ctrl_handler; +#define AUDIO_CL_VOLUME (0) +#define AUDIO_CL_MUTE (1) + struct v4l2_ctrl *audio_cluster[2]; + ... + }; + + state->audio_cluster[AUDIO_CL_VOLUME] = + v4l2_ctrl_new_std(&state->ctrl_handler, ...); + state->audio_cluster[AUDIO_CL_MUTE] = + v4l2_ctrl_new_std(&state->ctrl_handler, ...); + v4l2_ctrl_cluster(ARRAY_SIZE(state->audio_cluster), state->audio_cluster); + +From now on whenever one or more of the controls belonging to the same +cluster is set (or 'gotten', or 'tried'), only the control ops of the first +control ('volume' in this example) is called. You effectively create a new +composite control. Similar to how a 'struct' works in C. + +So when s_ctrl is called with V4L2_CID_AUDIO_VOLUME as argument, you should set +all two controls belonging to the audio_cluster: + + static int foo_s_ctrl(struct v4l2_ctrl *ctrl) + { + struct foo *state = container_of(ctrl->handler, struct foo, ctrl_handler); + + switch (ctrl->id) { + case V4L2_CID_AUDIO_VOLUME: { + struct v4l2_ctrl *mute = ctrl->cluster[AUDIO_CL_MUTE]; + + write_reg(0x123, mute->val ? 0 : ctrl->val); + break; + } + case V4L2_CID_CONTRAST: + write_reg(0x456, ctrl->val); + break; + } + return 0; + } + +In the example above the following are equivalent for the VOLUME case: + + ctrl == ctrl->cluster[AUDIO_CL_VOLUME] == state->audio_cluster[AUDIO_CL_VOLUME] + ctrl->cluster[AUDIO_CL_MUTE] == state->audio_cluster[AUDIO_CL_MUTE] + +Note that controls in a cluster may be NULL. For example, if for some +reason mute was never added (because the hardware doesn't support that +particular feature), then mute will be NULL. So in that case we have a +cluster of 2 controls, of which only 1 is actually instantiated. The +only restriction is that the first control of the cluster must always be +present, since that is the 'master' control of the cluster. The master +control is the one that identifies the cluster and that provides the +pointer to the v4l2_ctrl_ops struct that is used for that cluster. + +Obviously, all controls in the cluster array must be initialized to either +a valid control or to NULL. + + +VIDIOC_LOG_STATUS Support +========================= + +This ioctl allow you to dump the current status of a driver to the kernel log. +The v4l2_ctrl_handler_log_status(ctrl_handler, prefix) can be used to dump the +value of the controls owned by the given handler to the log. You can supply a +prefix as well. If the prefix didn't end with a space, then ': ' will be added +for you. + + +Different Handlers for Different Video Nodes +============================================ + +Usually the V4L2 driver has just one control handler that is global for +all video nodes. But you can also specify different control handlers for +different video nodes. You can do that by manually setting the ctrl_handler +field of struct video_device. + +That is no problem if there are no subdevs involved but if there are, then +you need to block the automatic merging of subdev controls to the global +control handler. You do that by simply setting the ctrl_handler field in +struct v4l2_device to NULL. Now v4l2_device_register_subdev() will no longer +merge subdev controls. + +After each subdev was added, you will then have to call v4l2_ctrl_add_handler +manually to add the subdev's control handler (sd->ctrl_handler) to the desired +control handler. This control handler may be specific to the video_device or +for a subset of video_device's. For example: the radio device nodes only have +audio controls, while the video and vbi device nodes share the same control +handler for the audio and video controls. + +If you want to have one handler (e.g. for a radio device node) have a subset +of another handler (e.g. for a video device node), then you should first add +the controls to the first handler, add the other controls to the second +handler and finally add the first handler to the second. For example: + + v4l2_ctrl_new_std(&radio_ctrl_handler, &radio_ops, V4L2_CID_AUDIO_VOLUME, ...); + 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); + +Or you can add specific controls to a handler: + + volume = v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_AUDIO_VOLUME, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_BRIGHTNESS, ...); + v4l2_ctrl_new_std(&video_ctrl_handler, &ops, V4L2_CID_CONTRAST, ...); + v4l2_ctrl_add_ctrl(&radio_ctrl_handler, volume); + +What you should not do is make two identical controls for two handlers. +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_AUDIO_MUTE, ...); + +This would be bad since muting the radio would not change the video mute +control. The rule is to have one control for each hardware 'knob' that you +can twiddle. + + +Finding Controls +================ + +Normally you have created the controls yourself and you can store the struct +v4l2_ctrl pointer into your own struct. + +But sometimes you need to find a control from another handler that you do +not own. For example, if you have to find a volume control from a subdev. + +You can do that by calling v4l2_ctrl_find: + + struct v4l2_ctrl *volume; + + volume = v4l2_ctrl_find(sd->ctrl_handler, V4L2_CID_AUDIO_VOLUME); + +Since v4l2_ctrl_find will lock the handler you have to be careful where you +use it. For example, this is not a good idea: + + struct v4l2_ctrl_handler ctrl_handler; + + v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_BRIGHTNESS, ...); + v4l2_ctrl_new_std(&ctrl_handler, &video_ops, V4L2_CID_CONTRAST, ...); + +...and in video_ops.s_ctrl: + + case V4L2_CID_BRIGHTNESS: + contrast = v4l2_find_ctrl(&ctrl_handler, V4L2_CID_CONTRAST); + ... + +When s_ctrl is called by the framework the ctrl_handler.lock is already taken, so +attempting to find another control from the same handler will deadlock. + +It is recommended not to use this function from inside the control ops. + + +Inheriting Controls +=================== + +When one control handler is added to another using v4l2_ctrl_add_handler, then +by default all controls from one are merged to the other. But a subdev might +have low-level controls that make sense for some advanced embedded system, but +not when it is used in consumer-level hardware. In that case you want to keep +those low-level controls local to the subdev. You can do this by simply +setting the 'is_private' flag of the control to 1: + + static const struct v4l2_ctrl_config ctrl_private = { + .ops = &ctrl_custom_ops, + .id = V4L2_CID_..., + .name = "Some Private Control", + .type = V4L2_CTRL_TYPE_INTEGER, + .max = 15, + .step = 1, + .is_private = 1, + }; + + ctrl = v4l2_ctrl_new_custom(&foo->ctrl_handler, &ctrl_private, NULL); + +These controls will now be skipped when v4l2_ctrl_add_handler is called. + + +V4L2_CTRL_TYPE_CTRL_CLASS Controls +================================== + +Controls of this type can be used by GUIs to get the name of the control class. +A fully featured GUI can make a dialog with multiple tabs with each tab +containing the controls belonging to a particular control class. The name of +each tab can be found by querying a special control with ID <control class | 1>. + +Drivers do not have to care about this. The framework will automatically add +a control of this type whenever the first control belonging to a new control +class is added. + + +Differences from the Spec +========================= + +There are a few places where the framework acts slightly differently from the +V4L2 Specification. Those differences are described in this section. We will +have to see whether we need to adjust the spec or not. + +1) It is no longer required to have all controls contained in a +v4l2_ext_control array be from the same control class. The framework will be +able to handle any type of control in the array. You need to set ctrl_class +to 0 in order to enable this. If ctrl_class is non-zero, then it will still +check that all controls belong to that control class. + +If you set ctrl_class to 0 and count to 0, then it will only return an error +if there are no controls at all. + +2) Clarified the way error_idx works. For get and set it will be equal to +count if nothing was done yet. If it is less than count then only the controls +up to error_idx-1 were successfully applied. + +3) When attempting to read a button control the framework will return -EACCES +instead of -EINVAL as stated in the spec. It seems to make more sense since +button controls are write-only controls. + +4) Attempting to write to a read-only control will return -EACCES instead of +-EINVAL as the spec says. + +5) The spec does not mention what should happen when you try to set/get a +control class controls. ivtv currently returns -EINVAL (indicating that the +control ID does not exist) while the framework will return -EACCES, which +makes more sense. + + +Proposals for Extensions +======================== + +Some ideas for future extensions to the spec: + +1) Add a V4L2_CTRL_FLAG_HEX to have values shown as hexadecimal instead of +decimal. Useful for e.g. video_mute_yuv. + +2) It is possible to mark in the controls array which controls have been +successfully written and which failed by for example adding a bit to the +control ID. Not sure if it is worth the effort, though. + +3) Trying to set volatile inactive controls should result in -EACCESS. + +4) Add a new flag to mark volatile controls. Any application that wants +to store the state of the controls can then skip volatile inactive controls. +Currently it is not possible to detect such controls. |