diff options
37220 files changed, 5231818 insertions, 2497749 deletions
diff --git a/.gitignore b/.gitignore index 57af07cf7e68..7e9932e55475 100644 --- a/.gitignore +++ b/.gitignore @@ -29,6 +29,7 @@ modules.builtin *.bz2 *.lzma *.xz +*.lz4 *.lzo *.patch *.gcno @@ -60,7 +61,6 @@ modules.builtin # Generated include files # include/config -include/linux/version.h include/generated arch/*/include/generated @@ -84,3 +84,11 @@ GTAGS *.orig *~ \#*# + +# +# Leavings from module signing +# +extra_certificates +signing_key.priv +signing_key.x509 +x509.genkey @@ -111,5 +111,8 @@ Uwe Kleine-König <ukleinek@informatik.uni-freiburg.de> Uwe Kleine-König <ukl@pengutronix.de> Uwe Kleine-König <Uwe.Kleine-Koenig@digi.com> Valdis Kletnieks <Valdis.Kletnieks@vt.edu> +Viresh Kumar <viresh.linux@gmail.com> <viresh.kumar@st.com> Takashi YOSHII <takashi.yoshii.zj@renesas.com> Yusuke Goda <goda.yusuke@renesas.com> +Gustavo Padovan <gustavo@las.ic.unicamp.br> +Gustavo Padovan <padovan@profusion.mobi> @@ -514,6 +514,11 @@ S: Bessemerstraat 21 S: Amsterdam S: The Netherlands +N: NeilBrown +E: neil@brown.name +P: 4096R/566281B9 1BC6 29EB D390 D870 7B5F 497A 39EC 9EDD 5662 81B9 +D: NFSD Maintainer 2000-2007 + N: Zach Brown E: zab@zabbo.net D: maestro pci sound @@ -632,14 +637,13 @@ S: 14509 NE 39th Street #1096 S: Bellevue, Washington 98007 S: USA -N: Christopher L. Cheney -E: ccheney@debian.org -E: ccheney@cheney.cx -W: http://www.cheney.cx +N: Chris Cheney +E: chris.cheney@gmail.com +E: ccheney@redhat.com P: 1024D/8E384AF2 2D31 1927 87D7 1F24 9FF9 1BC5 D106 5AB3 8E38 4AF2 D: Vista Imaging usb webcam driver -S: 314 Prince of Wales -S: Conroe, TX 77304 +S: 2308 Therrell Way +S: McKinney, TX 75070 S: USA N: Stuart Cheshire @@ -688,10 +692,13 @@ S: Oxfordshire, UK. N: Kees Cook E: kees@outflux.net -W: http://outflux.net/ -P: 1024D/17063E6D 9FA3 C49C 23C9 D1BC 2E30 1975 1FFF 4BA9 1706 3E6D -D: Minor updates to SCSI types, added /proc/pid/maps protection +E: kees@ubuntu.com +E: keescook@chromium.org +W: http://outflux.net/blog/ +P: 4096R/DC6DC026 A5C3 F68F 229D D60F 723E 6E13 8972 F4DF DC6D C026 +D: Various security things, bug fixes, and documentation. S: (ask for current address) +S: Portland, Oregon S: USA N: Robin Cornelius @@ -753,6 +760,10 @@ S: Northampton S: NN1 3QT S: United Kingdom +N: Massimo Dal Zotto +E: dz@debian.org +D: i8k Dell laptop SMM driver + N: Uwe Dannowski E: Uwe.Dannowski@ira.uka.de W: http://i30www.ira.uka.de/~dannowsk/ @@ -945,11 +956,11 @@ S: Blacksburg, Virginia 24061 S: USA N: Randy Dunlap -E: rdunlap@xenotime.net -W: http://www.xenotime.net/linux/linux.html -W: http://www.linux-usb.org +E: rdunlap@infradead.org +W: http://www.infradead.org/~rdunlap/ D: Linux-USB subsystem, USB core/UHCI/printer/storage drivers D: x86 SMP, ACPI, bootflag hacking +D: documentation, builds S: (ask for current address) S: USA @@ -1108,6 +1119,7 @@ D: author of userfs filesystem D: Improved mmap and munmap handling D: General mm minor tidyups D: autofs v4 maintainer +D: Xen subsystem S: 987 Alabama St S: San Francisco S: CA, 94110 @@ -1502,6 +1514,14 @@ D: Natsemi ethernet D: Cobalt Networks (x86) support D: This-and-That +N: Mark M. Hoffman +E: mhoffman@lightlink.com +D: asb100, lm93 and smsc47b397 hardware monitoring drivers +D: hwmon subsystem core +D: hwmon subsystem maintainer +D: i2c-sis96x and i2c-stub SMBus drivers +S: USA + N: Dirk Hohndel E: hohndel@suse.de D: The XFree86[tm] Project @@ -1564,12 +1584,12 @@ S: Wantage, New Jersey 07461 S: USA N: Harald Hoyer -E: harald.hoyer@parzelle.de -W: http://parzelle.de/ +E: harald@redhat.com +W: http://www.harald-hoyer.de D: ip_masq_quake D: md boot support -S: Hohe Strasse 30 -S: D-70176 Stuttgart +S: Am Strand 5 +S: D-19063 Schwerin S: Germany N: Jan Hubicka @@ -1815,6 +1835,11 @@ S: Kattreinstr 38 S: D-64295 S: Germany +N: Avi Kivity +E: avi.kivity@gmail.com +D: Kernel-based Virtual Machine (KVM) +S: Ra'annana, Israel + N: Andi Kleen E: andi@firstfloor.org U: http://www.halobates.de @@ -2783,8 +2808,7 @@ S: Ottawa, Ontario S: Canada K2P 0X8 N: Mikael Pettersson -E: mikpe@it.uu.se -W: http://user.it.uu.se/~mikpe/linux/ +E: mikpelinux@gmail.com D: Miscellaneous fixes N: Reed H. Petty @@ -3806,8 +3830,8 @@ D: INFO-SHEET, former maintainer D: Author of the longest-living linux bug N: Jonathan Woithe -E: jwoithe@physics.adelaide.edu.au -W: http://www.physics.adelaide.edu.au/~jwoithe +E: jwoithe@just42.net +W: http:/www.just42.net/jwoithe D: ALS-007 sound card extensions to Sound Blaster driver S: 20 Jordan St S: Valley View, SA 5093 diff --git a/Documentation/00-INDEX b/Documentation/00-INDEX index 65bbd2622396..38f8444bdd0e 100644 --- a/Documentation/00-INDEX +++ b/Documentation/00-INDEX @@ -2,13 +2,13 @@ This is a brief list of all the files in ./linux/Documentation and what they contain. If you add a documentation file, please list it here in alphabetical order as well, or risk being hunted down like a rabid dog. -Please try and keep the descriptions small enough to fit on one line. +Please keep the descriptions small enough to fit on one line. Thanks -- Paul G. Following translations are available on the WWW: - - Japanese, maintained by the JF Project (JF@linux.or.jp), at - http://www.linux.or.jp/JF/ + - Japanese, maintained by the JF Project (jf@listserv.linux.or.jp), at + http://linuxjf.sourceforge.jp/ 00-INDEX - this file. @@ -20,24 +20,33 @@ BUG-HUNTING Changes - list of changes that break older software packages. CodingStyle - - how the boss likes the C code in the kernel to look. -development-process/ - - An extended tutorial on how to work with the kernel development - process. + - how the maintainers expect the C code in the kernel to look. DMA-API.txt - DMA API, pci_ API & extensions for non-consistent memory machines. +DMA-API-HOWTO.txt + - Dynamic DMA mapping Guide DMA-ISA-LPC.txt - How to do DMA with ISA (and LPC) devices. +DMA-attributes.txt + - listing of the various possible attributes a DMA region can have DocBook/ - directory with DocBook templates etc. for kernel documentation. +EDID/ + - directory with info on customizing EDID for broken gfx/displays. HOWTO - the process and procedures of how to do Linux kernel development. IPMI.txt - info on Linux Intelligent Platform Management Interface (IPMI) Driver. IRQ-affinity.txt - how to select which CPU(s) handle which interrupt events on SMP. +IRQ-domain.txt + - info on interrupt numbering and setting up IRQ domains. IRQ.txt - description of what an IRQ is. +Intel-IOMMU.txt + - basic info on the Intel IOMMU virtualization support. +Makefile + - some files in Documentation dir are actually sample code to build ManagementStyle - how to (attempt to) manage kernel hackers. RCU/ @@ -66,10 +75,16 @@ applying-patches.txt - description of various trees and how to apply their patches. arm/ - directory with info about Linux on the ARM architecture. +arm64/ + - directory with info about Linux on the 64 bit ARM architecture. atomic_ops.txt - semantics and behavior of atomic and bitmask operations. auxdisplay/ - misc. LCD driver documentation (cfag12864b, ks0108). +backlight/ + - directory with info on controlling backlights in flat panel displays +bad_memory.txt + - how to use kernel parameters to exclude bad RAM regions. basic_profiling.txt - basic instructions for those who wants to profile Linux kernel. binfmt_misc.txt @@ -80,8 +95,14 @@ block/ - info on the Block I/O (BIO) layer. blockdev/ - info on block devices & drivers +braille-console.txt + - info on how to use serial devices for Braille support. +bt8xxgpio.txt + - info on how to modify a bt8xx video card for GPIO usage. btmrvl.txt - info on Marvell Bluetooth driver usage. +bus-devices/ + - directory with info on TI GPMC (General Purpose Memory Controller) bus-virt-phys-mapping.txt - how to access I/O mapped memory from within device drivers. cachetlb.txt @@ -90,6 +111,12 @@ cdrom/ - directory with information on the CD-ROM drivers that Linux has. cgroups/ - cgroups features, including cpusets and memory controller. +circular-buffers.txt + - how to make use of the existing circular buffer infrastructure +clk.txt + - info on the common clock framework +coccinelle.txt + - info on how to get and use the Coccinelle code checking tool. connector/ - docs on the netlink based userspace<->kernel space communication mod. console/ @@ -104,6 +131,8 @@ cpuidle/ - info on CPU_IDLE, CPU idle state management subsystem. cputopology.txt - documentation on how CPU topology info is exported via sysfs. +crc32.txt + - brief tutorial on CRC computation cris/ - directory with info about Linux on CRIS architecture. crypto/ @@ -112,40 +141,68 @@ dcdbas.txt - information on the Dell Systems Management Base Driver. debugging-modules.txt - some notes on debugging modules after Linux 2.6.3. +debugging-via-ohci1394.txt + - how to use firewire like a hardware debugger memory reader. dell_rbu.txt - document demonstrating the use of the Dell Remote BIOS Update driver. +development-process/ + - how to work with the mainline kernel development process. device-mapper/ - directory with info on Device Mapper. devices.txt - plain ASCII listing of all the nodes in /dev/ with major minor #'s. +devicetree/ + - directory with info on device tree files used by OF/PowerPC/ARM +digsig.txt + -info on the Digital Signature Verification API +dma-buf-sharing.txt + - the DMA Buffer Sharing API Guide +dmaengine.txt + -the DMA Engine API Guide dontdiff - file containing a list of files that should never be diff'ed. driver-model/ - directory with info about Linux driver model. dvb/ - info on Linux Digital Video Broadcast (DVB) subsystem. +dynamic-debug-howto.txt + - how to use the dynamic debug (dyndbg) feature. early-userspace/ - info about initramfs, klibc, and userspace early during boot. edac.txt - information on EDAC - Error Detection And Correction eisa.txt - info on EISA bus support. +email-clients.txt + - info on how to use e-mail to send un-mangled (git) patches. +extcon/ + - directory with porting guide for Android kernel switch driver. fault-injection/ - dir with docs about the fault injection capabilities infrastructure. fb/ - directory with info on the frame buffer graphics abstraction layer. -feature-removal-schedule.txt - - list of files and features that are going to be removed. filesystems/ - info on the vfs and the various filesystems that Linux supports. firmware_class/ - request_firmware() hotplug interface info. +flexible-arrays.txt + - how to make use of flexible sized arrays in linux +fmc/ + - information about the FMC bus abstraction frv/ - Fujitsu FR-V Linux documentation. +futex-requeue-pi.txt + - info on requeueing of tasks from a non-PI futex to a PI futex +gcov.txt + - use of GCC's coverage testing tool "gcov" with the Linux kernel gpio.txt - overview of GPIO (General Purpose Input/Output) access conventions. +hid/ + - directory with information on human interface devices highuid.txt - notes on the change from 16 bit to 32 bit user/group IDs. +hwspinlock.txt + - hardware spinlock provides hardware assistance for synchronization timers/ - info on the timer related topics hw_random.txt @@ -162,10 +219,14 @@ ia64/ - directory with info about Linux on Intel 64 bit architecture. infiniband/ - directory with documents concerning Linux InfiniBand support. +init.txt + - what to do when the kernel can't find the 1st process to run. initrd.txt - how to use the RAM disk as an initial/temporary root filesystem. input/ - info on Linux input device support. +intel_txt.txt + - info on intel Trusted Execution Technology (intel TXT). io-mapping.txt - description of io_mapping functions in linux/io-mapping.h io_ordering.txt @@ -182,6 +243,8 @@ isdn/ - directory with info on the Linux ISDN support, and supported cards. java.txt - info on the in-kernel binary support for Java(tm). +ja_JP/ + - directory with Japanese translations of various documents kbuild/ - directory with info about the kernel build process. kdump/ @@ -192,6 +255,12 @@ kernel-docs.txt - listing of various WWW + books that document kernel internals. kernel-parameters.txt - summary listing of command line / boot prompt args for the kernel. +kmemcheck.txt + - info on dynamic checker that detects uses of uninitialized memory. +kmemleak.txt + - info on how to make use of the kernel memory leak detection system +ko_KR/ + - directory with Korean translations of various documents kobject.txt - info of the kobject infrastructure of the Linux kernel. kprobes.txt @@ -208,6 +277,10 @@ local_ops.txt - semantics and behavior of local atomic operations. lockdep-design.txt - documentation on the runtime locking correctness validator. +lockstat.txt + - info on collecting statistics on locks (and contention). +lockup-watchdogs.txt + - info on soft and hard lockup detectors (aka nmi_watchdog). logo.gif - full colour GIF image of Linux logo (penguin - Tux). logo.txt @@ -216,20 +289,30 @@ m68k/ - directory with info about Linux on Motorola 68k architecture. magic-number.txt - list of magic numbers used to mark/protect kernel data structures. -mca.txt - - info on supporting Micro Channel Architecture (e.g. PS/2) systems. md.txt - info on boot arguments for the multiple devices driver. +media-framework.txt + - info on media framework, its data structures, functions and usage. memory-barriers.txt - info on Linux kernel memory barriers. +memory-devices/ + - directory with info on parts like the Texas Instruments EMIF driver memory-hotplug.txt - Hotpluggable memory support, how to use and current status. memory.txt - info on typical Linux memory problems. +metag/ + - directory with info about Linux on Meta architecture. mips/ - directory with info about Linux on MIPS architecture. +misc-devices/ + - directory with info about devices using the misc dev subsystem mmc/ - directory with info about the MMC subsystem +mn10300/ + - directory with info about the mn10300 architecture port +mtd/ + - directory with info about memory technology devices (flash) mono.txt - how to execute Mono-based .NET binaries with the help of BINFMT_MISC. mutex-design.txt @@ -240,8 +323,8 @@ netlabel/ - directory with information on the NetLabel subsystem. networking/ - directory with info on various aspects of networking with Linux. -nmi_watchdog.txt - - info on NMI watchdog for SMP systems. +nfc/ + - directory relating info about Near Field Communications support. nommu-mmap.txt - documentation about no-mmu memory mapping support. numastat.txt @@ -258,28 +341,46 @@ parport-lowlevel.txt - description and usage of the low level parallel port functions. pcmcia/ - info on the Linux PCMCIA driver. +percpu-rw-semaphore.txt + - RCU based read-write semaphore optimized for locking for reading pi-futex.txt - - documentation on lightweight PI-futexes. + - documentation on lightweight priority inheritance futexes. +pinctrl.txt + - info on pinctrl subsystem and the PINMUX/PINCONF and drivers pnp.txt - Linux Plug and Play documentation. power/ - directory with info on Linux PCI power management. powerpc/ - directory with info on using Linux with the PowerPC. +prctl/ + - directory with info on the priveledge control subsystem 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. +pps/ + - directory with information on the pulse-per-second support +ptp/ + - directory with info on support for IEEE 1588 PTP clocks in Linux. +pwm.txt + - info on the pulse width modulation driver subsystem ramoops.txt - documentation of the ramoops oops/panic logging module. +rapidio/ + - directory with info on RapidIO packet-based fabric interconnect rbtree.txt - info on what red-black trees are and what they are for. +remoteproc.txt + - info on how to handle remote processor (e.g. AMP) offloads/usage. +rfkill.txt + - info on the radio frequency kill switch subsystem/support. robust-futex-ABI.txt - documentation of the robust futex ABI. robust-futexes.txt - a description of what robust futexes are. +rpmsg.txt + - info on the Remote Processor Messaging (rpmsg) Framework rt-mutex-design.txt - description of the RealTime mutex implementation design. rt-mutex.txt @@ -304,10 +405,10 @@ sgi-visws.txt - short blurb on the SGI Visual Workstations. sh/ - directory with info on porting Linux to a new architecture. +smsc_ece1099.txt + -info on the smsc Keyboard Scan Expansion/GPIO Expansion device. sound/ - directory with info on sound card support. -sparc/ - - directory with info on using Linux on Sparc architecture. sparse.txt - info on how to obtain and use the sparse tool for typechecking. spi/ @@ -318,6 +419,8 @@ stable_api_nonsense.txt - info on why the kernel does not have a stable in-kernel api or abi. stable_kernel_rules.txt - rules and procedures for the -stable kernel releases. +static-keys.txt + - info on how static keys allow debug code in hotpaths via patching svga.txt - short guide on selecting video modes at boot via VGA BIOS. sysfs-rules.txt @@ -326,27 +429,53 @@ sysctl/ - directory with info on the /proc/sys/* files. sysrq.txt - info on the magic SysRq key. -telephony/ - - directory with info on telephony (e.g. voice over IP) support. +target/ + - directory with info on generating TCM v4 fabric .ko modules +thermal/ + - directory with information on managing thermal issues (CPU/temp) +trace/ + - directory with info on tracing technologies within linux +unaligned-memory-access.txt + - info on how to avoid arch breaking unaligned memory access in code. unicode.txt - info on the Unicode character/font mapping used in Linux. unshare.txt - description of the Linux unshare system call. usb/ - directory with info regarding the Universal Serial Bus. +vDSO/ + - directory with info regarding virtual dynamic shared objects +vfio.txt + - info on Virtual Function I/O used in guest/hypervisor instances. +vgaarbiter.txt + - info on enable/disable the legacy decoding on different VGA devices video-output.txt - sysfs class driver interface to enable/disable a video output device. video4linux/ - directory with info regarding video/TV/radio cards and linux. +virtual/ + - directory with information on the various linux virtualizations. vm/ - directory with info on the Linux vm code. +vme_api.txt + - file relating info on the VME bus API in linux volatile-considered-harmful.txt - Why the "volatile" type class should not be used w1/ - directory with documents regarding the 1-wire (w1) subsystem. watchdog/ - how to auto-reboot Linux if it has "fallen and can't get up". ;-) +wimax/ + - directory with info about Intel Wireless Wimax Connections +workqueue.txt + - information on the Concurrency Managed Workqueue implementation x86/x86_64/ - directory with info on Linux support for AMD x86-64 (Hammer) machines. +xtensa/ + - directory with documents relating to arch/xtensa port/implementation +xz.txt + - how to make use of the XZ data compression within linux kernel +zh_CN/ + - directory with Chinese translations of various documents zorro.txt - info on writing drivers for Zorro bus devices found on Amigas. diff --git a/Documentation/ABI/README b/Documentation/ABI/README index 9feaf16f1617..10069828568b 100644 --- a/Documentation/ABI/README +++ b/Documentation/ABI/README @@ -36,9 +36,6 @@ The different levels of stability are: the kernel, but are marked to be removed at some later point in time. The description of the interface will document the reason why it is obsolete and when it can be expected to be removed. - The file Documentation/feature-removal-schedule.txt may describe - some of these interfaces, giving a schedule for when they will - be removed. removed/ This directory contains a list of the old interfaces that have 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/obsolete/proc-sys-vm-nr_pdflush_threads b/Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads new file mode 100644 index 000000000000..b0b0eeb20fe3 --- /dev/null +++ b/Documentation/ABI/obsolete/proc-sys-vm-nr_pdflush_threads @@ -0,0 +1,5 @@ +What: /proc/sys/vm/nr_pdflush_threads +Date: June 2012 +Contact: Wanpeng Li <liwp@linux.vnet.ibm.com> +Description: Since pdflush is replaced by per-BDI flusher, the interface of old pdflush + exported in /proc/sys/vm/ should be removed. diff --git a/Documentation/ABI/obsolete/sysfs-class-rfkill b/Documentation/ABI/obsolete/sysfs-class-rfkill index 4201d5b05515..ff60ad9eca4c 100644 --- a/Documentation/ABI/obsolete/sysfs-class-rfkill +++ b/Documentation/ABI/obsolete/sysfs-class-rfkill @@ -7,7 +7,7 @@ Date: 09-Jul-2007 KernelVersion v2.6.22 Contact: linux-wireless@vger.kernel.org Description: Current state of the transmitter. - This file is deprecated and sheduled to be removed in 2014, + This file is deprecated and scheduled to be removed in 2014, because its not possible to express the 'soft and hard block' state of the rfkill driver. Values: A numeric value. diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus index c2a270b45b03..833fd59926a7 100644 --- a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-koneplus @@ -8,3 +8,41 @@ Description: The integer value of this attribute ranges from 0-4. When written, this file sets the number of the startup profile and the mouse activates this profile immediately. Please use actual_profile, it does the same thing. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/firmware_version +Date: October 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the raw integer version number of the + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 121 means 1.21 + This file is readonly. + Please read binary attribute info which contains firmware version. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When read, these files return the respective profile buttons. + The returned data is 77 bytes in size. + This file is readonly. + Write control to select profile and read profile_buttons instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 43 bytes in size. + This file is readonly. + Write control to select profile and read profile_settings instead. +Users: http://roccat.sourceforge.net
\ No newline at end of file diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus new file mode 100644 index 000000000000..4a98e02b6c6a --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-kovaplus @@ -0,0 +1,66 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_cpi +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-4. + When read, this attribute returns the number of the active + cpi level. + This file is readonly. + Has never been used. If bookkeeping is done, it's done in userland tools. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_x +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-10. + When read, this attribute returns the number of the actual + sensitivity in x direction. + This file is readonly. + Has never been used. If bookkeeping is done, it's done in userland tools. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_y +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 1-10. + When read, this attribute returns the number of the actual + sensitivity in y direction. + This file is readonly. + Has never been used. If bookkeeping is done, it's done in userland tools. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/firmware_version +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the raw integer version number of the + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 121 means 1.21 + This file is readonly. + Obsoleted by binary sysfs attribute "info". +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_buttons +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When read, these files return the respective profile buttons. + The returned data is 23 bytes in size. + This file is readonly. + Write control to select profile and read profile_buttons instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_settings +Date: January 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 16 bytes in size. + This file is readonly. + Write control to select profile and read profile_settings instead. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra new file mode 100644 index 000000000000..87ac87e9556d --- /dev/null +++ b/Documentation/ABI/obsolete/sysfs-driver-hid-roccat-pyra @@ -0,0 +1,73 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: It is possible to switch the cpi setting of the mouse with the + press of a button. + When read, this file returns the raw number of the actual cpi + setting reported by the mouse. This number has to be further + processed to receive the real dpi value. + + VALUE DPI + 1 400 + 2 800 + 4 1600 + + This file is readonly. + Has never been used. If bookkeeping is done, it's done in userland tools. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_profile +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the number of the actual profile in + range 0-4. + This file is readonly. + Please use binary attribute "settings" which provides this information. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/firmware_version +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns the raw integer version number of the + firmware reported by the mouse. Using the integer value eases + further usage in other programs. To receive the real version + number the decimal point has to be shifted 2 positions to the + left. E.g. a returned value of 138 means 1.38 + This file is readonly. + Please use binary attribute "info" which provides this information. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_buttons +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When read, these files return the respective profile buttons. + The returned data is 19 bytes in size. + This file is readonly. + Write control to select profile and read profile_buttons instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_settings +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When read, these files return the respective profile settings. + The returned data is 13 bytes in size. + This file is readonly. + Write control to select profile and read profile_settings instead. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/startup_profile +Date: August 2010 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the profile + that's active when the mouse is powered on. + This file is readonly. + Please use binary attribute "settings" which provides this information. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/removed/devfs b/Documentation/ABI/removed/devfs index 8ffd28bf6598..0020c49933c4 100644 --- a/Documentation/ABI/removed/devfs +++ b/Documentation/ABI/removed/devfs @@ -1,6 +1,6 @@ What: devfs Date: July 2005 (scheduled), finally removed in kernel v2.6.18 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: devfs has been unmaintained for a number of years, has unfixable races, contains a naming policy within the kernel that is diff --git a/Documentation/ABI/removed/ip_queue b/Documentation/ABI/removed/ip_queue new file mode 100644 index 000000000000..3243613bc2d2 --- /dev/null +++ b/Documentation/ABI/removed/ip_queue @@ -0,0 +1,9 @@ +What: ip_queue +Date: finally removed in kernel v3.5.0 +Contact: Pablo Neira Ayuso <pablo@netfilter.org> +Description: + ip_queue has been replaced by nfnetlink_queue which provides + more advanced queueing mechanism to user-space. The ip_queue + module was already announced to become obsolete years ago. + +Users: diff --git a/Documentation/ABI/stable/sysfs-bus-firewire b/Documentation/ABI/stable/sysfs-bus-firewire index 3d484e5dc846..41e5a0cd1e3e 100644 --- a/Documentation/ABI/stable/sysfs-bus-firewire +++ b/Documentation/ABI/stable/sysfs-bus-firewire @@ -39,6 +39,17 @@ Users: udev rules to set ownership and access permissions or ACLs of /dev/fw[0-9]+ character device files +What: /sys/bus/firewire/devices/fw[0-9]+/is_local +Date: July 2012 +KernelVersion: 3.6 +Contact: linux1394-devel@lists.sourceforge.net +Description: + IEEE 1394 node device attribute. + Read-only and immutable. +Values: 1: The sysfs entry represents a local node (a controller card). + 0: The sysfs entry represents a remote node. + + What: /sys/bus/firewire/devices/fw[0-9]+[.][0-9]+/ Date: May 2007 KernelVersion: 2.6.22 diff --git a/Documentation/ABI/stable/sysfs-bus-usb b/Documentation/ABI/stable/sysfs-bus-usb new file mode 100644 index 000000000000..a6b685724740 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-usb @@ -0,0 +1,142 @@ +What: /sys/bus/usb/devices/.../power/persist +Date: May 2007 +KernelVersion: 2.6.23 +Contact: Alan Stern <stern@rowland.harvard.edu> +Description: + If CONFIG_USB_PERSIST is set, then each USB device directory + will contain a file named power/persist. The file holds a + boolean value (0 or 1) indicating whether or not the + "USB-Persist" facility is enabled for the device. Since the + facility is inherently dangerous, it is disabled by default + for all devices except hubs. For more information, see + Documentation/usb/persist.txt. + +What: /sys/bus/usb/devices/.../power/autosuspend +Date: March 2007 +KernelVersion: 2.6.21 +Contact: Alan Stern <stern@rowland.harvard.edu> +Description: + Each USB device directory will contain a file named + power/autosuspend. This file holds the time (in seconds) + the device must be idle before it will be autosuspended. + 0 means the device will be autosuspended as soon as + possible. Negative values will prevent the device from + being autosuspended at all, and writing a negative value + will resume the device if it is already suspended. + + The autosuspend delay for newly-created devices is set to + the value of the usbcore.autosuspend module parameter. + +What: /sys/bus/usb/device/.../power/connected_duration +Date: January 2008 +KernelVersion: 2.6.25 +Contact: Sarah Sharp <sarah.a.sharp@intel.com> +Description: + If CONFIG_PM_RUNTIME is enabled then this file + is present. When read, it returns the total time (in msec) + that the USB device has been connected to the machine. This + file is read-only. +Users: + PowerTOP <powertop@lists.01.org> + https://01.org/powertop/ + +What: /sys/bus/usb/device/.../power/active_duration +Date: January 2008 +KernelVersion: 2.6.25 +Contact: Sarah Sharp <sarah.a.sharp@intel.com> +Description: + If CONFIG_PM_RUNTIME is enabled then this file + is present. When read, it returns the total time (in msec) + that the USB device has been active, i.e. not in a suspended + state. This file is read-only. + + Tools can use this file and the connected_duration file to + compute the percentage of time that a device has been active. + For example, + echo $((100 * `cat active_duration` / `cat connected_duration`)) + will give an integer percentage. Note that this does not + account for counter wrap. +Users: + PowerTOP <powertop@lists.01.org> + https://01.org/powertop/ + +What: /sys/bus/usb/devices/<busnum>-<port[.port]>...:<config num>-<interface num>/supports_autosuspend +Date: January 2008 +KernelVersion: 2.6.27 +Contact: Sarah Sharp <sarah.a.sharp@intel.com> +Description: + When read, this file returns 1 if the interface driver + for this interface supports autosuspend. It also + returns 1 if no driver has claimed this interface, as an + unclaimed interface will not stop the device from being + autosuspended if all other interface drivers are idle. + The file returns 0 if autosuspend support has not been + added to the driver. +Users: + USB PM tool + git://git.moblin.org/users/sarah/usb-pm-tool/ + +What: /sys/bus/usb/device/.../avoid_reset_quirk +Date: December 2009 +Contact: Oliver Neukum <oliver@neukum.org> +Description: + Writing 1 to this file tells the kernel that this + device will morph into another mode when it is reset. + Drivers will not use reset for error handling for + such devices. +Users: + usb_modeswitch + +What: /sys/bus/usb/devices/.../devnum +KernelVersion: since at least 2.6.18 +Description: + Device address on the USB bus. +Users: + libusb + +What: /sys/bus/usb/devices/.../bConfigurationValue +KernelVersion: since at least 2.6.18 +Description: + bConfigurationValue of the *active* configuration for the + device. Writing 0 or -1 to bConfigurationValue will reset the + active configuration (unconfigure the device). Writing + another value will change the active configuration. + + Note that some devices, in violation of the USB spec, have a + configuration with a value equal to 0. Writing 0 to + bConfigurationValue for these devices will install that + configuration, rather then unconfigure the device. + + Writing -1 will always unconfigure the device. +Users: + libusb + +What: /sys/bus/usb/devices/.../busnum +KernelVersion: 2.6.22 +Description: + Bus-number of the USB-bus the device is connected to. +Users: + libusb + +What: /sys/bus/usb/devices/.../descriptors +KernelVersion: 2.6.26 +Description: + Binary file containing cached descriptors of the device. The + binary data consists of the device descriptor followed by the + descriptors for each configuration of the device. + Note that the wTotalLength of the config descriptors can not + be trusted, as the device may have a smaller config descriptor + than it advertises. The bLength field of each (sub) descriptor + can be trusted, and can be used to seek forward one (sub) + descriptor at a time until the next config descriptor is found. + All descriptors read from this file are in bus-endian format +Users: + libusb + +What: /sys/bus/usb/devices/.../speed +KernelVersion: since at least 2.6.18 +Description: + Speed the device is connected with to the usb-host in + Mbit / second. IE one of 1.5 / 12 / 480 / 5000. +Users: + libusb diff --git a/Documentation/ABI/stable/sysfs-bus-xen-backend b/Documentation/ABI/stable/sysfs-bus-xen-backend new file mode 100644 index 000000000000..3d5951c8bf5f --- /dev/null +++ b/Documentation/ABI/stable/sysfs-bus-xen-backend @@ -0,0 +1,75 @@ +What: /sys/bus/xen-backend/devices/*/devtype +Date: Feb 2009 +KernelVersion: 2.6.38 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The type of the device. e.g., one of: 'vbd' (block), + 'vif' (network), or 'vfb' (framebuffer). + +What: /sys/bus/xen-backend/devices/*/nodename +Date: Feb 2009 +KernelVersion: 2.6.38 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + XenStore node (under /local/domain/NNN/) for this + backend device. + +What: /sys/bus/xen-backend/devices/vbd-*/physical_device +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The major:minor number (in hexidecimal) of the + physical device providing the storage for this backend + block device. + +What: /sys/bus/xen-backend/devices/vbd-*/mode +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Whether the block device is read-only ('r') or + read-write ('w'). + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/f_req +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of flush requests from the frontend. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/oo_req +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of requests delayed because the backend was too + busy processing previous requests. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/rd_req +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of read requests from the frontend. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/rd_sect +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of sectors read by the frontend. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/wr_req +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of write requests from the frontend. + +What: /sys/bus/xen-backend/devices/vbd-*/statistics/wr_sect +Date: April 2011 +KernelVersion: 3.0 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Number of sectors written by the frontend. diff --git a/Documentation/ABI/stable/sysfs-class-tpm b/Documentation/ABI/stable/sysfs-class-tpm new file mode 100644 index 000000000000..a60b45e2493b --- /dev/null +++ b/Documentation/ABI/stable/sysfs-class-tpm @@ -0,0 +1,185 @@ +What: /sys/class/misc/tpmX/device/ +Date: April 2005 +KernelVersion: 2.6.12 +Contact: tpmdd-devel@lists.sf.net +Description: The device/ directory under a specific TPM instance exposes + the properties of that TPM chip + + +What: /sys/class/misc/tpmX/device/active +Date: April 2006 +KernelVersion: 2.6.17 +Contact: tpmdd-devel@lists.sf.net +Description: The "active" property prints a '1' if the TPM chip is accepting + commands. An inactive TPM chip still contains all the state of + an active chip (Storage Root Key, NVRAM, etc), and can be + visible to the OS, but will only accept a restricted set of + commands. See the TPM Main Specification part 2, Structures, + section 17 for more information on which commands are + available. + +What: /sys/class/misc/tpmX/device/cancel +Date: June 2005 +KernelVersion: 2.6.13 +Contact: tpmdd-devel@lists.sf.net +Description: The "cancel" property allows you to cancel the currently + pending TPM command. Writing any value to cancel will call the + TPM vendor specific cancel operation. + +What: /sys/class/misc/tpmX/device/caps +Date: April 2005 +KernelVersion: 2.6.12 +Contact: tpmdd-devel@lists.sf.net +Description: The "caps" property contains TPM manufacturer and version info. + + Example output: + + Manufacturer: 0x53544d20 + TCG version: 1.2 + Firmware version: 8.16 + + Manufacturer is a hex dump of the 4 byte manufacturer info + space in a TPM. TCG version shows the TCG TPM spec level that + the chip supports. Firmware version is that of the chip and + is manufacturer specific. + +What: /sys/class/misc/tpmX/device/durations +Date: March 2011 +KernelVersion: 3.1 +Contact: tpmdd-devel@lists.sf.net +Description: The "durations" property shows the 3 vendor-specific values + used to wait for a short, medium and long TPM command. All + TPM commands are categorized as short, medium or long in + execution time, so that the driver doesn't have to wait + any longer than necessary before starting to poll for a + result. + + Example output: + + 3015000 4508000 180995000 [original] + + Here the short, medium and long durations are displayed in + usecs. "[original]" indicates that the values are displayed + unmodified from when they were queried from the chip. + Durations can be modified in the case where a buggy chip + reports them in msec instead of usec and they need to be + scaled to be displayed in usecs. In this case "[adjusted]" + will be displayed in place of "[original]". + +What: /sys/class/misc/tpmX/device/enabled +Date: April 2006 +KernelVersion: 2.6.17 +Contact: tpmdd-devel@lists.sf.net +Description: The "enabled" property prints a '1' if the TPM chip is enabled, + meaning that it should be visible to the OS. This property + may be visible but produce a '0' after some operation that + disables the TPM. + +What: /sys/class/misc/tpmX/device/owned +Date: April 2006 +KernelVersion: 2.6.17 +Contact: tpmdd-devel@lists.sf.net +Description: The "owned" property produces a '1' if the TPM_TakeOwnership + ordinal has been executed successfully in the chip. A '0' + indicates that ownership hasn't been taken. + +What: /sys/class/misc/tpmX/device/pcrs +Date: April 2005 +KernelVersion: 2.6.12 +Contact: tpmdd-devel@lists.sf.net +Description: The "pcrs" property will dump the current value of all Platform + Configuration Registers in the TPM. Note that since these + values may be constantly changing, the output is only valid + for a snapshot in time. + + Example output: + + PCR-00: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-01: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-02: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-03: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + PCR-04: 3A 3F 78 0F 11 A4 B4 99 69 FC AA 80 CD 6E 39 57 C3 3B 22 75 + ... + + The number of PCRs and hex bytes needed to represent a PCR + value will vary depending on TPM chip version. For TPM 1.1 and + 1.2 chips, PCRs represent SHA-1 hashes, which are 20 bytes + long. Use the "caps" property to determine TPM version. + +What: /sys/class/misc/tpmX/device/pubek +Date: April 2005 +KernelVersion: 2.6.12 +Contact: tpmdd-devel@lists.sf.net +Description: The "pubek" property will return the TPM's public endorsement + key if possible. If the TPM has had ownership established and + is version 1.2, the pubek will not be available without the + owner's authorization. Since the TPM driver doesn't store any + secrets, it can't authorize its own request for the pubek, + making it unaccessible. The public endorsement key is gener- + ated at TPM menufacture time and exists for the life of the + chip. + + Example output: + + Algorithm: 00 00 00 01 + Encscheme: 00 03 + Sigscheme: 00 01 + Parameters: 00 00 08 00 00 00 00 02 00 00 00 00 + Modulus length: 256 + Modulus: + B4 76 41 82 C9 20 2C 10 18 40 BC 8B E5 44 4C 6C + 3A B2 92 0C A4 9B 2A 83 EB 5C 12 85 04 48 A0 B6 + 1E E4 81 84 CE B2 F2 45 1C F0 85 99 61 02 4D EB + 86 C4 F7 F3 29 60 52 93 6B B2 E5 AB 8B A9 09 E3 + D7 0E 7D CA 41 BF 43 07 65 86 3C 8C 13 7A D0 8B + 82 5E 96 0B F8 1F 5F 34 06 DA A2 52 C1 A9 D5 26 + 0F F4 04 4B D9 3F 2D F2 AC 2F 74 64 1F 8B CD 3E + 1E 30 38 6C 70 63 69 AB E2 50 DF 49 05 2E E1 8D + 6F 78 44 DA 57 43 69 EE 76 6C 38 8A E9 8E A3 F0 + A7 1F 3C A8 D0 12 15 3E CA 0E BD FA 24 CD 33 C6 + 47 AE A4 18 83 8E 22 39 75 93 86 E6 FD 66 48 B6 + 10 AD 94 14 65 F9 6A 17 78 BD 16 53 84 30 BF 70 + E0 DC 65 FD 3C C6 B0 1E BF B9 C1 B5 6C EF B1 3A + F8 28 05 83 62 26 11 DC B4 6B 5A 97 FF 32 26 B6 + F7 02 71 CF 15 AE 16 DD D1 C1 8E A8 CF 9B 50 7B + C3 91 FF 44 1E CF 7C 39 FE 17 77 21 20 BD CE 9B + + Possible values: + + Algorithm: TPM_ALG_RSA (1) + Encscheme: TPM_ES_RSAESPKCSv15 (2) + TPM_ES_RSAESOAEP_SHA1_MGF1 (3) + Sigscheme: TPM_SS_NONE (1) + Parameters, a byte string of 3 u32 values: + Key Length (bits): 00 00 08 00 (2048) + Num primes: 00 00 00 02 (2) + Exponent Size: 00 00 00 00 (0 means the + default exp) + Modulus Length: 256 (bytes) + Modulus: The 256 byte Endorsement Key modulus + +What: /sys/class/misc/tpmX/device/temp_deactivated +Date: April 2006 +KernelVersion: 2.6.17 +Contact: tpmdd-devel@lists.sf.net +Description: The "temp_deactivated" property returns a '1' if the chip has + been temporarily dectivated, usually until the next power + cycle. Whether a warm boot (reboot) will clear a TPM chip + from a temp_deactivated state is platform specific. + +What: /sys/class/misc/tpmX/device/timeouts +Date: March 2011 +KernelVersion: 3.1 +Contact: tpmdd-devel@lists.sf.net +Description: The "timeouts" property shows the 4 vendor-specific values + for the TPM's interface spec timeouts. The use of these + timeouts is defined by the TPM interface spec that the chip + conforms to. + + Example output: + + 750000 750000 750000 750000 [original] + + The four timeout values are shown in usecs, with a trailing + "[original]" or "[adjusted]" depending on whether the values + were scaled by the driver to be reported in usec from msecs. diff --git a/Documentation/ABI/stable/sysfs-devices-node b/Documentation/ABI/stable/sysfs-devices-node index 49b82cad7003..ce259c13c36a 100644 --- a/Documentation/ABI/stable/sysfs-devices-node +++ b/Documentation/ABI/stable/sysfs-devices-node @@ -1,7 +1,101 @@ +What: /sys/devices/system/node/possible +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that could be possibly become online at some point. + +What: /sys/devices/system/node/online +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that are online. + +What: /sys/devices/system/node/has_normal_memory +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that have regular memory. + +What: /sys/devices/system/node/has_cpu +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that have one or more CPUs. + +What: /sys/devices/system/node/has_high_memory +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Nodes that have regular or high memory. + Depends on CONFIG_HIGHMEM. + What: /sys/devices/system/node/nodeX Date: October 2002 Contact: Linux Memory Management list <linux-mm@kvack.org> Description: When CONFIG_NUMA is enabled, this is a directory containing information on node X such as what CPUs are local to the - node. + node. Each file is detailed next. + +What: /sys/devices/system/node/nodeX/cpumap +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + The node's cpumap. + +What: /sys/devices/system/node/nodeX/cpulist +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + The CPUs associated to the node. + +What: /sys/devices/system/node/nodeX/meminfo +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Provides information about the node's distribution and memory + utilization. Similar to /proc/meminfo, see Documentation/filesystems/proc.txt + +What: /sys/devices/system/node/nodeX/numastat +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + The node's hit/miss statistics, in units of pages. + See Documentation/numastat.txt + +What: /sys/devices/system/node/nodeX/distance +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + Distance between the node and all the other nodes + in the system. + +What: /sys/devices/system/node/nodeX/vmstat +Date: October 2002 +Contact: Linux Memory Management list <linux-mm@kvack.org> +Description: + The node's zoned virtual memory statistics. + This is a superset of numastat. + +What: /sys/devices/system/node/nodeX/compact +Date: February 2010 +Contact: Mel Gorman <mel@csn.ul.ie> +Description: + When this file is written to, all memory within that node + will be compacted. When it completes, memory will be freed + into blocks which have as many contiguous pages as possible + +What: /sys/devices/system/node/nodeX/scan_unevictable_pages +Date: October 2008 +Contact: Lee Schermerhorn <lee.schermerhorn@hp.com> +Description: + When set, it triggers scanning the node's unevictable lists + and move any pages that have become evictable onto the respective + zone's inactive list. See mm/vmscan.c + +What: /sys/devices/system/node/nodeX/hugepages/hugepages-<size>/ +Date: December 2009 +Contact: Lee Schermerhorn <lee.schermerhorn@hp.com> +Description: + The node's huge page size control/query attributes. + See Documentation/vm/hugetlbpage.txt
\ No newline at end of file diff --git a/Documentation/ABI/stable/sysfs-devices-system-xen_memory b/Documentation/ABI/stable/sysfs-devices-system-xen_memory new file mode 100644 index 000000000000..caa311d59ac1 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-devices-system-xen_memory @@ -0,0 +1,77 @@ +What: /sys/devices/system/xen_memory/xen_memory0/max_retry_count +Date: May 2011 +KernelVersion: 2.6.39 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The maximum number of times the balloon driver will + attempt to increase the balloon before giving up. See + also 'retry_count' below. + A value of zero means retry forever and is the default one. + +What: /sys/devices/system/xen_memory/xen_memory0/max_schedule_delay +Date: May 2011 +KernelVersion: 2.6.39 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The limit that 'schedule_delay' (see below) will be + increased to. The default value is 32 seconds. + +What: /sys/devices/system/xen_memory/xen_memory0/retry_count +Date: May 2011 +KernelVersion: 2.6.39 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The current number of times that the balloon driver + has attempted to increase the size of the balloon. + The default value is one. With max_retry_count being + zero (unlimited), this means that the driver will attempt + to retry with a 'schedule_delay' delay. + +What: /sys/devices/system/xen_memory/xen_memory0/schedule_delay +Date: May 2011 +KernelVersion: 2.6.39 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The time (in seconds) to wait between attempts to + increase the balloon. Each time the balloon cannot be + increased, 'schedule_delay' is increased (until + 'max_schedule_delay' is reached at which point it + will use the max value). + +What: /sys/devices/system/xen_memory/xen_memory0/target +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + The target number of pages to adjust this domain's + memory reservation to. + +What: /sys/devices/system/xen_memory/xen_memory0/target_kb +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + As target above, except the value is in KiB. + +What: /sys/devices/system/xen_memory/xen_memory0/info/current_kb +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Current size (in KiB) of this domain's memory + reservation. + +What: /sys/devices/system/xen_memory/xen_memory0/info/high_kb +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Amount (in KiB) of high memory in the balloon. + +What: /sys/devices/system/xen_memory/xen_memory0/info/low_kb +Date: April 2008 +KernelVersion: 2.6.26 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Amount (in KiB) of low (or normal) memory in the + balloon. diff --git a/Documentation/ABI/stable/sysfs-driver-ib_srp b/Documentation/ABI/stable/sysfs-driver-ib_srp new file mode 100644 index 000000000000..5c53d28f775c --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-ib_srp @@ -0,0 +1,163 @@ +What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/add_target +Date: January 2, 2006 +KernelVersion: 2.6.15 +Contact: linux-rdma@vger.kernel.org +Description: Interface for making ib_srp connect to a new target. + One can request ib_srp to connect to a new target by writing + a comma-separated list of login parameters to this sysfs + attribute. The supported parameters are: + * id_ext, a 16-digit hexadecimal number specifying the eight + byte identifier extension in the 16-byte SRP target port + identifier. The target port identifier is sent by ib_srp + to the target in the SRP_LOGIN_REQ request. + * ioc_guid, a 16-digit hexadecimal number specifying the eight + byte I/O controller GUID portion of the 16-byte target port + identifier. + * dgid, a 32-digit hexadecimal number specifying the + destination GID. + * pkey, a four-digit hexadecimal number specifying the + InfiniBand partition key. + * service_id, a 16-digit hexadecimal number specifying the + InfiniBand service ID used to establish communication with + the SRP target. How to find out the value of the service ID + is specified in the documentation of the SRP target. + * max_sect, a decimal number specifying the maximum number of + 512-byte sectors to be transferred via a single SCSI command. + * max_cmd_per_lun, a decimal number specifying the maximum + number of outstanding commands for a single LUN. + * io_class, a hexadecimal number specifying the SRP I/O class. + Must be either 0xff00 (rev 10) or 0x0100 (rev 16a). The I/O + class defines the format of the SRP initiator and target + port identifiers. + * initiator_ext, a 16-digit hexadecimal number specifying the + identifier extension portion of the SRP initiator port + identifier. This data is sent by the initiator to the target + in the SRP_LOGIN_REQ request. + * cmd_sg_entries, a number in the range 1..255 that specifies + the maximum number of data buffer descriptors stored in the + SRP_CMD information unit itself. With allow_ext_sg=0 the + parameter cmd_sg_entries defines the maximum S/G list length + for a single SRP_CMD, and commands whose S/G list length + exceeds this limit after S/G list collapsing will fail. + * allow_ext_sg, whether ib_srp is allowed to include a partial + memory descriptor list in an SRP_CMD instead of the entire + list. If a partial memory descriptor list has been included + in an SRP_CMD the remaining memory descriptors are + communicated from initiator to target via an additional RDMA + transfer. Setting allow_ext_sg to 1 increases the maximum + amount of data that can be transferred between initiator and + target via a single SCSI command. Since not all SRP target + implementations support partial memory descriptor lists the + default value for this option is 0. + * sg_tablesize, a number in the range 1..2048 specifying the + maximum S/G list length the SCSI layer is allowed to pass to + ib_srp. Specifying a value that exceeds cmd_sg_entries is + only safe with partial memory descriptor list support enabled + (allow_ext_sg=1). + * comp_vector, a number in the range 0..n-1 specifying the + MSI-X completion vector. Some HCA's allocate multiple (n) + MSI-X vectors per HCA port. If the IRQ affinity masks of + these interrupts have been configured such that each MSI-X + interrupt is handled by a different CPU then the comp_vector + parameter can be used to spread the SRP completion workload + over multiple CPU's. + +What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/ibdev +Date: January 2, 2006 +KernelVersion: 2.6.15 +Contact: linux-rdma@vger.kernel.org +Description: HCA name (<hca>). + +What: /sys/class/infiniband_srp/srp-<hca>-<port_number>/port +Date: January 2, 2006 +KernelVersion: 2.6.15 +Contact: linux-rdma@vger.kernel.org +Description: HCA port number (<port_number>). + +What: /sys/class/scsi_host/host<n>/allow_ext_sg +Date: May 19, 2011 +KernelVersion: 2.6.39 +Contact: linux-rdma@vger.kernel.org +Description: Whether ib_srp is allowed to include a partial memory + descriptor list in an SRP_CMD when communicating with an SRP + target. + +What: /sys/class/scsi_host/host<n>/cmd_sg_entries +Date: May 19, 2011 +KernelVersion: 2.6.39 +Contact: linux-rdma@vger.kernel.org +Description: Maximum number of data buffer descriptors that may be sent to + the target in a single SRP_CMD request. + +What: /sys/class/scsi_host/host<n>/dgid +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: InfiniBand destination GID used for communication with the SRP + target. Differs from orig_dgid if port redirection has happened. + +What: /sys/class/scsi_host/host<n>/id_ext +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: Eight-byte identifier extension portion of the 16-byte target + port identifier. + +What: /sys/class/scsi_host/host<n>/ioc_guid +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: Eight-byte I/O controller GUID portion of the 16-byte target + port identifier. + +What: /sys/class/scsi_host/host<n>/local_ib_device +Date: November 29, 2006 +KernelVersion: 2.6.19 +Contact: linux-rdma@vger.kernel.org +Description: Name of the InfiniBand HCA used for communicating with the + SRP target. + +What: /sys/class/scsi_host/host<n>/local_ib_port +Date: November 29, 2006 +KernelVersion: 2.6.19 +Contact: linux-rdma@vger.kernel.org +Description: Number of the HCA port used for communicating with the + SRP target. + +What: /sys/class/scsi_host/host<n>/orig_dgid +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: InfiniBand destination GID specified in the parameters + written to the add_target sysfs attribute. + +What: /sys/class/scsi_host/host<n>/pkey +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: A 16-bit number representing the InfiniBand partition key used + for communication with the SRP target. + +What: /sys/class/scsi_host/host<n>/req_lim +Date: October 20, 2010 +KernelVersion: 2.6.36 +Contact: linux-rdma@vger.kernel.org +Description: Number of requests ib_srp can send to the target before it has + to wait for more credits. For more information see also the + SRP credit algorithm in the SRP specification. + +What: /sys/class/scsi_host/host<n>/service_id +Date: June 17, 2006 +KernelVersion: 2.6.17 +Contact: linux-rdma@vger.kernel.org +Description: InfiniBand service ID used for establishing communication with + the SRP target. + +What: /sys/class/scsi_host/host<n>/zero_req_lim +Date: September 20, 2006 +KernelVersion: 2.6.18 +Contact: linux-rdma@vger.kernel.org +Description: Number of times the initiator had to wait before sending a + request to the target because it ran out of credits. For more + information see also the SRP credit algorithm in the SRP + specification. diff --git a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc index 9a75fb22187d..e960cd027e1e 100644 --- a/Documentation/ABI/stable/sysfs-driver-usb-usbtmc +++ b/Documentation/ABI/stable/sysfs-driver-usb-usbtmc @@ -1,7 +1,7 @@ -What: /sys/bus/usb/drivers/usbtmc/devices/*/interface_capabilities -What: /sys/bus/usb/drivers/usbtmc/devices/*/device_capabilities +What: /sys/bus/usb/drivers/usbtmc/*/interface_capabilities +What: /sys/bus/usb/drivers/usbtmc/*/device_capabilities Date: August 2008 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: These files show the various USB TMC capabilities as described by the device itself. The full description of the bitfields @@ -12,10 +12,10 @@ Description: The files are read only. -What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_interface_capabilities -What: /sys/bus/usb/drivers/usbtmc/devices/*/usb488_device_capabilities +What: /sys/bus/usb/drivers/usbtmc/*/usb488_interface_capabilities +What: /sys/bus/usb/drivers/usbtmc/*/usb488_device_capabilities Date: August 2008 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: These files show the various USB TMC capabilities as described by the device itself. The full description of the bitfields @@ -27,9 +27,9 @@ Description: The files are read only. -What: /sys/bus/usb/drivers/usbtmc/devices/*/TermChar +What: /sys/bus/usb/drivers/usbtmc/*/TermChar Date: August 2008 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: This file is the TermChar value to be sent to the USB TMC device as described by the document, "Universal Serial Bus Test @@ -40,9 +40,9 @@ Description: sent to the device or not. -What: /sys/bus/usb/drivers/usbtmc/devices/*/TermCharEnabled +What: /sys/bus/usb/drivers/usbtmc/*/TermCharEnabled Date: August 2008 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: This file determines if the TermChar is to be sent to the device on every transaction or not. For more details about @@ -51,11 +51,11 @@ Description: published by the USB-IF. -What: /sys/bus/usb/drivers/usbtmc/devices/*/auto_abort +What: /sys/bus/usb/drivers/usbtmc/*/auto_abort Date: August 2008 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: - This file determines if the the transaction of the USB TMC + This file determines if the transaction of the USB TMC device is to be automatically aborted if there is any error. For more details about this, please see the document, "Universal Serial Bus Test and Measurement Class Specification diff --git a/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 new file mode 100644 index 000000000000..26579ee868c9 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-driver-w1_ds28e04 @@ -0,0 +1,15 @@ +What: /sys/bus/w1/devices/.../pio +Date: May 2012 +Contact: Markus Franke <franm@hrz.tu-chemnitz.de> +Description: read/write the contents of the two PIO's of the DS28E04-100 + see Documentation/w1/slaves/w1_ds28e04 for detailed information +Users: any user space application which wants to communicate with DS28E04-100 + + + +What: /sys/bus/w1/devices/.../eeprom +Date: May 2012 +Contact: Markus Franke <franm@hrz.tu-chemnitz.de> +Description: read/write the contents of the EEPROM memory of the DS28E04-100 + see Documentation/w1/slaves/w1_ds28e04 for detailed information +Users: any user space application which wants to communicate with DS28E04-100 diff --git a/Documentation/ABI/stable/sysfs-module b/Documentation/ABI/stable/sysfs-module index 75be43118335..6272ae5fb366 100644 --- a/Documentation/ABI/stable/sysfs-module +++ b/Documentation/ABI/stable/sysfs-module @@ -4,9 +4,13 @@ Description: /sys/module/MODULENAME The name of the module that is in the kernel. This - module name will show up either if the module is built - directly into the kernel, or if it is loaded as a - dyanmic module. + module name will always show up if the module is loaded as a + dynamic module. If it is built directly into the kernel, it + will only show up if it has a version or at least one + parameter. + + Note: The conditions of creation in the built-in case are not + by design and may be removed in the future. /sys/module/MODULENAME/parameters This directory contains individual files that are each diff --git a/Documentation/ABI/stable/sysfs-transport-srp b/Documentation/ABI/stable/sysfs-transport-srp new file mode 100644 index 000000000000..b36fb0dc13c8 --- /dev/null +++ b/Documentation/ABI/stable/sysfs-transport-srp @@ -0,0 +1,19 @@ +What: /sys/class/srp_remote_ports/port-<h>:<n>/delete +Date: June 1, 2012 +KernelVersion: 3.7 +Contact: linux-scsi@vger.kernel.org, linux-rdma@vger.kernel.org +Description: Instructs an SRP initiator to disconnect from a target and to + remove all LUNs imported from that target. + +What: /sys/class/srp_remote_ports/port-<h>:<n>/port_id +Date: June 27, 2007 +KernelVersion: 2.6.24 +Contact: linux-scsi@vger.kernel.org +Description: 16-byte local SRP port identifier in hexadecimal format. An + example: 4c:49:4e:55:58:20:56:49:4f:00:00:00:00:00:00:00. + +What: /sys/class/srp_remote_ports/port-<h>:<n>/roles +Date: June 27, 2007 +KernelVersion: 2.6.24 +Contact: linux-scsi@vger.kernel.org +Description: Role of the remote port. Either "SRP Initiator" or "SRP Target". diff --git a/Documentation/ABI/stable/vdso b/Documentation/ABI/stable/vdso index 8a1cbb594497..7cdfc28cc2c6 100644 --- a/Documentation/ABI/stable/vdso +++ b/Documentation/ABI/stable/vdso @@ -24,4 +24,4 @@ though. (As of this writing, this ABI documentation as been confirmed for x86_64. The maintainers of the other vDSO-using architectures should confirm - that it is correct for their architecture.)
\ No newline at end of file + that it is correct for their architecture.) diff --git a/Documentation/ABI/testing/configfs-usb-gadget b/Documentation/ABI/testing/configfs-usb-gadget new file mode 100644 index 000000000000..01e769d6984d --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget @@ -0,0 +1,81 @@ +What: /config/usb-gadget +Date: Jun 2013 +KenelVersion: 3.11 +Description: + This group contains sub-groups corresponding to created + USB gadgets. + +What: /config/usb-gadget/gadget +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + The attributes of a gadget: + + UDC - bind a gadget to UDC/unbind a gadget; + write UDC's name found in /sys/class/udc/* + to bind a gadget, empty string "" to unbind. + + bDeviceClass - USB device class code + bDeviceSubClass - USB device subclass code + bDeviceProtocol - USB device protocol code + bMaxPacketSize0 - maximum endpoint 0 packet size + bcdDevice - bcd device release number + bcdUSB - bcd USB specification version number + idProduct - product ID + idVendor - vendor ID + +What: /config/usb-gadget/gadget/configs +Date: Jun 2013 +KenelVersion: 3.11 +Description: + This group contains a USB gadget's configurations + +What: /config/usb-gadget/gadget/configs/config +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes of a configuration: + + bmAttributes - configuration characteristics + MaxPower - maximum power consumption from the bus + +What: /config/usb-gadget/gadget/configs/config/strings +Date: Jun 2013 +KernelVersion: 3.11 +Description: + This group contains subdirectories for language-specific + strings for this configuration. + +What: /config/usb-gadget/gadget/configs/config/strings/language +Date: Jun 2013 +KernelVersion: 3.11 +Description: + The attributes: + + configuration - configuration description + + +What: /config/usb-gadget/gadget/functions +Date: Jun 2013 +KenelVersion: 3.11 +Description: + This group contains functions available to this USB gadget. + +What: /config/usb-gadget/gadget/strings +Date: Jun 2013 +KenelVersion: 3.11 +Description: + This group contains subdirectories for language-specific + strings for this gadget. + +What: /config/usb-gadget/gadget/strings/language +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + serialnumber - gadget's serial number (string) + product - gadget's product description + manufacturer - gadget's manufacturer description + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-acm b/Documentation/ABI/testing/configfs-usb-gadget-acm new file mode 100644 index 000000000000..5708a568b5f6 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-acm @@ -0,0 +1,8 @@ +What: /config/usb-gadget/gadget/functions/acm.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with acm function's instance "name". diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ecm b/Documentation/ABI/testing/configfs-usb-gadget-ecm new file mode 100644 index 000000000000..6b9a582ce0b5 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ecm @@ -0,0 +1,16 @@ +What: /config/usb-gadget/gadget/functions/ecm.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-eem b/Documentation/ABI/testing/configfs-usb-gadget-eem new file mode 100644 index 000000000000..dbddf36b48b3 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-eem @@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/eem.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link diff --git a/Documentation/ABI/testing/configfs-usb-gadget-ncm b/Documentation/ABI/testing/configfs-usb-gadget-ncm new file mode 100644 index 000000000000..bc309f42357d --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-ncm @@ -0,0 +1,15 @@ +What: /config/usb-gadget/gadget/functions/ncm.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-obex b/Documentation/ABI/testing/configfs-usb-gadget-obex new file mode 100644 index 000000000000..aaa5c96fb7c6 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-obex @@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/obex.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with obex function's instance "name". + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-phonet b/Documentation/ABI/testing/configfs-usb-gadget-phonet new file mode 100644 index 000000000000..3e3b742cdfd7 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-phonet @@ -0,0 +1,8 @@ +What: /config/usb-gadget/gadget/functions/phonet.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + This item contains just one readonly attribute: ifname. + It contains the network interface name assigned during + network device registration. diff --git a/Documentation/ABI/testing/configfs-usb-gadget-rndis b/Documentation/ABI/testing/configfs-usb-gadget-rndis new file mode 100644 index 000000000000..822e6dad8fc0 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-rndis @@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/rndis.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link diff --git a/Documentation/ABI/testing/configfs-usb-gadget-serial b/Documentation/ABI/testing/configfs-usb-gadget-serial new file mode 100644 index 000000000000..16f130c1501f --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-serial @@ -0,0 +1,9 @@ +What: /config/usb-gadget/gadget/functions/gser.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + + This item contains just one readonly attribute: port_num. + It contains the port number of the /dev/ttyGS<n> device + associated with gser function's instance "name". + diff --git a/Documentation/ABI/testing/configfs-usb-gadget-subset b/Documentation/ABI/testing/configfs-usb-gadget-subset new file mode 100644 index 000000000000..154ae597cd99 --- /dev/null +++ b/Documentation/ABI/testing/configfs-usb-gadget-subset @@ -0,0 +1,14 @@ +What: /config/usb-gadget/gadget/functions/geth.name +Date: Jun 2013 +KenelVersion: 3.11 +Description: + The attributes: + + ifname - network device interface name associated with + this function instance + qmult - queue length multiplier for high and + super speed + host_addr - MAC address of host's end of this + Ethernet over USB link + dev_addr - MAC address of device's end of this + Ethernet over USB link diff --git a/Documentation/ABI/testing/debugfs-olpc b/Documentation/ABI/testing/debugfs-olpc new file mode 100644 index 000000000000..bd76cc6d55f9 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-olpc @@ -0,0 +1,16 @@ +What: /sys/kernel/debug/olpc-ec/cmd +Date: Dec 2011 +KernelVersion: 3.4 +Contact: devel@lists.laptop.org +Description: + +A generic interface for executing OLPC Embedded Controller commands and +reading their responses. + +To execute a command, write data with the format: CC:N A A A A +CC is the (hex) command, N is the count of expected reply bytes, and A A A A +are optional (hex) arguments. + +To read the response (if any), read from the generic node after executing +a command. Hex reply bytes will be returned, *whether or not* they came from +the immediately previous command. diff --git a/Documentation/ABI/testing/debugfs-pfo-nx-crypto b/Documentation/ABI/testing/debugfs-pfo-nx-crypto new file mode 100644 index 000000000000..685d5a448423 --- /dev/null +++ b/Documentation/ABI/testing/debugfs-pfo-nx-crypto @@ -0,0 +1,45 @@ +What: /sys/kernel/debug/nx-crypto/* +Date: March 2012 +KernelVersion: 3.4 +Contact: Kent Yoder <key@linux.vnet.ibm.com> +Description: + + These debugfs interfaces are built by the nx-crypto driver, built in +arch/powerpc/crypto/nx. + +Error Detection +=============== + +errors: +- A u32 providing a total count of errors since the driver was loaded. The +only errors counted here are those returned from the hcall, H_COP_OP. + +last_error: +- The most recent non-zero return code from the H_COP_OP hcall. -EBUSY is not +recorded here (the hcall will retry until -EBUSY goes away). + +last_error_pid: +- The process ID of the process who received the most recent error from the +hcall. + +Device Use +========== + +aes_bytes: +- The total number of bytes encrypted using AES in any of the driver's +supported modes. + +aes_ops: +- The total number of AES operations submitted to the hardware. + +sha256_bytes: +- The total number of bytes hashed by the hardware using SHA-256. + +sha256_ops: +- The total number of SHA-256 operations submitted to the hardware. + +sha512_bytes: +- The total number of bytes hashed by the hardware using SHA-512. + +sha512_ops: +- The total number of SHA-512 operations submitted to the hardware. diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg new file mode 100644 index 000000000000..bb820be48179 --- /dev/null +++ b/Documentation/ABI/testing/dev-kmsg @@ -0,0 +1,101 @@ +What: /dev/kmsg +Date: Mai 2012 +KernelVersion: 3.5 +Contact: Kay Sievers <kay@vrfy.org> +Description: The /dev/kmsg character device node provides userspace access + to the kernel's printk buffer. + + Injecting messages: + Every write() to the opened device node places a log entry in + the kernel's printk buffer. + + The logged line can be prefixed with a <N> syslog prefix, which + carries the syslog priority and facility. The single decimal + prefix number is composed of the 3 lowest bits being the syslog + priority and the higher bits the syslog facility number. + + If no prefix is given, the priority number is the default kernel + log priority and the facility number is set to LOG_USER (1). It + is not possible to inject messages from userspace with the + facility number LOG_KERN (0), to make sure that the origin of + the messages can always be reliably determined. + + Accessing the buffer: + Every read() from the opened device node receives one record + of the kernel's printk buffer. + + The first read() directly following an open() always returns + first message in the buffer; there is no kernel-internal + persistent state; many readers can concurrently open the device + and read from it, without affecting other readers. + + Every read() will receive the next available record. If no more + records are available read() will block, or if O_NONBLOCK is + used -EAGAIN returned. + + Messages in the record ring buffer get overwritten as whole, + there are never partial messages received by read(). + + In case messages get overwritten in the circular buffer while + the device is kept open, the next read() will return -EPIPE, + and the seek position be updated to the next available record. + Subsequent reads() will return available records again. + + Unlike the classic syslog() interface, the 64 bit record + sequence numbers allow to calculate the amount of lost + messages, in case the buffer gets overwritten. And they allow + to reconnect to the buffer and reconstruct the read position + if needed, without limiting the interface to a single reader. + + The device supports seek with the following parameters: + SEEK_SET, 0 + seek to the first entry in the buffer + SEEK_END, 0 + seek after the last entry in the buffer + SEEK_DATA, 0 + seek after the last record available at the time + the last SYSLOG_ACTION_CLEAR was issued. + + The output format consists of a prefix carrying the syslog + prefix including priority and facility, the 64 bit message + sequence number and the monotonic timestamp in microseconds, + and a flag field. All fields are separated by a ','. + + Future extensions might add more comma separated values before + the terminating ';'. Unknown fields and values should be + gracefully ignored. + + The human readable text string starts directly after the ';' + and is terminated by a '\n'. Untrusted values derived from + hardware or other facilities are printed, therefore + all non-printable characters and '\' itself in the log message + are escaped by "\x00" C-style hex encoding. + + A line starting with ' ', is a continuation line, adding + key/value pairs to the log message, which provide the machine + readable context of the message, for reliable processing in + userspace. + + Example: + 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored) + SUBSYSTEM=acpi + DEVICE=+acpi:PNP0A03:00 + 6,339,5140900,-;NET: Registered protocol family 10 + 30,340,5690716,-;udevd[80]: starting version 181 + + The DEVICE= key uniquely identifies devices the following way: + b12:8 - block dev_t + c127:3 - char dev_t + n8 - netdev ifindex + +sound:card0 - subsystem:devname + + The flags field carries '-' by default. A 'c' indicates a + fragment of a line. All following fragments are flagged with + '+'. Note, that these hints about continuation lines are not + necessarily correct, and the stream could be interleaved with + unrelated messages, but merging the lines in the output + usually produces better human readable results. A similar + logic is used internally when messages are printed to the + console, /proc/kmsg or the syslog() syscall. + +Users: dmesg(1), userspace kernel log consumers diff --git a/Documentation/ABI/testing/ima_policy b/Documentation/ABI/testing/ima_policy index 6cd6daefaaed..f1c5cc9d17a8 100644 --- a/Documentation/ABI/testing/ima_policy +++ b/Documentation/ABI/testing/ima_policy @@ -12,48 +12,70 @@ 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 - condition:= base | lsm - base: [[func=] [mask=] [fsmagic=] [uid=]] + action: measure | dont_measure | appraise | dont_appraise | audit + condition:= base | lsm [option] + base: [[func=] [mask=] [fsmagic=] [fsuuid=] [uid=] + [fowner]] lsm: [[subj_user=] [subj_role=] [subj_type=] [obj_user=] [obj_role=] [obj_type=]] + option: [[appraise_type=]] - base: func:= [BPRM_CHECK][FILE_MMAP][FILE_CHECK] + base: func:= [BPRM_CHECK][MMAP_CHECK][FILE_CHECK][MODULE_CHECK] mask:= [MAY_READ] [MAY_WRITE] [MAY_APPEND] [MAY_EXEC] fsmagic:= hex value + fsuuid:= file system UUID (e.g 8bcbe394-4f13-4144-be8e-5aa9ea2ce2f6) uid:= decimal value + fowner:=decimal value lsm: are LSM specific + option: appraise_type:= [imasig] 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 + measure func=MODULE_CHECK 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/pstore b/Documentation/ABI/testing/pstore index ff1df4e3b059..5fca9f5e10a3 100644 --- a/Documentation/ABI/testing/pstore +++ b/Documentation/ABI/testing/pstore @@ -1,4 +1,4 @@ -Where: /dev/pstore/... +Where: /sys/fs/pstore/... (or /dev/pstore/...) Date: March 2011 Kernel Version: 2.6.39 Contact: tony.luck@intel.com @@ -11,9 +11,9 @@ Description: Generic interface to platform dependent persistent storage. of the console log is captured, but other interesting data can also be saved. - # mount -t pstore -o kmsg_bytes=8000 - /dev/pstore + # mount -t pstore -o kmsg_bytes=8000 - /sys/fs/pstore - $ ls -l /dev/pstore + $ ls -l /sys/fs/pstore/ total 0 -r--r--r-- 1 root root 7896 Nov 30 15:38 dmesg-erst-1 @@ -27,9 +27,9 @@ Description: Generic interface to platform dependent persistent storage. the file will signal to the underlying persistent storage device that it can reclaim the space for later re-use. - $ rm /dev/pstore/dmesg-erst-1 + $ rm /sys/fs/pstore/dmesg-erst-1 - The expectation is that all files in /dev/pstore + The expectation is that all files in /sys/fs/pstore/ will be saved elsewhere and erased from persistent store soon after boot to free up space ready for the next catastrophe. diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block index c1eb41cb9876..279da08f7541 100644 --- a/Documentation/ABI/testing/sysfs-block +++ b/Documentation/ABI/testing/sysfs-block @@ -206,3 +206,17 @@ Description: when a discarded area is read the discard_zeroes_data parameter will be set to one. Otherwise it will be 0 and the result of reading a discarded area is undefined. + +What: /sys/block/<disk>/queue/write_same_max_bytes +Date: January 2012 +Contact: Martin K. Petersen <martin.petersen@oracle.com> +Description: + Some devices support a write same operation in which a + single data block can be written to a range of several + contiguous blocks on storage. This can be used to wipe + areas on disk or to initialize drives in a RAID + configuration. write_same_max_bytes indicates how many + bytes can be written in a single write same command. If + write_same_max_bytes is 0, write same is not supported + by the device. + diff --git a/Documentation/ABI/testing/sysfs-block-bcache b/Documentation/ABI/testing/sysfs-block-bcache new file mode 100644 index 000000000000..9e4bbc5d51fd --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-bcache @@ -0,0 +1,156 @@ +What: /sys/block/<disk>/bcache/unregister +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + A write to this file causes the backing device or cache to be + unregistered. If a backing device had dirty data in the cache, + writeback mode is automatically disabled and all dirty data is + flushed before the device is unregistered. Caches unregister + all associated backing devices before unregistering themselves. + +What: /sys/block/<disk>/bcache/clear_stats +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + Writing to this file resets all the statistics for the device. + +What: /sys/block/<disk>/bcache/cache +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a backing device that has cache, a symlink to + the bcache/ dir of that cache. + +What: /sys/block/<disk>/bcache/cache_hits +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: integer number of full cache hits, + counted per bio. A partial cache hit counts as a miss. + +What: /sys/block/<disk>/bcache/cache_misses +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: integer number of cache misses. + +What: /sys/block/<disk>/bcache/cache_hit_ratio +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: cache hits as a percentage. + +What: /sys/block/<disk>/bcache/sequential_cutoff +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: Threshold past which sequential IO will + skip the cache. Read and written as bytes in human readable + units (i.e. echo 10M > sequntial_cutoff). + +What: /sys/block/<disk>/bcache/bypassed +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + Sum of all reads and writes that have bypassed the cache (due + to the sequential cutoff). Expressed as bytes in human + readable units. + +What: /sys/block/<disk>/bcache/writeback +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: When on, writeback caching is enabled and + writes will be buffered in the cache. When off, caching is in + writethrough mode; reads and writes will be added to the + cache but no write buffering will take place. + +What: /sys/block/<disk>/bcache/writeback_running +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: when off, dirty data will not be written + from the cache to the backing device. The cache will still be + used to buffer writes until it is mostly full, at which point + writes transparently revert to writethrough mode. Intended only + for benchmarking/testing. + +What: /sys/block/<disk>/bcache/writeback_delay +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: In writeback mode, when dirty data is + written to the cache and the cache held no dirty data for that + backing device, writeback from cache to backing device starts + after this delay, expressed as an integer number of seconds. + +What: /sys/block/<disk>/bcache/writeback_percent +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For backing devices: If nonzero, writeback from cache to + backing device only takes place when more than this percentage + of the cache is used, allowing more write coalescing to take + place and reducing total number of writes sent to the backing + device. Integer between 0 and 40. + +What: /sys/block/<disk>/bcache/synchronous +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, a boolean that allows synchronous mode to be + switched on and off. In synchronous mode all writes are ordered + such that the cache can reliably recover from unclean shutdown; + if disabled bcache will not generally wait for writes to + complete but if the cache is not shut down cleanly all data + will be discarded from the cache. Should not be turned off with + writeback caching enabled. + +What: /sys/block/<disk>/bcache/discard +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, a boolean allowing discard/TRIM to be turned off + or back on if the device supports it. + +What: /sys/block/<disk>/bcache/bucket_size +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, bucket size in human readable units, as set at + cache creation time; should match the erase block size of the + SSD for optimal performance. + +What: /sys/block/<disk>/bcache/nbuckets +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, the number of usable buckets. + +What: /sys/block/<disk>/bcache/tree_depth +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, height of the btree excluding leaf nodes (i.e. a + one node tree will have a depth of 0). + +What: /sys/block/<disk>/bcache/btree_cache_size +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + Number of btree buckets/nodes that are currently cached in + memory; cache dynamically grows and shrinks in response to + memory pressure from the rest of the system. + +What: /sys/block/<disk>/bcache/written +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, total amount of data in human readable units + written to the cache, excluding all metadata. + +What: /sys/block/<disk>/bcache/btree_written +Date: November 2010 +Contact: Kent Overstreet <kent.overstreet@gmail.com> +Description: + For a cache, sum of all btree writes in human readable units. diff --git a/Documentation/ABI/testing/sysfs-block-dm b/Documentation/ABI/testing/sysfs-block-dm new file mode 100644 index 000000000000..87ca5691e29b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-dm @@ -0,0 +1,25 @@ +What: /sys/block/dm-<num>/dm/name +Date: January 2009 +KernelVersion: 2.6.29 +Contact: dm-devel@redhat.com +Description: Device-mapper device name. + Read-only string containing mapped device name. +Users: util-linux, device-mapper udev rules + +What: /sys/block/dm-<num>/dm/uuid +Date: January 2009 +KernelVersion: 2.6.29 +Contact: dm-devel@redhat.com +Description: Device-mapper device UUID. + Read-only string containing DM-UUID or empty string + if DM-UUID is not set. +Users: util-linux, device-mapper udev rules + +What: /sys/block/dm-<num>/dm/suspended +Date: June 2009 +KernelVersion: 2.6.31 +Contact: dm-devel@redhat.com +Description: Device-mapper device suspend state. + Contains the value 1 while the device is suspended. + Otherwise it contains 0. Read-only attribute. +Users: util-linux, device-mapper udev rules diff --git a/Documentation/ABI/testing/sysfs-block-rssd b/Documentation/ABI/testing/sysfs-block-rssd new file mode 100644 index 000000000000..beef30c046b0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-block-rssd @@ -0,0 +1,5 @@ +What: /sys/block/rssd*/status +Date: April 2012 +KernelVersion: 3.4 +Contact: Asai Thambi S P <asamymuthupa@micron.com> +Description: This is a read-only file. Indicates the status of the device. diff --git a/Documentation/ABI/testing/sysfs-block-zram b/Documentation/ABI/testing/sysfs-block-zram index c8b3b48ec62c..3f0b9ae61d8c 100644 --- a/Documentation/ABI/testing/sysfs-block-zram +++ b/Documentation/ABI/testing/sysfs-block-zram @@ -5,20 +5,21 @@ Description: The disksize file is read-write and specifies the disk size which represents the limit on the *uncompressed* worth of data that can be stored in this disk. + Unit: bytes What: /sys/block/zram<id>/initstate Date: August 2010 Contact: Nitin Gupta <ngupta@vflare.org> Description: - The disksize file is read-only and shows the initialization + The initstate file is read-only and shows the initialization state of the device. What: /sys/block/zram<id>/reset Date: August 2010 Contact: Nitin Gupta <ngupta@vflare.org> Description: - The disksize file is write-only and allows resetting the - device. The reset operation frees all the memory assocaited + The reset file is write-only and allows resetting the + device. The reset operation frees all the memory associated with this device. What: /sys/block/zram<id>/num_reads @@ -48,7 +49,7 @@ Contact: Nitin Gupta <ngupta@vflare.org> Description: The notify_free file is read-only and specifies the number of swap slot free notifications received by this device. These - notifications are send to a swap block device when a swap slot + notifications are sent to a swap block device when a swap slot is freed. This statistic is applicable only when this disk is being used as a swap disk. @@ -96,4 +97,4 @@ Description: overhead, allocated for this disk. So, allocator space efficiency can be calculated using compr_data_size and this statistic. - Unit: bytes
\ No newline at end of file + Unit: bytes diff --git a/Documentation/ABI/testing/sysfs-bus-acpi b/Documentation/ABI/testing/sysfs-bus-acpi new file mode 100644 index 000000000000..7fa9cbc75344 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-acpi @@ -0,0 +1,58 @@ +What: /sys/bus/acpi/devices/.../path +Date: December 2006 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute indicates the full path of ACPI namespace + object associated with the device object. For example, + \_SB_.PCI0. + This file is not present for device objects representing + fixed ACPI hardware features (like power and sleep + buttons). + +What: /sys/bus/acpi/devices/.../modalias +Date: July 2007 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute indicates the PNP IDs of the device object. + That is acpi:HHHHHHHH:[CCCCCCC:]. Where each HHHHHHHH or + CCCCCCCC contains device object's PNPID (_HID or _CID). + +What: /sys/bus/acpi/devices/.../hid +Date: April 2005 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute indicates the hardware ID (_HID) of the + device object. For example, PNP0103. + This file is present for device objects having the _HID + control method. + +What: /sys/bus/acpi/devices/.../description +Date: October 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute contains the output of the device object's + _STR control method, if present. + +What: /sys/bus/acpi/devices/.../adr +Date: October 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute contains the output of the device object's + _ADR control method, which is present for ACPI device + objects representing devices having standard enumeration + algorithms, such as PCI. + +What: /sys/bus/acpi/devices/.../uid +Date: October 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + This attribute contains the output of the device object's + _UID control method, if present. + +What: /sys/bus/acpi/devices/.../eject +Date: December 2006 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + Writing 1 to this attribute will trigger hot removal of + this device object. This file exists for every device + object that has _EJ0 method. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-events b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events new file mode 100644 index 000000000000..3c1cc24361bd --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-events @@ -0,0 +1,84 @@ +What: /sys/devices/cpu/events/ + /sys/devices/cpu/events/branch-misses + /sys/devices/cpu/events/cache-references + /sys/devices/cpu/events/cache-misses + /sys/devices/cpu/events/stalled-cycles-frontend + /sys/devices/cpu/events/branch-instructions + /sys/devices/cpu/events/stalled-cycles-backend + /sys/devices/cpu/events/instructions + /sys/devices/cpu/events/cpu-cycles + +Date: 2013/01/08 + +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> + +Description: Generic performance monitoring events + + A collection of performance monitoring events that may be + supported by many/most CPUs. These events can be monitored + using the 'perf(1)' tool. + + The contents of each file would look like: + + event=0xNNNN + + where 'N' is a hex digit and the number '0xNNNN' shows the + "raw code" for the perf event identified by the file's + "basename". + + +What: /sys/devices/cpu/events/PM_1PLUS_PPC_CMPL + /sys/devices/cpu/events/PM_BRU_FIN + /sys/devices/cpu/events/PM_BR_MPRED + /sys/devices/cpu/events/PM_CMPLU_STALL + /sys/devices/cpu/events/PM_CMPLU_STALL_BRU + /sys/devices/cpu/events/PM_CMPLU_STALL_DCACHE_MISS + /sys/devices/cpu/events/PM_CMPLU_STALL_DFU + /sys/devices/cpu/events/PM_CMPLU_STALL_DIV + /sys/devices/cpu/events/PM_CMPLU_STALL_ERAT_MISS + /sys/devices/cpu/events/PM_CMPLU_STALL_FXU + /sys/devices/cpu/events/PM_CMPLU_STALL_IFU + /sys/devices/cpu/events/PM_CMPLU_STALL_LSU + /sys/devices/cpu/events/PM_CMPLU_STALL_REJECT + /sys/devices/cpu/events/PM_CMPLU_STALL_SCALAR + /sys/devices/cpu/events/PM_CMPLU_STALL_SCALAR_LONG + /sys/devices/cpu/events/PM_CMPLU_STALL_STORE + /sys/devices/cpu/events/PM_CMPLU_STALL_THRD + /sys/devices/cpu/events/PM_CMPLU_STALL_VECTOR + /sys/devices/cpu/events/PM_CMPLU_STALL_VECTOR_LONG + /sys/devices/cpu/events/PM_CYC + /sys/devices/cpu/events/PM_GCT_NOSLOT_BR_MPRED + /sys/devices/cpu/events/PM_GCT_NOSLOT_BR_MPRED_IC_MISS + /sys/devices/cpu/events/PM_GCT_NOSLOT_CYC + /sys/devices/cpu/events/PM_GCT_NOSLOT_IC_MISS + /sys/devices/cpu/events/PM_GRP_CMPL + /sys/devices/cpu/events/PM_INST_CMPL + /sys/devices/cpu/events/PM_LD_MISS_L1 + /sys/devices/cpu/events/PM_LD_REF_L1 + /sys/devices/cpu/events/PM_RUN_CYC + /sys/devices/cpu/events/PM_RUN_INST_CMPL + +Date: 2013/01/08 + +Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> + Linux Powerpc mailing list <linuxppc-dev@ozlabs.org> + +Description: POWER-systems specific performance monitoring events + + A collection of performance monitoring events that may be + supported by the POWER CPU. These events can be monitored + using the 'perf(1)' tool. + + These events may not be supported by other CPUs. + + The contents of each file would look like: + + event=0xNNNN + + where 'N' is a hex digit and the number '0xNNNN' shows the + "raw code" for the perf event identified by the file's + "basename". + + Further, multiple terms like 'event=0xNNNN' can be specified + and separated with comma. All available terms are defined in + the /sys/bus/event_source/devices/<dev>/format file. diff --git a/Documentation/ABI/testing/sysfs-bus-event_source-devices-format b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format new file mode 100644 index 000000000000..77f47ff5ee02 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-event_source-devices-format @@ -0,0 +1,20 @@ +Where: /sys/bus/event_source/devices/<dev>/format +Date: January 2012 +Kernel Version: 3.3 +Contact: Jiri Olsa <jolsa@redhat.com> +Description: + Attribute group to describe the magic bits that go into + perf_event_attr::config[012] for a particular pmu. + Each attribute of this group defines the 'hardware' bitmask + we want to export, so that userspace can deal with sane + name/value pairs. + + Userspace must be prepared for the possibility that attributes + define overlapping bit ranges. For example: + attr1 = 'config:0-23' + attr2 = 'config:0-7' + attr3 = 'config:12-35' + + Example: 'config1:1,6-10,44' + Defines contents of attribute that occupies bits 1,6-10,44 of + perf_event_attr::config1. diff --git a/Documentation/ABI/testing/sysfs-bus-fcoe b/Documentation/ABI/testing/sysfs-bus-fcoe new file mode 100644 index 000000000000..21640eaad371 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-fcoe @@ -0,0 +1,116 @@ +What: /sys/bus/fcoe/ +Date: August 2012 +KernelVersion: TBD +Contact: Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org +Description: The FCoE bus. Attributes in this directory are control interfaces. +Attributes: + + ctlr_create: 'FCoE Controller' instance creation interface. Writing an + <ifname> to this file will allocate and populate sysfs with a + fcoe_ctlr_device (ctlr_X). The user can then configure any + per-port settings and finally write to the fcoe_ctlr_device's + 'start' attribute to begin the kernel's discovery and login + process. + + ctlr_destroy: 'FCoE Controller' instance removal interface. Writing a + fcoe_ctlr_device's sysfs name to this file will log the + fcoe_ctlr_device out of the fabric or otherwise connected + FCoE devices. It will also free all kernel memory allocated + for this fcoe_ctlr_device and any structures associated + with it, this includes the scsi_host. + +What: /sys/bus/fcoe/devices/ctlr_X +Date: March 2012 +KernelVersion: TBD +Contact: Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org +Description: 'FCoE Controller' instances on the fcoe bus. + The FCoE Controller now has a three stage creation process. + 1) Write interface name to ctlr_create 2) Configure the FCoE + Controller (ctlr_X) 3) Enable the FCoE Controller to begin + discovery and login. The FCoE Controller is destroyed by + writing it's name, i.e. ctlr_X to the ctlr_delete file. + +Attributes: + + fcf_dev_loss_tmo: Device loss timeout peroid (see below). Changing + this value will change the dev_loss_tmo for all + FCFs discovered by this controller. + + mode: Display or change the FCoE Controller's mode. Possible + modes are 'Fabric' and 'VN2VN'. If a FCoE Controller + is started in 'Fabric' mode then FIP FCF discovery is + initiated and ultimately a fabric login is attempted. + If a FCoE Controller is started in 'VN2VN' mode then + FIP VN2VN discovery and login is performed. A FCoE + Controller only supports one mode at a time. + + enabled: Whether an FCoE controller is enabled or disabled. + 0 if disabled, 1 if enabled. Writing either 0 or 1 + to this file will enable or disable the FCoE controller. + + lesb/link_fail: Link Error Status Block (LESB) link failure count. + + lesb/vlink_fail: Link Error Status Block (LESB) virtual link + failure count. + + lesb/miss_fka: Link Error Status Block (LESB) missed FCoE + Initialization Protocol (FIP) Keep-Alives (FKA). + + lesb/symb_err: Link Error Status Block (LESB) symbolic error count. + + lesb/err_block: Link Error Status Block (LESB) block error count. + + lesb/fcs_error: Link Error Status Block (LESB) Fibre Channel + Serivces error count. + +Notes: ctlr_X (global increment starting at 0) + +What: /sys/bus/fcoe/devices/fcf_X +Date: March 2012 +KernelVersion: TBD +Contact: Robert Love <robert.w.love@intel.com>, devel@open-fcoe.org +Description: 'FCoE FCF' instances on the fcoe bus. A FCF is a Fibre Channel + Forwarder, which is a FCoE switch that can accept FCoE + (Ethernet) packets, unpack them, and forward the embedded + Fibre Channel frames into a FC fabric. It can also take + outbound FC frames and pack them in Ethernet packets to + be sent to their destination on the Ethernet segment. +Attributes: + + fabric_name: Identifies the fabric that the FCF services. + + switch_name: Identifies the FCF. + + priority: The switch's priority amongst other FCFs on the same + fabric. + + selected: 1 indicates that the switch has been selected for use; + 0 indicates that the swich will not be used. + + fc_map: The Fibre Channel MAP + + vfid: The Virtual Fabric ID + + mac: The FCF's MAC address + + fka_peroid: The FIP Keep-Alive peroid + + fabric_state: The internal kernel state + "Unknown" - Initialization value + "Disconnected" - No link to the FCF/fabric + "Connected" - Host is connected to the FCF + "Deleted" - FCF is being removed from the system + + dev_loss_tmo: The device loss timeout peroid for this FCF. + +Notes: A device loss infrastructre similar to the FC Transport's + is present in fcoe_sysfs. It is nice to have so that a + link flapping adapter doesn't continually advance the count + used to identify the discovered FCF. FCFs will exist in a + "Disconnected" state until either the timer expires and the + FCF becomes "Deleted" or the FCF is rediscovered and becomes + "Connected." + + +Users: The first user of this interface will be the fcoeadm application, + which is commonly packaged in the fcoe-utils package. diff --git a/Documentation/ABI/testing/sysfs-bus-hsi b/Documentation/ABI/testing/sysfs-bus-hsi new file mode 100644 index 000000000000..1b1b282a99e1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-hsi @@ -0,0 +1,19 @@ +What: /sys/bus/hsi +Date: April 2012 +KernelVersion: 3.4 +Contact: Carlos Chinea <carlos.chinea@nokia.com> +Description: + High Speed Synchronous Serial Interface (HSI) is a + serial interface mainly used for connecting application + engines (APE) with cellular modem engines (CMT) in cellular + handsets. + The bus will be populated with devices (hsi_clients) representing + the protocols available in the system. Bus drivers implement + those protocols. + +What: /sys/bus/hsi/devices/.../modalias +Date: April 2012 +KernelVersion: 3.4 +Contact: Carlos Chinea <carlos.chinea@nokia.com> +Description: Stores the same MODALIAS value emitted by uevent + Format: hsi:<hsi_client device name> diff --git a/Documentation/ABI/testing/sysfs-bus-i2c-devices-lm3533 b/Documentation/ABI/testing/sysfs-bus-i2c-devices-lm3533 new file mode 100644 index 000000000000..1b62230b33b9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-i2c-devices-lm3533 @@ -0,0 +1,15 @@ +What: /sys/bus/i2c/devices/.../output_hvled[n] +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the controlling backlight device for high-voltage current + sink HVLED[n] (n = 1, 2) (0, 1). + +What: /sys/bus/i2c/devices/.../output_lvled[n] +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the controlling led device for low-voltage current sink + LVLED[n] (n = 1..5) (0..3). diff --git a/drivers/staging/iio/Documentation/sysfs-bus-iio b/Documentation/ABI/testing/sysfs-bus-iio index 0d6823d19b61..39c8de0e53d0 100644 --- a/drivers/staging/iio/Documentation/sysfs-bus-iio +++ b/Documentation/ABI/testing/sysfs-bus-iio @@ -40,9 +40,9 @@ Contact: linux-iio@vger.kernel.org Description: Some devices have internal clocks. This parameter sets the resulting sampling frequency. In many devices this - parameter has an effect on input filters etc rather than + parameter has an effect on input filters etc. rather than simply controlling when the input is sampled. As this - effects datardy triggers, hardware buffers and the sysfs + effects data ready triggers, hardware buffers and the sysfs direct access interfaces, it may be found in any of the relevant directories. If it effects all of the above then it is to be found in the base device directory. @@ -74,7 +74,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_raw KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: - Raw (unscaled no bias removal etc) voltage measurement from + Raw (unscaled no bias removal etc.) voltage measurement from channel Y. In special cases where the channel does not correspond to externally available input one of the named versions may be used. The number must always be specified and @@ -108,7 +108,7 @@ Description: physically equivalent inputs when non differential readings are separately available. In differential only parts, then all that is required is a consistent labeling. Units after application - of scale and offset are nanofarads.. + of scale and offset are nanofarads. What: /sys/bus/iio/devices/iio:deviceX/in_temp_raw What: /sys/bus/iio/devices/iio:deviceX/in_tempX_raw @@ -118,11 +118,11 @@ What: /sys/bus/iio/devices/iio:deviceX/in_temp_z_raw KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: - Raw (unscaled no bias removal etc) temperature measurement. - It an axis is specified it generally means that the temperature + Raw (unscaled no bias removal etc.) temperature measurement. + If an axis is specified it generally means that the temperature sensor is associated with one part of a compound device (e.g. a gyroscope axis). Units after application of scale and offset - are milli degrees Celsuis. + are milli degrees Celsius. What: /sys/bus/iio/devices/iio:deviceX/in_tempX_input KernelVersion: 2.6.38 @@ -148,10 +148,9 @@ KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: Angular velocity about axis x, y or z (may be arbitrarily - assigned) Data converted by application of offset then scale to - radians per second. Has all the equivalent parameters as - per voltageY. Units after application of scale and offset are - radians per second. + assigned). Has all the equivalent parameters as per voltageY. + Units after application of scale and offset are radians per + second. What: /sys/bus/iio/devices/iio:deviceX/in_incli_x_raw What: /sys/bus/iio/devices/iio:deviceX/in_incli_y_raw @@ -161,7 +160,7 @@ Contact: linux-iio@vger.kernel.org Description: Inclination raw reading about axis x, y or z (may be arbitrarily assigned). Data converted by application of offset - and scale to Degrees. + and scale to degrees. What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_raw What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_raw @@ -190,6 +189,14 @@ Description: A computed peak value based on the sum squared magnitude of the underlying value in the specified directions. +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_raw +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_raw +KernelVersion: 3.8 +Contact: linux-iio@vger.kernel.org +Description: + Raw pressure measurement from channel Y. Units after + application of scale and offset are kilopascal. + What: /sys/bus/iio/devices/iio:deviceX/in_accel_offset What: /sys/bus/iio/devices/iio:deviceX/in_accel_x_offset What: /sys/bus/iio/devices/iio:deviceX/in_accel_y_offset @@ -198,12 +205,14 @@ What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_offset What: /sys/bus/iio/devices/iio:deviceX/in_voltage_offset What: /sys/bus/iio/devices/iio:deviceX/in_tempY_offset What: /sys/bus/iio/devices/iio:deviceX/in_temp_offset +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_offset +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_offset KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: If known for a device, offset to be added to <type>[Y]_raw prior to scaling by <type>[Y]_scale in order to obtain value in the - <type> units as specified in <type>[y]_raw documentation. + <type> units as specified in <type>[Y]_raw documentation. Not present if the offset is always 0 or unknown. If Y or axis <x|y|z> is not present, then the offset applies to all in channels of <type>. @@ -219,6 +228,7 @@ What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_scale What: /sys/bus/iio/devices/iio:deviceX/in_voltageY_supply_scale What: /sys/bus/iio/devices/iio:deviceX/in_voltage_scale What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_scale +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_scale What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale What: /sys/bus/iio/devices/iio:deviceX/in_accel_peak_scale What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_scale @@ -226,13 +236,15 @@ What: /sys/bus/iio/devices/iio:deviceX/in_magn_scale What: /sys/bus/iio/devices/iio:deviceX/in_magn_x_scale What: /sys/bus/iio/devices/iio:deviceX/in_magn_y_scale What: /sys/bus/iio/devices/iio:deviceX/in_magn_z_scale +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_scale +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_scale KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: If known for a device, scale to be applied to <type>Y[_name]_raw post addition of <type>[Y][_name]_offset in order to obtain the measured value in <type> units as specified in - <type>[Y][_name]_raw documentation.. If shared across all in + <type>[Y][_name]_raw documentation. If shared across all in channels then Y and <x|y|z> are not present and the value is called <type>[Y][_name]_scale. The peak modifier means this value is applied to <type>Y[_name]_peak_raw values. @@ -243,10 +255,14 @@ What: /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibbias What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibbias What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibbias What: /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_calibbias +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_calibbias KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: - Hardware applied calibration offset. (assumed to fix production + Hardware applied calibration offset (assumed to fix production inaccuracies). What /sys/bus/iio/devices/iio:deviceX/in_voltageY_calibscale @@ -258,10 +274,14 @@ What /sys/bus/iio/devices/iio:deviceX/in_accel_z_calibscale What /sys/bus/iio/devices/iio:deviceX/in_anglvel_x_calibscale What /sys/bus/iio/devices/iio:deviceX/in_anglvel_y_calibscale What /sys/bus/iio/devices/iio:deviceX/in_anglvel_z_calibscale +what /sys/bus/iio/devices/iio:deviceX/in_illuminance0_calibscale +what /sys/bus/iio/devices/iio:deviceX/in_proximity0_calibscale +What: /sys/bus/iio/devices/iio:deviceX/in_pressureY_calibscale +What: /sys/bus/iio/devices/iio:deviceX/in_pressure_calibscale KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: - Hardware applied calibration scale factor. (assumed to fix + Hardware applied calibration scale factor (assumed to fix production inaccuracies). If shared across all channels, <type>_calibscale is used. @@ -269,22 +289,47 @@ What: /sys/bus/iio/devices/iio:deviceX/in_accel_scale_available What: /sys/.../iio:deviceX/in_voltageX_scale_available What: /sys/.../iio:deviceX/in_voltage-voltage_scale_available What: /sys/.../iio:deviceX/out_voltageX_scale_available +What: /sys/.../iio:deviceX/out_altvoltageX_scale_available What: /sys/.../iio:deviceX/in_capacitance_scale_available -KernelVersion: 2.635 +What: /sys/.../iio:deviceX/in_pressure_scale_available +What: /sys/.../iio:deviceX/in_pressureY_scale_available +KernelVersion: 2.6.35 Contact: linux-iio@vger.kernel.org Description: - If a discrete set of scale values are available, they + If a discrete set of scale values is available, they are listed in this attribute. +What /sys/bus/iio/devices/iio:deviceX/out_voltageY_hardwaregain +KernelVersion: 2.6.35 +Contact: linux-iio@vger.kernel.org +Description: + Hardware applied gain factor. If shared across all channels, + <type>_hardwaregain is used. + +What: /sys/.../in_accel_filter_low_pass_3db_frequency +What: /sys/.../in_magn_filter_low_pass_3db_frequency +What: /sys/.../in_anglvel_filter_low_pass_3db_frequency +KernelVersion: 3.2 +Contact: linux-iio@vger.kernel.org +Description: + If a known or controllable low pass filter is applied + to the underlying data channel, then this parameter + gives the 3dB frequency of the filter in Hz. + What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_raw +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_raw KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: Raw (unscaled, no bias etc.) output voltage for channel Y. The number must always be specified and unique if the output corresponds to a single channel. + While DAC like devices typically use out_voltage, + a continuous frequency generating device, such as + a DDS or PLL should use out_altvoltage. What: /sys/bus/iio/devices/iio:deviceX/out_voltageY&Z_raw +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY&Z_raw KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -295,20 +340,27 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown_mode What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown_mode +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown_mode +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltage_powerdown_mode KernelVersion: 2.6.38 Contact: linux-iio@vger.kernel.org Description: Specifies the output powerdown mode. DAC output stage is disconnected from the amplifier and - 1kohm_to_gnd: connected to ground via an 1kOhm resistor - 100kohm_to_gnd: connected to ground via an 100kOhm resistor - three_state: left floating + 1kohm_to_gnd: connected to ground via an 1kOhm resistor, + 6kohm_to_gnd: connected to ground via a 6kOhm resistor, + 20kohm_to_gnd: connected to ground via a 20kOhm resistor, + 100kohm_to_gnd: connected to ground via an 100kOhm resistor, + 500kohm_to_gnd: connected to ground via a 500kOhm resistor, + three_state: left floating. For a list of available output power down options read outX_powerdown_mode_available. If Y is not present the mode is shared across all outputs. What: /sys/.../iio:deviceX/out_votlageY_powerdown_mode_available What: /sys/.../iio:deviceX/out_voltage_powerdown_mode_available +What: /sys/.../iio:deviceX/out_altvotlageY_powerdown_mode_available +What: /sys/.../iio:deviceX/out_altvoltage_powerdown_mode_available KernelVersion: 2.6.38 Contact: linux-iio@vger.kernel.org Description: @@ -317,13 +369,34 @@ Description: What: /sys/bus/iio/devices/iio:deviceX/out_voltageY_powerdown What: /sys/bus/iio/devices/iio:deviceX/out_voltage_powerdown +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_powerdown +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltage_powerdown KernelVersion: 2.6.38 Contact: linux-iio@vger.kernel.org Description: Writing 1 causes output Y to enter the power down mode specified - by the corresponding outY_powerdown_mode. Clearing returns to - normal operation. Y may be suppressed if all outputs are - controlled together. + by the corresponding outY_powerdown_mode. DAC output stage is + disconnected from the amplifier. Clearing returns to normal + operation. Y may be suppressed if all outputs are controlled + together. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Output frequency for channel Y in Hz. The number must always be + specified and unique if the output corresponds to a single + channel. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_phase +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Phase in radians of one frequency/clock output Y + (out_altvoltageY) relative to another frequency/clock output + (out_altvoltageZ) of the device X. The number must always be + specified and unique if the output corresponds to a single + channel. What: /sys/bus/iio/devices/iio:deviceX/events KernelVersion: 2.6.35 @@ -369,12 +442,12 @@ Description: different values, but the device can only enable both thresholds or neither. Note the driver will assume the last p events requested are - to be enabled where p is however many it supports (which may - vary depending on the exact set requested. So if you want to be + to be enabled where p is how many it supports (which may vary + depending on the exact set requested. So if you want to be sure you have set what you think you have, check the contents of these attributes after everything is configured. Drivers may have to buffer any parameters so that they are consistent when - a given event type is enabled a future point (and not those for + a given event type is enabled at a future point (and not those for whatever event was previously enabled). What: /sys/.../iio:deviceX/events/in_accel_x_roc_rising_en @@ -443,10 +516,14 @@ What: /sys/.../events/in_magn_z_raw_thresh_rising_value What: /sys/.../events/in_magn_z_raw_thresh_falling_value What: /sys/.../events/in_voltageY_supply_raw_thresh_rising_value What: /sys/.../events/in_voltageY_supply_raw_thresh_falling_value +What: /sys/.../events/in_voltageY_raw_thresh_rising_value What: /sys/.../events/in_voltageY_raw_thresh_falling_value -What: /sys/.../events/in_voltageY_raw_thresh_falling_value -What: /sys/.../events/in_tempY_raw_thresh_falling_value +What: /sys/.../events/in_tempY_raw_thresh_rising_value What: /sys/.../events/in_tempY_raw_thresh_falling_value +What: /sys/.../events/in_illuminance0_thresh_falling_value +what: /sys/.../events/in_illuminance0_thresh_rising_value +what: /sys/.../events/in_proximity0_thresh_falling_value +what: /sys/.../events/in_proximity0_thresh_rising_value KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -480,9 +557,9 @@ What: /sys/.../events/in_magn_z_raw_roc_rising_value What: /sys/.../events/in_magn_z_raw_roc_falling_value What: /sys/.../events/in_voltageY_supply_raw_roc_rising_value What: /sys/.../events/in_voltageY_supply_raw_roc_falling_value +What: /sys/.../events/in_voltageY_raw_roc_rising_value What: /sys/.../events/in_voltageY_raw_roc_falling_value -What: /sys/.../events/in_voltageY_raw_roc_falling_value -What: /sys/.../events/in_tempY_raw_roc_falling_value +What: /sys/.../events/in_tempY_raw_roc_rising_value What: /sys/.../events/in_tempY_raw_roc_falling_value KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org @@ -546,6 +623,8 @@ What: /sys/.../events/in_tempY_thresh_falling_period What: /sys/.../events/in_tempY_roc_rising_period What: /sys/.../events/in_tempY_roc_falling_period What: /sys/.../events/in_accel_x&y&z_mag_falling_period +What: /sys/.../events/in_intensity0_thresh_period +What: /sys/.../events/in_proximity0_thresh_period KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -612,41 +691,45 @@ Description: Actually start the buffer capture up. Will start trigger if first device and appropriate. -What: /sys/bus/iio/devices/iio:deviceX/buffer/scan_elements +What: /sys/bus/iio/devices/iio:deviceX/scan_elements KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: Directory containing interfaces for elements that will be captured for a single triggered sample set in the buffer. -What: /sys/.../buffer/scan_elements/in_accel_x_en -What: /sys/.../buffer/scan_elements/in_accel_y_en -What: /sys/.../buffer/scan_elements/in_accel_z_en -What: /sys/.../buffer/scan_elements/in_anglvel_x_en -What: /sys/.../buffer/scan_elements/in_anglvel_y_en -What: /sys/.../buffer/scan_elements/in_anglvel_z_en -What: /sys/.../buffer/scan_elements/in_magn_x_en -What: /sys/.../buffer/scan_elements/in_magn_y_en -What: /sys/.../buffer/scan_elements/in_magn_z_en -What: /sys/.../buffer/scan_elements/in_timestamp_en -What: /sys/.../buffer/scan_elements/in_voltageY_supply_en -What: /sys/.../buffer/scan_elements/in_voltageY_en -What: /sys/.../buffer/scan_elements/in_voltageY-voltageZ_en -What: /sys/.../buffer/scan_elements/in_incli_x_en -What: /sys/.../buffer/scan_elements/in_incli_y_en +What: /sys/.../iio:deviceX/scan_elements/in_accel_x_en +What: /sys/.../iio:deviceX/scan_elements/in_accel_y_en +What: /sys/.../iio:deviceX/scan_elements/in_accel_z_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_en +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_x_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_y_en +What: /sys/.../iio:deviceX/scan_elements/in_magn_z_en +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_en +What: /sys/.../iio:deviceX/scan_elements/in_voltageY-voltageZ_en +What: /sys/.../iio:deviceX/scan_elements/in_incli_x_en +What: /sys/.../iio:deviceX/scan_elements/in_incli_y_en +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_en +What: /sys/.../iio:deviceX/scan_elements/in_pressure_en KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: Scan element control for triggered data capture. -What: /sys/.../buffer/scan_elements/in_accel_type -What: /sys/.../buffer/scan_elements/in_anglvel_type -What: /sys/.../buffer/scan_elements/in_magn_type -What: /sys/.../buffer/scan_elements/in_incli_type -What: /sys/.../buffer/scan_elements/in_voltageY_type -What: /sys/.../buffer/scan_elements/in_voltage-in_type -What: /sys/.../buffer/scan_elements/in_voltageY_supply_type -What: /sys/.../buffer/scan_elements/in_timestamp_type +What: /sys/.../iio:deviceX/scan_elements/in_accel_type +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_type +What: /sys/.../iio:deviceX/scan_elements/in_magn_type +What: /sys/.../iio:deviceX/scan_elements/in_incli_type +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_type +What: /sys/.../iio:deviceX/scan_elements/in_voltage_type +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_type +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_type +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_type +What: /sys/.../iio:deviceX/scan_elements/in_pressure_type KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -665,32 +748,34 @@ Description: the buffer output value appropriately. The storagebits value also specifies the data alignment. So s48/64>>2 will be a signed 48 bit integer stored in a 64 bit location aligned to - a a64 bit boundary. To obtain the clean value, shift right 2 + a 64 bit boundary. To obtain the clean value, shift right 2 and apply a mask to zero the top 16 bits of the result. For other storage combinations this attribute will be extended appropriately. -What: /sys/.../buffer/scan_elements/in_accel_type_available +What: /sys/.../iio:deviceX/scan_elements/in_accel_type_available KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: If the type parameter can take one of a small set of values, this attribute lists them. -What: /sys/.../buffer/scan_elements/in_voltageY_index -What: /sys/.../buffer/scan_elements/in_voltageY_supply_index -What: /sys/.../buffer/scan_elements/in_accel_x_index -What: /sys/.../buffer/scan_elements/in_accel_y_index -What: /sys/.../buffer/scan_elements/in_accel_z_index -What: /sys/.../buffer/scan_elements/in_anglvel_x_index -What: /sys/.../buffer/scan_elements/in_anglvel_y_index -What: /sys/.../buffer/scan_elements/in_anglvel_z_index -What: /sys/.../buffer/scan_elements/in_magn_x_index -What: /sys/.../buffer/scan_elements/in_magn_y_index -What: /sys/.../buffer/scan_elements/in_magn_z_index -What: /sys/.../buffer/scan_elements/in_incli_x_index -What: /sys/.../buffer/scan_elements/in_incli_y_index -What: /sys/.../buffer/scan_elements/in_timestamp_index +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_index +What: /sys/.../iio:deviceX/scan_elements/in_voltageY_supply_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_x_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_y_index +What: /sys/.../iio:deviceX/scan_elements/in_accel_z_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_x_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_y_index +What: /sys/.../iio:deviceX/scan_elements/in_anglvel_z_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_x_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_y_index +What: /sys/.../iio:deviceX/scan_elements/in_magn_z_index +What: /sys/.../iio:deviceX/scan_elements/in_incli_x_index +What: /sys/.../iio:deviceX/scan_elements/in_incli_y_index +What: /sys/.../iio:deviceX/scan_elements/in_timestamp_index +What: /sys/.../iio:deviceX/scan_elements/in_pressureY_index +What: /sys/.../iio:deviceX/scan_elements/in_pressure_index KernelVersion: 2.6.37 Contact: linux-iio@vger.kernel.org Description: @@ -709,23 +794,20 @@ Description: This attribute is used to read the amount of quadrature error present in the device at a given time. -What: /sys/.../iio:deviceX/ac_excitation_en -KernelVersion: 3.1.0 +What: /sys/.../iio:deviceX/in_accelX_power_mode +KernelVersion: 3.11 Contact: linux-iio@vger.kernel.org Description: - This attribute, if available, is used to enable the AC - excitation mode found on some converters. In ac excitation mode, - the polarity of the excitation voltage is reversed on - alternate cycles, to eliminate DC errors. + Specifies the chip power mode. + low_noise: reduce noise level from ADC, + low_power: enable low current consumption. + For a list of available output power modes read + in_accel_power_mode_available. -What: /sys/.../iio:deviceX/bridge_switch_en -KernelVersion: 3.1.0 +What: /sys/bus/iio/devices/iio:deviceX/store_eeprom +KernelVersion: 3.4.0 Contact: linux-iio@vger.kernel.org Description: - This attribute, if available, is used to close or open the - bridge power down switch found on some converters. - In bridge applications, such as strain gauges and load cells, - the bridge itself consumes the majority of the current in the - system. To minimize the current consumption of the system, - the bridge can be disconnected (when it is not being used - using the bridge_switch_en attribute. + Writing '1' stores the current device configuration into + on-chip EEPROM. After power-up or chip reset the device will + automatically load the saved configuration. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 new file mode 100644 index 000000000000..a91aeabe7b24 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-ad9523 @@ -0,0 +1,29 @@ +What: /sys/bus/iio/devices/iio:deviceX/pll2_feedback_clk_present +What: /sys/bus/iio/devices/iio:deviceX/pll2_reference_clk_present +What: /sys/bus/iio/devices/iio:deviceX/pll1_reference_clk_a_present +What: /sys/bus/iio/devices/iio:deviceX/pll1_reference_clk_b_present +What: /sys/bus/iio/devices/iio:deviceX/pll1_reference_clk_test_present +What: /sys/bus/iio/devices/iio:deviceX/vcxo_clk_present +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns either '1' or '0'. + '1' means that the clock in question is present. + '0' means that the clock is missing. + +What: /sys/bus/iio/devices/iio:deviceX/pllY_locked +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Reading returns either '1' or '0'. '1' means that the + pllY is locked. + +What: /sys/bus/iio/devices/iio:deviceX/sync_dividers +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Writing '1' triggers the clock distribution synchronization + functionality. All dividers are reset and the channels start + with their predefined phase offsets (out_altvoltageY_phase). + Writing this file has the effect as driving the external + /SYNC pin low. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4350 b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4350 new file mode 100644 index 000000000000..1254457a726e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-frequency-adf4350 @@ -0,0 +1,21 @@ +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_frequency_resolution +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Stores channel Y frequency resolution/channel spacing in Hz. + The value given directly influences the MODULUS used by + the fractional-N PLL. It is assumed that the algorithm + that is used to compute the various dividers, is able to + generate proper values for multiples of channel spacing. + +What: /sys/bus/iio/devices/iio:deviceX/out_altvoltageY_refin_frequency +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + Sets channel Y REFin frequency in Hz. In some clock chained + applications, the reference frequency used by the PLL may + change during runtime. This attribute allows the user to + adjust the reference frequency accordingly. + The value written has no effect until out_altvoltageY_frequency + is updated. Consider to use out_altvoltageY_powerdown to power + down the PLL and its RFOut buffers during REFin changes. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als new file mode 100644 index 000000000000..22c5ea670971 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-light-lm3533-als @@ -0,0 +1,61 @@ +What: /sys/.../events/in_illuminance0_thresh_either_en +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Event generated when channel passes one of the four thresholds + in each direction (rising|falling) and a zone change occurs. + The corresponding light zone can be read from + in_illuminance0_zone. + +What: /sys/.../events/in_illuminance0_threshY_hysteresis +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the hysteresis for thresholds Y, that is, + threshY_hysteresis = threshY_raising - threshY_falling + +What: /sys/.../events/illuminance_threshY_falling_value +What: /sys/.../events/illuminance_threshY_raising_value +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Specifies the value of threshold that the device is comparing + against for the events enabled by + in_illuminance0_thresh_either_en (0..255), where Y in 0..3. + + Note that threshY_falling must be less than or equal to + threshY_raising. + + These thresholds correspond to the eight zone-boundary + registers (boundaryY_{low,high}) and define the five light + zones. + +What: /sys/bus/iio/devices/iio:deviceX/in_illuminance0_zone +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the current light zone (0..4) as defined by the + in_illuminance0_threshY_{falling,rising} thresholds. + +What: /sys/bus/iio/devices/iio:deviceX/out_currentY_raw +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get output current for channel Y (0..255), that is, + out_currentY_currentZ_raw, where Z is the current zone. + +What: /sys/bus/iio/devices/iio:deviceX/out_currentY_currentZ_raw +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the output current for channel out_currentY when in zone + Z (0..255), where Y in 0..2 and Z in 0..4. + + These values correspond to the ALS-mapper target registers for + ALS-mapper Y + 1. diff --git a/Documentation/ABI/testing/sysfs-bus-iio-mpu6050 b/Documentation/ABI/testing/sysfs-bus-iio-mpu6050 new file mode 100644 index 000000000000..cb53737aacbf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-iio-mpu6050 @@ -0,0 +1,13 @@ +What: /sys/bus/iio/devices/iio:deviceX/in_gyro_matrix +What: /sys/bus/iio/devices/iio:deviceX/in_accel_matrix +What: /sys/bus/iio/devices/iio:deviceX/in_magn_matrix +KernelVersion: 3.4.0 +Contact: linux-iio@vger.kernel.org +Description: + This is mounting matrix for motion sensors. Mounting matrix + is a 3x3 unitary matrix. A typical mounting matrix would look like + [0, 1, 0; 1, 0, 0; 0, 0, -1]. Using this information, it would be + easy to tell the relative positions among sensors as well as their + positions relative to the board that holds these sensors. Identity matrix + [1, 0, 0; 0, 1, 0; 0, 0, 1] means sensor chip and device are perfectly + aligned with each other. All axes are exactly the same. diff --git a/Documentation/ABI/testing/sysfs-bus-mdio b/Documentation/ABI/testing/sysfs-bus-mdio new file mode 100644 index 000000000000..6349749ebc29 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-mdio @@ -0,0 +1,9 @@ +What: /sys/bus/mdio_bus/devices/.../phy_id +Date: November 2012 +KernelVersion: 3.8 +Contact: netdev@vger.kernel.org +Description: + This attribute contains the 32-bit PHY Identifier as reported + by the device during bus enumeration, encoded in hexadecimal. + This ID is used to match the device with the appropriate + driver. diff --git a/Documentation/ABI/testing/sysfs-bus-mei b/Documentation/ABI/testing/sysfs-bus-mei new file mode 100644 index 000000000000..2066f0bbd453 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-mei @@ -0,0 +1,7 @@ +What: /sys/bus/mei/devices/.../modalias +Date: March 2013 +KernelVersion: 3.10 +Contact: Samuel Ortiz <sameo@linux.intel.com> + linux-mei@linux.intel.com +Description: Stores the same MODALIAS value emitted by uevent + Format: mei:<mei device name> diff --git a/Documentation/ABI/testing/sysfs-bus-pci b/Documentation/ABI/testing/sysfs-bus-pci index 349ecf26ce10..5210a51c90fd 100644 --- a/Documentation/ABI/testing/sysfs-bus-pci +++ b/Documentation/ABI/testing/sysfs-bus-pci @@ -64,7 +64,24 @@ Description: Writing a non-zero value to this attribute will force a rescan of all PCI buses in the system, and re-discover previously removed devices. - Depends on CONFIG_HOTPLUG. + +What: /sys/bus/pci/devices/.../msi_irqs/ +Date: September, 2011 +Contact: Neil Horman <nhorman@tuxdriver.com> +Description: + The /sys/devices/.../msi_irqs directory contains a variable set + of sub-directories, with each sub-directory being named after a + corresponding msi irq vector allocated to that device. Each + numbered sub-directory N contains attributes of that irq. + Note that this directory is not created for device drivers which + do not support msi irqs + +What: /sys/bus/pci/devices/.../msi_irqs/<N>/mode +Date: September 2011 +Contact: Neil Horman <nhorman@tuxdriver.com> +Description: + This attribute indicates the mode that the irq vector named by + the parent directory is in (msi vs. msix) What: /sys/bus/pci/devices/.../remove Date: January 2009 @@ -72,7 +89,6 @@ Contact: Linux PCI developers <linux-pci@vger.kernel.org> Description: Writing a non-zero value to this attribute will hot-remove the PCI device and any of its children. - Depends on CONFIG_HOTPLUG. What: /sys/bus/pci/devices/.../pci_bus/.../rescan Date: May 2011 @@ -81,7 +97,7 @@ Description: Writing a non-zero value to this attribute will force a rescan of the bus and all child buses, and re-discover devices removed earlier from this - part of the device tree. Depends on CONFIG_HOTPLUG. + part of the device tree. What: /sys/bus/pci/devices/.../rescan Date: January 2009 @@ -91,7 +107,6 @@ Description: force a rescan of the device's parent bus and all child buses, and re-discover devices removed earlier from this part of the device tree. - Depends on CONFIG_HOTPLUG. What: /sys/bus/pci/devices/.../reset Date: July 2009 @@ -192,3 +207,49 @@ Users: firmware assigned instance number of the PCI device that can help in understanding the firmware intended order of the PCI device. + +What: /sys/bus/pci/devices/.../d3cold_allowed +Date: July 2012 +Contact: Huang Ying <ying.huang@intel.com> +Description: + d3cold_allowed is bit to control whether the corresponding PCI + device can be put into D3Cold state. If it is cleared, the + device will never be put into D3Cold state. If it is set, the + device may be put into D3Cold state if other requirements are + satisfied too. Reading this attribute will show the current + value of d3cold_allowed bit. Writing this attribute will set + the value of d3cold_allowed bit. + +What: /sys/bus/pci/devices/.../sriov_totalvfs +Date: November 2012 +Contact: Donald Dutile <ddutile@redhat.com> +Description: + This file appears when a physical PCIe device supports SR-IOV. + Userspace applications can read this file to determine the + maximum number of Virtual Functions (VFs) a PCIe physical + function (PF) can support. Typically, this is the value reported + in the PF's SR-IOV extended capability structure's TotalVFs + element. Drivers have the ability at probe time to reduce the + value read from this file via the pci_sriov_set_totalvfs() + function. + +What: /sys/bus/pci/devices/.../sriov_numvfs +Date: November 2012 +Contact: Donald Dutile <ddutile@redhat.com> +Description: + This file appears when a physical PCIe device supports SR-IOV. + Userspace applications can read and write to this file to + determine and control the enablement or disablement of Virtual + Functions (VFs) on the physical function (PF). A read of this + file will return the number of VFs that are enabled on this PF. + A number written to this file will enable the specified + number of VFs. A userspace application would typically read the + file and check that the value is zero, and then write the number + of VFs that should be enabled on the PF; the value written + should be less than or equal to the value in the sriov_totalvfs + file. A userspace application wanting to disable the VFs would + write a zero to this file. The core ensures that valid values + are written to this file, and returns errors when values are not + valid. For example, writing a 2 to this file when sriov_numvfs + is not 0 and not 2 already will return an error. Writing a 10 + when the value of sriov_totalvfs is 8 will return an error. diff --git a/Documentation/ABI/testing/sysfs-bus-rbd b/Documentation/ABI/testing/sysfs-bus-rbd index fa72ccb2282e..0a306476424e 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,10 +37,21 @@ 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 pool where this rbd image resides. The pool-name pair is unique - per rados system. + The name of the storage pool where this rbd image resides. + An rbd image name is unique within its pool. + +pool_id + + The unique identifier for the rbd image's pool. This is + a permanent attribute of the pool. A pool's id will never + change. size @@ -51,33 +66,7 @@ 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 - -rollback_snap - - Rolls back data to the specified snapshot. This goes over the entire - list of rados blocks and sends a rollback command to each. - - $ echo <snap-name> > /sys/bus/rbd/devices/<dev-id>/snap_rollback - -snap_* - - A directory per each snapshot - - -Entries under /sys/bus/rbd/devices/<dev-id>/snap_<snap-name> -------------------------------------------------------------- - -id - - The rados internal snapshot id assigned for this snapshot - -size - - The size of the image when this snapshot was taken. - +parent + Information identifying the pool, image, and snapshot id for + the parent image in a layered rbd image (format 2 only). diff --git a/Documentation/ABI/testing/sysfs-bus-rpmsg b/Documentation/ABI/testing/sysfs-bus-rpmsg new file mode 100644 index 000000000000..189e419a5a2d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-bus-rpmsg @@ -0,0 +1,75 @@ +What: /sys/bus/rpmsg/devices/.../name +Date: June 2011 +KernelVersion: 3.3 +Contact: Ohad Ben-Cohen <ohad@wizery.com> +Description: + Every rpmsg device is a communication channel with a remote + processor. Channels are identified with a (textual) name, + which is maximum 32 bytes long (defined as RPMSG_NAME_SIZE in + rpmsg.h). + + This sysfs entry contains the name of this channel. + +What: /sys/bus/rpmsg/devices/.../src +Date: June 2011 +KernelVersion: 3.3 +Contact: Ohad Ben-Cohen <ohad@wizery.com> +Description: + Every rpmsg device is a communication channel with a remote + processor. Channels have a local ("source") rpmsg address, + and remote ("destination") rpmsg address. When an entity + starts listening on one end of a channel, it assigns it with + a unique rpmsg address (a 32 bits integer). This way when + inbound messages arrive to this address, the rpmsg core + dispatches them to the listening entity (a kernel driver). + + This sysfs entry contains the src (local) rpmsg address + of this channel. If it contains 0xffffffff, then an address + wasn't assigned (can happen if no driver exists for this + channel). + +What: /sys/bus/rpmsg/devices/.../dst +Date: June 2011 +KernelVersion: 3.3 +Contact: Ohad Ben-Cohen <ohad@wizery.com> +Description: + Every rpmsg device is a communication channel with a remote + processor. Channels have a local ("source") rpmsg address, + and remote ("destination") rpmsg address. When an entity + starts listening on one end of a channel, it assigns it with + a unique rpmsg address (a 32 bits integer). This way when + inbound messages arrive to this address, the rpmsg core + dispatches them to the listening entity. + + This sysfs entry contains the dst (remote) rpmsg address + of this channel. If it contains 0xffffffff, then an address + wasn't assigned (can happen if the kernel driver that + is attached to this channel is exposing a service to the + remote processor. This make it a local rpmsg server, + and it is listening for inbound messages that may be sent + from any remote rpmsg client; it is not bound to a single + remote entity). + +What: /sys/bus/rpmsg/devices/.../announce +Date: June 2011 +KernelVersion: 3.3 +Contact: Ohad Ben-Cohen <ohad@wizery.com> +Description: + Every rpmsg device is a communication channel with a remote + processor. Channels are identified by a textual name (see + /sys/bus/rpmsg/devices/.../name above) and have a local + ("source") rpmsg address, and remote ("destination") rpmsg + address. + + A channel is first created when an entity, whether local + or remote, starts listening on it for messages (and is thus + called an rpmsg server). + + When that happens, a "name service" announcement is sent + to the other processor, in order to let it know about the + creation of the channel (this way remote clients know they + can start sending messages). + + This sysfs entry tells us whether the channel is a local + server channel that is announced (values are either + true or false). diff --git a/Documentation/ABI/testing/sysfs-bus-usb b/Documentation/ABI/testing/sysfs-bus-usb index e647378e9e88..1430f584b266 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb +++ b/Documentation/ABI/testing/sysfs-bus-usb @@ -1,81 +1,3 @@ -What: /sys/bus/usb/devices/.../power/autosuspend -Date: March 2007 -KernelVersion: 2.6.21 -Contact: Alan Stern <stern@rowland.harvard.edu> -Description: - Each USB device directory will contain a file named - power/autosuspend. This file holds the time (in seconds) - the device must be idle before it will be autosuspended. - 0 means the device will be autosuspended as soon as - possible. Negative values will prevent the device from - being autosuspended at all, and writing a negative value - will resume the device if it is already suspended. - - The autosuspend delay for newly-created devices is set to - the value of the usbcore.autosuspend module parameter. - -What: /sys/bus/usb/devices/.../power/persist -Date: May 2007 -KernelVersion: 2.6.23 -Contact: Alan Stern <stern@rowland.harvard.edu> -Description: - If CONFIG_USB_PERSIST is set, then each USB device directory - will contain a file named power/persist. The file holds a - boolean value (0 or 1) indicating whether or not the - "USB-Persist" facility is enabled for the device. Since the - facility is inherently dangerous, it is disabled by default - for all devices except hubs. For more information, see - Documentation/usb/persist.txt. - -What: /sys/bus/usb/device/.../power/connected_duration -Date: January 2008 -KernelVersion: 2.6.25 -Contact: Sarah Sharp <sarah.a.sharp@intel.com> -Description: - If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file - is present. When read, it returns the total time (in msec) - that the USB device has been connected to the machine. This - file is read-only. -Users: - PowerTOP <power@bughost.org> - http://www.lesswatts.org/projects/powertop/ - -What: /sys/bus/usb/device/.../power/active_duration -Date: January 2008 -KernelVersion: 2.6.25 -Contact: Sarah Sharp <sarah.a.sharp@intel.com> -Description: - If CONFIG_PM and CONFIG_USB_SUSPEND are enabled, then this file - is present. When read, it returns the total time (in msec) - that the USB device has been active, i.e. not in a suspended - state. This file is read-only. - - Tools can use this file and the connected_duration file to - compute the percentage of time that a device has been active. - For example, - echo $((100 * `cat active_duration` / `cat connected_duration`)) - will give an integer percentage. Note that this does not - account for counter wrap. -Users: - PowerTOP <power@bughost.org> - http://www.lesswatts.org/projects/powertop/ - -What: /sys/bus/usb/device/<busnum>-<devnum>...:<config num>-<interface num>/supports_autosuspend -Date: January 2008 -KernelVersion: 2.6.27 -Contact: Sarah Sharp <sarah.a.sharp@intel.com> -Description: - When read, this file returns 1 if the interface driver - for this interface supports autosuspend. It also - returns 1 if no driver has claimed this interface, as an - unclaimed interface will not stop the device from being - autosuspended if all other interface drivers are idle. - The file returns 0 if autosuspend support has not been - added to the driver. -Users: - USB PM tool - git://git.moblin.org/users/sarah/usb-pm-tool/ - What: /sys/bus/usb/device/.../authorized Date: July 2008 KernelVersion: 2.6.26 @@ -119,6 +41,42 @@ Description: Write a 1 to force the device to disconnect (equivalent to unplugging a wired USB device). +What: /sys/bus/usb/drivers/.../new_id +Date: October 2011 +Contact: linux-usb@vger.kernel.org +Description: + Writing a device ID to this file will attempt to + dynamically add a new device ID to a USB device driver. + This may allow the driver to support more hardware than + was included in the driver's static device ID support + table at compile time. The format for the device ID is: + idVendor idProduct bInterfaceClass. + The vendor ID and device ID fields are required, the + interface class is optional. + Upon successfully adding an ID, the driver will probe + for the device and attempt to bind to it. For example: + # echo "8086 10f5" > /sys/bus/usb/drivers/foo/new_id + + Reading from this file will list all dynamically added + device IDs in the same format, with one entry per + line. For example: + # cat /sys/bus/usb/drivers/foo/new_id + 8086 10f5 + dead beef 06 + f00d cafe + + The list will be truncated at PAGE_SIZE bytes due to + sysfs restrictions. + +What: /sys/bus/usb-serial/drivers/.../new_id +Date: October 2011 +Contact: linux-usb@vger.kernel.org +Description: + For serial USB drivers, this attribute appears under the + extra bus folder "usb-serial" in sysfs; apart from that + difference, all descriptions from the entry + "/sys/bus/usb/drivers/.../new_id" apply. + What: /sys/bus/usb/drivers/.../remove_id Date: November 2009 Contact: CHENG Renquan <rqcheng@smu.edu.sg> @@ -132,22 +90,15 @@ Description: match the driver to the device. For example: # echo "046d c315" > /sys/bus/usb/drivers/foo/remove_id -What: /sys/bus/usb/device/.../avoid_reset_quirk -Date: December 2009 -Contact: Oliver Neukum <oliver@neukum.org> -Description: - Writing 1 to this file tells the kernel that this - device will morph into another mode when it is reset. - Drivers will not use reset for error handling for - such devices. -Users: - usb_modeswitch + Reading from this file will list the dynamically added + device IDs, exactly like reading from the entry + "/sys/bus/usb/drivers/.../new_id" What: /sys/bus/usb/devices/.../power/usb2_hardware_lpm Date: September 2011 Contact: Andiry Xu <andiry.xu@amd.com> Description: - If CONFIG_USB_SUSPEND is set and a USB 2.0 lpm-capable device + If CONFIG_PM_RUNTIME is set and a USB 2.0 lpm-capable device is plugged in to a xHCI host which support link PM, it will perform a LPM test; if the test is passed and host supports USB2 hardware LPM (xHCI 1.0 feature), USB2 hardware LPM will @@ -157,3 +108,69 @@ Description: USB2 hardware LPM is enabled for the device. Developer can write y/Y/1 or n/N/0 to the file to enable/disable the feature. + +What: /sys/bus/usb/devices/.../removable +Date: February 2012 +Contact: Matthew Garrett <mjg@redhat.com> +Description: + Some information about whether a given USB device is + physically fixed to the platform can be inferred from a + combination of hub descriptor bits and platform-specific data + such as ACPI. This file will read either "removable" or + "fixed" if the information is available, and "unknown" + otherwise. + +What: /sys/bus/usb/devices/.../ltm_capable +Date: July 2012 +Contact: Sarah Sharp <sarah.a.sharp@linux.intel.com> +Description: + USB 3.0 devices may optionally support Latency Tolerance + Messaging (LTM). They indicate their support by setting a bit + in the bmAttributes field of their SuperSpeed BOS descriptors. + If that bit is set for the device, ltm_capable will read "yes". + 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. + +What: /sys/bus/usb/devices/.../(hub interface)/portX/connect_type +Date: January 2013 +Contact: Lan Tianyu <tianyu.lan@intel.com> +Description: + Some platforms provide usb port connect types through ACPI. + This attribute is to expose these information to user space. + The file will read "hotplug", "wired" and "not used" if the + information is available, and "unknown" otherwise. + +What: /sys/bus/usb/devices/.../power/usb2_lpm_l1_timeout +Date: May 2013 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + USB 2.0 devices may support hardware link power management (LPM) + L1 sleep state. The usb2_lpm_l1_timeout attribute allows + tuning the timeout for L1 inactivity timer (LPM timer), e.g. + needed inactivity time before host requests the device to go to L1 sleep. + Useful for power management tuning. + Supported values are 0 - 65535 microseconds. + +What: /sys/bus/usb/devices/.../power/usb2_lpm_besl +Date: May 2013 +Contact: Mathias Nyman <mathias.nyman@linux.intel.com> +Description: + USB 2.0 devices that support hardware link power management (LPM) + L1 sleep state now use a best effort service latency value (BESL) to + indicate the best effort to resumption of service to the device after the + initiation of the resume event. + If the device does not have a preferred besl value then the host can select + one instead. This usb2_lpm_besl attribute allows to tune the host selected besl + value in order to tune power saving and service latency. + + Supported values are 0 - 15. + More information on how besl values map to microseconds can be found in + USB 2.0 ECN Errata for Link Power Management, section 4.10) diff --git a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg index cb830df8777c..70d00dfa443d 100644 --- a/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg +++ b/Documentation/ABI/testing/sysfs-bus-usb-devices-usbsevseg @@ -40,4 +40,4 @@ Description: Controls the decimal places on the device. the value of 10 ** n. Assume this field has the value k and has 1 or more decimal places set, to set the mth place (where m is not already set), - change this fields value to k + 10 ** m.
\ No newline at end of file + change this fields value to k + 10 ** m. diff --git a/Documentation/ABI/testing/sysfs-cfq-target-latency b/Documentation/ABI/testing/sysfs-cfq-target-latency new file mode 100644 index 000000000000..df0f7828c5e3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-cfq-target-latency @@ -0,0 +1,8 @@ +What: /sys/block/<device>/iosched/target_latency +Date: March 2012 +contact: Tao Ma <boyu.mt@taobao.com> +Description: + The /sys/block/<device>/iosched/target_latency only exists + when the user sets cfq to /sys/block/<device>/scheduler. + It contains an estimated latency time for the cfq. cfq will + use it to calculate the time slice used for every task. diff --git a/Documentation/ABI/testing/sysfs-class b/Documentation/ABI/testing/sysfs-class index 4b0cb891e46e..676530fcf747 100644 --- a/Documentation/ABI/testing/sysfs-class +++ b/Documentation/ABI/testing/sysfs-class @@ -1,6 +1,6 @@ What: /sys/class/ Date: Febuary 2006 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: The /sys/class directory will consist of a group of subdirectories describing individual classes of devices diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 index 4a9c545bda4b..33e648808117 100644 --- a/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 +++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-adp8870 @@ -53,4 +53,4 @@ Description: Documentation/ABI/stable/sysfs-class-backlight. It can be enabled by writing the value stored in /sys/class/backlight/<backlight>/max_brightness to - /sys/class/backlight/<backlight>/brightness.
\ No newline at end of file + /sys/class/backlight/<backlight>/brightness. diff --git a/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 new file mode 100644 index 000000000000..77cf7ac949af --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-backlight-driver-lm3533 @@ -0,0 +1,48 @@ +What: /sys/class/backlight/<backlight>/als_channel +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the ALS output channel used as input in + ALS-current-control mode (0, 1), where + + 0 - out_current0 (backlight 0) + 1 - out_current1 (backlight 1) + +What: /sys/class/backlight/<backlight>/als_en +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Enable ALS-current-control mode (0, 1). + +What: /sys/class/backlight/<backlight>/id +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the id of this backlight (0, 1). + +What: /sys/class/backlight/<backlight>/linear +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the brightness-mapping mode (0, 1), where + + 0 - exponential mode + 1 - linear mode + +What: /sys/class/backlight/<backlight>/pwm +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the PWM-input control mask (5 bits), where + + bit 5 - PWM-input enabled in Zone 4 + bit 4 - PWM-input enabled in Zone 3 + bit 3 - PWM-input enabled in Zone 2 + bit 2 - PWM-input enabled in Zone 1 + bit 1 - PWM-input enabled in Zone 0 + bit 0 - PWM-input enabled diff --git a/Documentation/ABI/testing/sysfs-class-bdi b/Documentation/ABI/testing/sysfs-class-bdi index 5f500977b42f..d773d5697cf5 100644 --- a/Documentation/ABI/testing/sysfs-class-bdi +++ b/Documentation/ABI/testing/sysfs-class-bdi @@ -48,3 +48,8 @@ max_ratio (read-write) most of the write-back cache. For example in case of an NFS mount that is prone to get stuck, or a FUSE mount which cannot be trusted to play fair. + +stable_pages_required (read-only) + + If set, the backing device requires that all pages comprising a write + request must not be changed until writeout is complete. diff --git a/Documentation/ABI/testing/sysfs-class-devfreq b/Documentation/ABI/testing/sysfs-class-devfreq index 23d78b5aab11..ee39acacf6f8 100644 --- a/Documentation/ABI/testing/sysfs-class-devfreq +++ b/Documentation/ABI/testing/sysfs-class-devfreq @@ -11,7 +11,7 @@ What: /sys/class/devfreq/.../governor Date: September 2011 Contact: MyungJoo Ham <myungjoo.ham@samsung.com> Description: - The /sys/class/devfreq/.../governor shows the name of the + The /sys/class/devfreq/.../governor show or set the name of the governor used by the corresponding devfreq object. What: /sys/class/devfreq/.../cur_freq @@ -19,15 +19,16 @@ Date: September 2011 Contact: MyungJoo Ham <myungjoo.ham@samsung.com> Description: The /sys/class/devfreq/.../cur_freq shows the current - frequency of the corresponding devfreq object. + frequency of the corresponding devfreq object. Same as + target_freq when get_cur_freq() is not implemented by + devfreq driver. -What: /sys/class/devfreq/.../central_polling -Date: September 2011 -Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +What: /sys/class/devfreq/.../target_freq +Date: September 2012 +Contact: Rajagopal Venkat <rajagopal.venkat@linaro.org> Description: - The /sys/class/devfreq/.../central_polling shows whether - the devfreq ojbect is using devfreq-provided central - polling mechanism or not. + The /sys/class/devfreq/.../target_freq shows the next governor + predicted target frequency of the corresponding devfreq object. What: /sys/class/devfreq/.../polling_interval Date: September 2011 @@ -43,6 +44,17 @@ Description: (/sys/class/devfreq/.../central_polling is 0), this value may be useless. +What: /sys/class/devfreq/.../trans_stat +Date: October 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Descrtiption: + This ABI shows the statistics of devfreq behavior on a + specific device. It shows the time spent in each state and + the number of transitions between states. + In order to activate this ABI, the devfreq target device + driver should provide the list of available frequencies + with its profile. + What: /sys/class/devfreq/.../userspace/set_freq Date: September 2011 Contact: MyungJoo Ham <myungjoo.ham@samsung.com> @@ -50,3 +62,39 @@ Description: The /sys/class/devfreq/.../userspace/set_freq shows and sets the requested frequency for the devfreq object if userspace governor is in effect. + +What: /sys/class/devfreq/.../available_frequencies +Date: October 2012 +Contact: Nishanth Menon <nm@ti.com> +Description: + The /sys/class/devfreq/.../available_frequencies shows + the available frequencies of the corresponding devfreq object. + This is a snapshot of available frequencies and not limited + by the min/max frequency restrictions. + +What: /sys/class/devfreq/.../available_governors +Date: October 2012 +Contact: Nishanth Menon <nm@ti.com> +Description: + The /sys/class/devfreq/.../available_governors shows + currently available governors in the system. + +What: /sys/class/devfreq/.../min_freq +Date: January 2013 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/devfreq/.../min_freq shows and stores + the minimum frequency requested by users. It is 0 if + the user does not care. min_freq overrides the + frequency requested by governors. + +What: /sys/class/devfreq/.../max_freq +Date: January 2013 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/devfreq/.../max_freq shows and stores + the maximum frequency requested by users. It is 0 if + the user does not care. max_freq overrides the + frequency requested by governors and min_freq. + The max_freq overrides min_freq because max_freq may be + used to throttle devices to avoid overheating. diff --git a/Documentation/ABI/testing/sysfs-class-extcon b/Documentation/ABI/testing/sysfs-class-extcon new file mode 100644 index 000000000000..57a726232912 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-extcon @@ -0,0 +1,97 @@ +What: /sys/class/extcon/.../ +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + Provide a place in sysfs for the extcon objects. + This allows accessing extcon specific variables. + The name of extcon object denoted as ... is the name given + with extcon_dev_register. + + One extcon device denotes a single external connector + port. An external connector may have multiple cables + attached simultaneously. Many of docks, cradles, and + 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 simultaneously. + + If there are cables mutually exclusive with each other, + such binary relations may be expressed with extcon_dev's + mutually_exclusive array. + +What: /sys/class/extcon/.../name +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/extcon/.../name shows the name of the extcon + object. If the extcon object has an optional callback + "show_name" defined, the callback will provide the name with + this sysfs node. + +What: /sys/class/extcon/.../state +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +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 overridden with the optional + callback. + + If the default callback for showing function is used, the + format is like this: + # cat state + USB_OTG=1 + HDMI=0 + TA=1 + EAR_JACK=0 + # + 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 + + This updates the whole state of the extcon device. + Inputs of all the methods are required to meet the + mutually_exclusive conditions if they exist. + + It is recommended to use this "global" state interface if + 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. + +What: /sys/class/extcon/.../cable.x/name +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + The /sys/class/extcon/.../cable.x/name shows the name of cable + "x" (integer between 0 and 31) of an extcon device. + +What: /sys/class/extcon/.../cable.x/state +Date: February 2012 +Contact: MyungJoo Ham <myungjoo.ham@samsung.com> +Description: + 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). + +What: /sys/class/extcon/.../mutually_exclusive/... +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 device is + {0x3, 0x5, 0xC, 0x0}, then the output is: + # ls mutually_exclusive/ + 0x3 + 0x5 + 0xc + # + + Note that mutually_exclusive is a sub-directory of the extcon + device and the file names under the mutually_exclusive + directory show the mutually-exclusive sets, not the contents + of the files. diff --git a/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 new file mode 100644 index 000000000000..620ebb3b9baa --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-led-driver-lm3533 @@ -0,0 +1,65 @@ +What: /sys/class/leds/<led>/als_channel +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the ALS output channel to use as input in + ALS-current-control mode (1, 2), where + + 1 - out_current1 + 2 - out_current2 + +What: /sys/class/leds/<led>/als_en +Date: May 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Enable ALS-current-control mode (0, 1). + +What: /sys/class/leds/<led>/falltime +What: /sys/class/leds/<led>/risetime +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the pattern generator fall and rise times (0..7), where + + 0 - 2048 us + 1 - 262 ms + 2 - 524 ms + 3 - 1.049 s + 4 - 2.097 s + 5 - 4.194 s + 6 - 8.389 s + 7 - 16.78 s + +What: /sys/class/leds/<led>/id +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Get the id of this led (0..3). + +What: /sys/class/leds/<led>/linear +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the brightness-mapping mode (0, 1), where + + 0 - exponential mode + 1 - linear mode + +What: /sys/class/leds/<led>/pwm +Date: April 2012 +KernelVersion: 3.5 +Contact: Johan Hovold <jhovold@gmail.com> +Description: + Set the PWM-input control mask (5 bits), where + + bit 5 - PWM-input enabled in Zone 4 + bit 4 - PWM-input enabled in Zone 3 + bit 3 - PWM-input enabled in Zone 2 + bit 2 - PWM-input enabled in Zone 1 + bit 1 - PWM-input enabled in Zone 0 + bit 0 - PWM-input enabled diff --git a/Documentation/ABI/testing/sysfs-class-mtd b/Documentation/ABI/testing/sysfs-class-mtd index 4d55a1888981..bfd119ace6ad 100644 --- a/Documentation/ABI/testing/sysfs-class-mtd +++ b/Documentation/ABI/testing/sysfs-class-mtd @@ -14,8 +14,7 @@ Description: The /sys/class/mtd/mtd{0,1,2,3,...} directories correspond to each /dev/mtdX character device. These may represent physical/simulated flash devices, partitions on a flash - device, or concatenated flash devices. They exist regardless - of whether CONFIG_MTD_CHAR is actually enabled. + device, or concatenated flash devices. What: /sys/class/mtd/mtdXro/ Date: April 2009 @@ -23,8 +22,7 @@ KernelVersion: 2.6.29 Contact: linux-mtd@lists.infradead.org Description: These directories provide the corresponding read-only device - nodes for /sys/class/mtd/mtdX/ . They are only created - (for the benefit of udev) if CONFIG_MTD_CHAR is enabled. + nodes for /sys/class/mtd/mtdX/ . What: /sys/class/mtd/mtdX/dev Date: April 2009 @@ -123,3 +121,66 @@ Description: half page, or a quarter page). In the case of ECC NOR, it is the ECC block size. + +What: /sys/class/mtd/mtdX/ecc_strength +Date: April 2012 +KernelVersion: 3.4 +Contact: linux-mtd@lists.infradead.org +Description: + Maximum number of bit errors that the device is capable of + correcting within each region covering an ECC step (see + ecc_step_size). This will always be a non-negative integer. + + In the case of devices lacking any ECC capability, it is 0. + +What: /sys/class/mtd/mtdX/bitflip_threshold +Date: April 2012 +KernelVersion: 3.4 +Contact: linux-mtd@lists.infradead.org +Description: + This allows the user to examine and adjust the criteria by which + mtd returns -EUCLEAN from mtd_read() and mtd_read_oob(). If the + maximum number of bit errors that were corrected on any single + region comprising an ecc step (as reported by the driver) equals + or exceeds this value, -EUCLEAN is returned. Otherwise, absent + an error, 0 is returned. Higher layers (e.g., UBI) use this + return code as an indication that an erase block may be + degrading and should be scrutinized as a candidate for being + marked as bad. + + The initial value may be specified by the flash device driver. + If not, then the default value is ecc_strength. + + The introduction of this feature brings a subtle change to the + meaning of the -EUCLEAN return code. Previously, it was + interpreted to mean simply "one or more bit errors were + corrected". Its new interpretation can be phrased as "a + dangerously high number of bit errors were corrected on one or + more regions comprising an ecc step". The precise definition of + "dangerously high" can be adjusted by the user with + bitflip_threshold. Users are discouraged from doing this, + however, unless they know what they are doing and have intimate + knowledge of the properties of their device. Broadly speaking, + bitflip_threshold should be low enough to detect genuine erase + block degradation, but high enough to avoid the consequences of + a persistent return value of -EUCLEAN on devices where sticky + bitflips occur. Note that if bitflip_threshold exceeds + ecc_strength, -EUCLEAN is never returned by the read operations. + Conversely, if bitflip_threshold is zero, -EUCLEAN is always + returned, absent a hard error. + + This is generally applicable only to NAND flash devices with ECC + capability. It is ignored on devices lacking ECC capability; + i.e., devices for which ecc_strength is zero. + +What: /sys/class/mtd/mtdX/ecc_step_size +Date: May 2013 +KernelVersion: 3.10 +Contact: linux-mtd@lists.infradead.org +Description: + The size of a single region covered by ECC, known as the ECC + step. Devices may have several equally sized ECC steps within + each writesize region. + + It will always be a non-negative integer. In the case of + devices lacking any ECC capability, it is 0. diff --git a/Documentation/ABI/testing/sysfs-class-net-batman-adv b/Documentation/ABI/testing/sysfs-class-net-batman-adv index 38dd762def4b..bdc00707c751 100644 --- a/Documentation/ABI/testing/sysfs-class-net-batman-adv +++ b/Documentation/ABI/testing/sysfs-class-net-batman-adv @@ -1,4 +1,10 @@ +What: /sys/class/net/<iface>/batman-adv/iface_status +Date: May 2010 +Contact: Marek Lindner <lindner_marek@yahoo.de> +Description: + Indicates the status of <iface> as it is seen by batman. + What: /sys/class/net/<iface>/batman-adv/mesh_iface Date: May 2010 Contact: Marek Lindner <lindner_marek@yahoo.de> @@ -7,8 +13,3 @@ Description: displays the batman mesh interface this <iface> currently is associated with. -What: /sys/class/net/<iface>/batman-adv/iface_status -Date: May 2010 -Contact: Marek Lindner <lindner_marek@yahoo.de> -Description: - Indicates the status of <iface> as it is seen by batman. diff --git a/Documentation/ABI/testing/sysfs-class-net-grcan b/Documentation/ABI/testing/sysfs-class-net-grcan new file mode 100644 index 000000000000..f418c92ca555 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-net-grcan @@ -0,0 +1,35 @@ + +What: /sys/class/net/<iface>/grcan/enable0 +Date: October 2012 +KernelVersion: 3.8 +Contact: Andreas Larsson <andreas@gaisler.com> +Description: + Hardware configuration of physical interface 0. This file reads + and writes the "Enable 0" bit of the configuration register. + Possible values: 0 or 1. See the GRCAN chapter of the GRLIB IP + core library documentation for details. The default value is 0 + or set by the module parameter grcan.enable0 and can be read at + /sys/module/grcan/parameters/enable0. + +What: /sys/class/net/<iface>/grcan/enable1 +Date: October 2012 +KernelVersion: 3.8 +Contact: Andreas Larsson <andreas@gaisler.com> +Description: + Hardware configuration of physical interface 1. This file reads + and writes the "Enable 1" bit of the configuration register. + Possible values: 0 or 1. See the GRCAN chapter of the GRLIB IP + core library documentation for details. The default value is 0 + or set by the module parameter grcan.enable1 and can be read at + /sys/module/grcan/parameters/enable1. + +What: /sys/class/net/<iface>/grcan/select +Date: October 2012 +KernelVersion: 3.8 +Contact: Andreas Larsson <andreas@gaisler.com> +Description: + Configuration of which physical interface to be used. Possible + values: 0 or 1. See the GRCAN chapter of the GRLIB IP core + library documentation for details. The default value is 0 or is + set by the module parameter grcan.select and can be read at + /sys/module/grcan/parameters/select. diff --git a/Documentation/ABI/testing/sysfs-class-net-mesh b/Documentation/ABI/testing/sysfs-class-net-mesh index b02001488eef..bdcd8b4e38f2 100644 --- a/Documentation/ABI/testing/sysfs-class-net-mesh +++ b/Documentation/ABI/testing/sysfs-class-net-mesh @@ -6,6 +6,14 @@ Description: Indicates whether the batman protocol messages of the mesh <mesh_iface> shall be aggregated or not. +What: /sys/class/net/<mesh_iface>/mesh/ap_isolation +Date: May 2011 +Contact: Antonio Quartulli <ordex@autistici.org> +Description: + Indicates whether the data traffic going from a + wireless client to another wireless client will be + silently dropped. + What: /sys/class/net/<mesh_iface>/mesh/bonding Date: June 2010 Contact: Simon Wunderlich <siwu@hrz.tu-chemnitz.de> @@ -14,6 +22,15 @@ Description: mesh will be sent using multiple interfaces at the same time (if available). +What: /sys/class/net/<mesh_iface>/mesh/bridge_loop_avoidance +Date: November 2011 +Contact: Simon Wunderlich <siwu@hrz.tu-chemnitz.de> +Description: + Indicates whether the bridge loop avoidance feature + is enabled. This feature detects and avoids loops + between the mesh and devices bridged with the soft + interface <mesh_iface>. + What: /sys/class/net/<mesh_iface>/mesh/fragmentation Date: October 2010 Contact: Andreas Langer <an.langer@gmx.de> @@ -22,14 +39,6 @@ Description: mesh will be fragmented or silently discarded if the packet size exceeds the outgoing interface MTU. -What: /sys/class/net/<mesh_iface>/mesh/ap_isolation -Date: May 2011 -Contact: Antonio Quartulli <ordex@autistici.org> -Description: - Indicates whether the data traffic going from a - wireless client to another wireless client will be - silently dropped. - What: /sys/class/net/<mesh_iface>/mesh/gw_bandwidth Date: October 2010 Contact: Marek Lindner <lindner_marek@yahoo.de> @@ -51,6 +60,21 @@ Description: Defines the selection criteria this node will use to choose a gateway if gw_mode was set to 'client'. +What: /sys/class/net/<mesh_iface>/mesh/hop_penalty +Date: Oct 2010 +Contact: Linus Lüssing <linus.luessing@web.de> +Description: + Defines the penalty which will be applied to an + originator message's tq-field on every hop. + +What: /sys/class/net/<mesh_iface>/mesh/network_coding +Date: Nov 2012 +Contact: Martin Hundeboll <martin@hundeboll.net> +Description: + Controls whether Network Coding (using some magic + to send fewer wifi packets but still the same + content) is enabled or not. + What: /sys/class/net/<mesh_iface>/mesh/orig_interval Date: May 2010 Contact: Marek Lindner <lindner_marek@yahoo.de> @@ -58,12 +82,12 @@ Description: Defines the interval in milliseconds in which batman sends its protocol messages. -What: /sys/class/net/<mesh_iface>/mesh/hop_penalty -Date: Oct 2010 -Contact: Linus Lüssing <linus.luessing@web.de> +What: /sys/class/net/<mesh_iface>/mesh/routing_algo +Date: Dec 2011 +Contact: Marek Lindner <lindner_marek@yahoo.de> Description: - Defines the penalty which will be applied to an - originator message's tq-field on every hop. + Defines the routing procotol this mesh instance + uses to find the optimal paths through the mesh. What: /sys/class/net/<mesh_iface>/mesh/vis_mode Date: May 2010 diff --git a/Documentation/ABI/testing/sysfs-class-pwm b/Documentation/ABI/testing/sysfs-class-pwm new file mode 100644 index 000000000000..c479d77b67c5 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-pwm @@ -0,0 +1,79 @@ +What: /sys/class/pwm/ +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + The pwm/ class sub-directory belongs to the Generic PWM + Framework and provides a sysfs interface for using PWM + channels. + +What: /sys/class/pwm/pwmchipN/ +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + A /sys/class/pwm/pwmchipN directory is created for each + probed PWM controller/chip where N is the base of the + PWM chip. + +What: /sys/class/pwm/pwmchipN/npwm +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + The number of PWM channels supported by the PWM chip. + +What: /sys/class/pwm/pwmchipN/export +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Exports a PWM channel from the PWM chip for sysfs control. + Value is between 0 and /sys/class/pwm/pwmchipN/npwm - 1. + +What: /sys/class/pwm/pwmchipN/unexport +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Unexports a PWM channel. + +What: /sys/class/pwm/pwmchipN/pwmX +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + A /sys/class/pwm/pwmchipN/pwmX directory is created for + each exported PWM channel where X is the exported PWM + channel number. + +What: /sys/class/pwm/pwmchipN/pwmX/period +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Sets the PWM signal period in nanoseconds. + +What: /sys/class/pwm/pwmchipN/pwmX/duty_cycle +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Sets the PWM signal duty cycle in nanoseconds. + +What: /sys/class/pwm/pwmchipN/pwmX/polarity +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Sets the output polarity of the PWM signal to "normal" or + "inversed". + +What: /sys/class/pwm/pwmchipN/pwmX/enable +Date: May 2013 +KernelVersion: 3.11 +Contact: H Hartley Sweeten <hsweeten@visionengravers.com> +Description: + Enable/disable the PWM signal. + 0 is disabled + 1 is enabled 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-class-rtc-rtc0-device-rtc_calibration b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration new file mode 100644 index 000000000000..4cf1e72222d9 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-class-rtc-rtc0-device-rtc_calibration @@ -0,0 +1,12 @@ +What: Attribute for calibrating ST-Ericsson AB8500 Real Time Clock +Date: Oct 2011 +KernelVersion: 3.0 +Contact: Mark Godfrey <mark.godfrey@stericsson.com> +Description: The rtc_calibration attribute allows the userspace to + calibrate the AB8500.s 32KHz Real Time Clock. + Every 60 seconds the AB8500 will correct the RTC's value + by adding to it the value of this attribute. + The range of the attribute is -127 to +127 in units of + 30.5 micro-seconds (half-parts-per-million of the 32KHz clock) +Users: The /vendor/st-ericsson/base_utilities/core/rtc_calibration + daemon uses this interface. diff --git a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc index 25b1e751b777..5977e2875325 100644 --- a/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc +++ b/Documentation/ABI/testing/sysfs-class-uwb_rc-wusbhc @@ -36,3 +36,22 @@ Description: Refer to [ECMA-368] section 10.3.1.1 for the value to use. + +What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_dnts +Date: June 2013 +KernelVersion: 3.11 +Contact: Thomas Pugliese <thomas.pugliese@gmail.com> +Description: + The device notification time slot (DNTS) count and inverval in + milliseconds that the WUSB host should use. This controls how + often the devices will have the opportunity to send + notifications to the host. + +What: /sys/class/uwb_rc/uwbN/wusbhc/wusb_retry_count +Date: June 2013 +KernelVersion: 3.11 +Contact: Thomas Pugliese <thomas.pugliese@gmail.com> +Description: + The number of retries that the WUSB host should attempt + before reporting an error for a bus transaction. The range of + valid values is [0..15], where 0 indicates infinite retries. diff --git a/Documentation/ABI/testing/sysfs-devices b/Documentation/ABI/testing/sysfs-devices index 6a25671ee5f6..5fcc94358b8d 100644 --- a/Documentation/ABI/testing/sysfs-devices +++ b/Documentation/ABI/testing/sysfs-devices @@ -1,6 +1,6 @@ What: /sys/devices Date: February 2006 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: The /sys/devices tree contains a snapshot of the internal state of the kernel device tree. Devices will diff --git a/Documentation/ABI/testing/sysfs-devices-edac b/Documentation/ABI/testing/sysfs-devices-edac new file mode 100644 index 000000000000..6568e0010e1a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-edac @@ -0,0 +1,140 @@ +What: /sys/devices/system/edac/mc/mc*/reset_counters +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This write-only control file will zero all the statistical + counters for UE and CE errors on the given memory controller. + Zeroing the counters will also reset the timer indicating how + long since the last counter were reset. This is useful for + computing errors/time. Since the counters are always reset + at driver initialization time, no module/kernel parameter + is available. + +What: /sys/devices/system/edac/mc/mc*/seconds_since_reset +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays how many seconds have elapsed + since the last counter reset. This can be used with the error + counters to measure error rates. + +What: /sys/devices/system/edac/mc/mc*/mc_name +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the type of memory controller + that is being utilized. + +What: /sys/devices/system/edac/mc/mc*/size_mb +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays, in count of megabytes, of memory + that this memory controller manages. + +What: /sys/devices/system/edac/mc/mc*/ue_count +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the total count of uncorrectable + errors that have occurred on this memory controller. If + panic_on_ue is set, this counter will not have a chance to + increment, since EDAC will panic the system + +What: /sys/devices/system/edac/mc/mc*/ue_noinfo_count +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the number of UEs that have + occurred on this memory controller with no information as to + which DIMM slot is having errors. + +What: /sys/devices/system/edac/mc/mc*/ce_count +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the total count of correctable + errors that have occurred on this memory controller. This + count is very important to examine. CEs provide early + indications that a DIMM is beginning to fail. This count + field should be monitored for non-zero values and report + such information to the system administrator. + +What: /sys/devices/system/edac/mc/mc*/ce_noinfo_count +Date: January 2006 +Contact: linux-edac@vger.kernel.org +Description: This attribute file displays the number of CEs that + have occurred on this memory controller wherewith no + information as to which DIMM slot is having errors. Memory is + handicapped, but operational, yet no information is available + to indicate which slot the failing memory is in. This count + field should be also be monitored for non-zero values. + +What: /sys/devices/system/edac/mc/mc*/sdram_scrub_rate +Date: February 2007 +Contact: linux-edac@vger.kernel.org +Description: Read/Write attribute file that controls memory scrubbing. + The scrubbing rate used by the memory controller is set by + writing a minimum bandwidth in bytes/sec to the attribute file. + The rate will be translated to an internal value that gives at + least the specified rate. + Reading the file will return the actual scrubbing rate employed. + If configuration fails or memory scrubbing is not implemented, + the value of the attribute file will be -1. + +What: /sys/devices/system/edac/mc/mc*/max_location +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file displays the information about the last + available memory slot in this memory controller. It is used by + userspace tools in order to display the memory filling layout. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/size +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display the size of dimm or rank. + For dimm*/size, this is the size, in MB of the DIMM memory + stick. For rank*/size, this is the size, in MB for one rank + of the DIMM memory stick. On single rank memories (1R), this + is also the total size of the dimm. On dual rank (2R) memories, + this is half the size of the total DIMM memories. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_dev_type +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display what type of DRAM device is + being utilized on this DIMM (x1, x2, x4, x8, ...). + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_edac_mode +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display what type of Error detection + and correction is being utilized. For example: S4ECD4ED would + mean a Chipkill with x4 DRAM. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_label +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This control file allows this DIMM to have a label assigned + to it. With this label in the module, when errors occur + the output can provide the DIMM label in the system log. + This becomes vital for panic events to isolate the + cause of the UE event. + DIMM Labels must be assigned after booting, with information + that correctly identifies the physical slot with its + silk screen label. This information is currently very + motherboard specific and determination of this information + must occur in userland at this time. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_location +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display the location (csrow/channel, + branch/channel/slot or channel/slot) of the dimm or rank. + +What: /sys/devices/system/edac/mc/mc*/(dimm|rank)*/dimm_mem_type +Date: April 2012 +Contact: Mauro Carvalho Chehab <m.chehab@samsung.com> + linux-edac@vger.kernel.org +Description: This attribute file will display what type of memory is + currently on this csrow. Normally, either buffered or + unbuffered memory (for example, Unbuffered-DDR3). 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-lpss_ltr b/Documentation/ABI/testing/sysfs-devices-lpss_ltr new file mode 100644 index 000000000000..ea9298d9bbaf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-lpss_ltr @@ -0,0 +1,44 @@ +What: /sys/devices/.../lpss_ltr/ +Date: March 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../lpss_ltr/ directory is only present for + devices included into the Intel Lynxpoint Low Power Subsystem + (LPSS). If present, it contains attributes containing the LTR + mode and the values of LTR registers of the device. + +What: /sys/devices/.../lpss_ltr/ltr_mode +Date: March 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../lpss_ltr/ltr_mode attribute contains an + integer number (0 or 1) indicating whether or not the devices' + LTR functionality is working in the software mode (1). + + This attribute is read-only. If the device's runtime PM status + is not "active", attempts to read from this attribute cause + -EAGAIN to be returned. + +What: /sys/devices/.../lpss_ltr/auto_ltr +Date: March 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../lpss_ltr/auto_ltr attribute contains the + current value of the device's AUTO_LTR register (raw) + represented as an 8-digit hexadecimal number. + + This attribute is read-only. If the device's runtime PM status + is not "active", attempts to read from this attribute cause + -EAGAIN to be returned. + +What: /sys/devices/.../lpss_ltr/sw_ltr +Date: March 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../lpss_ltr/auto_ltr attribute contains the + current value of the device's SW_LTR register (raw) represented + as an 8-digit hexadecimal number. + + This attribute is read-only. If the device's runtime PM status + is not "active", attempts to read from this attribute cause + -EAGAIN to be returned. diff --git a/Documentation/ABI/testing/sysfs-devices-node b/Documentation/ABI/testing/sysfs-devices-node deleted file mode 100644 index 453a210c3ceb..000000000000 --- a/Documentation/ABI/testing/sysfs-devices-node +++ /dev/null @@ -1,7 +0,0 @@ -What: /sys/devices/system/node/nodeX/compact -Date: February 2010 -Contact: Mel Gorman <mel@csn.ul.ie> -Description: - When this file is written to, all memory within that node - will be compacted. When it completes, memory will be freed - into blocks which have as many contiguous pages as possible diff --git a/Documentation/ABI/testing/sysfs-devices-online b/Documentation/ABI/testing/sysfs-devices-online new file mode 100644 index 000000000000..f990026c0740 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-online @@ -0,0 +1,20 @@ +What: /sys/devices/.../online +Date: April 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../online attribute is only present for + devices whose bus types provide .online() and .offline() + callbacks. The number read from it (0 or 1) reflects the value + of the device's 'offline' field. If that number is 1 and '0' + (or 'n', or 'N') is written to this file, the device bus type's + .offline() callback is executed for the device and (if + successful) its 'offline' field is updated accordingly. In + turn, if that number is 0 and '1' (or 'y', or 'Y') is written to + this file, the device bus type's .online() callback is executed + for the device and (if successful) its 'offline' field is + updated as appropriate. + + After a successful execution of the bus type's .offline() + callback the device cannot be used for any purpose until either + it is removed (i.e. device_del() is called for it), or its bus + type's .online() is exeucted successfully. diff --git a/Documentation/ABI/testing/sysfs-devices-platform-docg3 b/Documentation/ABI/testing/sysfs-devices-platform-docg3 new file mode 100644 index 000000000000..8aa36716882f --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-docg3 @@ -0,0 +1,34 @@ +What: /sys/devices/platform/docg3/f[0-3]_dps[01]_is_keylocked +Date: November 2011 +KernelVersion: 3.3 +Contact: Robert Jarzmik <robert.jarzmik@free.fr> +Description: + Show whether the floor (0 to 4), protection area (0 or 1) is + keylocked. Each docg3 chip (or floor) has 2 protection areas, + which can cover any part of it, block aligned, called DPS. + The protection has information embedded whether it blocks reads, + writes or both. + The result is: + 0 -> the DPS is not keylocked + 1 -> the DPS is keylocked +Users: None identified so far. + +What: /sys/devices/platform/docg3/f[0-3]_dps[01]_protection_key +Date: November 2011 +KernelVersion: 3.3 +Contact: Robert Jarzmik <robert.jarzmik@free.fr> +Description: + Enter the protection key for the floor (0 to 4), protection area + (0 or 1). Each docg3 chip (or floor) has 2 protection areas, + which can cover any part of it, block aligned, called DPS. + The protection has information embedded whether it blocks reads, + writes or both. + The protection key is a string of 8 bytes (value 0-255). + Entering the correct value toggle the lock, and can be observed + through f[0-3]_dps[01]_is_keylocked. + Possible values are: + - 8 bytes + Typical values are: + - "00000000" + - "12345678" +Users: None identified so far. diff --git a/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb new file mode 100644 index 000000000000..2107082426da --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-platform-sh_mobile_lcdc_fb @@ -0,0 +1,44 @@ +What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_alpha +Date: May 2012 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Description: + This file is only available on fb[0-9] devices corresponding + to overlay planes. + + Stores the alpha blending value for the overlay. Values range + from 0 (transparent) to 255 (opaque). The value is ignored if + the mode is not set to Alpha Blending. + +What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_mode +Date: May 2012 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Description: + This file is only available on fb[0-9] devices corresponding + to overlay planes. + + Selects the composition mode for the overlay. Possible values + are + + 0 - Alpha Blending + 1 - ROP3 + +What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_position +Date: May 2012 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Description: + This file is only available on fb[0-9] devices corresponding + to overlay planes. + + Stores the x,y overlay position on the display in pixels. The + position format is `[0-9]+,[0-9]+'. + +What: /sys/devices/platform/sh_mobile_lcdc_fb.[0-3]/graphics/fb[0-9]/ovl_rop3 +Date: May 2012 +Contact: Laurent Pinchart <laurent.pinchart@ideasonboard.com> +Description: + This file is only available on fb[0-9] devices corresponding + to overlay planes. + + Stores the raster operation (ROP3) for the overlay. Values + range from 0 to 255. The value is ignored if the mode is not + set to ROP3. diff --git a/Documentation/ABI/testing/sysfs-devices-power b/Documentation/ABI/testing/sysfs-devices-power index 8ffbc25376a0..efe449bdf811 100644 --- a/Documentation/ABI/testing/sysfs-devices-power +++ b/Documentation/ABI/testing/sysfs-devices-power @@ -1,6 +1,6 @@ What: /sys/devices/.../power/ Date: January 2009 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../power directory contains attributes allowing the user space to check and modify some power @@ -8,7 +8,7 @@ Description: What: /sys/devices/.../power/wakeup Date: January 2009 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../power/wakeup attribute allows the user space to check if the device is enabled to wake up the system @@ -34,7 +34,7 @@ Description: What: /sys/devices/.../power/control Date: January 2009 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../power/control attribute allows the user space to control the run-time power management of the device. @@ -53,7 +53,7 @@ Description: What: /sys/devices/.../power/async Date: January 2009 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../async attribute allows the user space to enable or diasble the device's suspend and resume callbacks to @@ -79,7 +79,7 @@ Description: What: /sys/devices/.../power/wakeup_count Date: September 2010 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../wakeup_count attribute contains the number of signaled wakeup events associated with the device. This @@ -88,7 +88,7 @@ Description: What: /sys/devices/.../power/wakeup_active_count Date: September 2010 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../wakeup_active_count attribute contains the number of times the processing of wakeup events associated with @@ -96,20 +96,30 @@ Description: is read-only. If the device is not enabled to wake up the system from sleep states, this attribute is not present. -What: /sys/devices/.../power/wakeup_hit_count -Date: September 2010 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +What: /sys/devices/.../power/wakeup_abort_count +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: - The /sys/devices/.../wakeup_hit_count attribute contains the + The /sys/devices/.../wakeup_abort_count attribute contains the number of times the processing of a wakeup event associated with - the device might prevent the system from entering a sleep state. - This attribute is read-only. If the device is not enabled to - wake up the system from sleep states, this attribute is not - present. + the device might have aborted system transition into a sleep + state in progress. This attribute is read-only. If the device + is not enabled to wake up the system from sleep states, this + attribute is not present. + +What: /sys/devices/.../power/wakeup_expire_count +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_expire_count attribute contains the + number of times a wakeup event associated with the device has + been reported with a timeout that expired. This attribute is + read-only. If the device is not enabled to wake up the system + from sleep states, this attribute is not present. What: /sys/devices/.../power/wakeup_active Date: September 2010 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../wakeup_active attribute contains either 1, or 0, depending on whether or not a wakeup event associated with @@ -119,7 +129,7 @@ Description: What: /sys/devices/.../power/wakeup_total_time_ms Date: September 2010 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../wakeup_total_time_ms attribute contains the total time of processing wakeup events associated with the @@ -129,7 +139,7 @@ Description: What: /sys/devices/.../power/wakeup_max_time_ms Date: September 2010 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../wakeup_max_time_ms attribute contains the maximum time of processing a single wakeup event associated @@ -139,7 +149,7 @@ Description: What: /sys/devices/.../power/wakeup_last_time_ms Date: September 2010 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/devices/.../wakeup_last_time_ms attribute contains the value of the monotonic clock corresponding to the time of @@ -148,6 +158,17 @@ Description: not enabled to wake up the system from sleep states, this attribute is not present. +What: /sys/devices/.../power/wakeup_prevent_sleep_time_ms +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../wakeup_prevent_sleep_time_ms attribute + contains the total time the device has been preventing + opportunistic transitions to sleep states from occurring. + This attribute is read-only. If the device is not enabled to + wake up the system from sleep states, this attribute is not + present. + What: /sys/devices/.../power/autosuspend_delay_ms Date: September 2010 Contact: Alan Stern <stern@rowland.harvard.edu> @@ -165,3 +186,52 @@ Description: Not all drivers support this attribute. If it isn't supported, attempts to read or write it will yield I/O errors. + +What: /sys/devices/.../power/pm_qos_latency_us +Date: March 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/pm_qos_resume_latency_us attribute + contains the PM QoS resume latency limit for the given device, + which is the maximum allowed time it can take to resume the + device, after it has been suspended at run time, from a resume + request to the moment the device will be ready to process I/O, + in microseconds. If it is equal to 0, however, this means that + the PM QoS resume latency may be arbitrary. + + Not all drivers support this attribute. If it isn't supported, + it is not present. + + This attribute has no effect on system-wide suspend/resume and + hibernation. + +What: /sys/devices/.../power/pm_qos_no_power_off +Date: September 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/pm_qos_no_power_off attribute + is used for manipulating the PM QoS "no power off" flag. If + set, this flag indicates to the kernel that power should not + be removed entirely from the device. + + Not all drivers support this attribute. If it isn't supported, + it is not present. + + This attribute has no effect on system-wide suspend/resume and + hibernation. + +What: /sys/devices/.../power/pm_qos_remote_wakeup +Date: September 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/devices/.../power/pm_qos_remote_wakeup attribute + is used for manipulating the PM QoS "remote wakeup required" + flag. If set, this flag indicates to the kernel that the + device is a source of user events that have to be signaled from + its low-power states. + + Not all drivers support this attribute. If it isn't supported, + it is not present. + + This attribute has no effect on system-wide suspend/resume and + hibernation. diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_D0 b/Documentation/ABI/testing/sysfs-devices-power_resources_D0 new file mode 100644 index 000000000000..73b77a6be196 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_D0 @@ -0,0 +1,13 @@ +What: /sys/devices/.../power_resources_D0/ +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_D0/ directory is only + present for device objects representing ACPI device nodes that + use ACPI power resources for power management. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be in ACPI power state D0. The names + of the links are the same as the names of the directories they + point to. diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_D1 b/Documentation/ABI/testing/sysfs-devices-power_resources_D1 new file mode 100644 index 000000000000..30c20703fb8c --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_D1 @@ -0,0 +1,14 @@ +What: /sys/devices/.../power_resources_D1/ +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_D1/ directory is only + present for device objects representing ACPI device nodes that + use ACPI power resources for power management and support ACPI + power state D1. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be in ACPI power state D1. The names + of the links are the same as the names of the directories they + point to. diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_D2 b/Documentation/ABI/testing/sysfs-devices-power_resources_D2 new file mode 100644 index 000000000000..fd9d84b421e1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_D2 @@ -0,0 +1,14 @@ +What: /sys/devices/.../power_resources_D2/ +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_D2/ directory is only + present for device objects representing ACPI device nodes that + use ACPI power resources for power management and support ACPI + power state D2. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be in ACPI power state D2. The names + of the links are the same as the names of the directories they + point to. diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_D3hot b/Documentation/ABI/testing/sysfs-devices-power_resources_D3hot new file mode 100644 index 000000000000..3df32c20addf --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_D3hot @@ -0,0 +1,14 @@ +What: /sys/devices/.../power_resources_D3hot/ +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_D3hot/ directory is only + present for device objects representing ACPI device nodes that + use ACPI power resources for power management and support ACPI + power state D3hot. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be in ACPI power state D3hot. The + names of the links are the same as the names of the directories + they point to. diff --git a/Documentation/ABI/testing/sysfs-devices-power_resources_wakeup b/Documentation/ABI/testing/sysfs-devices-power_resources_wakeup new file mode 100644 index 000000000000..e0588feeb6e1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_resources_wakeup @@ -0,0 +1,13 @@ +What: /sys/devices/.../power_resources_wakeup/ +Date: April 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_resources_wakeup/ directory is only + present for device objects representing ACPI device nodes that + require ACPI power resources for wakeup signaling. + + If present, it contains symbolic links to device directories + representing ACPI power resources that need to be turned on for + the given device node to be able to signal wakeup. The names of + the links are the same as the names of the directories they + point to. diff --git a/Documentation/ABI/testing/sysfs-devices-power_state b/Documentation/ABI/testing/sysfs-devices-power_state new file mode 100644 index 000000000000..7ad9546748f0 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-power_state @@ -0,0 +1,20 @@ +What: /sys/devices/.../power_state +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../power_state attribute is only present for + device objects representing ACPI device nodes that provide power + management methods. + + If present, it contains a string representing the current ACPI + power state of the given device node. Its possible values, + "D0", "D1", "D2", "D3hot", and "D3cold", reflect the power state + names defined by the ACPI specification (ACPI 4 and above). + + If the device node uses shared ACPI power resources, this state + determines a list of power resources required not to be turned + off. However, some power resources needed by the device node in + higher-power (lower-number) states may also be ON because of + some other devices using them at the moment. + + This attribute is read-only. diff --git a/Documentation/ABI/testing/sysfs-devices-real_power_state b/Documentation/ABI/testing/sysfs-devices-real_power_state new file mode 100644 index 000000000000..8b3527c82a7d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-real_power_state @@ -0,0 +1,23 @@ +What: /sys/devices/.../real_power_state +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../real_power_state attribute is only present + for device objects representing ACPI device nodes that provide + power management methods and use ACPI power resources for power + management. + + If present, it contains a string representing the real ACPI + power state of the given device node as returned by the _PSC + control method or inferred from the configuration of power + resources. Its possible values, "D0", "D1", "D2", "D3hot", and + "D3cold", reflect the power state names defined by the ACPI + specification (ACPI 4 and above). + + In some situations the value of this attribute may be different + from the value of the /sys/devices/.../power_state attribute for + the same device object. If that happens, some shared power + resources used by the device node are only ON because of some + other devices using them at the moment. + + This attribute is read-only. diff --git a/Documentation/ABI/testing/sysfs-devices-resource_in_use b/Documentation/ABI/testing/sysfs-devices-resource_in_use new file mode 100644 index 000000000000..b4a3bc5922a3 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-resource_in_use @@ -0,0 +1,12 @@ +What: /sys/devices/.../resource_in_use +Date: January 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The /sys/devices/.../resource_in_use attribute is only present + for device objects representing ACPI power resources. + + If present, it contains a number (0 or 1) representing the + current status of the given power resource (0 means that the + resource is not in use and therefore it has been turned off). + + This attribute is read-only. diff --git a/Documentation/ABI/testing/sysfs-devices-soc b/Documentation/ABI/testing/sysfs-devices-soc new file mode 100644 index 000000000000..6d9cc253f2b2 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-soc @@ -0,0 +1,58 @@ +What: /sys/devices/socX +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + The /sys/devices/ directory contains a sub-directory for each + System-on-Chip (SoC) device on a running platform. Information + regarding each SoC can be obtained by reading sysfs files. This + functionality is only available if implemented by the platform. + + The directory created for each SoC will also house information + about devices which are commonly contained in /sys/devices/platform. + It has been agreed that if an SoC device exists, its supported + devices would be better suited to appear as children of that SoC. + +What: /sys/devices/socX/machine +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute common to all SoCs. Contains the SoC machine + name (e.g. Ux500). + +What: /sys/devices/socX/family +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute common to all SoCs. Contains SoC family name + (e.g. DB8500). + +What: /sys/devices/socX/soc_id +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute supported by most SoCs. In the case of + ST-Ericsson's chips this contains the SoC serial number. + +What: /sys/devices/socX/revision +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute supported by most SoCs. Contains the SoC's + manufacturing revision number. + +What: /sys/devices/socX/process +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + Read-only attribute supported ST-Ericsson's silicon. Contains the + the process by which the silicon chip was manufactured. + +What: /sys/bus/soc +Date: January 2012 +contact: Lee Jones <lee.jones@linaro.org> +Description: + The /sys/bus/soc/ directory contains the usual sub-folders + expected under most buses. /sys/bus/soc/devices is of particular + interest, as it contains a symlink for each SoC device found on + the system. Each symlink points back into the aforementioned + /sys/devices/socX devices. diff --git a/Documentation/ABI/testing/sysfs-devices-sun b/Documentation/ABI/testing/sysfs-devices-sun new file mode 100644 index 000000000000..625ce4b63758 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-sun @@ -0,0 +1,14 @@ +What: /sys/devices/.../sun +Date: October 2012 +Contact: Yasuaki Ishimatsu <isimatu.yasuaki@jp.fujitsu.com> +Description: + The file contains a Slot-unique ID which provided by the _SUN + method in the ACPI namespace. The value is written in Advanced + Configuration and Power Interface Specification as follows: + + "The _SUN value is required to be unique among the slots of + the same type. It is also recommended that this number match + the slot number printed on the physical slot whenever possible." + + So reading the sysfs file, we can identify a physical position + of the slot in the system. diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu index e7be75b96e4b..468e4d48f884 100644 --- a/Documentation/ABI/testing/sysfs-devices-system-cpu +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu @@ -9,31 +9,6 @@ Description: /sys/devices/system/cpu/cpu#/ -What: /sys/devices/system/cpu/sched_mc_power_savings - /sys/devices/system/cpu/sched_smt_power_savings -Date: June 2006 -Contact: Linux kernel mailing list <linux-kernel@vger.kernel.org> -Description: Discover and adjust the kernel's multi-core scheduler support. - - Possible values are: - - 0 - No power saving load balance (default value) - 1 - Fill one thread/core/package first for long running threads - 2 - Also bias task wakeups to semi-idle cpu package for power - savings - - sched_mc_power_savings is dependent upon SCHED_MC, which is - itself architecture dependent. - - sched_smt_power_savings is dependent upon SCHED_SMT, which - is itself architecture dependent. - - The two files are independent of each other. It is possible - that one file may be present without the other. - - Introduced by git commit 5c45bf27. - - What: /sys/devices/system/cpu/kernel_max /sys/devices/system/cpu/offline /sys/devices/system/cpu/online @@ -92,20 +67,6 @@ Description: Discover NUMA node a CPU belongs to /sys/devices/system/cpu/cpu42/node2 -> ../../node/node2 -What: /sys/devices/system/cpu/cpu#/node -Date: October 2009 -Contact: Linux memory management mailing list <linux-mm@kvack.org> -Description: Discover NUMA node a CPU belongs to - - When CONFIG_NUMA is enabled, a symbolic link that points - to the corresponding NUMA node directory. - - For example, the following symlink is created for cpu42 - in NUMA node 2: - - /sys/devices/system/cpu/cpu42/node2 -> ../../node/node2 - - What: /sys/devices/system/cpu/cpu#/topology/core_id /sys/devices/system/cpu/cpu#/topology/core_siblings /sys/devices/system/cpu/cpu#/topology/core_siblings_list @@ -183,6 +144,21 @@ Description: Discover and change clock speed of CPUs to learn how to control the knobs. +What: /sys/devices/system/cpu/cpu#/cpufreq/freqdomain_cpus +Date: June 2013 +Contact: cpufreq@vger.kernel.org +Description: Discover CPUs in the same CPU frequency coordination domain + + freqdomain_cpus is the list of CPUs (online+offline) that share + the same clock/freq domain (possibly at the hardware level). + That information may be hidden from the cpufreq core and the + value of related_cpus may be different from freqdomain_cpus. This + attribute is useful for user space DVFS controllers to get better + power/performance results for platforms using acpi-cpufreq. + + This file is only present if the acpi-cpufreq driver is in use. + + What: /sys/devices/system/cpu/cpu*/cache/index3/cache_disable_{0,1} Date: August 2008 KernelVersion: 2.6.27 @@ -201,3 +177,26 @@ 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 + + +What: /sys/devices/system/cpu/cpu#/crash_notes + /sys/devices/system/cpu/cpu#/crash_notes_size +Date: April 2013 +Contact: kexec@lists.infradead.org +Description: address and size of the percpu note. + + crash_notes: the physical address of the memory that holds the + note of cpu#. + + crash_notes_size: size of the note of cpu#. diff --git a/Documentation/ABI/testing/sysfs-devices-system-xen_cpu b/Documentation/ABI/testing/sysfs-devices-system-xen_cpu new file mode 100644 index 000000000000..9ca02fb2d498 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-devices-system-xen_cpu @@ -0,0 +1,20 @@ +What: /sys/devices/system/xen_cpu/ +Date: May 2012 +Contact: Liu, Jinsong <jinsong.liu@intel.com> +Description: + A collection of global/individual Xen physical cpu attributes + + Individual physical cpu attributes are contained in + subdirectories named by the Xen's logical cpu number, e.g.: + /sys/devices/system/xen_cpu/xen_cpu#/ + + +What: /sys/devices/system/xen_cpu/xen_cpu#/online +Date: May 2012 +Contact: Liu, Jinsong <jinsong.liu@intel.com> +Description: + Interface to online/offline Xen physical cpus + + When running under Xen platform, it provide user interface + to online/offline physical cpus, except cpu0 due to several + logic restrictions and assumptions. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-lenovo-tpkbd b/Documentation/ABI/testing/sysfs-driver-hid-lenovo-tpkbd new file mode 100644 index 000000000000..57b92cbdceae --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-lenovo-tpkbd @@ -0,0 +1,38 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/press_to_select +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: This controls if mouse clicks should be generated if the trackpoint is quickly pressed. How fast this press has to be + is being controlled by press_speed. + Values are 0 or 1. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/dragging +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: If this setting is enabled, it is possible to do dragging by pressing the trackpoint. This requires press_to_select to be enabled. + Values are 0 or 1. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/release_to_select +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: For details regarding this setting please refer to http://www.pc.ibm.com/ww/healthycomputing/trkpntb.html + Values are 0 or 1. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/select_right +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: This setting controls if the mouse click events generated by pressing the trackpoint (if press_to_select is enabled) generate + a left or right mouse button click. + Values are 0 or 1. + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/sensitivity +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: This file contains the trackpoint sensitivity. + Values are decimal integers from 1 (lowest sensitivity) to 255 (highest sensitivity). + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/press_speed +Date: July 2011 +Contact: linux-input@vger.kernel.org +Description: This setting controls how fast the trackpoint needs to be pressed to generate a mouse click if press_to_select is enabled. + Values are decimal integers from 1 (slowest) to 255 (fastest). + diff --git a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff index 9aec8ef228b0..167d9032b970 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff +++ b/Documentation/ABI/testing/sysfs-driver-hid-logitech-lg4ff @@ -1,7 +1,7 @@ What: /sys/module/hid_logitech/drivers/hid:logitech/<dev>/range. Date: July 2011 KernelVersion: 3.2 -Contact: Michal Malý <madcatxster@gmail.com> +Contact: Michal Malý <madcatxster@gmail.com> Description: Display minimum, maximum and current range of the steering wheel. Writing a value within min and max boundaries sets the range of the wheel. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-multitouch b/Documentation/ABI/testing/sysfs-driver-hid-multitouch new file mode 100644 index 000000000000..f79839d1af37 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-multitouch @@ -0,0 +1,9 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/quirks +Date: November 2011 +Contact: Benjamin Tissoires <benjamin.tissoires@gmail.com> +Description: The integer value of this attribute corresponds to the + quirks actually in place to handle the device's protocol. + When read, this attribute returns the current settings (see + MT_QUIRKS_* in hid-multitouch.c). + When written this attribute change on the fly the quirks, then + the protocol to handle the device. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-isku b/Documentation/ABI/testing/sysfs-driver-hid-roccat-isku new file mode 100644 index 000000000000..c601d0f2ac46 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-isku @@ -0,0 +1,153 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/actual_profile +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The integer value of this attribute ranges from 0-4. + When read, this attribute returns the number of the actual + profile. This value is persistent, so its equivalent to the + profile that's active when the device is powered on next time. + When written, this file sets the number of the startup profile + and the device activates this profile immediately. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/info +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + The data is 6 bytes long. + This file is readonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/key_mask +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one deactivate certain keys like + windows and application keys, to prevent accidental presses. + Profile number for which this settings occur is included in + written data. The data has to be 6 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_capslock +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + capslock key for a specific profile. Profile number is included + in written data. The data has to be 6 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_easyzone +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + easyzone keys for a specific profile. Profile number is included + in written data. The data has to be 65 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_function +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + function keys for a specific profile. Profile number is included + in written data. The data has to be 41 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_macro +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the macro + keys for a specific profile. Profile number is included in + written data. The data has to be 35 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_media +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the media + keys for a specific profile. Profile number is included in + written data. The data has to be 29 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/keys_thumbster +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the function of the + thumbster keys for a specific profile. Profile number is included + in written data. The data has to be 23 bytes long. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/last_set +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the time in secs since + epoch in which the last configuration took place. + The data has to be 20 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/light +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one set the backlight intensity for + a specific profile. Profile number is included in written data. + The data has to be 10 bytes long for Isku, IskuFX needs 16 bytes + of data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/macro +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one store macros with max 500 + keystrokes for a specific button for a specific profile. + Button and profile numbers are included in written data. + The data has to be 2083 bytes long. + Before reading this file, control has to be written to select + which profile and key to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/reset +Date: November 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one reset the device. + The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/control +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one select which data from which + profile will be read next. The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/talk +Date: June 2011 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one trigger easyshift functionality + from the host. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/isku/roccatisku<minor>/talkfx +Date: February 2013 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one trigger temporary color schemes + from the host. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus b/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus index 65e6e5dd67e8..7bd776f9c3c7 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-koneplus @@ -9,15 +9,12 @@ Description: The integer value of this attribute ranges from 0-4. and the mouse activates this profile immediately. Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/firmware_version -Date: October 2010 +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/info +Date: November 2012 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns the raw integer version number of the - firmware reported by the mouse. Using the integer value eases - further usage in other programs. To receive the real version - number the decimal point has to be shifted 2 positions to the - left. E.g. a returned value of 121 means 1.21 - This file is readonly. +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 8 bytes long. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/macro @@ -42,18 +39,8 @@ Description: The mouse can store 5 profiles which can be switched by the The mouse will reject invalid data. Which profile to write is determined by the profile number contained in the data. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_buttons -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_buttons holds information about button layout. - When read, these files return the respective profile buttons. - The returned data is 77 bytes in size. - This file is readonly. + Before reading this file, control has to be written to select + which profile to read. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile_settings @@ -68,19 +55,8 @@ Description: The mouse can store 5 profiles which can be switched by the The mouse will reject invalid data. Which profile to write is determined by the profile number contained in the data. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/profile[1-5]_settings -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_settings holds information like resolution, sensitivity - and light effects. - When read, these files return the respective profile settings. - The returned data is 43 bytes in size. - This file is readonly. + Before reading this file, control has to be written to select + which profile to read. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/sensor @@ -104,9 +80,9 @@ What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid- Date: October 2010 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> Description: When written a calibration process for the tracking control unit - can be initiated/cancelled. - The data has to be 3 bytes long. - This file is writeonly. + can be initiated/cancelled. Also lets one read/write sensor + registers. + The data has to be 4 bytes long. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/koneplus/roccatkoneplus<minor>/tcu_image diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-konepure b/Documentation/ABI/testing/sysfs-driver-hid-roccat-konepure new file mode 100644 index 000000000000..41a9b7fbfc79 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-konepure @@ -0,0 +1,105 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/actual_profile +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. actual_profile holds number of actual profile. + This value is persistent, so its value determines the profile + that's active when the mouse is powered on next time. + When written, the mouse activates the set profile immediately. + The data has to be 3 bytes long. + The mouse will reject invalid data. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/control +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one select which data from which + profile will be read next. The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/info +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 6 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/macro +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store a macro with max 500 key/button strokes + internally. + When written, this file lets one set the sequence for a specific + button for a specific profile. Button and profile numbers are + included in written data. The data has to be 2082 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/profile_buttons +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_buttons holds information about button layout. + When written, this file lets one write the respective profile + buttons back to the mouse. The data has to be 59 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/profile_settings +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split in settings and buttons. + profile_settings holds information like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 31 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/sensor +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a tracking- and a distance-control-unit. These + can be activated/deactivated and the lift-off distance can be + set. The data has to be 6 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/talk +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: Used to active some easy* functions of the mouse from outside. + The data has to be 16 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/tcu +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written a calibration process for the tracking control unit + can be initiated/cancelled. Also lets one read/write sensor + registers. + The data has to be 4 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/konepure/roccatkonepure<minor>/tcu_image +Date: December 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read the mouse returns a 30x30 pixel image of the + sampled underground. This works only in the course of a + calibration process initiated with tcu. + The returned data is 1028 bytes in size. + This file is readonly. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus index 20f937c9d84f..a10404f15a54 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-kovaplus @@ -1,12 +1,3 @@ -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_cpi -Date: January 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The integer value of this attribute ranges from 1-4. - When read, this attribute returns the number of the active - cpi level. - This file is readonly. -Users: http://roccat.sourceforge.net - What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_profile Date: January 2011 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> @@ -18,33 +9,12 @@ Description: The integer value of this attribute ranges from 0-4. active when the mouse is powered on. Users: http://roccat.sourceforge.net -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_x -Date: January 2011 +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/info +Date: November 2012 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The integer value of this attribute ranges from 1-10. - When read, this attribute returns the number of the actual - sensitivity in x direction. - This file is readonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/actual_sensitivity_y -Date: January 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The integer value of this attribute ranges from 1-10. - When read, this attribute returns the number of the actual - sensitivity in y direction. - This file is readonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/firmware_version -Date: January 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns the raw integer version number of the - firmware reported by the mouse. Using the integer value eases - further usage in other programs. To receive the real version - number the decimal point has to be shifted 2 positions to the - left. E.g. a returned value of 121 means 1.21 - This file is readonly. +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 6 bytes long. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_buttons @@ -58,18 +28,8 @@ Description: The mouse can store 5 profiles which can be switched by the The mouse will reject invalid data. Which profile to write is determined by the profile number contained in the data. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_buttons -Date: January 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_buttons holds information about button layout. - When read, these files return the respective profile buttons. - The returned data is 23 bytes in size. - This file is readonly. + Before reading this file, control has to be written to select + which profile to read. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile_settings @@ -84,17 +44,6 @@ Description: The mouse can store 5 profiles which can be switched by the The mouse will reject invalid data. Which profile to write is determined by the profile number contained in the data. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/kovaplus/roccatkovaplus<minor>/profile[1-5]_settings -Date: January 2011 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_settings holds information like resolution, sensitivity - and light effects. - When read, these files return the respective profile settings. - The returned data is 16 bytes in size. - This file is readonly. + Before reading this file, control has to be written to select + which profile to read. Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-lua b/Documentation/ABI/testing/sysfs-driver-hid-roccat-lua new file mode 100644 index 000000000000..31c6c4c8ba2b --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-lua @@ -0,0 +1,7 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/control +Date: October 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, cpi, button and light settings can be configured. + When read, actual cpi setting and sensor data are returned. + The data has to be 8 bytes long. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra b/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra index 3f8de50e4ff1..9fa9de30d14b 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-pyra @@ -1,37 +1,9 @@ -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_cpi -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: It is possible to switch the cpi setting of the mouse with the - press of a button. - When read, this file returns the raw number of the actual cpi - setting reported by the mouse. This number has to be further - processed to receive the real dpi value. - - VALUE DPI - 1 400 - 2 800 - 4 1600 - - This file is readonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/actual_profile -Date: August 2010 +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/info +Date: November 2012 Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns the number of the actual profile in - range 0-4. - This file is readonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/firmware_version -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: When read, this file returns the raw integer version number of the - firmware reported by the mouse. Using the integer value eases - further usage in other programs. To receive the real version - number the decimal point has to be shifted 2 positions to the - left. E.g. a returned value of 138 means 1.38 - This file is readonly. +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 6 bytes long. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_settings @@ -46,19 +18,8 @@ Description: The mouse can store 5 profiles which can be switched by the The mouse will reject invalid data. Which profile to write is determined by the profile number contained in the data. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_settings -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_settings holds information like resolution, sensitivity - and light effects. - When read, these files return the respective profile settings. - The returned data is 13 bytes in size. - This file is readonly. + Before reading this file, control has to be written to select + which profile to read. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile_buttons @@ -72,27 +33,8 @@ Description: The mouse can store 5 profiles which can be switched by the The mouse will reject invalid data. Which profile to write is determined by the profile number contained in the data. - This file is writeonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/profile[1-5]_buttons -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The mouse can store 5 profiles which can be switched by the - press of a button. A profile is split in settings and buttons. - profile_buttons holds information about button layout. - When read, these files return the respective profile buttons. - The returned data is 19 bytes in size. - This file is readonly. -Users: http://roccat.sourceforge.net - -What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/startup_profile -Date: August 2010 -Contact: Stefan Achatz <erazor_de@users.sourceforge.net> -Description: The integer value of this attribute ranges from 0-4. - When read, this attribute returns the number of the profile - that's active when the mouse is powered on. - This file is readonly. + Before reading this file, control has to be written to select + which profile to read. Users: http://roccat.sourceforge.net What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/pyra/roccatpyra<minor>/settings diff --git a/Documentation/ABI/testing/sysfs-driver-hid-roccat-savu b/Documentation/ABI/testing/sysfs-driver-hid-roccat-savu new file mode 100644 index 000000000000..f1e02a98bd9d --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-roccat-savu @@ -0,0 +1,76 @@ +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/buttons +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split into general settings and + button settings. buttons holds informations about button layout. + When written, this file lets one write the respective profile + buttons to the mouse. The data has to be 47 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + Before reading this file, control has to be written to select + which profile to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/control +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one select which data from which + profile will be read next. The data has to be 3 bytes long. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/general +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. A profile is split into general settings and + button settings. profile holds informations like resolution, sensitivity + and light effects. + When written, this file lets one write the respective profile + settings back to the mouse. The data has to be 43 bytes long. + The mouse will reject invalid data. + Which profile to write is determined by the profile number + contained in the data. + This file is writeonly. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/info +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When read, this file returns general data like firmware version. + When written, the device can be reset. + The data is 8 bytes long. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/macro +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: When written, this file lets one store macros with max 500 + keystrokes for a specific button for a specific profile. + Button and profile numbers are included in written data. + The data has to be 2083 bytes long. + Before reading this file, control has to be written to select + which profile and key to read. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/profile +Date: Mai 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse can store 5 profiles which can be switched by the + press of a button. profile holds number of actual profile. + This value is persistent, so its value determines the profile + that's active when the mouse is powered on next time. + When written, the mouse activates the set profile immediately. + The data has to be 3 bytes long. + The mouse will reject invalid data. +Users: http://roccat.sourceforge.net + +What: /sys/bus/usb/devices/<busnum>-<devnum>:<config num>.<interface num>/<hid-bus>:<vendor-id>:<product-id>.<num>/savu/roccatsavu<minor>/sensor +Date: July 2012 +Contact: Stefan Achatz <erazor_de@users.sourceforge.net> +Description: The mouse has a Avago ADNS-3090 sensor. + This file allows reading and writing of the mouse sensors registers. + The data has to be 4 bytes long. +Users: http://roccat.sourceforge.net diff --git a/Documentation/ABI/testing/sysfs-driver-hid-srws1 b/Documentation/ABI/testing/sysfs-driver-hid-srws1 new file mode 100644 index 000000000000..d0eba70c7d40 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-srws1 @@ -0,0 +1,21 @@ +What: /sys/class/leds/SRWS1::<serial>::RPM1 +What: /sys/class/leds/SRWS1::<serial>::RPM2 +What: /sys/class/leds/SRWS1::<serial>::RPM3 +What: /sys/class/leds/SRWS1::<serial>::RPM4 +What: /sys/class/leds/SRWS1::<serial>::RPM5 +What: /sys/class/leds/SRWS1::<serial>::RPM6 +What: /sys/class/leds/SRWS1::<serial>::RPM7 +What: /sys/class/leds/SRWS1::<serial>::RPM8 +What: /sys/class/leds/SRWS1::<serial>::RPM9 +What: /sys/class/leds/SRWS1::<serial>::RPM10 +What: /sys/class/leds/SRWS1::<serial>::RPM11 +What: /sys/class/leds/SRWS1::<serial>::RPM12 +What: /sys/class/leds/SRWS1::<serial>::RPM13 +What: /sys/class/leds/SRWS1::<serial>::RPM14 +What: /sys/class/leds/SRWS1::<serial>::RPM15 +What: /sys/class/leds/SRWS1::<serial>::RPMALL +Date: Jan 2013 +KernelVersion: 3.9 +Contact: Simon Wood <simon@mungewell.org> +Description: Provides a control for turning on/off the LEDs which form + an RPM meter on the front of the controller diff --git a/Documentation/ABI/testing/sysfs-driver-hid-thingm b/Documentation/ABI/testing/sysfs-driver-hid-thingm new file mode 100644 index 000000000000..abcffeedd20a --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-hid-thingm @@ -0,0 +1,23 @@ +What: /sys/class/leds/blink1::<serial>/rgb +Date: January 2013 +Contact: Vivien Didelot <vivien.didelot@savoirfairelinux.com> +Description: The ThingM blink1 is an USB RGB LED. The color notation is + 3-byte hexadecimal. Read this attribute to get the last set + color. Write the 24-bit hexadecimal color to change the current + LED color. The default color is full white (0xFFFFFF). + For instance, set the color to green with: echo 00FF00 > rgb + +What: /sys/class/leds/blink1::<serial>/fade +Date: January 2013 +Contact: Vivien Didelot <vivien.didelot@savoirfairelinux.com> +Description: This attribute allows to set a fade time in milliseconds for + the next color change. Read the attribute to know the current + fade time. The default value is set to 0 (no fade time). For + instance, set a fade time of 2 seconds with: echo 2000 > fade + +What: /sys/class/leds/blink1::<serial>/play +Date: January 2013 +Contact: Vivien Didelot <vivien.didelot@savoirfairelinux.com> +Description: This attribute is used to play/pause the light patterns. Write 1 + to start playing, 0 to stop. Reading this attribute returns the + current playing status. diff --git a/Documentation/ABI/testing/sysfs-driver-hid-wiimote b/Documentation/ABI/testing/sysfs-driver-hid-wiimote index 5d5a16ea57c6..ed5dd567d397 100644 --- a/Documentation/ABI/testing/sysfs-driver-hid-wiimote +++ b/Documentation/ABI/testing/sysfs-driver-hid-wiimote @@ -8,3 +8,52 @@ Contact: David Herrmann <dh.herrmann@googlemail.com> Description: Make it possible to set/get current led state. Reading from it returns 0 if led is off and 1 if it is on. Writing 0 to it disables the led, writing 1 enables it. + +What: /sys/bus/hid/drivers/wiimote/<dev>/extension +Date: August 2011 +KernelVersion: 3.2 +Contact: David Herrmann <dh.herrmann@gmail.com> +Description: This file contains the currently connected and initialized + extensions. It can be one of: none, motionp, nunchuck, classic, + motionp+nunchuck, motionp+classic + motionp is the official Nintendo Motion+ extension, nunchuck is + the official Nintendo Nunchuck extension and classic is the + Nintendo Classic Controller extension. The motionp extension can + be combined with the other two. + Starting with kernel-version 3.11 Motion Plus hotplugging is + supported and if detected, it's no longer reported as static + extension. You will get uevent notifications for the motion-plus + device then. + +What: /sys/bus/hid/drivers/wiimote/<dev>/devtype +Date: May 2013 +KernelVersion: 3.11 +Contact: David Herrmann <dh.herrmann@gmail.com> +Description: While a device is initialized by the wiimote driver, we perform + a device detection and signal a "change" uevent after it is + done. This file shows the detected device type. "pending" means + that the detection is still ongoing, "unknown" means, that the + device couldn't be detected or loaded. "generic" means, that the + device couldn't be detected but supports basic Wii Remote + features and can be used. + Other strings for each device-type are available and may be + added if new device-specific detections are added. + Currently supported are: + gen10: First Wii Remote generation + gen20: Second Wii Remote Plus generation (builtin MP) + balanceboard: Wii Balance Board + +What: /sys/bus/hid/drivers/wiimote/<dev>/bboard_calib +Date: May 2013 +KernelVersion: 3.11 +Contact: David Herrmann <dh.herrmann@gmail.com> +Description: This attribute is only provided if the device was detected as a + balance board. It provides a single line with 3 calibration + values for all 4 sensors. The values are separated by colons and + are each 2 bytes long (encoded as 4 digit hexadecimal value). + First, 0kg values for all 4 sensors are written, followed by the + 17kg values for all 4 sensors and last the 34kg values for all 4 + sensors. + Calibration data is already applied by the kernel to all input + values but may be used by user-space to perform other + transformations. diff --git a/Documentation/ABI/testing/sysfs-driver-intel-rapid-start b/Documentation/ABI/testing/sysfs-driver-intel-rapid-start new file mode 100644 index 000000000000..5a7d2e217d40 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-intel-rapid-start @@ -0,0 +1,21 @@ +What: /sys/bus/acpi/intel-rapid-start/wakeup_events +Date: July 2, 2013 +KernelVersion: 3.11 +Contact: Matthew Garrett <mjg59@srcf.ucam.org> +Description: An integer representing a set of wakeup events as follows: + 1: Wake to enter hibernation when the wakeup timer expires + 2: Wake to enter hibernation when the battery reaches a + critical level + + These values are ORed together. For example, a value of 3 + indicates that the system will wake to enter hibernation when + either the wakeup timer expires or the battery reaches a + critical level. + +What: /sys/bus/acpi/intel-rapid-start/wakeup_time +Date: July 2, 2013 +KernelVersion: 3.11 +Contact: Matthew Garrett <mjg59@srcf.ucam.org> +Description: An integer representing the length of time the system will + remain asleep before waking up to enter hibernation. + This value is in minutes. diff --git a/Documentation/ABI/testing/sysfs-driver-ppi b/Documentation/ABI/testing/sysfs-driver-ppi new file mode 100644 index 000000000000..7d1435bc976c --- /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 sense. 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-samsung-laptop b/Documentation/ABI/testing/sysfs-driver-samsung-laptop index 0a810231aad4..678819a3f8bf 100644 --- a/Documentation/ABI/testing/sysfs-driver-samsung-laptop +++ b/Documentation/ABI/testing/sysfs-driver-samsung-laptop @@ -1,7 +1,7 @@ What: /sys/devices/platform/samsung/performance_level Date: January 1, 2010 KernelVersion: 2.6.33 -Contact: Greg Kroah-Hartman <gregkh@suse.de> +Contact: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Description: Some Samsung laptops have different "performance levels" that are can be modified by a function key, and by this sysfs file. These values don't always make a whole lot @@ -17,3 +17,21 @@ Description: Some Samsung laptops have different "performance levels" Specifically, not all support the "overclock" option, and it's still unknown if this value even changes anything, other than making the user feel a bit better. + +What: /sys/devices/platform/samsung/battery_life_extender +Date: December 1, 2011 +KernelVersion: 3.3 +Contact: Corentin Chary <corentin.chary@gmail.com> +Description: Max battery charge level can be modified, battery cycle + life can be extended by reducing the max battery charge + level. + 0 means normal battery mode (100% charge) + 1 means battery life extender mode (80% charge) + +What: /sys/devices/platform/samsung/usb_charge +Date: December 1, 2011 +KernelVersion: 3.3 +Contact: Corentin Chary <corentin.chary@gmail.com> +Description: Use your USB ports to charge devices, even + when your laptop is powered off. + 1 means enabled, 0 means disabled. diff --git a/Documentation/ABI/testing/sysfs-driver-wacom b/Documentation/ABI/testing/sysfs-driver-wacom index 82d4df136444..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 @@ -9,15 +22,24 @@ Description: or 0 otherwise. Writing to this file one of these values switches reporting speed. +What: /sys/class/leds/0005\:056A\:00BD.0001\:selector\:*/ +Date: May 2012 +Kernel Version: 3.5 +Contact: linux-bluetooth@vger.kernel.org +Description: + LED selector for Intuos4 WL. There are 4 leds, but only one LED + can be lit at a time. Max brightness is 127. + What: /sys/bus/usb/devices/<busnum>-<devnum>:<cfg>.<intf>/wacom_led/led Date: August 2011 Contact: linux-input@vger.kernel.org Description: Attribute group for control of the status LEDs and the OLEDs. This attribute group is only available for Intuos 4 M, L, - and XL (with LEDs and OLEDs) and Cintiq 21UX2 (LEDs only). - Therefore its presence implicitly signifies the presence of - said LEDs and OLEDs on the tablet device. + and XL (with LEDs and OLEDs), Intuos 5 (LEDs only), and Cintiq + 21UX2 and Cintiq 24HD (LEDs only). Therefore its presence + implicitly signifies the presence of said LEDs and OLEDs on the + tablet device. What: /sys/bus/usb/devices/<busnum>-<devnum>:<cfg>.<intf>/wacom_led/status0_luminance Date: August 2011 @@ -40,17 +62,18 @@ What: /sys/bus/usb/devices/<busnum>-<devnum>:<cfg>.<intf>/wacom_led/status_led0 Date: August 2011 Contact: linux-input@vger.kernel.org Description: - Writing to this file sets which one of the four (for Intuos 4) - or of the right four (for Cintiq 21UX2) status LEDs is active (0..3). - The other three LEDs on the same side are always inactive. + Writing to this file sets which one of the four (for Intuos 4 + and Intuos 5) or of the right four (for Cintiq 21UX2 and Cintiq + 24HD) status LEDs is active (0..3). The other three LEDs on the + same side are always inactive. What: /sys/bus/usb/devices/<busnum>-<devnum>:<cfg>.<intf>/wacom_led/status_led1_select Date: September 2011 Contact: linux-input@vger.kernel.org Description: - Writing to this file sets which one of the left four (for Cintiq 21UX2) - status LEDs is active (0..3). The other three LEDs on the left are always - inactive. + Writing to this file sets which one of the left four (for Cintiq 21UX2 + and Cintiq 24HD) status LEDs is active (0..3). The other three LEDs on + the left are always inactive. What: /sys/bus/usb/devices/<busnum>-<devnum>:<cfg>.<intf>/wacom_led/buttons_luminance Date: August 2011 diff --git a/Documentation/ABI/testing/sysfs-driver-xen-blkback b/Documentation/ABI/testing/sysfs-driver-xen-blkback new file mode 100644 index 000000000000..8bb43b66eb55 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-xen-blkback @@ -0,0 +1,17 @@ +What: /sys/module/xen_blkback/parameters/max_buffer_pages +Date: March 2013 +KernelVersion: 3.11 +Contact: Roger Pau Monné <roger.pau@citrix.com> +Description: + Maximum number of free pages to keep in each block + backend buffer. + +What: /sys/module/xen_blkback/parameters/max_persistent_grants +Date: March 2013 +KernelVersion: 3.11 +Contact: Roger Pau Monné <roger.pau@citrix.com> +Description: + Maximum number of grants to map persistently in + blkback. If the frontend tries to use more than + max_persistent_grants, the LRU kicks in and starts + removing 5% of max_persistent_grants every 100ms. diff --git a/Documentation/ABI/testing/sysfs-driver-xen-blkfront b/Documentation/ABI/testing/sysfs-driver-xen-blkfront new file mode 100644 index 000000000000..c0a6cb7eb314 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-driver-xen-blkfront @@ -0,0 +1,10 @@ +What: /sys/module/xen_blkfront/parameters/max +Date: June 2013 +KernelVersion: 3.11 +Contact: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com> +Description: + Maximum number of segments that the frontend will negotiate + with the backend for indirect descriptors. The default value + is 32 - higher value means more potential throughput but more + memory usage. The backend picks the minimum of the frontend + and its default backend value. diff --git a/Documentation/ABI/testing/sysfs-firmware-acpi b/Documentation/ABI/testing/sysfs-firmware-acpi index 4f9ba3c2fca7..b4436cca97a8 100644 --- a/Documentation/ABI/testing/sysfs-firmware-acpi +++ b/Documentation/ABI/testing/sysfs-firmware-acpi @@ -1,3 +1,59 @@ +What: /sys/firmware/acpi/bgrt/ +Date: January 2012 +Contact: Matthew Garrett <mjg@redhat.com> +Description: + The BGRT is an ACPI 5.0 feature that allows the OS + to obtain a copy of the firmware boot splash and + some associated metadata. This is intended to be used + by boot splash applications in order to interact with + the firmware boot splash in order to avoid jarring + transitions. + + image: The image bitmap. Currently a 32-bit BMP. + status: 1 if the image is valid, 0 if firmware invalidated it. + type: 0 indicates image is in BMP format. + version: The version of the BGRT. Currently 1. + xoffset: The number of pixels between the left of the screen + and the left edge of the image. + yoffset: The number of pixels between the top of the screen + and the top edge of the image. + +What: /sys/firmware/acpi/hotplug/ +Date: February 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + There are separate hotplug profiles for different classes of + devices supported by ACPI, such as containers, memory modules, + processors, PCI root bridges etc. A hotplug profile for a given + class of devices is a collection of settings defining the way + that class of devices will be handled by the ACPI core hotplug + code. Those profiles are represented in sysfs as subdirectories + of /sys/firmware/acpi/hotplug/. + + The following setting is available to user space for each + hotplug profile: + + enabled: If set, the ACPI core will handle notifications of + hotplug events associated with the given class of + devices and will allow those devices to be ejected with + the help of the _EJ0 control method. Unsetting it + effectively disables hotplug for the correspoinding + class of devices. + + The value of the above attribute is an integer number: 1 (set) + or 0 (unset). Attempts to write any other values to it will + cause -EINVAL to be returned. + +What: /sys/firmware/acpi/hotplug/force_remove +Date: May 2013 +Contact: Rafael J. Wysocki <rafael.j.wysocki@intel.com> +Description: + The number in this file (0 or 1) determines whether (1) or not + (0) the ACPI subsystem will allow devices to be hot-removed even + if they cannot be put offline gracefully (from the kernel's + viewpoint). That number can be changed by writing a boolean + value to this file. + What: /sys/firmware/acpi/interrupts/ Date: February 2008 Contact: Len Brown <lenb@kernel.org> 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-fs-f2fs b/Documentation/ABI/testing/sysfs-fs-f2fs new file mode 100644 index 000000000000..31942efcaf0e --- /dev/null +++ b/Documentation/ABI/testing/sysfs-fs-f2fs @@ -0,0 +1,26 @@ +What: /sys/fs/f2fs/<disk>/gc_max_sleep_time +Date: July 2013 +Contact: "Namjae Jeon" <namjae.jeon@samsung.com> +Description: + Controls the maximun sleep time for gc_thread. Time + is in milliseconds. + +What: /sys/fs/f2fs/<disk>/gc_min_sleep_time +Date: July 2013 +Contact: "Namjae Jeon" <namjae.jeon@samsung.com> +Description: + Controls the minimum sleep time for gc_thread. Time + is in milliseconds. + +What: /sys/fs/f2fs/<disk>/gc_no_gc_sleep_time +Date: July 2013 +Contact: "Namjae Jeon" <namjae.jeon@samsung.com> +Description: + Controls the default sleep time for gc_thread. Time + is in milliseconds. + +What: /sys/fs/f2fs/<disk>/gc_idle +Date: July 2013 +Contact: "Namjae Jeon" <namjae.jeon@samsung.com> +Description: + Controls the victim selection policy for garbage collection. diff --git a/Documentation/ABI/testing/sysfs-kernel-iommu_groups b/Documentation/ABI/testing/sysfs-kernel-iommu_groups new file mode 100644 index 000000000000..9b31556cfdda --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-iommu_groups @@ -0,0 +1,14 @@ +What: /sys/kernel/iommu_groups/ +Date: May 2012 +KernelVersion: v3.5 +Contact: Alex Williamson <alex.williamson@redhat.com> +Description: /sys/kernel/iommu_groups/ contains a number of sub- + directories, each representing an IOMMU group. The + name of the sub-directory matches the iommu_group_id() + for the group, which is an integer value. Within each + subdirectory is another directory named "devices" with + links to the sysfs devices contained in this group. + The group directory also optionally contains a "name" + file if the IOMMU driver has chosen to register a more + common name for the group. +Users: diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-cleancache b/Documentation/ABI/testing/sysfs-kernel-mm-cleancache deleted file mode 100644 index 662ae646ea12..000000000000 --- a/Documentation/ABI/testing/sysfs-kernel-mm-cleancache +++ /dev/null @@ -1,11 +0,0 @@ -What: /sys/kernel/mm/cleancache/ -Date: April 2011 -Contact: Dan Magenheimer <dan.magenheimer@oracle.com> -Description: - /sys/kernel/mm/cleancache/ contains a number of files which - record a count of various cleancache operations - (sum across all filesystems): - succ_gets - failed_gets - puts - flushes diff --git a/Documentation/ABI/testing/sysfs-kernel-mm-ksm b/Documentation/ABI/testing/sysfs-kernel-mm-ksm new file mode 100644 index 000000000000..73e653ee2481 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-kernel-mm-ksm @@ -0,0 +1,52 @@ +What: /sys/kernel/mm/ksm +Date: September 2009 +KernelVersion: 2.6.32 +Contact: Linux memory management mailing list <linux-mm@kvack.org> +Description: Interface for Kernel Samepage Merging (KSM) + +What: /sys/kernel/mm/ksm/full_scans +What: /sys/kernel/mm/ksm/pages_shared +What: /sys/kernel/mm/ksm/pages_sharing +What: /sys/kernel/mm/ksm/pages_to_scan +What: /sys/kernel/mm/ksm/pages_unshared +What: /sys/kernel/mm/ksm/pages_volatile +What: /sys/kernel/mm/ksm/run +What: /sys/kernel/mm/ksm/sleep_millisecs +Date: September 2009 +Contact: Linux memory management mailing list <linux-mm@kvack.org> +Description: Kernel Samepage Merging daemon sysfs interface + + full_scans: how many times all mergeable areas have been + scanned. + + pages_shared: how many shared pages are being used. + + pages_sharing: how many more sites are sharing them i.e. how + much saved. + + pages_to_scan: how many present pages to scan before ksmd goes + to sleep. + + pages_unshared: how many pages unique but repeatedly checked + for merging. + + pages_volatile: how many pages changing too fast to be placed + in a tree. + + run: write 0 to disable ksm, read 0 while ksm is disabled. + write 1 to run ksm, read 1 while ksm is running. + write 2 to disable ksm and unmerge all its pages. + + sleep_millisecs: how many milliseconds ksm should sleep between + scans. + + See Documentation/vm/ksm.txt for more information. + +What: /sys/kernel/mm/ksm/merge_across_nodes +Date: January 2013 +KernelVersion: 3.9 +Contact: Linux memory management mailing list <linux-mm@kvack.org> +Description: Control merging pages across different NUMA nodes. + + When it is set to 0 only pages from the same node are merged, + otherwise pages from all nodes can be merged together (default). diff --git a/Documentation/ABI/testing/sysfs-kernel-slab b/Documentation/ABI/testing/sysfs-kernel-slab index 8b093f8222d3..91bd6ca5440f 100644 --- a/Documentation/ABI/testing/sysfs-kernel-slab +++ b/Documentation/ABI/testing/sysfs-kernel-slab @@ -346,6 +346,10 @@ Description: number of objects per slab. If a slab cannot be allocated because of fragmentation, SLUB will retry with the minimum order possible depending on its characteristics. + When debug_guardpage_minorder=N (N > 0) parameter is specified + (see Documentation/kernel-parameters.txt), the minimum possible + order is used and this sysfs entry can not be used to change + the order at run time. What: /sys/kernel/slab/cache/order_fallback Date: April 2008 diff --git a/Documentation/ABI/testing/sysfs-module b/Documentation/ABI/testing/sysfs-module index 9489ea8e294c..47064c2b1f79 100644 --- a/Documentation/ABI/testing/sysfs-module +++ b/Documentation/ABI/testing/sysfs-module @@ -33,3 +33,19 @@ Description: Maximum time allowed for periodic transfers per microframe (μs) Beware, non-standard modes are usually not thoroughly tested by hardware designers, and the hardware can malfunction when this setting differ from default 100. + +What: /sys/module/*/{coresize,initsize} +Date: Jan 2012 +KernelVersion:»·3.3 +Contact: Kay Sievers <kay.sievers@vrfy.org> +Description: Module size in bytes. + +What: /sys/module/*/taint +Date: Jan 2012 +KernelVersion:»·3.3 +Contact: Kay Sievers <kay.sievers@vrfy.org> +Description: Module taint flags: + P - proprietary module + O - out-of-tree module + F - force-loaded module + C - staging driver module diff --git a/Documentation/ABI/testing/sysfs-platform-asus-wmi b/Documentation/ABI/testing/sysfs-platform-asus-wmi index 2e7df91620de..019e1e29370e 100644 --- a/Documentation/ABI/testing/sysfs-platform-asus-wmi +++ b/Documentation/ABI/testing/sysfs-platform-asus-wmi @@ -29,3 +29,10 @@ KernelVersion: 2.6.39 Contact: "Corentin Chary" <corentincj@iksaif.net> Description: Control the card touchpad. 1 means on, 0 means off. + +What: /sys/devices/platform/<platform>/lid_resume +Date: May 2012 +KernelVersion: 3.5 +Contact: "AceLan Kao" <acelan.kao@canonical.com> +Description: + Resume on lid open. 1 means on, 0 means off. diff --git a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop index 814b01354c41..b31e782bd985 100644 --- a/Documentation/ABI/testing/sysfs-platform-ideapad-laptop +++ b/Documentation/ABI/testing/sysfs-platform-ideapad-laptop @@ -5,4 +5,15 @@ Contact: "Ike Panhc <ike.pan@canonical.com>" Description: Control the power of camera module. 1 means on, 0 means off. +What: /sys/devices/platform/ideapad/fan_mode +Date: June 2012 +KernelVersion: 3.6 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Change fan mode + There are four available modes: + * 0 -> Super Silent Mode + * 1 -> Standard Mode + * 2 -> Dust Cleaning + * 4 -> Efficient Thermal Dissipation Mode diff --git a/Documentation/ABI/testing/sysfs-platform-msi-laptop b/Documentation/ABI/testing/sysfs-platform-msi-laptop new file mode 100644 index 000000000000..307a247ba1ef --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-msi-laptop @@ -0,0 +1,83 @@ +What: /sys/devices/platform/msi-laptop-pf/lcd_level +Date: Oct 2006 +KernelVersion: 2.6.19 +Contact: "Lennart Poettering <mzxreary@0pointer.de>" +Description: + Screen brightness: contains a single integer in the range 0..8. + +What: /sys/devices/platform/msi-laptop-pf/auto_brightness +Date: Oct 2006 +KernelVersion: 2.6.19 +Contact: "Lennart Poettering <mzxreary@0pointer.de>" +Description: + Enable automatic brightness control: contains either 0 or 1. If + set to 1 the hardware adjusts the screen brightness + automatically when the power cord is plugged/unplugged. + +What: /sys/devices/platform/msi-laptop-pf/wlan +Date: Oct 2006 +KernelVersion: 2.6.19 +Contact: "Lennart Poettering <mzxreary@0pointer.de>" +Description: + WLAN subsystem enabled: contains either 0 or 1. + +What: /sys/devices/platform/msi-laptop-pf/bluetooth +Date: Oct 2006 +KernelVersion: 2.6.19 +Contact: "Lennart Poettering <mzxreary@0pointer.de>" +Description: + Bluetooth subsystem enabled: contains either 0 or 1. Please + note that this file is constantly 0 if no Bluetooth hardware is + available. + +What: /sys/devices/platform/msi-laptop-pf/touchpad +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains either 0 or 1 and indicates if touchpad is turned on. + Touchpad state can only be toggled by pressing Fn+F3. + +What: /sys/devices/platform/msi-laptop-pf/turbo_mode +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains either 0 or 1 and indicates if turbo mode is turned + on. In turbo mode power LED is orange and processor is + overclocked. Turbo mode is available only if charging. It is + only possible to toggle turbo mode state by pressing Fn+F10, + and there is a few seconds cooldown between subsequent toggles. + If user presses Fn+F10 too frequent, turbo mode state is not + changed. + +What: /sys/devices/platform/msi-laptop-pf/eco_mode +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains either 0 or 1 and indicates if ECO mode is turned on. + In ECO mode power LED is green and userspace should do some + powersaving actions. ECO mode is available only on battery + power. ECO mode can only be toggled by pressing Fn+F10. + +What: /sys/devices/platform/msi-laptop-pf/turbo_cooldown +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains value in range 0..3: + * 0 -> Turbo mode is off + * 1 -> Turbo mode is on, cannot be turned off yet + * 2 -> Turbo mode is off, cannot be turned on yet + * 3 -> Turbo mode is on + +What: /sys/devices/platform/msi-laptop-pf/auto_fan +Date: Nov 2012 +KernelVersion: 3.8 +Contact: "Maxim Mikityanskiy <maxtram95@gmail.com>" +Description: + Contains either 0 or 1 and indicates if fan speed is controlled + automatically (1) or fan runs at maximal speed (0). Can be + toggled in software. + diff --git a/Documentation/ABI/testing/sysfs-platform-ts5500 b/Documentation/ABI/testing/sysfs-platform-ts5500 new file mode 100644 index 000000000000..c88375a537a1 --- /dev/null +++ b/Documentation/ABI/testing/sysfs-platform-ts5500 @@ -0,0 +1,47 @@ +What: /sys/devices/platform/ts5500/adc +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Indicates the presence of an A/D Converter. If it is present, + it will display "1", otherwise "0". + +What: /sys/devices/platform/ts5500/ereset +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Indicates the presence of an external reset. If it is present, + it will display "1", otherwise "0". + +What: /sys/devices/platform/ts5500/id +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Product ID of the TS board. TS-5500 ID is 0x60. + +What: /sys/devices/platform/ts5500/jumpers +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Bitfield showing the jumpers' state. If a jumper is present, + the corresponding bit is set. For instance, 0x0e means jumpers + 2, 3 and 4 are set. + +What: /sys/devices/platform/ts5500/rs485 +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Indicates the presence of the RS485 option. If it is present, + it will display "1", otherwise "0". + +What: /sys/devices/platform/ts5500/sram +Date: January 2013 +KernelVersion: 3.7 +Contact: "Savoir-faire Linux Inc." <kernel@savoirfairelinux.com> +Description: + Indicates the presence of the SRAM option. If it is present, + it will display "1", otherwise "0". diff --git a/Documentation/ABI/testing/sysfs-power b/Documentation/ABI/testing/sysfs-power index b464d12761ba..205a73878441 100644 --- a/Documentation/ABI/testing/sysfs-power +++ b/Documentation/ABI/testing/sysfs-power @@ -1,6 +1,6 @@ What: /sys/power/ Date: August 2006 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/power directory will contain files that will provide a unified interface to the power management @@ -8,7 +8,7 @@ Description: What: /sys/power/state Date: August 2006 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/power/state file controls the system power state. Reading from this file returns what states are supported, @@ -22,7 +22,7 @@ Description: What: /sys/power/disk Date: September 2006 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/power/disk file controls the operating mode of the suspend-to-disk mechanism. Reading from this file returns @@ -67,7 +67,7 @@ Description: What: /sys/power/image_size Date: August 2006 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/power/image_size file controls the size of the image created by the suspend-to-disk mechanism. It can be written a @@ -84,7 +84,7 @@ Description: What: /sys/power/pm_trace Date: August 2006 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/power/pm_trace file controls the code which saves the last PM event point in the RTC across reboots, so that you can @@ -133,7 +133,7 @@ Description: What: /sys/power/pm_async Date: January 2009 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/power/pm_async file controls the switch allowing the user space to enable or disable asynchronous suspend and resume @@ -146,7 +146,7 @@ Description: What: /sys/power/wakeup_count Date: July 2010 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/power/wakeup_count file allows user space to put the system into a sleep state while taking into account the @@ -161,7 +161,7 @@ Description: What: /sys/power/reserved_size Date: May 2011 -Contact: Rafael J. Wysocki <rjw@sisk.pl> +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> Description: The /sys/power/reserved_size file allows user space to control the amount of memory reserved for allocations made by device @@ -172,3 +172,75 @@ Description: Reading from this file will display the current value, which is set to 1 MB by default. + +What: /sys/power/autosleep +Date: April 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/autosleep file can be written one of the strings + returned by reads from /sys/power/state. If that happens, a + work item attempting to trigger a transition of the system to + the sleep state represented by that string is queued up. This + attempt will only succeed if there are no active wakeup sources + in the system at that time. After every execution, regardless + of whether or not the attempt to put the system to sleep has + succeeded, the work item requeues itself until user space + writes "off" to /sys/power/autosleep. + + Reading from this file causes the last string successfully + written to it to be returned. + +What: /sys/power/wake_lock +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/wake_lock file allows user space to create + wakeup source objects and activate them on demand (if one of + those wakeup sources is active, reads from the + /sys/power/wakeup_count file block or return false). When a + string without white space is written to /sys/power/wake_lock, + it will be assumed to represent a wakeup source name. If there + is a wakeup source object with that name, it will be activated + (unless active already). Otherwise, a new wakeup source object + will be registered, assigned the given name and activated. + If a string written to /sys/power/wake_lock contains white + space, the part of the string preceding the white space will be + regarded as a wakeup source name and handled as descrived above. + The other part of the string will be regarded as a timeout (in + nanoseconds) such that the wakeup source will be automatically + deactivated after it has expired. The timeout, if present, is + set regardless of the current state of the wakeup source object + in question. + + Reads from this file return a string consisting of the names of + wakeup sources created with the help of it that are active at + the moment, separated with spaces. + + +What: /sys/power/wake_unlock +Date: February 2012 +Contact: Rafael J. Wysocki <rjw@rjwysocki.net> +Description: + The /sys/power/wake_unlock file allows user space to deactivate + wakeup sources created with the help of /sys/power/wake_lock. + When a string is written to /sys/power/wake_unlock, it will be + assumed to represent the name of a wakeup source to deactivate. + If a wakeup source object of that name exists and is active at + the moment, it will be deactivated. + + Reads from this file return a string consisting of the names of + wakeup sources created with the help of /sys/power/wake_lock + that are inactive at the moment, separated with spaces. + +What: /sys/power/pm_print_times +Date: May 2012 +Contact: Sameer Nanda <snanda@chromium.org> +Description: + The /sys/power/pm_print_times file allows user space to + control whether the time taken by devices to suspend and + resume is printed. These prints are useful for hunting down + devices that take too long to suspend or resume. + + Writing a "1" enables this printing while writing a "0" + disables it. The default value is "0". Reading from this file + will display the current value. diff --git a/Documentation/ABI/testing/sysfs-profiling b/Documentation/ABI/testing/sysfs-profiling index b02d8b8c173a..8a8e466eb2c0 100644 --- a/Documentation/ABI/testing/sysfs-profiling +++ b/Documentation/ABI/testing/sysfs-profiling @@ -1,13 +1,13 @@ -What: /sys/kernel/profile +What: /sys/kernel/profiling Date: September 2008 Contact: Dave Hansen <dave@linux.vnet.ibm.com> Description: - /sys/kernel/profile is the runtime equivalent + /sys/kernel/profiling is the runtime equivalent of the boot-time profile= option. You can get the same effect running: - echo 2 > /sys/kernel/profile + echo 2 > /sys/kernel/profiling as you would by issuing profile=2 on the boot command line. 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..ad22fb0ee765 100644 --- a/Documentation/ABI/testing/sysfs-tty +++ b/Documentation/ABI/testing/sysfs-tty @@ -17,3 +17,124 @@ 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 + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/type +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Shows the current tty type for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/line +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Shows the current tty line number for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/port +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Shows the current tty port I/O address for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/irq +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Shows the current primary interrupt for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/flags +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the tty port status flags for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/xmit_fifo_size +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the transmit FIFO size for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/close_delay +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the closing delay time for this port in ms. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/closing_wait +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the close wait time for this port in ms. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/custom_divisor +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the custom divisor if any that is set on this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/io_type +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the I/O type that is to be used with the iomem base + address. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/iomem_base +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + The I/O memory base for this port. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. + +What: /sys/class/tty/ttyS0/iomem_reg_shift +Date: October 2012 +Contact: Alan Cox <alan@linux.intel.com> +Description: + Show the register shift indicating the spacing to be used + for accesses on this iomem address. + + These sysfs values expose the TIOCGSERIAL interface via + sysfs rather than via ioctls. diff --git a/Documentation/CodingStyle b/Documentation/CodingStyle index 2b90d328b3ba..7fe0546c504a 100644 --- a/Documentation/CodingStyle +++ b/Documentation/CodingStyle @@ -389,7 +389,8 @@ Albeit deprecated by some people, the equivalent of the goto statement is used frequently by compilers in form of the unconditional jump instruction. The goto statement comes in handy when a function exits from multiple -locations and some common work such as cleanup has to be done. +locations and some common work such as cleanup has to be done. If there is no +cleanup needed then just return directly. The rationale is: @@ -454,6 +455,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 @@ -536,15 +547,7 @@ config AUDIT logging of avc messages output). Does not do system-call auditing without CONFIG_AUDITSYSCALL. -Features that might still be considered unstable should be defined as -dependent on "EXPERIMENTAL": - -config SLUB - depends on EXPERIMENTAL && !ARCH_USES_SLAB_PAGE_STRUCT - bool "SLUB (Unqueued Allocator)" - ... - -while seriously dangerous features (such as write support for certain +Seriously dangerous features (such as write support for certain filesystems) should advertise this prominently in their prompt string: config ADFS_FS_RW @@ -671,8 +674,9 @@ ones already enabled by DEBUG. Chapter 14: Allocating memory The kernel provides the following general purpose memory allocators: -kmalloc(), kzalloc(), kcalloc(), vmalloc(), and vzalloc(). Please refer to -the API documentation for further information about them. +kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and +vzalloc(). Please refer to the API documentation for further information +about them. The preferred form for passing a size of a struct is the following: @@ -686,6 +690,17 @@ Casting the return value which is a void pointer is redundant. The conversion from void pointer to any other pointer type is guaranteed by the C programming language. +The preferred form for allocating an array is the following: + + p = kmalloc_array(n, sizeof(...), ...); + +The preferred form for allocating a zeroed array is the following: + + p = kcalloc(n, sizeof(...), ...); + +Both forms check for overflow on the allocation size n * sizeof(...), +and return NULL if that occurred. + Chapter 15: The inline disease @@ -793,6 +808,35 @@ own custom mode, or may have some other magic method for making indentation work correctly. + Chapter 19: Inline assembly + +In architecture-specific code, you may need to use inline assembly to interface +with CPU or platform functionality. Don't hesitate to do so when necessary. +However, don't use inline assembly gratuitously when C can do the job. You can +and should poke hardware from C when possible. + +Consider writing simple helper functions that wrap common bits of inline +assembly, rather than repeatedly writing them with slight variations. Remember +that inline assembly can use C parameters. + +Large, non-trivial assembly functions should go in .S files, with corresponding +C prototypes defined in C header files. The C prototypes for assembly +functions should use "asmlinkage". + +You may need to mark your asm statement as volatile, to prevent GCC from +removing it if GCC doesn't notice any side effects. You don't always need to +do so, though, and doing so unnecessarily can limit optimization. + +When writing a single inline assembly statement containing multiple +instructions, put each instruction on a separate line in a separate quoted +string, and end each string except the last with \n\t to properly indent the +next instruction in the assembly output: + + asm ("magic %reg1, #42\n\t" + "more_magic %reg2, %reg3" + : /* outputs */ : /* inputs */ : /* clobbers */); + + Appendix I: References diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt index a0b6250add79..14129f149a75 100644 --- a/Documentation/DMA-API-HOWTO.txt +++ b/Documentation/DMA-API-HOWTO.txt @@ -468,11 +468,47 @@ To map a single region, you do: size_t size = buffer->len; dma_handle = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dma_handle)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } and to unmap it: dma_unmap_single(dev, dma_handle, size, direction); +You should call dma_mapping_error() as dma_map_single() could fail and return +error. Not all dma implementations support dma_mapping_error() interface. +However, it is a good practice to call dma_mapping_error() interface, which +will invoke the generic mapping error check interface. Doing so will ensure +that the mapping code will work correctly on all dma implementations without +any dependency on the specifics of the underlying implementation. Using the +returned address without checking for errors could result in failures ranging +from panics to silent data corruption. A couple of examples of incorrect ways +to check for errors that make assumptions about the underlying dma +implementation are as follows and these are applicable to dma_map_page() as +well. + +Incorrect example 1: + dma_addr_t dma_handle; + + dma_handle = dma_map_single(dev, addr, size, direction); + if ((dma_handle & 0xffff != 0) || (dma_handle >= 0x1000000)) { + goto map_error; + } + +Incorrect example 2: + dma_addr_t dma_handle; + + dma_handle = dma_map_single(dev, addr, size, direction); + if (dma_handle == DMA_ERROR_CODE) { + goto map_error; + } + You should call dma_unmap_single when the DMA activity is finished, e.g. from the interrupt which told you that the DMA transfer is done. @@ -489,6 +525,14 @@ Specifically: size_t size = buffer->len; dma_handle = dma_map_page(dev, page, offset, size, direction); + if (dma_mapping_error(dma_handle)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } ... @@ -496,6 +540,12 @@ Specifically: Here, "offset" means byte offset within the given page. +You should call dma_mapping_error() as dma_map_page() could fail and return +error as outlined under the dma_map_single() discussion. + +You should call dma_unmap_page when the DMA activity is finished, e.g. +from the interrupt which told you that the DMA transfer is done. + With scatterlists, you map a region gathered from several regions by: int i, count = dma_map_sg(dev, sglist, nents, direction); @@ -578,6 +628,14 @@ to use the dma_sync_*() interfaces. dma_addr_t mapping; mapping = dma_map_single(cp->dev, buffer, len, DMA_FROM_DEVICE); + if (dma_mapping_error(dma_handle)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } cp->rx_buf = buffer; cp->rx_len = len; @@ -658,6 +716,75 @@ failure can be determined by: * delay and try again later or * reset driver. */ + goto map_error_handling; + } + +- unmap pages that are already mapped, when mapping error occurs in the middle + of a multiple page mapping attempt. These example are applicable to + dma_map_page() as well. + +Example 1: + dma_addr_t dma_handle1; + dma_addr_t dma_handle2; + + dma_handle1 = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_handle1)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling1; + } + dma_handle2 = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_handle2)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling2; + } + + ... + + map_error_handling2: + dma_unmap_single(dma_handle1); + map_error_handling1: + +Example 2: (if buffers are allocated in a loop, unmap all mapped buffers when + mapping error is detected in the middle) + + dma_addr_t dma_addr; + dma_addr_t array[DMA_BUFFERS]; + int save_index = 0; + + for (i = 0; i < DMA_BUFFERS; i++) { + + ... + + dma_addr = dma_map_single(dev, addr, size, direction); + if (dma_mapping_error(dev, dma_addr)) { + /* + * reduce current DMA mapping usage, + * delay and try again later or + * reset driver. + */ + goto map_error_handling; + } + array[i].dma_addr = dma_addr; + save_index++; + } + + ... + + map_error_handling: + + for (i = 0; i < save_index; i++) { + + ... + + dma_unmap_single(array[i].dma_addr); } Networking drivers must call dev_kfree_skb to free the socket buffer diff --git a/Documentation/DMA-API.txt b/Documentation/DMA-API.txt index 66bd97a95f10..78a6c569d204 100644 --- a/Documentation/DMA-API.txt +++ b/Documentation/DMA-API.txt @@ -678,3 +678,15 @@ out of dma_debug_entries. These entries are preallocated at boot. The number of preallocated entries is defined per architecture. If it is too low for you boot with 'dma_debug_entries=<your_desired_number>' to overwrite the architectural default. + +void debug_dmap_mapping_error(struct device *dev, dma_addr_t dma_addr); + +dma-debug interface debug_dma_mapping_error() to debug drivers that fail +to check dma mapping errors on addresses returned by dma_map_single() and +dma_map_page() interfaces. This interface clears a flag set by +debug_dma_map_page() to indicate that dma_mapping_error() has been called by +the driver. When driver does unmap, debug_dma_unmap() checks the flag and if +this flag is still set, prints warning message that includes call trace that +leads up to the unmap. This interface can be called from dma_mapping_error() +routines to enable dma mapping error check debugging. + diff --git a/Documentation/DMA-attributes.txt b/Documentation/DMA-attributes.txt index b768cc0e402b..e59480db9ee0 100644 --- a/Documentation/DMA-attributes.txt +++ b/Documentation/DMA-attributes.txt @@ -31,3 +31,72 @@ may be weakly ordered, that is that reads and writes may pass each other. Since it is optional for platforms to implement DMA_ATTR_WEAK_ORDERING, those that do not will simply ignore the attribute and exhibit default behavior. + +DMA_ATTR_WRITE_COMBINE +---------------------- + +DMA_ATTR_WRITE_COMBINE specifies that writes to the mapping may be +buffered to improve performance. + +Since it is optional for platforms to implement DMA_ATTR_WRITE_COMBINE, +those that do not will simply ignore the attribute and exhibit default +behavior. + +DMA_ATTR_NON_CONSISTENT +----------------------- + +DMA_ATTR_NON_CONSISTENT lets the platform to choose to return either +consistent or non-consistent memory as it sees fit. By using this API, +you are guaranteeing to the platform that you have all the correct and +necessary sync points for this memory in the driver. + +DMA_ATTR_NO_KERNEL_MAPPING +-------------------------- + +DMA_ATTR_NO_KERNEL_MAPPING lets the platform to avoid creating a kernel +virtual mapping for the allocated buffer. On some architectures creating +such mapping is non-trivial task and consumes very limited resources +(like kernel virtual address space or dma consistent address space). +Buffers allocated with this attribute can be only passed to user space +by calling dma_mmap_attrs(). By using this API, you are guaranteeing +that you won't dereference the pointer returned by dma_alloc_attr(). You +can threat it as a cookie that must be passed to dma_mmap_attrs() and +dma_free_attrs(). Make sure that both of these also get this attribute +set on each call. + +Since it is optional for platforms to implement +DMA_ATTR_NO_KERNEL_MAPPING, those that do not will simply ignore the +attribute and exhibit default behavior. + +DMA_ATTR_SKIP_CPU_SYNC +---------------------- + +By default dma_map_{single,page,sg} functions family transfer a given +buffer from CPU domain to device domain. Some advanced use cases might +require sharing a buffer between more than one device. This requires +having a mapping created separately for each device and is usually +performed by calling dma_map_{single,page,sg} function more than once +for the given buffer with device pointer to each device taking part in +the buffer sharing. The first call transfers a buffer from 'CPU' domain +to 'device' domain, what synchronizes CPU caches for the given region +(usually it means that the cache has been flushed or invalidated +depending on the dma direction). However, next calls to +dma_map_{single,page,sg}() for other devices will perform exactly the +same sychronization operation on the CPU cache. CPU cache sychronization +might be a time consuming operation, especially if the buffers are +large, so it is highly recommended to avoid it if possible. +DMA_ATTR_SKIP_CPU_SYNC allows platform code to skip synchronization of +the CPU cache for the given buffer assuming that it has been already +transferred to 'device' domain. This attribute can be also used for +dma_unmap_{single,page,sg} functions family to force buffer to stay in +device domain after releasing a mapping for it. Use this attribute with +care! + +DMA_ATTR_FORCE_CONTIGUOUS +------------------------- + +By default DMA-mapping subsystem is allowed to assemble the buffer +allocated by dma_alloc_attrs() function from individual pages if it can +be mapped as contiguous chunk into device dma address space. By +specifing this attribute the allocated buffer is forced to be contiguous +also in physical memory. diff --git a/Documentation/DocBook/80211.tmpl b/Documentation/DocBook/80211.tmpl index 2014155c899d..f403ec3c5c9a 100644 --- a/Documentation/DocBook/80211.tmpl +++ b/Documentation/DocBook/80211.tmpl @@ -107,8 +107,8 @@ !Finclude/net/cfg80211.h key_params !Finclude/net/cfg80211.h survey_info_flags !Finclude/net/cfg80211.h survey_info -!Finclude/net/cfg80211.h beacon_parameters -!Finclude/net/cfg80211.h plink_actions +!Finclude/net/cfg80211.h cfg80211_beacon_data +!Finclude/net/cfg80211.h cfg80211_ap_settings !Finclude/net/cfg80211.h station_parameters !Finclude/net/cfg80211.h station_info_flags !Finclude/net/cfg80211.h rate_info_flags @@ -127,15 +127,11 @@ !Finclude/net/cfg80211.h cfg80211_ibss_params !Finclude/net/cfg80211.h cfg80211_connect_params !Finclude/net/cfg80211.h cfg80211_pmksa -!Finclude/net/cfg80211.h cfg80211_send_rx_auth -!Finclude/net/cfg80211.h cfg80211_send_auth_timeout -!Finclude/net/cfg80211.h __cfg80211_auth_canceled -!Finclude/net/cfg80211.h cfg80211_send_rx_assoc -!Finclude/net/cfg80211.h cfg80211_send_assoc_timeout -!Finclude/net/cfg80211.h cfg80211_send_deauth -!Finclude/net/cfg80211.h __cfg80211_send_deauth -!Finclude/net/cfg80211.h cfg80211_send_disassoc -!Finclude/net/cfg80211.h __cfg80211_send_disassoc +!Finclude/net/cfg80211.h cfg80211_rx_mlme_mgmt +!Finclude/net/cfg80211.h cfg80211_auth_timeout +!Finclude/net/cfg80211.h cfg80211_rx_assoc_resp +!Finclude/net/cfg80211.h cfg80211_assoc_timeout +!Finclude/net/cfg80211.h cfg80211_tx_mlme_mgmt !Finclude/net/cfg80211.h cfg80211_ibss_joined !Finclude/net/cfg80211.h cfg80211_connect_result !Finclude/net/cfg80211.h cfg80211_roamed @@ -329,6 +325,7 @@ <title>functions/definitions</title> !Finclude/net/mac80211.h ieee80211_rx_status !Finclude/net/mac80211.h mac80211_rx_flags +!Finclude/net/mac80211.h mac80211_tx_info_flags !Finclude/net/mac80211.h mac80211_tx_control_flags !Finclude/net/mac80211.h mac80211_rate_control_flags !Finclude/net/mac80211.h ieee80211_tx_rate @@ -405,7 +402,6 @@ !Finclude/net/mac80211.h ieee80211_get_tkip_p1k !Finclude/net/mac80211.h ieee80211_get_tkip_p1k_iv !Finclude/net/mac80211.h ieee80211_get_tkip_p2k -!Finclude/net/mac80211.h ieee80211_key_removed </chapter> <chapter id="powersave"> @@ -439,7 +435,7 @@ </section> !Finclude/net/mac80211.h ieee80211_get_buffered_bc !Finclude/net/mac80211.h ieee80211_beacon_get -!Finclude/net/mac80211.h ieee80211_sta_eosp_irqsafe +!Finclude/net/mac80211.h ieee80211_sta_eosp !Finclude/net/mac80211.h ieee80211_frame_release_type !Finclude/net/mac80211.h ieee80211_sta_ps_transition !Finclude/net/mac80211.h ieee80211_sta_ps_transition_ni @@ -517,7 +513,7 @@ !Finclude/net/mac80211.h ieee80211_start_tx_ba_cb_irqsafe !Finclude/net/mac80211.h ieee80211_stop_tx_ba_session !Finclude/net/mac80211.h ieee80211_stop_tx_ba_cb_irqsafe -!Finclude/net/mac80211.h rate_control_changed +!Finclude/net/mac80211.h ieee80211_rate_control_changed !Finclude/net/mac80211.h ieee80211_tx_rate_control !Finclude/net/mac80211.h rate_control_send_low </chapter> diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 66725a3d30dc..bc3d9f8c0a90 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -6,7 +6,7 @@ # To add a new book the only step required is to add the book to the # list of DOCBOOKS. -DOCBOOKS := z8530book.xml mcabook.xml device-drivers.xml \ +DOCBOOKS := z8530book.xml device-drivers.xml \ kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ writing_usb_driver.xml networking.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml kgdb.xml \ diff --git a/Documentation/DocBook/debugobjects.tmpl b/Documentation/DocBook/debugobjects.tmpl index 08ff908aa7a2..24979f691e3e 100644 --- a/Documentation/DocBook/debugobjects.tmpl +++ b/Documentation/DocBook/debugobjects.tmpl @@ -96,6 +96,7 @@ <listitem><para>debug_object_deactivate</para></listitem> <listitem><para>debug_object_destroy</para></listitem> <listitem><para>debug_object_free</para></listitem> + <listitem><para>debug_object_assert_init</para></listitem> </itemizedlist> Each of these functions takes the address of the real object and a pointer to the object type specific debug description @@ -273,6 +274,26 @@ debug checks. </para> </sect1> + + <sect1 id="debug_object_assert_init"> + <title>debug_object_assert_init</title> + <para> + This function is called to assert that an object has been + initialized. + </para> + <para> + When the real object is not tracked by debugobjects, it calls + fixup_assert_init of the object type description structure + provided by the caller, with the hardcoded object state + ODEBUG_NOT_AVAILABLE. The fixup function can correct the problem + by calling debug_object_init and other specific initializing + functions. + </para> + <para> + When the real object is already tracked by debugobjects it is + ignored. + </para> + </sect1> </chapter> <chapter id="fixupfunctions"> <title>Fixup functions</title> @@ -381,6 +402,35 @@ statistics. </para> </sect1> + <sect1 id="fixup_assert_init"> + <title>fixup_assert_init</title> + <para> + This function is called from the debug code whenever a problem + in debug_object_assert_init is detected. + </para> + <para> + Called from debug_object_assert_init() with a hardcoded state + ODEBUG_STATE_NOTAVAILABLE when the object is not found in the + debug bucket. + </para> + <para> + The function returns 1 when the fixup was successful, + otherwise 0. The return value is used to update the + statistics. + </para> + <para> + Note, this function should make sure debug_object_init() is + called before returning. + </para> + <para> + The handling of statically initialized objects is a special + case. The fixup function should check if this is a legitimate + case of a statically initialized object or not. In this case only + debug_object_init() should be called to make the object known to + the tracker. Then the function should return 0 because this is not + a real fixup. + </para> + </sect1> </chapter> <chapter id="bugs"> <title>Known Bugs And Assumptions</title> diff --git a/Documentation/DocBook/device-drivers.tmpl b/Documentation/DocBook/device-drivers.tmpl index b638e50cf8f6..fe397f90a34f 100644 --- a/Documentation/DocBook/device-drivers.tmpl +++ b/Documentation/DocBook/device-drivers.tmpl @@ -50,7 +50,9 @@ <sect1><title>Delaying, scheduling, and timer routines</title> !Iinclude/linux/sched.h -!Ekernel/sched.c +!Ekernel/sched/core.c +!Ikernel/sched/cpupri.c +!Ikernel/sched/fair.c !Iinclude/linux/completion.h !Ekernel/timer.c </sect1> @@ -82,7 +84,7 @@ X!Iinclude/linux/kobject.h <sect1><title>Kernel utility functions</title> !Iinclude/linux/kernel.h -!Ekernel/printk.c +!Ekernel/printk/printk.c !Ekernel/panic.c !Ekernel/sys.c !Ekernel/rcupdate.c @@ -100,9 +102,12 @@ X!Iinclude/linux/kobject.h !Iinclude/linux/device.h </sect1> <sect1><title>Device Drivers Base</title> +!Idrivers/base/init.c !Edrivers/base/driver.c !Edrivers/base/core.c +!Edrivers/base/syscore.c !Edrivers/base/class.c +!Idrivers/base/node.c !Edrivers/base/firmware_class.c !Edrivers/base/transport_class.c <!-- Cannot be included, because @@ -111,7 +116,7 @@ X!Iinclude/linux/kobject.h exceed allowed 44 characters maximum X!Edrivers/base/attribute_container.c --> -!Edrivers/base/sys.c +!Edrivers/base/dd.c <!-- X!Edrivers/base/interface.c --> @@ -119,6 +124,13 @@ X!Edrivers/base/interface.c !Edrivers/base/platform.c !Edrivers/base/bus.c </sect1> + <sect1><title>Device Drivers DMA Management</title> +!Edrivers/base/dma-buf.c +!Edrivers/base/reservation.c +!Iinclude/linux/reservation.h +!Edrivers/base/dma-coherent.c +!Edrivers/base/dma-mapping.c + </sect1> <sect1><title>Device Drivers Power Management</title> !Edrivers/base/power/main.c </sect1> @@ -216,9 +228,8 @@ X!Isound/sound_firmware.c <chapter id="uart16x50"> <title>16x50 UART Driver</title> -!Iinclude/linux/serial_core.h !Edrivers/tty/serial/serial_core.c -!Edrivers/tty/serial/8250.c +!Edrivers/tty/serial/8250/8250_core.c </chapter> <chapter id="fbdev"> @@ -288,10 +299,10 @@ KAO --> </sect1> <sect1><title>Frame Buffer Fonts</title> <para> - Refer to the file drivers/video/console/fonts.c for more information. + Refer to the file lib/fonts/fonts.c for more information. </para> <!-- FIXME: Removed for now since no structured comments in source -X!Idrivers/video/console/fonts.c +X!Ilib/fonts/fonts.c --> </sect1> </chapter> @@ -437,4 +448,21 @@ X!Idrivers/video/console/fonts.c !Edrivers/i2c/i2c-core.c </chapter> + <chapter id="hsi"> + <title>High Speed Synchronous Serial Interface (HSI)</title> + + <para> + High Speed Synchronous Serial Interface (HSI) is a + serial interface mainly used for connecting application + engines (APE) with cellular modem engines (CMT) in cellular + handsets. + + HSI provides multiplexing for up to 16 logical channels, + low-latency and full duplex communication. + </para> + +!Iinclude/linux/hsi/hsi.h +!Edrivers/hsi/hsi.c + </chapter> + </book> diff --git a/Documentation/DocBook/deviceiobook.tmpl b/Documentation/DocBook/deviceiobook.tmpl index c1ed6a49e598..54199a0dcf9a 100644 --- a/Documentation/DocBook/deviceiobook.tmpl +++ b/Documentation/DocBook/deviceiobook.tmpl @@ -317,7 +317,7 @@ CPU B: spin_unlock_irqrestore(&dev_lock, flags) <chapter id="pubfunctions"> <title>Public Functions Provided</title> !Iarch/x86/include/asm/io.h -!Elib/iomap.c +!Elib/pci_iomap.c </chapter> </book> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index 196b8b9dba11..ed1d6d289022 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,360 @@ 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_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 + managed by the DRM Core. The core will support simple IRQ handler + installation when the flag is set. The installation process is + described in <xref linkend="drm-irq-registration"/>.</para> + <para>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_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> + <varlistentry> + <term>DRIVER_RENDER</term> + <listitem><para> + Driver supports dedicated render nodes. + </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, devices that use more than one + IRQs need to be handled manually. + </para> + <sect4> + <title>Managed IRQ Registration</title> + <para> + Both the <function>drm_irq_install</function> and + <function>drm_irq_uninstall</function> 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> + </sect4> + <sect4> + <title>Manual IRQ Registration</title> + <para> + Drivers that require multiple interrupt handlers can't use the managed + IRQ registration functions. In that case IRQs must be registered and + unregistered manually (usually with the <function>request_irq</function> + and <function>free_irq</function> functions, or their devm_* equivalent). + </para> + <para> + When manually registering IRQs, drivers must not set the DRIVER_HAVE_IRQ + driver feature flag, and must not provide the + <methodname>irq_handler</methodname> driver operation. They must set the + <structname>drm_device</structname> <structfield>irq_enabled</structfield> + field to 1 upon registration of the IRQs, and clear it to 0 after + unregistering the IRQs. + </para> + </sect4> + </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 accommodate 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 +499,1139 @@ 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> - 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 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 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 explicitly 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> + <sect4> + <title>DRM PRIME Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + </sect4> + </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. 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> + + <para> + The initailization of the new framebuffer instance is finalized with a + call to <function>drm_framebuffer_init</function> which takes a pointer + to DRM frame buffer operations (struct + <structname>drm_framebuffer_funcs</structname>). Note that this function + publishes the framebuffer and so from this point on it can be accessed + concurrently from other threads. Hence it must be the last step in the + driver's framebuffer initialization sequence. 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> + The lifetime of a drm framebuffer is controlled with a reference count, + drivers can grab additional references with + <function>drm_framebuffer_reference</function> </para> and drop them + again with <function>drm_framebuffer_unreference</function>. For + driver-private framebuffers for which the last reference is never + dropped (e.g. for the fbdev framebuffer when the struct + <structname>drm_framebuffer</structname> is embedded into the fbdev + helper struct) drivers can manually clean up a framebuffer at module + unload time with + <function>drm_framebuffer_unregister_private</function>. + </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> + <sect2> + <title>Locking</title> + <para> + Beside some lookup structures with their own locking (which is hidden + behind the interface functions) most of the modeset state is protected + by the <code>dev-<mode_config.lock</code> mutex and additionally + per-crtc locks to allow cursor updates, pageflips and similar operations + to occur concurrently with background tasks like output detection. + Operations which cross domains like a full modeset always grab all + locks. Drivers there need to protect resources shared between crtcs with + additional locking. They also need to be careful to always grab the + relevant crtc locks if a modset functions touches crtc state, e.g. for + load detection (which does only grab the <code>mode_config.lock</code> + to allow concurrent screen updates on live crtcs). + </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 targeting 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 can be successfully scheduled the driver must set the + <code>drm_crtc-<fb</code> field to the new framebuffer pointed to + by <code>fb</code>. This is important so that the reference counting + on framebuffers stays balanced. + </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 call <methodname>drm_send_vblank_event</methodname> + to fill in the event and send to wake up any waiting processes. + This can be performed with + <programlisting><![CDATA[ + spin_lock_irqsave(&dev->event_lock, flags); + ... + drm_send_vblank_event(dev, pipe, event); + 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 (*set_property)(struct drm_crtc *crtc, + struct drm_property *property, uint64_t value);</synopsis> + <para> + Set the value of the given CRTC property to + <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> + for more information about properties. + </para> + </listitem> + <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> + <listitem> + <synopsis>void (*set_property)(struct drm_plane *plane, + struct drm_property *property, uint64_t value);</synopsis> + <para> + Set the value of the given plane property to + <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> + for more information about properties. + </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 (*set_property)(struct drm_connector *connector, + struct drm_property *property, uint64_t value);</synopsis> + <para> + Set the value of the given connector property to + <parameter>value</parameter>. See <xref linkend="drm-kms-properties"/> + for more information about properties. + </para> + </listitem> + <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 +1667,899 @@ 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> + <sect2> + <title>KMS API Functions</title> +!Edrivers/gpu/drm/drm_crtc.c </sect2> </sect1> - <!-- Internals: vblank handling --> + <!-- Internals: kms helper functions --> <sect1> - <title>VBlank event handling</title> + <title>Mode Setting Helper Functions</title> + <para> + 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 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> - The DRM core exposes two vertical blank related ioctls: + 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> + <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> + <sect2> + <title>Modeset Helper Functions Reference</title> +!Edrivers/gpu/drm/drm_crtc_helper.c + </sect2> + <sect2> + <title>fbdev Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_fb_helper.c fbdev helpers +!Edrivers/gpu/drm/drm_fb_helper.c +!Iinclude/drm/drm_fb_helper.h + </sect2> + <sect2> + <title>Display Port Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_dp_helper.c dp helpers +!Iinclude/drm/drm_dp_helper.h +!Edrivers/gpu/drm/drm_dp_helper.c + </sect2> + <sect2> + <title>EDID Helper Functions Reference</title> +!Edrivers/gpu/drm/drm_edid.c + </sect2> + <sect2> + <title>Rectangle Utilities Reference</title> +!Pinclude/drm/drm_rect.h rect utils +!Iinclude/drm/drm_rect.h +!Edrivers/gpu/drm/drm_rect.c + </sect2> + <sect2> + <title>Flip-work Helper Reference</title> +!Pinclude/drm/drm_flip_work.h flip utils +!Iinclude/drm/drm_flip_work.h +!Edrivers/gpu/drm/drm_flip_work.c + </sect2> + <sect2> + <title>VMA Offset Manager</title> +!Pdrivers/gpu/drm/drm_vma_manager.c vma offset manager +!Edrivers/gpu/drm/drm_vma_manager.c +!Iinclude/drm/drm_vma_manager.h + </sect2> + </sect1> + + <!-- Internals: kms properties --> + + <sect1 id="drm-kms-properties"> + <title>KMS Properties</title> + <para> + Drivers may need to expose additional parameters to applications than + those described in the previous sections. KMS supports attaching + properties to CRTCs, connectors and planes and offers a userspace API to + list, get and set the property values. + </para> + <para> + Properties are identified by a name that uniquely defines the property + purpose, and store an associated value. For all property types except blob + properties the value is a 64-bit unsigned integer. + </para> + <para> + KMS differentiates between properties and property instances. Drivers + first create properties and then create and associate individual instances + of those properties to objects. A property can be instantiated multiple + times and associated with different objects. Values are stored in property + instances, and all other property information are stored in the propery + and shared between all instances of the property. + </para> + <para> + Every property is created with a type that influences how the KMS core + handles the property. Supported property types are <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> + <term>DRM_MODE_PROP_RANGE</term> + <listitem><para>Range properties report their minimum and maximum + admissible values. The KMS core verifies that values set by + application fit in that range.</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> + <term>DRM_MODE_PROP_ENUM</term> + <listitem><para>Enumerated properties take a numerical value that + ranges from 0 to the number of enumerated values defined by the + property minus one, and associate a free-formed string name to each + value. Applications can retrieve the list of defined value-name pairs + and use the numerical value to get and set property instance values. + </para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_PROP_BITMASK</term> + <listitem><para>Bitmask properties are enumeration properties that + additionally restrict all enumerated values to the 0..63 range. + Bitmask property instance values combine one or more of the + enumerated bits defined by the property.</para></listitem> + </varlistentry> + <varlistentry> + <term>DRM_MODE_PROP_BLOB</term> + <listitem><para>Blob properties store a binary blob without any format + restriction. The binary blobs are created as KMS standalone objects, + and blob property instance values store the ID of their associated + blob object.</para> + <para>Blob properties are only used for the connector EDID property + and cannot be created by drivers.</para></listitem> </varlistentry> </variablelist> -<!--!Edrivers/char/drm/drm_irq.c--> </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 create a property drivers call one of the following functions depending + on the property type. All property creation functions take property flags + and name, as well as type-specific arguments. + <itemizedlist> + <listitem> + <synopsis>struct drm_property *drm_property_create_range(struct drm_device *dev, int flags, + const char *name, + uint64_t min, uint64_t max);</synopsis> + <para>Create a range property with the given minimum and maximum + values.</para> + </listitem> + <listitem> + <synopsis>struct drm_property *drm_property_create_enum(struct drm_device *dev, int flags, + const char *name, + const struct drm_prop_enum_list *props, + int num_values);</synopsis> + <para>Create an enumerated property. The <parameter>props</parameter> + argument points to an array of <parameter>num_values</parameter> + value-name pairs.</para> + </listitem> + <listitem> + <synopsis>struct drm_property *drm_property_create_bitmask(struct drm_device *dev, + int flags, const char *name, + const struct drm_prop_enum_list *props, + int num_values);</synopsis> + <para>Create a bitmask property. The <parameter>props</parameter> + argument points to an array of <parameter>num_values</parameter> + value-name pairs.</para> + </listitem> + </itemizedlist> + </para> + <para> + Properties can additionally be created as immutable, in which case they + will be read-only for applications but can be modified by the driver. To + create an immutable property drivers must set the DRM_MODE_PROP_IMMUTABLE + flag at property creation time. </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). + When no array of value-name pairs is readily available at property + creation time for enumerated or range properties, drivers can create + the property using the <function>drm_property_create</function> function + and manually add enumeration value-name pairs by calling the + <function>drm_property_add_enum</function> function. Care must be taken to + properly specify the property type through the <parameter>flags</parameter> + argument. + </para> + <para> + After creating properties drivers can attach property instances to CRTC, + connector and plane objects by calling the + <function>drm_object_attach_property</function>. The function takes a + pointer to the target object, a pointer to the previously created property + and an initial instance value. </para> </sect1> - <sect1> - <title>Memory management</title> + <!-- Internals: vertical blanking --> + + <sect1 id="drm-vertical-blank"> + <title>Vertical Blanking</title> <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. + 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> + 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 + for legacy UMS (User Mode Setting) drivers only when an application + opens a device that has no other opened file handle. UMS drivers can + implement it to acquire device resources. KMS drivers can't use the + method and must acquire resources in the <methodname>load</methodname> + method instead. </para> <para> - Drivers wishing to support TTM must fill out a drm_bo_driver - structure. + Similarly the <methodname>lastclose</methodname> method is called when + the last application holding a file handle opened on the device closes + it, for both UMS and KMS drivers. Additionally, the 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. It can also be + used to execute delayed power switching state changes, e.g. in + conjunction with the vga-switcheroo infrastructure. Beyond that KMS + drivers should not do any further cleanup. Only legacy UMS drivers might + need to clean up device state so that the vga console or an independent + fbdev driver could take over. </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, + .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 +2570,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. + 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> + 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 +2600,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 +2649,105 @@ 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: render nodes --> + + <sect1> + <title>Render nodes</title> + <para> + DRM core provides multiple character-devices for user-space to use. + Depending on which device is opened, user-space can perform a different + set of operations (mainly ioctls). The primary node is always created + and called <term>card<num></term>. Additionally, a currently + unused control node, called <term>controlD<num></term> is also + created. The primary node provides all legacy operations and + historically was the only interface used by userspace. With KMS, the + control node was introduced. However, the planned KMS control interface + has never been written and so the control node stays unused to date. + </para> + <para> + With the increased use of offscreen renderers and GPGPU applications, + clients no longer require running compositors or graphics servers to + make use of a GPU. But the DRM API required unprivileged clients to + authenticate to a DRM-Master prior to getting GPU access. To avoid this + step and to grant clients GPU access without authenticating, render + nodes were introduced. Render nodes solely serve render clients, that + is, no modesetting or privileged ioctls can be issued on render nodes. + Only non-global rendering commands are allowed. If a driver supports + render nodes, it must advertise it via the <term>DRIVER_RENDER</term> + DRM driver capability. If not supported, the primary node must be used + for render clients together with the legacy drmAuth authentication + procedure. + </para> + <para> + If a driver advertises render node support, DRM core will create a + separate render node called <term>renderD<num></term>. There will + be one render node per device. No ioctls except PRIME-related ioctls + will be allowed on this node. Especially <term>GEM_OPEN</term> will be + explicitly prohibited. Render nodes are designed to avoid the + buffer-leaks, which occur if clients guess the flink names or mmap + offsets on the legacy interface. Additionally to this basic interface, + drivers must mark their driver-dependent render-only ioctls as + <term>DRM_RENDER_ALLOW</term> so render clients can use them. Driver + authors must be careful not to allow any privileged ioctls on render + nodes. + </para> + <para> + With render nodes, user-space can now control access to the render node + via basic file-system access-modes. A running graphics server which + authenticates clients on the privileged primary/legacy node is no longer + required. Instead, a client can open the render node and is immediately + granted GPU access. Communication between clients (or servers) is done + via PRIME. FLINK from render node to legacy node is not supported. New + clients must not use the insecure FLINK interface. + </para> + <para> + Besides dropping all modeset/global ioctls, render nodes also drop the + DRM-Master concept. There is no reason to associate render clients with + a DRM-Master as they are independent of any graphics server. Besides, + they must work without any running master, anyway. + Drivers must be able to run without a master object if they support + render nodes. If, on the other hand, a driver requires shared state + between clients which is visible to user-space and accessible beyond + open-file boundaries, they cannot support render nodes. + </para> + </sect1> + + <!-- 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/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl index f51f28531b8d..25b58efd955d 100644 --- a/Documentation/DocBook/filesystems.tmpl +++ b/Documentation/DocBook/filesystems.tmpl @@ -224,8 +224,8 @@ all your transactions. </para> <para> -Then at umount time , in your put_super() (2.4) or write_super() (2.5) -you can then call journal_destroy() to clean up your in-core journal object. +Then at umount time , in your put_super() you can then call journal_destroy() +to clean up your in-core journal object. </para> <para> @@ -387,7 +387,7 @@ an example. <title>See also</title> <para> <citation> - <ulink url="ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz"> + <ulink url="http://kernel.org/pub/linux/kernel/people/sct/ext3/journal-design.ps.gz"> Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie </ulink> </citation> diff --git a/Documentation/DocBook/gadget.tmpl b/Documentation/DocBook/gadget.tmpl index 6ef2f0073e5a..4017f147ba2f 100644 --- a/Documentation/DocBook/gadget.tmpl +++ b/Documentation/DocBook/gadget.tmpl @@ -671,7 +671,7 @@ than a kernel driver. <para>There's a USB Mass Storage class driver, which provides a different solution for interoperability with systems such as MS-Windows and MacOS. -That <emphasis>File-backed Storage</emphasis> driver uses a +That <emphasis>Mass Storage</emphasis> driver uses a file or block device as backing store for a drive, like the <filename>loop</filename> driver. The USB host uses the BBB, CB, or CBI versions of the mass diff --git a/Documentation/DocBook/genericirq.tmpl b/Documentation/DocBook/genericirq.tmpl index b3422341d65c..d16d21b7a3b7 100644 --- a/Documentation/DocBook/genericirq.tmpl +++ b/Documentation/DocBook/genericirq.tmpl @@ -464,6 +464,19 @@ if (desc->irq_data.chip->irq_eoi) protected via desc->lock, by the generic layer. </para> </chapter> + + <chapter id="genericchip"> + <title>Generic interrupt chip</title> + <para> + To avoid copies of identical implementations of irq chips the + core provides a configurable generic interrupt chip + implementation. Developers should check carefuly whether the + generic chip fits their needs before implementing the same + functionality slightly different themself. + </para> +!Ekernel/irq/generic-chip.c + </chapter> + <chapter id="structs"> <title>Structures</title> <para> diff --git a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl index 7160652a8736..f75ab4c1b281 100644 --- a/Documentation/DocBook/kernel-api.tmpl +++ b/Documentation/DocBook/kernel-api.tmpl @@ -58,6 +58,9 @@ <sect1><title>String Conversions</title> !Elib/vsprintf.c +!Finclude/linux/kernel.h kstrtol +!Finclude/linux/kernel.h kstrtoul +!Elib/kstrtox.c </sect1> <sect1><title>String Manipulation</title> <!-- All functions are exported at now @@ -212,19 +215,6 @@ X!Edrivers/pci/hotplug.c <sect1><title>PCI Hotplug Support Library</title> !Edrivers/pci/hotplug/pci_hotplug_core.c </sect1> - <sect1><title>MCA Architecture</title> - <sect2><title>MCA Device Functions</title> - <para> - Refer to the file arch/x86/kernel/mca_32.c for more information. - </para> -<!-- FIXME: Removed for now since no structured comments in source -X!Earch/x86/kernel/mca_32.c ---> - </sect2> - <sect2><title>MCA Bus DMA</title> -!Iarch/x86/include/asm/mca_dma.h - </sect2> - </sect1> </chapter> <chapter id="firmware"> diff --git a/Documentation/DocBook/kernel-hacking.tmpl b/Documentation/DocBook/kernel-hacking.tmpl index 07a9c48de5a2..d0758b241b23 100644 --- a/Documentation/DocBook/kernel-hacking.tmpl +++ b/Documentation/DocBook/kernel-hacking.tmpl @@ -945,7 +945,7 @@ printk(KERN_INFO "my ip: %pI4\n", &ipaddress); <sect1 id="sym-exportsymbols"> <title><function>EXPORT_SYMBOL()</function> - <filename class="headerfile">include/linux/module.h</filename></title> + <filename class="headerfile">include/linux/export.h</filename></title> <para> This is the classic method of exporting a symbol: dynamically @@ -955,7 +955,7 @@ printk(KERN_INFO "my ip: %pI4\n", &ipaddress); <sect1 id="sym-exportsymbols-gpl"> <title><function>EXPORT_SYMBOL_GPL()</function> - <filename class="headerfile">include/linux/module.h</filename></title> + <filename class="headerfile">include/linux/export.h</filename></title> <para> Similar to <function>EXPORT_SYMBOL()</function> except that the @@ -1185,13 +1185,6 @@ static struct block_device_operations opt_fops = { </para> <para> - You may well want to make your CONFIG option only visible if - <symbol>CONFIG_EXPERIMENTAL</symbol> is enabled: this serves as a - warning to users. There many other fancy things you can do: see - the various <filename>Kconfig</filename> files for ideas. - </para> - - <para> In your description of the option, make sure you address both the expert user and the user who knows nothing about your feature. Mention incompatibilities and issues here. <emphasis> Definitely @@ -1289,7 +1282,7 @@ static struct block_device_operations opt_fops = { * Sparc assembly will do this to ya. */ C_LABEL(cputypvar): - .asciz "compatability" + .asciz "compatibility" /* Tested on SS-5, SS-10. Probably someone at Sun applied a spell-checker. */ .align 4 diff --git a/Documentation/DocBook/kernel-locking.tmpl b/Documentation/DocBook/kernel-locking.tmpl index 67e7ab41c0a6..09e884e5b9f5 100644 --- a/Documentation/DocBook/kernel-locking.tmpl +++ b/Documentation/DocBook/kernel-locking.tmpl @@ -1955,12 +1955,17 @@ machines due to caching. </sect1> </chapter> - <chapter id="apiref"> + <chapter id="apiref-mutex"> <title>Mutex API reference</title> !Iinclude/linux/mutex.h !Ekernel/mutex.c </chapter> + <chapter id="apiref-futex"> + <title>Futex API reference</title> +!Ikernel/futex.c + </chapter> + <chapter id="references"> <title>Further reading</title> diff --git a/Documentation/DocBook/kgdb.tmpl b/Documentation/DocBook/kgdb.tmpl index d71b57fcf116..f77358f96930 100644 --- a/Documentation/DocBook/kgdb.tmpl +++ b/Documentation/DocBook/kgdb.tmpl @@ -94,10 +94,8 @@ <sect1 id="CompileKGDB"> <title>Kernel config options for kgdb</title> <para> - To enable <symbol>CONFIG_KGDB</symbol> you should first turn on - "Prompt for development and/or incomplete code/drivers" - (CONFIG_EXPERIMENTAL) in "General setup", then under the - "Kernel debugging" select "KGDB: kernel debugger". + To enable <symbol>CONFIG_KGDB</symbol> you should look under + "Kernel debugging" and select "KGDB: kernel debugger". </para> <para> While it is not a hard requirement that you have symbols in your @@ -362,6 +360,23 @@ </para> </para> </sect1> + <sect1 id="kgdbreboot"> + <title>Run time parameter: kgdbreboot</title> + <para> The kgdbreboot feature allows you to change how the debugger + deals with the reboot notification. You have 3 choices for the + behavior. The default behavior is always set to 0.</para> + <orderedlist> + <listitem><para>echo -1 > /sys/module/debug_core/parameters/kgdbreboot</para> + <para>Ignore the reboot notification entirely.</para> + </listitem> + <listitem><para>echo 0 > /sys/module/debug_core/parameters/kgdbreboot</para> + <para>Send the detach message to any attached debugger client.</para> + </listitem> + <listitem><para>echo 1 > /sys/module/debug_core/parameters/kgdbreboot</para> + <para>Enter the debugger on reboot notify.</para> + </listitem> + </orderedlist> + </sect1> </chapter> <chapter id="usingKDB"> <title>Using kdb</title> diff --git a/Documentation/DocBook/libata.tmpl b/Documentation/DocBook/libata.tmpl index cdd1bb9aac0d..deb71baed328 100644 --- a/Documentation/DocBook/libata.tmpl +++ b/Documentation/DocBook/libata.tmpl @@ -22,8 +22,8 @@ <para> The contents of this file are subject to the Open Software License version 1.1 that can be found at - <ulink url="http://www.opensource.org/licenses/osl-1.1.txt">http://www.opensource.org/licenses/osl-1.1.txt</ulink> and is included herein - by reference. + <ulink url="http://fedoraproject.org/wiki/Licensing:OSL1.1">http://fedoraproject.org/wiki/Licensing:OSL1.1</ulink> + and is included herein by reference. </para> <para> @@ -918,7 +918,7 @@ and other resources, etc. <title>HSM violation</title> <para> This error is indicated when STATUS value doesn't match HSM - requirement during issuing or excution any ATA/ATAPI command. + requirement during issuing or execution any ATA/ATAPI command. </para> <itemizedlist> @@ -945,7 +945,7 @@ and other resources, etc. <listitem> <para> - !BSY && ERR after CDB tranfer starts but before the + !BSY && ERR after CDB transfer starts but before the last byte of CDB is transferred. ATA/ATAPI standard states that "The device shall not terminate the PACKET command with an error before the last byte of the command packet has @@ -1050,7 +1050,7 @@ and other resources, etc. to complete a command. Combined with the fact that MWDMA and PIO transfer errors aren't allowed to use ICRC bit up to ATA/ATAPI-7, it seems to imply that ABRT bit alone could - indicate tranfer errors. + indicate transfer errors. </para> <para> However, ATA/ATAPI-8 draft revision 1f removes the part diff --git a/Documentation/DocBook/mcabook.tmpl b/Documentation/DocBook/mcabook.tmpl deleted file mode 100644 index 467ccac6ec50..000000000000 --- a/Documentation/DocBook/mcabook.tmpl +++ /dev/null @@ -1,107 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" - "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> - -<book id="MCAGuide"> - <bookinfo> - <title>MCA Driver Programming Interface</title> - - <authorgroup> - <author> - <firstname>Alan</firstname> - <surname>Cox</surname> - <affiliation> - <address> - <email>alan@lxorguk.ukuu.org.uk</email> - </address> - </affiliation> - </author> - <author> - <firstname>David</firstname> - <surname>Weinehall</surname> - </author> - <author> - <firstname>Chris</firstname> - <surname>Beauregard</surname> - </author> - </authorgroup> - - <copyright> - <year>2000</year> - <holder>Alan Cox</holder> - <holder>David Weinehall</holder> - <holder>Chris Beauregard</holder> - </copyright> - - <legalnotice> - <para> - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License as published by the Free Software Foundation; either - version 2 of the License, or (at your option) any later - version. - </para> - - <para> - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - </para> - - <para> - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - </para> - - <para> - For more details see the file COPYING in the source - distribution of Linux. - </para> - </legalnotice> - </bookinfo> - -<toc></toc> - - <chapter id="intro"> - <title>Introduction</title> - <para> - The MCA bus functions provide a generalised interface to find MCA - bus cards, to claim them for a driver, and to read and manipulate POS - registers without being aware of the motherboard internals or - certain deep magic specific to onboard devices. - </para> - <para> - The basic interface to the MCA bus devices is the slot. Each slot - is numbered and virtual slot numbers are assigned to the internal - devices. Using a pci_dev as other busses do does not really make - sense in the MCA context as the MCA bus resources require card - specific interpretation. - </para> - <para> - Finally the MCA bus functions provide a parallel set of DMA - functions mimicing the ISA bus DMA functions as closely as possible, - although also supporting the additional DMA functionality on the - MCA bus controllers. - </para> - </chapter> - <chapter id="bugs"> - <title>Known Bugs And Assumptions</title> - <para> - None. - </para> - </chapter> - - <chapter id="pubfunctions"> - <title>Public Functions Provided</title> -!Edrivers/mca/mca-legacy.c - </chapter> - - <chapter id="dmafunctions"> - <title>DMA Functions Provided</title> -!Iarch/x86/include/asm/mca_dma.h - </chapter> - -</book> diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index 6628b4b9cac4..f9fd615427fb 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -56,48 +56,50 @@ FUNCS = \ write \ IOCTLS = \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/audio.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/ca.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/dmx.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/frontend.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/net.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/dvb/video.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/media.h) \ - $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/linux/v4l2-subdev.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/videodev2.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/audio.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/ca.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/dmx.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/frontend.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([A-Z][^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/net.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/dvb/video.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /\#define\s+([^\s]+)\s+_IO/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ VIDIOC_SUBDEV_G_FRAME_INTERVAL \ VIDIOC_SUBDEV_S_FRAME_INTERVAL \ VIDIOC_SUBDEV_ENUM_MBUS_CODE \ VIDIOC_SUBDEV_ENUM_FRAME_SIZE \ VIDIOC_SUBDEV_ENUM_FRAME_INTERVAL \ + VIDIOC_SUBDEV_G_SELECTION \ + VIDIOC_SUBDEV_S_SELECTION \ TYPES = \ - $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if /^}\s+([a-z0-9_]+_t)/' $(srctree)/include/linux/dvb/frontend.h) + $(shell perl -ne 'print "$$1 " if /^typedef\s+[^\s]+\s+([^\s]+)\;/' $(srctree)/include/uapi/linux/videodev2.h) \ + $(shell perl -ne 'print "$$1 " if /^}\s+([a-z0-9_]+_t)/' $(srctree)/include/uapi/linux/dvb/frontend.h) ENUMS = \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/audio.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/ca.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/dmx.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/frontend.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/net.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/dvb/video.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/media.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h) \ - $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-subdev.h) + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/videodev2.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/audio.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/ca.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/dmx.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/frontend.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/net.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/dvb/video.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) \ + $(shell perl -ne 'print "$$1 " if /^enum\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) STRUCTS = \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/videodev2.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s\{]+)\s*/)' $(srctree)/include/linux/dvb/audio.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/linux/dvb/ca.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/linux/dvb/dmx.h) \ - $(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/linux/dvb/frontend.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([A-Z][^\s]+)\s+/)' $(srctree)/include/linux/dvb/net.h) \ - $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/linux/dvb/video.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/media.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-subdev.h) \ - $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/linux/v4l2-mediabus.h) + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/videodev2.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s\{]+)\s*/)' $(srctree)/include/uapi/linux/dvb/audio.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/ca.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/dmx.h) \ + $(shell perl -ne 'print "$$1 " if (!/dtv\_cmds\_h/ && /^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/frontend.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([A-Z][^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/net.h) \ + $(shell perl -ne 'print "$$1 " if (/^struct\s+([^\s]+)\s+/)' $(srctree)/include/uapi/linux/dvb/video.h) \ + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/media.h) \ + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-subdev.h) \ + $(shell perl -ne 'print "$$1 " if /^struct\s+([^\s]+)\s+/' $(srctree)/include/uapi/linux/v4l2-mediabus.h) ERRORS = \ E2BIG \ @@ -193,7 +195,7 @@ DVB_DOCUMENTED = \ # install_media_images = \ - $(Q)cp $(OBJIMGFILES) $(MEDIA_OBJ_DIR)/media_api + $(Q)cp $(OBJIMGFILES) $(MEDIA_SRC_DIR)/v4l/*.svg $(MEDIA_OBJ_DIR)/media_api $(MEDIA_OBJ_DIR)/%: $(MEDIA_SRC_DIR)/%.b64 $(Q)base64 -d $< >$@ @@ -203,7 +205,7 @@ $(MEDIA_OBJ_DIR)/v4l2.xml: $(OBJIMGFILES) @(ln -sf $(MEDIA_SRC_DIR)/v4l/*xml $(MEDIA_OBJ_DIR)/) @(ln -sf $(MEDIA_SRC_DIR)/dvb/*xml $(MEDIA_OBJ_DIR)/) -$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/uapi/linux/videodev2.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "<programlisting>") > $@ @@ -214,7 +216,7 @@ $(MEDIA_OBJ_DIR)/videodev2.h.xml: $(srctree)/include/linux/videodev2.h $(MEDIA_O @( \ echo "</programlisting>") >> $@ -$(MEDIA_OBJ_DIR)/audio.h.xml: $(srctree)/include/linux/dvb/audio.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/audio.h.xml: $(srctree)/include/uapi/linux/dvb/audio.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "<programlisting>") > $@ @@ -225,7 +227,7 @@ $(MEDIA_OBJ_DIR)/audio.h.xml: $(srctree)/include/linux/dvb/audio.h $(MEDIA_OBJ_D @( \ echo "</programlisting>") >> $@ -$(MEDIA_OBJ_DIR)/ca.h.xml: $(srctree)/include/linux/dvb/ca.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/ca.h.xml: $(srctree)/include/uapi/linux/dvb/ca.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "<programlisting>") > $@ @@ -236,7 +238,7 @@ $(MEDIA_OBJ_DIR)/ca.h.xml: $(srctree)/include/linux/dvb/ca.h $(MEDIA_OBJ_DIR)/v4 @( \ echo "</programlisting>") >> $@ -$(MEDIA_OBJ_DIR)/dmx.h.xml: $(srctree)/include/linux/dvb/dmx.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/dmx.h.xml: $(srctree)/include/uapi/linux/dvb/dmx.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "<programlisting>") > $@ @@ -247,7 +249,7 @@ $(MEDIA_OBJ_DIR)/dmx.h.xml: $(srctree)/include/linux/dvb/dmx.h $(MEDIA_OBJ_DIR)/ @( \ echo "</programlisting>") >> $@ -$(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/linux/dvb/frontend.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/uapi/linux/dvb/frontend.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "<programlisting>") > $@ @@ -258,7 +260,7 @@ $(MEDIA_OBJ_DIR)/frontend.h.xml: $(srctree)/include/linux/dvb/frontend.h $(MEDIA @( \ echo "</programlisting>") >> $@ -$(MEDIA_OBJ_DIR)/net.h.xml: $(srctree)/include/linux/dvb/net.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/net.h.xml: $(srctree)/include/uapi/linux/dvb/net.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "<programlisting>") > $@ @@ -269,7 +271,7 @@ $(MEDIA_OBJ_DIR)/net.h.xml: $(srctree)/include/linux/dvb/net.h $(MEDIA_OBJ_DIR)/ @( \ echo "</programlisting>") >> $@ -$(MEDIA_OBJ_DIR)/video.h.xml: $(srctree)/include/linux/dvb/video.h $(MEDIA_OBJ_DIR)/v4l2.xml +$(MEDIA_OBJ_DIR)/video.h.xml: $(srctree)/include/uapi/linux/dvb/video.h $(MEDIA_OBJ_DIR)/v4l2.xml @$($(quiet)gen_xml) @( \ echo "<programlisting>") > $@ @@ -298,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/constraints.png.b64 b/Documentation/DocBook/media/constraints.png.b64 new file mode 100644 index 000000000000..125b4a94962c --- /dev/null +++ b/Documentation/DocBook/media/constraints.png.b64 @@ -0,0 +1,59 @@ +iVBORw0KGgoAAAANSUhEUgAAAlQAAAFYCAYAAACVsmLPAAAAAXNSR0IArs4c6QAAAAZiS0dEAP8A +/wD/oL2nkwAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAAd0SU1FB9sLCBIAKVtZsMAAAAxxSURBVHja +7d3ZbqvIAkDRLsv//8v0QytXvpYZap7Wko56OAnE2AXbBSbhOI7jHwAAkr1sAgAAQQUAIKgAAAQV +AICgAgBAUAEACCoAAEEFACCoAAAQVAAAzb2jvyMEWw0AmFvh37xnhgoAQFABAPT1zvruwtNlAADV +VLxsyQwVAICgAgAQVAAAggoAQFABACCoYEohuFkugKACsmLq178DIKiAyJgSVQCCCigQU6IKQFAB +BWJKVAEIKqBgKIkqAEEFFAgkUQUgqIACYSSqAAQViKkwxjIAEFSwbUyJKgBBBWJq8GUCIKhgm5gS +VQCCCsSUqAIQVMBYoSOqAAQVLOk41lwXAIIKhoqqJyFUYhkACCpYMqpiQqjEMgAQVLBUVKWEUIll +ACCoYImoygmhEssAQFDBElHVexkACCoAAEEFACCoAAAQVAAAggoAQFABAAgqAAAEFQCAoAIAEFQA +AIIKAABBBQAgqAAABBUAgKACAOA/b5sAGjsO2wBgMWaoAAAEFQCAoAIAEFQAADtzUXohIQQbAYDi +Dh9kmYIZKgAAQQUAIKgAAAQVAICgAgAgmU/5VeSTGQDE8InxeZmhAgAQVAAAggoAQFABAAgqAAAE +FQCAoAIAEFQAAHtyY0/o4O7efe4JCzAXM1QAAIIKAEBQAQAIKgAAQQUAgKACABBUAACCCgBAUAEA +IKgAAAQVAICgAgAQVAAACCoAAEEFACCoAAAEFVBICGMsAwBBBVPHVE4QlVgGAIIKpo6ps/9utQwA +BBUsEVMpQVRiGQAIKlgqpmKCqMQyABBUsGRMzbouAAQVNHMca64LAEEFy0WVmAIQVCCqxBSAoAL6 +hI+YAhBUIKrEFICgAvqEkJgCEFQgqo4+3wuAoILto0pMAQgqICOQxBSAoAIyQklMAQgqICOYxBSA +oAIyokpMAQgqICOqxBTAvN42AYwTVQDMyQwVAICgAgAQVAAAggoAQFABAJDMp/y4FIJtwJx8ehJo +yQwVAICgAgDoyyk/HnMKhdE5RQ30YoYKAEBQAQAIKgAAQQUAIKgAABBUAACCCgBAUAEACCoAAAQV +AICgAgAQVAAAggoAAEEFACCoAAAEFQCAoAIAQFABAAgqAABBBQAgqAAAEFQAAIIKAEBQAQAIKgAA +BBUAgKACABBUAACCCgAAQQUAIKgAAAQVAICgAgBAUAEACCoAAEEFACCoAAAQVAAAggoAQFABAAgq +AACGCKoQPAs2JQAIquwCUAI2JQAIqowCOPtvbEoAEFQRBaAEbEoAEFQFCkAJ2JQAIKgKFIASsClh +szEKrDGoXkNuiOPwwim4iezYoc9+39iDfQbVq+mGEFOiCjZ7E23swR6D6tV8Q4gpUQWb7PeNPdhn +UL26bAgxJapgk/2+sQd7DKr3EDE1y96mUPT1fqgh6Ffosbsz9mDdQfXquiEY/rUKlBtLYgoqDJZB +Dmjlg8qRWlSBMSSmYLOoKhtUjtCiCowdMQUbRtXLswUgpkBU5XkXf9CmPJZ9nQJrft6Gife9XmC/ +t0mHg9tr3FcJYgrmjilgn8Fa55SfI7WYAvtnYKNBW+8+VLGn/zY6wtd4qDY1iCngx+BtdNCre1G6 +W3gPt7MXUwAwW1CJKjEFCzB2wODtH1SiSkyB/TKw+KB9DfnARJWYAvtnYKLB+m7+AJ+UgL2WTQmT +jz1jEJVf0ASD7jXck2/vY1PCQscwE+6wfkz1CaqrB6wAbEoQVcBkMdUvqH49cAVgU4KoAiaMqb5B +9bkBFIBNCaIKmDSm+geVArApYaOxZ4zCuoPq5VkDqL//F1Ow9qASVACV9/9iCtYfVIIKoOL+X0zB +HoNKUAFU2v+LKdhnUAkqgAZvqoG1B5WgAgAQVAAAggoAQFABAAgqAAAEFQCAoAIAEFQAAIIKAABB +BQAgqAAABBUAgKACAEBQAQAIKgAAQQUAIKgAABBUAACCCgBAUAEACCoAAAQVAICgAgAY3NsmIEYI +//3zONK/7u/v/nx+zdPl/1rO0++LWd6vZZ59Xe7jSfnZSq3z6jnJ2ValX09PHj9AD2aoiPJ34Lo6 +wJWKiJQD7N2BN/WAzbNtZTsCuzJDRZeD8XHkH3zPZo5CSJudeTKbdrX+lkE7QkzFbq8VHj/AGTNU +dDkY1ziw1jjY7nAA/wzKqxnIu5gSPICggoTIuDroXh1YRz3ohuCUlcgESOOUH81iZdR1fJ9+zL1Q +use1Y6nrvLsearR46rHNAQQVw6l14HtyOurJz5USVqs9LynXt8V+ShBAUMHHQfdzFuMsQGqHSW5M +PQmrVtdsjRCkOwY5gKBiGne3Okg5WJaMqbuw2uX5+P6aX4H8/f922F4AgorlgyD3hp47z3ycPfZf +p/FSb00BIKjg4kD8/cm4mFNjKfd/OpsJyb2GJ+V+UzEXSK9wAfuvqGr9s7ooHRiV2yYgDCe8xUOp +gHny2GNjVdwAOzJDRbUYSfnep8srfdCOWV6tr225ztzt3PpxiTRgdGaoAAAEFQBAX075sbS7C6dH +OJU0w8/ocQEIKjY2w0F71bAQTMBOnPIDABBUAAB9OeXHY36tCAD8ZoYKAEBQAQD05ZQfl3xSCwDu +maECABBUAACCCgBAUAEACCqgiRDczwtAUAFZMfXr3wEQVEBkTIkqAEEFFIgpUQUgqIACMSWqAAQV +UDCURBWAoAIKBJKoAhBUQIEwElUAggrEVBhjGQAIKtg2pkQVgKACMTX4MgEQVLBNTIkqAEEFYkpU +AQgqYKzQEVUAggqWdBxrrgsAQQVDRdWTECqxDAAEFSwZVTEhVGIZAAgqWCqqUkKoxDIAEFSwRFTl +hFCJZQAgqGCJqOq9DAAEFQCAoAIAEFQAAAgqAABBBQAwibdNAECqcPKLJo8fH1cNN7+U8up7jpOP +v6as//PvPr+/xPpTlsEazFABUDSmnsRTie/pvX74ZIYKgKz4+J55+fu7EMLPWZmU2auY9YsjejBD +BUDRmDk7pdZq/Vf/P2bZT7/2OI7/rU/ICSoAiHIVLS2uFyq5Dtc3kcspPwCairmQvHUghhBOT1U+ +eQx/fyfQBBUALBNrtcPmc/l/QYagAoDqYi9ib/2zPZ2l+hVw7Ms1VAAkKXXbgpIXkH9eIF7r8T15 +bEJLUAHA4wD6FQ5PPoVXc/0ll3/3db/+sCen/ABIio7PU3U5YfIdY0++78n6RzPqxfiUYYYKqh94 +rv/AzFGV8nelouLue3JC5e5XzTx57E777SUcsa+4zxeIo8HlOw/vOgBwLBlqA1drGDNUAACCCgBA +UAEATM2n/CpyQSIA7MEMFQCAoAIAEFQAAIIKAGBnLkovxI3XAGBfZqgAAAQVAEBfTvlBbXf3I3O6 +GGB6ZqgAAAQVAICgAgAQVAAAggoAAEEFACCoAAAEFQCAoAIAQFABAAgqAABBBQAgqAAAEFQAAIIK +AEBQAQAIKiBFCGMsAwBBBVPHVE4QlVgGAM29bQIoGFOf/30c7ZcBrV/zd6/Rq6/7fs1/fs3T5Z+9 +AckZO2dvaL6XeffGJ/XxpPxspdZ59ZzkbKve278BM1RQOqaeDvbSy4CW/g5WV6/RUhHRcuwYc2W2 +VY3tP/hzY4YKar5bfLIDeLIMM1WsOnaOI/9AeTZzETt2YmbTrtbfMmhH2PfFbq/Syxxk/2iGCmrF +1Kzrgplez78OpjUOsDu8qfkMyqsZyLvwSdleNZYpqGASLQe3GSpGHgNXB92r1+6or+sQvInptV+a +eF/nlB/kDv7aO14xxUpahErqOr7Hc+yF9y3Hbul13l27NPJ+aJBTgYIKRo4qMcXK46b2wTVlHb9m +3VpcXD/i85Kyb4v9lGCvZQoq2CiqxBQzvfY/ZzHOAqR2mOTG1JOwanXN1ghBunucR3INFYw4qMUU +K/sLsO9rlXKuXSoZU99jcfXxmPpp5LP7f5W+B9Ukz4GggtGiSkxBn5ja/UL0v3D5/nO1jyq1zWos +szGn/KDGTinnoliY9TV/FzZnr++U+z+dfcIw93qblPtNxVwUvcIF7N/7uZJRlbLMQS5KN0MFtQ4w +YgrWGberjs+Y21vExmqN/eDAz0M4jsifrtZ5alh5ZyWmAMbaJxfe75qhgl7veMUUwDIEFfSMKjEF +sAQXpUOrqJrk5nSwpLvT7yOMxxl+Ro9LUMFQUSWmoP348zN6XIIK7FgAWDWo/DZuAAAXpQMACCoA +gM7iT/m5BgQA4P+YoQIAEFQAAIIKAEBQAQAIKgAABBUAgKACABBUAAB7+hfHbDX87cMFJQAAAABJ +RU5ErkJggg== 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..0197bcc7842d 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.10</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 3bc8a61efe30..a9b15e34c5b2 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -1,20 +1,47 @@ <section id="FE_GET_SET_PROPERTY"> <title><constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant></title> -<para>This section describes the DVB version 5 extention of the DVB-API, also +<para>This section describes the DVB version 5 extension of the DVB-API, also called "S2API", as this API were added to provide support for DVB-S2. It was designed to be able to replace the old frontend API. Yet, the DISEQC and the capability ioctls weren't implemented yet via the new way.</para> <para>The typical usage for the <constant>FE_GET_PROPERTY/FE_SET_PROPERTY</constant> API is to replace the ioctl's were the <link linkend="dvb-frontend-parameters"> struct <constant>dvb_frontend_parameters</constant></link> were used.</para> +<section id="dtv-stats"> +<title>DTV stats type</title> +<programlisting> +struct dtv_stats { + __u8 scale; /* enum fecap_scale_params type */ + union { + __u64 uvalue; /* for counters and relative scales */ + __s64 svalue; /* for 1/1000 dB measures */ + }; +} __packed; +</programlisting> +</section> +<section id="dtv-fe-stats"> +<title>DTV stats type</title> +<programlisting> +#define MAX_DTV_STATS 4 + +struct dtv_fe_stats { + __u8 len; + struct dtv_stats stat[MAX_DTV_STATS]; +} __packed; +</programlisting> +</section> + <section id="dtv-property"> <title>DTV property type</title> <programlisting> /* Reserved fields should be set to 0 */ + struct dtv_property { __u32 cmd; + __u32 reserved[3]; union { __u32 data; + struct dtv_fe_stats st; struct { __u8 data[32]; __u32 len; @@ -163,14 +190,16 @@ get/set up to 64 properties. The actual meaning of each property is described on <section id="DTV-FREQUENCY"> <title><constant>DTV_FREQUENCY</constant></title> - <para>Central frequency of the channel, in HZ.</para> + <para>Central frequency of the channel.</para> <para>Notes:</para> - <para>1)For ISDB-T, the channels are usually transmitted with an offset of 143kHz. + <para>1)For satellital delivery systems, it is measured in kHz. + For the other ones, it is measured in Hz.</para> + <para>2)For ISDB-T, the channels are usually transmitted with an offset of 143kHz. E.g. a valid frequncy could be 474143 kHz. The stepping is bound to the bandwidth of the channel which is 6MHz.</para> - <para>2)As in ISDB-Tsb the channel consists of only one or three segments the + <para>3)As in ISDB-Tsb the channel consists of only one or three segments the frequency step is 429kHz, 3*429 respectively. As for ISDB-T the central frequency of the channel is expected.</para> </section> @@ -192,6 +221,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> @@ -263,6 +293,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., @@ -334,9 +365,10 @@ typedef enum fe_rolloff { <title>fe_delivery_system type</title> <para>Possible values: </para> <programlisting> + typedef enum fe_delivery_system { SYS_UNDEFINED, - SYS_DVBC_ANNEX_AC, + SYS_DVBC_ANNEX_A, SYS_DVBC_ANNEX_B, SYS_DVBT, SYS_DSS, @@ -348,11 +380,12 @@ typedef enum fe_delivery_system { SYS_ISDBC, SYS_ATSC, SYS_ATSCMH, - SYS_DMBTH, + SYS_DTMB, SYS_CMMB, SYS_DAB, SYS_DVBT2, SYS_TURBO, + SYS_DVBC_ANNEX_C, } fe_delivery_system_t; </programlisting> </section> @@ -434,7 +467,7 @@ typedef enum fe_delivery_system { <title><constant>DTV-ISDBT-LAYER*</constant> parameters</title> <para>ISDB-T channels can be coded hierarchically. As opposed to DVB-T in ISDB-T hierarchical layers can be decoded simultaneously. For that - reason a ISDB-T demodulator has 3 viterbi and 3 reed-solomon-decoders.</para> + reason a ISDB-T demodulator has 3 Viterbi and 3 Reed-Solomon decoders.</para> <para>ISDB-T has 3 hierarchical layers which each can use a part of the available segments. The total number of segments over all layers has to 13 in ISDB-T.</para> @@ -527,6 +560,149 @@ typedef enum fe_delivery_system { here are referring to what can be found in the TMCC-structure - independent of the mode.</para> </section> + <section id="DTV-ATSCMH-FIC-VER"> + <title><constant>DTV_ATSCMH_FIC_VER</constant></title> + <para>Version number of the FIC (Fast Information Channel) signaling data.</para> + <para>FIC is used for relaying information to allow rapid service acquisition by the receiver.</para> + <para>Possible values: 0, 1, 2, 3, ..., 30, 31</para> + </section> + <section id="DTV-ATSCMH-PARADE-ID"> + <title><constant>DTV_ATSCMH_PARADE_ID</constant></title> + <para>Parade identification number</para> + <para>A parade is a collection of up to eight MH groups, conveying one or two ensembles.</para> + <para>Possible values: 0, 1, 2, 3, ..., 126, 127</para> + </section> + <section id="DTV-ATSCMH-NOG"> + <title><constant>DTV_ATSCMH_NOG</constant></title> + <para>Number of MH groups per MH subframe for a designated parade.</para> + <para>Possible values: 1, 2, 3, 4, 5, 6, 7, 8</para> + </section> + <section id="DTV-ATSCMH-TNOG"> + <title><constant>DTV_ATSCMH_TNOG</constant></title> + <para>Total number of MH groups including all MH groups belonging to all MH parades in one MH subframe.</para> + <para>Possible values: 0, 1, 2, 3, ..., 30, 31</para> + </section> + <section id="DTV-ATSCMH-SGN"> + <title><constant>DTV_ATSCMH_SGN</constant></title> + <para>Start group number.</para> + <para>Possible values: 0, 1, 2, 3, ..., 14, 15</para> + </section> + <section id="DTV-ATSCMH-PRC"> + <title><constant>DTV_ATSCMH_PRC</constant></title> + <para>Parade repetition cycle.</para> + <para>Possible values: 1, 2, 3, 4, 5, 6, 7, 8</para> + </section> + <section id="DTV-ATSCMH-RS-FRAME-MODE"> + <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, + ATSCMH_RSCODE_223_187 = 1, + 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> + <para>RS code mode (secondary).</para> + <para>Possible values are:</para> +<programlisting> +typedef enum atscmh_rs_code_mode { + ATSCMH_RSCODE_211_187 = 0, + ATSCMH_RSCODE_223_187 = 1, + ATSCMH_RSCODE_235_187 = 2, +} atscmh_rs_code_mode_t; +</programlisting> + </section> + <section id="DTV-ATSCMH-SCCC-BLOCK-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> + <para>Series Concatenated Convolutional Code Rate.</para> + <para>Possible values are:</para> +<programlisting> +typedef enum atscmh_sccc_code_mode { + ATSCMH_SCCC_CODE_HLF = 0, + ATSCMH_SCCC_CODE_QTR = 1, +} atscmh_sccc_code_mode_t; +</programlisting> + </section> + <section id="DTV-ATSCMH-SCCC-CODE-MODE-C"> + <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_C</constant></title> + <para>Series Concatenated Convolutional Code Rate.</para> + <para>Possible values are:</para> +<programlisting> +typedef enum atscmh_sccc_code_mode { + ATSCMH_SCCC_CODE_HLF = 0, + ATSCMH_SCCC_CODE_QTR = 1, +} atscmh_sccc_code_mode_t; +</programlisting> + </section> + <section id="DTV-ATSCMH-SCCC-CODE-MODE-D"> + <title><constant>DTV_ATSCMH_SCCC_CODE_MODE_D</constant></title> + <para>Series Concatenated Convolutional Code Rate.</para> + <para>Possible values are:</para> +<programlisting> +typedef enum atscmh_sccc_code_mode { + ATSCMH_SCCC_CODE_HLF = 0, + ATSCMH_SCCC_CODE_QTR = 1, +} atscmh_sccc_code_mode_t; +</programlisting> + </section> </section> <section id="DTV-API-VERSION"> <title><constant>DTV_API_VERSION</constant></title> @@ -588,6 +764,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> @@ -596,6 +775,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> @@ -612,6 +792,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> @@ -623,6 +805,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> @@ -637,17 +820,202 @@ 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-LEGACY"> + <title><constant>DTV_DVBT2_PLP_ID_LEGACY</constant></title> + <para>Obsolete, replaced with DTV_STREAM_ID.</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-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 + any other operation with the frontend. Prior to it's introduction, + FE_GET_INFO was used to determine a frontend type. A frontend which + provides more than a single delivery system, FE_GET_INFO doesn't help much. + Applications which intends to use a multistandard frontend must enumerate + the delivery systems associated with it, rather than trying to use + 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-stat-properties"> + <title>Frontend statistics indicators</title> + <para>The values are returned via <constant>dtv_property.stat</constant>. + If the property is supported, <constant>dtv_property.stat.len</constant> is bigger than zero.</para> + <para>For most delivery systems, <constant>dtv_property.stat.len</constant> + will be 1 if the stats is supported, and the properties will + return a single value for each parameter.</para> + <para>It should be noticed, however, that new OFDM delivery systems + like ISDB can use different modulation types for each group of + carriers. On such standards, up to 3 groups of statistics can be + provided, and <constant>dtv_property.stat.len</constant> is updated + to reflect the "global" metrics, plus one metric per each carrier + group (called "layer" on ISDB).</para> + <para>So, in order to be consistent with other delivery systems, the first + value at <link linkend="dtv-stats"><constant>dtv_property.stat.dtv_stats</constant></link> + array refers to the global metric. The other elements of the array + represent each layer, starting from layer A(index 1), + layer B (index 2) and so on.</para> + <para>The number of filled elements are stored at <constant>dtv_property.stat.len</constant>.</para> + <para>Each element of the <constant>dtv_property.stat.dtv_stats</constant> array consists on two elements:</para> + <itemizedlist mark='opencircle'> + <listitem><para><constant>svalue</constant> or <constant>uvalue</constant>, where + <constant>svalue</constant> is for signed values of the measure (dB measures) + and <constant>uvalue</constant> is for unsigned values (counters, relative scale)</para></listitem> + <listitem><para><constant>scale</constant> - Scale for the value. It can be:</para> + <itemizedlist mark='bullet' id="fecap-scale-params"> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - The parameter is supported by the frontend, but it was not possible to collect it (could be a transitory or permanent condition)</para></listitem> + <listitem><para><constant>FE_SCALE_DECIBEL</constant> - parameter is a signed value, measured in 1/1000 dB</para></listitem> + <listitem><para><constant>FE_SCALE_RELATIVE</constant> - parameter is a unsigned value, where 0 means 0% and 65535 means 100%.</para></listitem> + <listitem><para><constant>FE_SCALE_COUNTER</constant> - parameter is a unsigned value that counts the occurrence of an event, like bit error, block error, or lapsed time.</para></listitem> + </itemizedlist> + </listitem> + </itemizedlist> + <section id="DTV-STAT-SIGNAL-STRENGTH"> + <title><constant>DTV_STAT_SIGNAL_STRENGTH</constant></title> + <para>Indicates the signal strength level at the analog part of the tuner or of the demod.</para> + <para>Possible scales for this metric are:</para> + <itemizedlist mark='bullet'> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> + <listitem><para><constant>FE_SCALE_DECIBEL</constant> - signal strength is in 0.0001 dBm units, power measured in miliwatts. This value is generally negative.</para></listitem> + <listitem><para><constant>FE_SCALE_RELATIVE</constant> - The frontend provides a 0% to 100% measurement for power (actually, 0 to 65535).</para></listitem> + </itemizedlist> + </section> + <section id="DTV-STAT-CNR"> + <title><constant>DTV_STAT_CNR</constant></title> + <para>Indicates the Signal to Noise ratio for the main carrier.</para> + <para>Possible scales for this metric are:</para> + <itemizedlist mark='bullet'> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> + <listitem><para><constant>FE_SCALE_DECIBEL</constant> - Signal/Noise ratio is in 0.0001 dB units.</para></listitem> + <listitem><para><constant>FE_SCALE_RELATIVE</constant> - The frontend provides a 0% to 100% measurement for Signal/Noise (actually, 0 to 65535).</para></listitem> + </itemizedlist> + </section> + <section id="DTV-STAT-PRE-ERROR-BIT-COUNT"> + <title><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></title> + <para>Measures the number of bit errors before the forward error correction (FEC) on the inner coding block (before Viterbi, LDPC or other inner code).</para> + <para>This measure is taken during the same interval as <constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant>.</para> + <para>In order to get the BER (Bit Error Rate) measurement, it should be divided by + <link linkend="DTV-STAT-PRE-TOTAL-BIT-COUNT"><constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant></link>.</para> + <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. + The frontend may reset it when a channel/transponder is tuned.</para> + <para>Possible scales for this metric are:</para> + <itemizedlist mark='bullet'> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> + <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error bits counted before the inner coding.</para></listitem> + </itemizedlist> + </section> + <section id="DTV-STAT-PRE-TOTAL-BIT-COUNT"> + <title><constant>DTV_STAT_PRE_TOTAL_BIT_COUNT</constant></title> + <para>Measures the amount of bits received before the inner code block, during the same period as + <link linkend="DTV-STAT-PRE-ERROR-BIT-COUNT"><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></link> measurement was taken.</para> + <para>It should be noticed that this measurement can be smaller than the total amount of bits on the transport stream, + as the frontend may need to manually restart the measurement, losing some data between each measurement interval.</para> + <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. + The frontend may reset it when a channel/transponder is tuned.</para> + <para>Possible scales for this metric are:</para> + <itemizedlist mark='bullet'> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> + <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of bits counted while measuring + <link linkend="DTV-STAT-PRE-ERROR-BIT-COUNT"><constant>DTV_STAT_PRE_ERROR_BIT_COUNT</constant></link>.</para></listitem> + </itemizedlist> + </section> + <section id="DTV-STAT-POST-ERROR-BIT-COUNT"> + <title><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></title> + <para>Measures the number of bit errors after the forward error correction (FEC) done by inner code block (after Viterbi, LDPC or other inner code).</para> + <para>This measure is taken during the same interval as <constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant>.</para> + <para>In order to get the BER (Bit Error Rate) measurement, it should be divided by + <link linkend="DTV-STAT-POST-TOTAL-BIT-COUNT"><constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant></link>.</para> + <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. + The frontend may reset it when a channel/transponder is tuned.</para> + <para>Possible scales for this metric are:</para> + <itemizedlist mark='bullet'> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> + <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error bits counted after the inner coding.</para></listitem> + </itemizedlist> + </section> + <section id="DTV-STAT-POST-TOTAL-BIT-COUNT"> + <title><constant>DTV_STAT_POST_TOTAL_BIT_COUNT</constant></title> + <para>Measures the amount of bits received after the inner coding, during the same period as + <link linkend="DTV-STAT-POST-ERROR-BIT-COUNT"><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></link> measurement was taken.</para> + <para>It should be noticed that this measurement can be smaller than the total amount of bits on the transport stream, + as the frontend may need to manually restart the measurement, losing some data between each measurement interval.</para> + <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. + The frontend may reset it when a channel/transponder is tuned.</para> + <para>Possible scales for this metric are:</para> + <itemizedlist mark='bullet'> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> + <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of bits counted while measuring + <link linkend="DTV-STAT-POST-ERROR-BIT-COUNT"><constant>DTV_STAT_POST_ERROR_BIT_COUNT</constant></link>.</para></listitem> + </itemizedlist> + </section> + <section id="DTV-STAT-ERROR-BLOCK-COUNT"> + <title><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></title> + <para>Measures the number of block errors after the outer forward error correction coding (after Reed-Solomon or other outer code).</para> + <para>This measurement is monotonically increased, as the frontend gets more bit count measurements. + The frontend may reset it when a channel/transponder is tuned.</para> + <para>Possible scales for this metric are:</para> + <itemizedlist mark='bullet'> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> + <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of error blocks counted after the outer coding.</para></listitem> + </itemizedlist> + </section> + <section id="DTV-STAT-TOTAL-BLOCK-COUNT"> + <title><constant>DTV-STAT_TOTAL_BLOCK_COUNT</constant></title> + <para>Measures the total number of blocks received during the same period as + <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link> measurement was taken.</para> + <para>It can be used to calculate the PER indicator, by dividing + <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link> + by <link linkend="DTV-STAT-TOTAL-BLOCK-COUNT"><constant>DTV-STAT-TOTAL-BLOCK-COUNT</constant></link>.</para> + <para>Possible scales for this metric are:</para> + <itemizedlist mark='bullet'> + <listitem><para><constant>FE_SCALE_NOT_AVAILABLE</constant> - it failed to measure it, or the measurement was not complete yet.</para></listitem> + <listitem><para><constant>FE_SCALE_COUNTER</constant> - Number of blocks counted while measuring + <link linkend="DTV-STAT-ERROR-BLOCK-COUNT"><constant>DTV_STAT_ERROR_BLOCK_COUNT</constant></link>.</para></listitem> + </itemizedlist> + </section> + </section> + <section id="frontend-property-terrestrial-systems"> <title>Properties used on terrestrial delivery systems</title> <section id="dvbt-params"> @@ -667,7 +1035,9 @@ 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> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> </section> <section id="dvbt2-params"> <title>DVB-T2 delivery system</title> @@ -689,8 +1059,10 @@ 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> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> </section> <section id="isdbt"> <title>ISDB-T delivery system</title> @@ -721,14 +1093,10 @@ typedef enum fe_hierarchy { <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-CODE-RATE-HP"><constant>DTV_CODE_RATE_HP</constant></link></para></listitem> - <listitem><para><link linkend="DTV-CODE-RATE-LP"><constant>DTV_CODE_RATE_LP</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-HIERARCHY"><constant>DTV_HIERARCHY</constant></link></para></listitem> <listitem><para><link linkend="DTV-ISDBT-LAYER-ENABLED"><constant>DTV_ISDBT_LAYER_ENABLED</constant></link></para></listitem> <listitem><para><link linkend="DTV-ISDBT-PARTIAL-RECEPTION"><constant>DTV_ISDBT_PARTIAL_RECEPTION</constant></link></para></listitem> <listitem><para><link linkend="DTV-ISDBT-SOUND-BROADCASTING"><constant>DTV_ISDBT_SOUND_BROADCASTING</constant></link></para></listitem> @@ -748,6 +1116,7 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-ISDBT-LAYER-SEGMENT-COUNT"><constant>DTV_ISDBT_LAYERC_SEGMENT_COUNT</constant></link></para></listitem> <listitem><para><link linkend="DTV-ISDBT-LAYER-TIME-INTERLEAVING"><constant>DTV_ISDBT_LAYERC_TIME_INTERLEAVING</constant></link></para></listitem> </itemizedlist> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> </section> <section id="atsc-params"> <title>ATSC delivery system</title> @@ -761,13 +1130,63 @@ typedef enum fe_hierarchy { <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> </itemizedlist> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> + </section> + <section id="atscmh-params"> + <title>ATSC-MH delivery system</title> + <para>The following parameters are valid for ATSC-MH:</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-BANDWIDTH-HZ"><constant>DTV_BANDWIDTH_HZ</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-FIC-VER"><constant>DTV_ATSCMH_FIC_VER</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-PARADE-ID"><constant>DTV_ATSCMH_PARADE_ID</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-NOG"><constant>DTV_ATSCMH_NOG</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-TNOG"><constant>DTV_ATSCMH_TNOG</constant></link></para></listitem> + <listitem><para><link linkend="DTV-ATSCMH-SGN"><constant>DTV_ATSCMH_SGN</constant></link></para></listitem> + <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-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> + </itemizedlist> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> + </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> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> </section> </section> <section id="frontend-property-cable-systems"> <title>Properties used on cable delivery systems</title> <section id="dvbc-params"> <title>DVB-C delivery system</title> - <para>The DVB-C Annex-A/C is the widely used cable standard. Transmission uses QAM modulation.</para> + <para>The DVB-C Annex-A is the widely used cable standard. Transmission uses QAM modulation.</para> + <para>The DVB-C Annex-C is optimized for 6MHz, and is used in Japan. It supports a subset of the Annex A modulation types, and a roll-off of 0.13, instead of 0.15</para> <para>The following parameters are valid for DVB-C Annex A/C:</para> <itemizedlist mark='opencircle'> <listitem><para><link linkend="DTV-API-VERSION"><constant>DTV_API_VERSION</constant></link></para></listitem> @@ -779,7 +1198,9 @@ 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> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> </section> <section id="dvbc-annex-b-params"> <title>DVB-C Annex B delivery system</title> @@ -793,7 +1214,9 @@ 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> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> </section> </section> <section id="frontend-property-satellital-systems"> @@ -813,6 +1236,7 @@ typedef enum fe_hierarchy { <listitem><para><link linkend="DTV-VOLTAGE"><constant>DTV_VOLTAGE</constant></link></para></listitem> <listitem><para><link linkend="DTV-TONE"><constant>DTV_TONE</constant></link></para></listitem> </itemizedlist> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> <para>Future implementations might add those two missing parameters:</para> <itemizedlist mark='opencircle'> <listitem><para><link linkend="DTV-DISEQC-MASTER"><constant>DTV_DISEQC_MASTER</constant></link></para></listitem> @@ -826,7 +1250,9 @@ 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> + <para>In addition, the <link linkend="frontend-stat-properties">DTV QoS statistics</link> are also valid.</para> </section> <section id="turbo-params"> <title>Turbo code delivery system</title> @@ -848,7 +1274,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 61407eaba020..0d6e81bd9ed2 100644 --- a/Documentation/DocBook/media/dvb/frontend.xml +++ b/Documentation/DocBook/media/dvb/frontend.xml @@ -45,8 +45,8 @@ transmission. The fontend types are given by fe_type_t type, defined as:</para> </row> <row> <entry id="FE_QAM"><constant>FE_QAM</constant></entry> - <entry>For DVB-C annex A/C standard</entry> - <entry><constant>SYS_DVBC_ANNEX_AC</constant></entry> + <entry>For DVB-C annex A standard</entry> + <entry><constant>SYS_DVBC_ANNEX_A</constant></entry> </row> <row> <entry id="FE_OFDM"><constant>FE_OFDM</constant></entry> @@ -63,6 +63,10 @@ transmission. The fontend types are given by fe_type_t type, defined as:</para> <para>Newer formats like DVB-S2, ISDB-T, ISDB-S and DVB-T2 are not described at the above, as they're supported via the new <link linkend="FE_GET_SET_PROPERTY">FE_GET_PROPERTY/FE_GET_SET_PROPERTY</link> ioctl's, using the <link linkend="DTV-DELIVERY-SYSTEM">DTV_DELIVERY_SYSTEM</link> parameter. </para> + +<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> </section> <section id="fe-caps-t"> @@ -97,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, @@ -203,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 inner coding (Viterbi, LDPC or other inner code) is stable</entry> +</row><row> +<entry align="char">FE_HAS_SYNC</entry> +<entry align="char">Synchronization 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> @@ -234,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 ⋆/ @@ -247,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> @@ -317,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 { @@ -343,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> @@ -366,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> @@ -423,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/selection.png.b64 b/Documentation/DocBook/media/selection.png.b64 new file mode 100644 index 000000000000..416186558cb2 --- /dev/null +++ b/Documentation/DocBook/media/selection.png.b64 @@ -0,0 +1,206 @@ +iVBORw0KGgoAAAANSUhEUgAABIsAAAHpCAYAAAACi7yYAAAAAXNSR0IArs4c6QAAAAZiS0dEAP8A +/wD/oL2nkwAAAAlwSFlzAAAOxAAADsQBlSsOGwAAAAd0SU1FB9sLCBAiCLMGMtAAACAASURBVHja +7d3rkds4FgZQaMohTBY7ObRCV+fgyWJy4P6wJavVIgmSAIjHOVWu3bElPkBSAj5dgpdpmqYAAAAA +ACGEvzQBAAAAAHfCIgAAAAAehEUAAAAAPAiLAAAAAHgQFgEAAADwICwCAAAA4EFYBAAAAMDDD00A +21wul9XXTNN0aHnP749Z39o2rK0jRzssLX/pvVve9+61S69Jdey2bn/sMTx6TAAA/cIW+oVb+2tb +3p+izwioLIJsHYe9X+a979vae89ut6Pb1+txBwD0C3vZN0ERrFNZBAct/ZJxuVx2Vdg8v+/oLyEx +69j7xbq2/1u2e0u75Th2Mevf8ytVzDkDAOgXjtYv3LquVP0nQRHEUVkEBTsJve/r0hfu2hdz7e0W +27HQ4QAA9Avr7BcJiiCesAhO+GKK/YIt8SV+RscoNmippUPl1jIAQL/w3PUc7Y8JimAbYRGc9KVY +Yu6b3OsYNUTRuQAA9AvL9AtT9LsERbCdOYsAX74ZOiVbO1M6LQCAfmH7/TzohcoiqOhLK+eXV4p1 +xP4y1krF0X1bn7dXBwIA0C+ss19oagAoR1gEJ4j9osv5iPq965imKUk59eidwNc/AIB+oX7h/HpK +tzeMzm1oQJIv7Ra/eO/7sOWxtgAAtN0v1N+DdcIiyPQFlPP1JbZpTyehl19q1joQOhgAgH7hOf3C +Pct9tz36c7DMbWhQwPMXUYkOQ6517P3Sj/216axJEdfWoyMBAOgXpukX5uqv7Xm/W9JgnsoiSGxr +4FHiiyvlOu7v21pu/PqLzuuvOTHtlmIZW/bz+f1r6177ewBAv1C/8FwqjCCesAgSdwK2dAh63e+5 +fX8XuBxtt1SdkZhy6djt37vNOioAoF84Sr8wV39tzzIERvCd29Agg7knQ8T+unTk15mc64j5El17 +KsbRW75inrqR6glj79rELWsAgH5hmn7hmcckpt8HI7tMRjYAAAAA/KayCAAAAIAHYREAAAAAD8Ii +AAAAAB6ERQAAAAA8CIsAAAAAeBAWAQAAAPAgLAIAAADgQVgEAAAAwIOwCAAAAIAHYREAAAAADz80 +AQAAqVwuF40AABWbpmn1NbvDIh0BAKDGzg3n0T8EgD7sCot0BAAAmDNNUwj6iwBQlS3fzIduQ7vd +blobAMjuer1qhKZ6o4IiAGiZOYsAAMji0w+LAHC6jx0/unkaGgAAAAAPwiIAAAAAHoRFAAAAADwI +iwAAAAB4EBYBAAAA8OBpaAAAFDf3ZJa5J6htef3za5eeyDb3urWnxsQuM/V7jmxX7Dr3HIMUbfj6 ++qXjurZ977Zja1vuaVOAnqgsAgCgqKWB+rt/2/r6s7Z/z3aesf0x+1fjdgFQjsoiALpyfRng3J5+ +Fb7/2+3NL8Xv/m1pWa/veX7t/XXXN4OtuWXs+fe59c/t45H2erd/Mdu/9XX0b63q5zWkWHr9/d8+ +rtfFapOY9byz9L7X5e7ZzqVKmT2VP3ts2cc966+1MmfuGKkkAvhFZREA3XgON94FNnMhzlJQNLes +1/ffX/f62ue/fw1d3r3m9d/nlhu7/rX22rv8LW20d/voT8ztYbEBzNJrS4YMubbzzNCidLs+BzX3 +datsAjiXsAiALrwLfPYGE1uXtaVK5l2YNLes2OXurdI5svwtbaSKiFdbg5Cl18f821y1UupAZu92 +1njblwobgLG5DQ0AZqSofjkSnOSuvsmxf2fsB5SUMtT5vN2+LC82xNoziXaJNthyO11MBdHS7YUA +5CUsAmAo91u97rdGLc1jdKQi5t08QiH8uSVrTcwcSkekWv7avuTeD1hzD2TuwcOWqqIS8wa9C01G +nD/neV9fQzQAyhMWAUAma5NVA23KEeLMhUZHJ5g+e/9jXyscAqiLOYsA6MK7+XLW5gWK/fdnsYHP +2uvWJtveu969ti5/bxsJzNgTDOx5JP2z1yAmNsC4T7j8+ifXdj6vs7VjlGsdQiSAc6gsAqAbz7eY +Pf9dqmVtWd7cbWivE0LPbe/rv80tL1Vb7Vl+TBvl3g/a8nx70dIj7e9/v/b6mKer1bBfc9tZ65w8 +pdt1bh1zQdFaGwNw3GWapmnzmy6XQx1wAIAt7gHTjm4LJTuWv/uI084QYC482Pv6LfMSvXtc/Nag +pNR+xb7+yLYeXX9MG669ZunYpN7mEeeJAsZx/4y7/P7vmP6U29AAAChq6yPm9z6S3n7t34/c648J +Z97N49TKuQDQOpVFAED1VBY10rGMrCwCAMpRWQQAAADAIcIiAAAAAB48DQ0AADqSciJsAMYkLAIA +gI4IgwA4SlgEAADAZh9/X9/+/ed/t8Ovf37t3PKWXje3rq3LTP2eI9sVs961969t59r2LbX16zJi +t+Xzv1vyduE4YVHpD9SZsuDnX4COlA7HLD/Ferase2lZW7Zh6/a+vn6pDda27912rK0vVbsCAEB1 +45qFwf3H39dNIcm715fY/rWQKsV7Wj5me93Dn6VlxgZKnEdYVPLiXAgTPq7X6BBh7rWpln/kPWv7 +LigBAIDGxzUrVT+vocTS6+//thYs7A1plt73utw927kUeixt3xnhWEybzO13qe0VHtVDWFTq4nwK +cmKDni2B0NLy7/82F/4srWdPYLRneVvWUWvgNNfuAjIAALoZ10TcHhYbwNz/LiYwStpvf3PbU47t +zL0v727/WqvqijlmEEIIf2mCAh+oK0HR0UBhbflbbuVKsT1ry4vdhhRt/nm7PdZdYr0AADCCreHC +0utj/m0u3EkdcuzdzntQ09MxS7Gud23iFrQ2qCwqeXFmrjBZWv7n7XZ6WFLDNgAAAGNLGeq8Vilt +ndz53fKO7sMZc0DlPjaCpfKERTVfKBsmqy617hr2de21qeduAgAAzvM6YfKWypQS8wa9q6IpVT3z +vPyYp4pBLGERu55i1sSXytO2q2oCAAAe44MMIc5caDQ3B1KSsVzF4dC7p6KthWgqiOohLKr5A2zj +RNW511/LurY8NQ4AAEhv661OMY9RXxwDPAUP9/+OGjtsDB+ObufzOnMFOTHLnZvoWhhDLBNcl/xA +PRherIUka7dfLS333Z/a9j/VOoRIAACwc0wy86SzL/3tmadvLU12/Pra2vZryz6V3OZ3f44eMwhB +ZVGZi/jpFqi5qqAj1UJry495Gltupbdhbh1zQdFauwEAAL/72i+PkU/x+hoeRb93O/fMi1R6Iuet +xyz1emNDQRNc10NYVOoieQl0jnoNN2KWXyoo2jMH0lnbfKTdzm5nAAA4bXyzMJnyXHVLC0FA7fsV +cxveu7mCWjoG1EFYVPKDZ2GS5diAYW0ZtQYYJZ/gtrSuexs9h201txsAAFQ7vtkYMGx5/dHXHgk/ +atmvI+9PNYF0ioqvGqrG2O4yTdO0+U2XSwghhJuBNABQwPV3qL+j20LJjuXvPuL9KPnRBWCbtVvE +hCrsOq9+96Muv/87pj+lsggAAKDFAeBLsCBIaJ9jSC2ERQAAAB0QHgGpCIuI++JZmZRbmTkAAFTW +h98QHn1cPzQYFPR5+6x6+4RFRJ7IN40AAAA19dGfwp+Yx6HHPr4cQFgEAADQuNfwZy08inkEOzAu +YREAAECjYiqKdvl50bg04Ujg+Xr7Ze5bw1q63VNYlPzgXzUCAP13zNyeDJB/bJErCAKKB0WtERYB +AACcNWA9IRBy6xnDX3eColXCoowUbgLQk0kTAMQPRguFQItPOHuzDXuCoss/jieV9Ul+Hrg2TwqK +WnvioLAIAABgy6CvgiBoz/apKGL4a1dQFE1YBAAA8DywK3hrWOoAJ1U1EXR3XQuKNhEWAQAAYwwW +Gw6B9u6foAgERXsIiwAAgLYHgoUnia4tgBESwcL1UUlQ9Hn7bCo8EhYBAAB1DvJOenR860GLoAh+ +f4ZUFBS1RlgEAACUH8R5ZLx9hJyfMYKiQ4RFAABAuoGSEMj+w9mfQ4Kiw4RFAADA+iBICAS08Fkl +KEpCWAQAACMPrMwLBPTyeSYoSkZYBAAAPQ6ahEDASJ95gqKkhEUAANDaoMgtYQB/PhMFRckJiwAA +oJYBjxAIYNvnpqAoC2ERAADkHlQIgQDyf+4JipIRFgEAwN4Bg3mBAKogKEpLWAQAAK+DASEQQDME +RekJiwAAGIpbwgD6ISjKQ1gEAEAXhEAAZPl+GSwoCkFYBABA7Z10IRAAZ30HDRgUhSAsAgDgrA64 +eYEAqPl7atCgKARhEQAAR/17CSGEMP186WSHa9HNEAIB70zTNMy+Xi4XBzyRkYOiEIRFAAAs+ff8 +gYcQCICSRg+KQhAWAQCMSQgE0J25KioVR/EERb8IiwAAenJGCPS/6ctgZHp0sG+OB0AFXkMk4dF7 +gqI/hEUAAC04qxLof5O2B6B7gqKvhEUAAGcSAgFQ2HOlkSojQdE7wiIAgFxOvCUMAFgnKHpPWAQA +sJUQCIBOjFxlJCiaJywCALgTAgHAEARFy4RFAED/zAsEAKvuVUa9VxgJitYJi6DmD+uf7//+8s/6 +a969ds/yU6xn636uLWttu9e2dakdX5cRuy2Xf/K2ETBDCAQAbHBWUPS63toJi6BSS8HD9DM+eJh7 +barlH3nPme2y5h7+LC0zNlACdnaq/r5+v/Zzh0NCIADotsJIUBRPWAQ1fjg/BSKxQc+WQGhp+fd/ +mwtJltaTOzCKbZe5fSoV6giPYKXD9BQCFSMEAoCx+x+Cok2ERVCZtUBk6e9TLP/5dqrY8CfmFqy1 +7Xm+/evdenO3C5CgMyQEAoC+xibT1EV1kaBoO2ERVCp38LG0/CPhT+vt8q4dlsIrARVDdBTffB58 +hGv29X7+d3v8/+v1+ui0AgDEqiUo+rx9NhUeCYug48FcCOfPI7T3faXmQOrtWECJa/eo5xAIAKi8 +v9Dw/EU1BUWtERYByQaXe8OQ5/fVXNUEvVyruQiBAIBaCIqOERZBJ7ZOVJ17/bUParfs1+utaGu3 +oKkgIqczrpfHuf+l43NzMABgpD5IQ/MXCYqOExZBxQPCI6HDWoVOzCPhlwaNJQa8c3MFCWPo9Zov +zbUEAPRGUJSGsAgqE/M0siOBydryY546VmKw+jpwzt0ukMtZlXOuBQAgeb+m8uoiQVE6wiKo0Gsw +kmKwOjcvUEuTMadul63rjQ3STHA9SGdJCAQAUA1BUVrCIqjU0m1ksYPFtWWcFWrEPHZ+7rH1Z243 +43BLGADATD+pwuoiQVF6wiKoWMzgce01a4HMGQPZLWFXim3J3Y4G+w11boRAAABdERTlISwCoHlC +IACAgn2v6dczUmurMBIUpSMsAqDejoh5gQAAiCAoSktYBBQf4BuIIwQCACAVQVF6wiLAgJyk3BIG +AEApgqI8hEUARBECAQDwpX9Y4ZPRchgtKApBWATgS14IBAAAb40YFIUgLALolnmBAADI3ufsuLpo +1KAoBGERQHtfyEIgAADIauSgKARhEUBV3BIGAEBzfdjOqotGD4pCEBYBlPkCFQIBAED1BEW/CIsA +DhACAQCMpbYKmmmaqtmO1quLBEV/CIsA3n3ZmRcIAACGISj6SlgEDEUIBABAT16reWqpNGqJoOg7 +YRHQDbeEAQAAWwiK3hMWAdUTAgEAQGQ/9qnSqHSVUWvzFgmK5gmLgNMIgQAAgDMIipYJi4DkzAsE +AADnu1f5mMfoK0HROmEREE0IBAAAtOysoOh1vbUTFgEhBLeEAQBAr0pWGNU8b5GgKJ6wCDonBAIA +AEYnKNpGWASNEgIBAACb+vODzmEkKNpOWASVMS8QAABAGrUERZ+3z6bCI2ERFCIEAgAAanC5XLJW +F9Uyb1FNQVFrhEWQ+oOxUCgkBAIAAHaPJzIHRmcTFB0jLILaPrSFQAAAALsJio4TFkEhQiAAAKCq +MUqH1UWCojSERZD6A1coBAAAUJygKJ2/nE4AAABASqUrlgRFaaksghQfhD+1Af1QHQcAQEsERemp +LAIAAIBB1fCI+yMERXkIiwAAAIDmCYrScRsaJOYWHlrkVkoAgIHHMB08FU1QlJbKIgAAAKBZgqL0 +hEUAAABAkwRFeQiLAAAAAGaMFhSFICwCAAAAeGvEoCgEYREAAADAN6MGRSEIiwAAAGB4l8sl+TJb +fsLayEFRCCH8cEkAQJkOTo5OGAAAaY0eFIUgLAJgcCV/8VpalyAJAOB8gqJfhEUADKPmUuh32yZA +AgAoR1D0h7CIrgduBlp9DqqdM4xyHj9vv3MTACAfQdFXwiKAmcH5K4P19o9hT/vlfAQASENQ9J2w +iO4HjQZUGKyPeXxG2V/nIQCQyuVyGa5PJSh6T1iEgR0kOIcN2H2OOA8BANoiKJonLAIwYG+6vfne +Ls5BAIBlgqJlf2kCeh/oGVRyxvntvNO22gkAoE6ConUqiwAyDthDUOWRsi1xDgIAHHFWUPS63tqp +LAIoMGAXdhxrP5yDAABHCYriCYsYYuBnkIQBu/ZCmwIA4xIUbSMsAjhhwI42Ort9tTEAMApB0XbC +IoYZABoY4Vpoo120jfMQACCVWoKi1ibRFhYBGKhrD+0OANAdQdF+wiKAkwfqBusCCwAA0hIUHSMs +YqjBoAEp1Pe54LoEACAlQdFxP5xGAOebpilcLpfh9rkVKY6NUAwAID9BURrCIoBKjBQY1Rqc5Gz/ +uWULkQAA0hAUpSMsYriB4YgVHLR1rfR+ftb0eVBDW79ug/AIAGA7QVFawiJgqIH5O7UNznsOjGpo +69rb9nn7BEcAAOsERekJixhuIN77YJxjg3OD9D4/C1q93gVHAADLBEV5CIsAKhyk9xZonhV09NSG +giMAgGWConSERQCRg3QD9PaOmXMSAGAMgqJkHc0Qpin85ZQip5oHMgZZ7BmglwwhejlHS+/HSLeY +lj4nAQBqJChK2nkPIQRhEW0NisAAvbXvmslxse8AgDFcNoKiPIRFGMhCxV9+LZ+jpYMitAMAQA6j +BUUhCItoZKB4HwAZCGFwPt71v9b+joE2AQDa6sO1ZMSgKARhEUCSwTnaXfsAAPRl1KAoBGERmbSU +SEvPcY62t72CkPh20lYAANuNHBSFICyikcGOQSKtnaejEhQ5PwEAWjd6UBSCsAjAgFwbD9N22g8A +YJmg6BdhEcnlmNi6pW0G134egg7tCACQk6DoD2ERBjuAa157AgAMTVD0lbCIpFqu0FFdRM2D8NrP +z5zbJ9jQrgBAe/25lvoagqLvhEU0O5Ax0IE+OxbU8zkLANA7QdF7wiIAqiXM0MYAALkIiuYJi0im +xYmtc+4DBt+ue+0IAECdBEXLhEUYlAMAAAxstB/NBUXrhEUAVNepEAQDAJDDWUHR63prJyyiukHj +1kFi6kGlW9HgXIIiAAD9uRwERfGERQAAAEDXBEXbCIs4rMdKHNVFcM41oqoIAMDYJzVB0XbCIqqy +d6BogAkAAMCrWoKi1ibRFhYBsImqIgAA/boW+nSCov2ERVTz4VLbQNGtaAAAAG0SFB0jLKIbqhLA +9QsAQJyefxwXFB0nLIJBP0BpSy1himsCAICaCYrSEBZRxaAx1UBYdQK9XRsAANBKf/Xs8ZigKB1h +EQCnEvICAHCUoCgtYRG79Dyxdc59Bdc9AABn9ud67NMJitITFtEdVQoAAABjEBTl8cOpBZBOjl9q +eg5AhbsAAG32UWvs1wmK0lFZxKkfNLk+UFIv1+03AAAA9RIUpaWyCCCRnkNFgSkAgD7cnLOrigRF +6akswoDRvlMxt2kBAMA8QVEeKovodhB8uVwEPBTjXKvvMwAAQL9Uny6F0YKiEFQWAVT7hSxMAQCA +c40YFIWgsoiTBsSlBsGpq4umaTKAJ9t1AQAALfVHex8bjRoUhaCyCKDKL+aavngFYgAAjGbkoCgE +lUUAmwlPjlOhBwDoC+rP1Wr0oCgElUWc8IFY+kMl9fp8OYx9HZQ4/oIUAAA4h6DoF5VFACtKBoSC +IgAAatdrn1VQ9IewiKID5V4+VEx07bz3pQsAAP0QFH0lLGIIqZ+KRl9qODcERQAAtDK26o2g6Dth +EVCMwG6cL1wAAGiBoOg9E1xTbHB/9oDYRNfUSFAEAEAr/dbe+q6ConnCIoATv3BrJxQFAKBHgqJl +bkMDKGz0aiLVVAAA+m5nEhStU1nErB6fguZWNM4+/wQlAABwnrOCotf11k5lEUBmAiIAAPRjzyco +iqeyiLd6rCrKtT2qi5g7z1QSAQBAHQRF26gsAjhIIAQAgL5tvQRF26ksAjhomqYvfwAAgDrUEhS1 +Nom2yiLeDnxTqTWVvlwuBvUUuYZUHQEAUKve+6qCov2ERQAZCY4AAGihr9pbf1VQdIzb0Fj8sDjC +wBi+X18q2gAAIC9B0XHCIoYlzOIsQiMAAGrup7bcVxUUpSEsAjjxyxgAAEhDUJSOsIgsA9dWqnZU +F1HDdSc0AgBAP/UYQVFawiKASr6MAQCA7QRF6QmLACohMAIAoMY+as39VEFRHj+c+qQepLZ2a9fl +ckm6/9M0ub2t4XPj7C9C5w8AAOwjKEpHWATw5F1QUzpAEhgBAFCbe5+41n6qoCgtt6ExdFVRru12 +O1FfLpfL40+L1yUAAPRMUJSesAhgg5LBkcAIAIDa1NZHFRTlISwC2KlEaCQwAgCAc40WFIUgLBqe +W9Dybb9B/jgERgAAjDaOHKWPOmJQFIKwCCCJ0nMaAQAAeY0aFIUgLCLhQBnIdy2oLgIAoDY991FH +DopCEBa5sMk60NfGzqPWz6cc++K6AACgZqMHRSEIiwCyUG0HAMAIevshUFD0i7DIBW1QnHl/VFHg +fAIAgPoJiv744XQAyONyuQh3AIDmTdOkavqlj1fzsXKO7CMo+kplEUBjnQkBFAAApCMo+k5YNCC3 +oJXfL4N7AACgxDjm+U+r48ySBEXvCYsACnxp+zIGAIC6CIrmCYsGo6rovP0zuAfXAwD47qb0mKZk +lVFL54mgaJkJrvGFAax2MlzvAAD0QlC0TmURQAGeIAIAwNn90RJVRrX/yHhWUPS63toJiwaiMsAx +wPkEAACjEhTFExYBcAphFwDAOXJXGNXYzxMUbSMsAgAAALolKNpOWDQIv+A7Fpyv5XmLzLkEAOjH +6p+2eL7UEhS1Nom2sAgAAADojqBoP2HRAPwC4JjgXLL9AAC8U+IJaWcQFB0jLAIAAAC6ISg6TlgE +QBTzFgEA6OttcUYVuaAoDWFR59zi4diAawEAgBEIitIRFgEAABDFjzx9a7m6SFCUlrAIgFM7EAAA +cISgKD1hUcek/o4RuBYAANiitR8HBUV5CIsAAACA5gmK0hEWdcqv9I4V5JLr1ybXAgDov+Kc2UtQ +lJawCAAAAGiWoCi9H04rYpjU9iu/puAz4ZLlOpimyecNAECnfb0cBEV5qCzqkCDDMcNxBgAA0hgt +KApBWEQEv/IDJQnVAACMA2sxYlAUgrDIIItqPjgdO1wHrgcAMO6AeowaFIUgLAJoml98AAAgvZGD +ohCERRiIahuK6PXXN9VFAAD01rcbPSgKQVjk4sMxBNeENgYAIIQgKLoTFjFL5Qzgs6JvgiIAfI/A +H4KiP4RFYJCMjpT2064AAEMTFH0lLNLpx7GkUTWFlbm3xXWhPQEAchEUfScsovpBKBiU+9wYrS21 +IwBAGYKi94RFOv5UOEB2TF2baNMcbaf9AICzxzo1ERTNExYB+OJuarsEHtoMAOAoQdEyYRHNDELB +4NxniPbVVgD4nsH5cpSgaJ2wyMWGY4tjp507bR9tBADw1VlB0et6aycsAkg8QM+theq/UtsoENEm +AACxBEXxhEU0NwgFA3SfJ+/aH+0AADBHULSNsMigAMeYho5Ta4Fu6cBo1GtGWAkAME9QtJ2wiGYH +oWCA7rNl7rg4BwEACKGeoKi1SbSFRQ0PEHCsOW9wfsZxEehuP072DwD0Vxm3Dyoo2u+HUx+g/g5Q +60HR5XI5pR3v6+whaNMRBwCIJyg6RlhENwMpMCCv/3PmrPZ9Xm9rn3fOSQCAbQRFxwmLDGZpYEA8 +TZPKiMHPKddHnvOwxrZ1nQAA7CcoSkNYBFCxHqv+agiM7l6344z2Fg4B0INeftyk7XNFUJSOsAgf +6uDaPGXfagxJ5rYpxbEQCgEA5CMoSktY1BiDjXEHwn6tGe8ccp347AUAYJ2gKL2/nFYGpIDr8sx9 +9TkEAMBegqI8hEUN8cu2Ab9zwHljv9H2AADvCYrSERYBGLTbf20OANA0QVFa5iwySABci1W1hQo6 +5xwAwBaCovRUFjXC4MmAzLngHBmpTbSLcw4AIIagKA+VRQAG7FW3kYDUOQcAcKbRgqIQVBY1IcdA +yaDBOcF5A3bXn88r5xwAQBtGDIpCUFkERQZqwh0M1tO0n2vJOQcAUMqoQVEIwiIAA/YG21No5JwD +AMhp5KAoBLehVc8taAZvJc8N0h1vt/6UaWO0CQB9j13gDKMHRSGoLAJINlDn3HYfsYPqvAMASEtQ +9IuwyMACcB11dVxGCI2cgwAA6QmK/hAWVUwZZ3+Du9THdJomg0aDcRaOXS+fo85HAIC8BEVfCYsM +DnBMnX8Mc821FB65BgFokR8zaZGg6DthEaT+gvypDaBW7zqvNQRIOtUAAOcQFL0nLAJgaEtBTcog +SSAEAFAXQdE8YREAzBDwAAD0SVC0TFgEKQaU//z637lb0O7/DgAAwLkEReuERVBAzDxGAiUAAIC8 +zgqKXtdbO2ERVGItUBImAQDQRL/WE9G6O569EBTFExZBQnOBToonpKlOAgAA2EdQtI2wCAqICXEE +SgAAAOkJirYTFkEl1kKcFGFS7HIESgAAHOpzuhWNStQSFH3ePpsKj4RF0IhS1UkxyxEmAQAAtasp +KGqNsAg64nY3AACg6jFLoYozQdExwiIY7cPZ7W4AAEDHBEXHCYuAL2q63S12ewAAgPSmaWpumwVF +aQiLgM3MnwQAANRGUJSOsAjIwvxJAABj80Q0ShIUpSUsAk5j/iQA8i3Z/QAADThJREFUAOAoQVF6 +wiKgWm53AwAAlgiK8hAWAU1zuxsAABCCoCglYRHQPYESAAD0TVCUlrAIIJg/CQAAWiUoSk9YBBDB +/EkAADv6NZ6IxnM/NsO5ICjKQ1gEkOrLz+1uAADQndGCohCERQBFCZQAAGjBNE0aIYwZFIUgLAKo +jvmTAADgfKMGRSEIiwCaY/4kAKAl5i1q85iNbuSgKARhEUCX3O4GAAD7jB4UhSAsAhiW290AACjW +92ykukxQ9IuwCID3X+gV3e4Wuz0AALCXoOgPYREAu5k/CQCgL6POVyQo+kpYBEBW5k8CAKBmgqLv +hEUAnM78SQDQN09Ea+c4jUZQ9J6wCIDqmT8JAIDUBEXzhEUAdMH8SQAAB/o3g1UVCYqWCYsAGIb5 +kwAAEBStExYBwBPzJwEAI1FR9HnKemsnLAKADdzuBgDQJkFRPGERACTmdjcAePO95YloVR6TIn2j +Co67oGgbYREAnECgBABQhqBoO2ERAFTK/EkAQA4jzVNUS1D0eftsKjwSFgFAo86cP+kjXL92gP67 +OSAAQFVqCopaIywCgI6VCpQ+/r6uvkagBIB5i85t+1P6Iicdb0HRMcIiABhcqdvdBEoAQAmCouOE +RQDAonuYNH3p/Ny+do4igqCoTtbMch6B1b+XEP43OSgAEOHsuYnOqCoSFKUhLAIADoupCEoVKIV/ +VzqewiQAGJKgKB1hEQBQRLFA6d+IXzEFSgB0aKSnnH3rQwiKkhIWAQDVmAuUrtfrr05wovmTBEoA +0A9BUXrCIgCgHTEBzr+J5kcQKAGEEH7NO5OyYqX1J6KNXL2z9bwpQVCUh7AIAOhLTYGSMAkAihEU +pSMsAgDGUypQUp0EwIDOqBwTFKUlLAIAeGctxHG7GwBUQVCUnrAIAGAPt7sBwDelq4oERXkIiwAA +cnG7G9BRAGCSa2LOkx6NFhSFICwCADiXQAkAqjViUBSCsAgAoH7mTwKgcj1WFY0aFIUgLAIAaF8l +8ydNP0O4/ONwANC+kYOiEIRFAABjKBQoTT+fOtrhGvWez/9ujg80wLxFLJ0bPRk9KApBWAQAwF2p +291eO+V/X1dfI1ACoARB0S/CIgAA4qyESZfL5UtlUdLOu0AJoEo9VRUJiv4QFgEAkG7Q8E8I06OT +fYvrnEcEQSmWI0wCYPY7RFD0hbAIAIBTxYQ4KQIl1UkA6ago6puwCACA6q2FOKWqk2K2BYB2CIre +ExYBANC8UtVJscsRKNErT0Tjfh70QFA0T1gEAMAQagqUhEkA5xIULRMWAQDAfbBg/iSAWSqKxiEs +AgCADcyfBNCus4Ki1/XWTlgEAAAJud0NtjFvUf1UFKVdbwuERQAAUJjb3QDKEhRtIywCAIAKCZSo +VeonolH3se6BoGg7YREAADTK/EkAK59flQRFn7fPpsIjYREAAHTK/EnAXj1UFdUUFLVGWAQAAANz +uxvQI0HRMcIiAABgkUCJV6nnLfJEtHqOaw8ERccJiwAAgMPMnwTUQFCUhrAIAADIzvxJUKeeKroE +RekIiwAAgCq43S3xAPZpPwVk9E5QlJawCAAAaEYNt7u1GLx8/H0VGNHtvFCCovSERQAAQDdKVCe1 +WpkkMKJHgqI8hEUAAMBQSlQn1TBv0ud/t2/bkTIw8kS0Oo3choKidIRFAAAAzwO/CsKkmO2I3Zec +gRFUc90KipISFgEAAGwZlJ44b9KekCdnYNRCFYtqpQGuSUFRcsIiAACAlAPXjPMm7b29TYUR3V5v +gqIshEUAAAClB7iZAqWt74kJjKafjhdjGy0oCkFYBAAAUKV3IU6qW9y+L3PS4PDu+hgwKApBWAQA +ANCMUvMlAeMGRSEIiwAAALqR6va2PXMZnTWwtl7r7Wm9tRAWAQAADCBn1ZEgwXqtty/Coozc9QsA +AJwt5glqHwb01mu9p663NsIiAACAzsQERAb01mu9day3RsIiAACATpQKiUYc0Fuv9Y5EWJTY5+2m +EQAAgHrGKAkDolEH9NZrvaMRFgEAAHQoR0g04oDeeq13RMIiAACATuQKiEYd0Fuv9Y7qL00AAACA +Ab31Wi93wiIAAAAM6K3XenkQFgEAAGBAb73WW3C9tRMWAQAAYEBvvdZbaL0tEBYBAABgQG+91ltg +va0QFgEAAGBAb73Wm3m9LREWAQAAMEuQYL3W2856UxEWAQAA8JYBvfVabzvrTekyTdO0+U2XSwgh +hNvt5tMTAMjuer2GEELY0W2hZMfydx9xenSO9RWhFS3fLgMtKhkgffzuR11+/3dMf0plEQAAAAAP +wiIAAAAAHn5oAgAAgLG1OKcKkI/KIgAAAAAehEUAAAAAPAiLAAAAAHgQFgEAAADwYIJrAAAAivq4 +frz9+7mJtre8/vm1SxN3z71ubl1bl5n6PUe2K3adW4/DWvsfPb5737PlmJrc/T2VRQAAABSzNHB/ +929bX3/W9u/ZzjO2/+gxOrrcrcve856alt8qlUUAAAAUsVb18zpoX3r9/d8+rh+L1Sdbq19itu91 +uXu28/73qapz9tiyjyWWneo9Z+xvb1QWAQAAkF3M7WGxAczSa3Pac9vbnu08M7RYu+3r8/b5eM3W +dj/aFjmO8xnnUQuERQAAABSzNQhZen3Mv81VK6UOZPZu52i3Qe1p99zhmYqi79yGBgAAABFShjqf +t88vy4sNsfZMon10H9fmYzozbMndHqMSFgEAANCleyBzDzS2VBWVmDfoXfVTrsqnFPv4/HevYRd9 +ERYBAABApBwhzlxodHRC59T7WGM4pIIoD2ERAAAAxWy9bWntaWdrnquL7v8dY2sIcXQ7n9d55oTd +e7Z9yzHds2+520OF1HcmuAYAACC7mKdOzT1ZbG0enVqeHrZlO1sLKO5PQXv9s8WeY5b7ONdyHtVG +ZREAAABFPM9zs6UqaOn1MQP8Ek/T2rOde+ZFamVC55T7lqo9SsxD1QuVRQAAABSz9RHzex9Jb7+O +i7l1b8utc3uqkfa8p6blt+oyTdO0+U2XSwghhNvtpgUBgOyu12sIIYQd3RZKdix/9xGnRwdcXxEA +zvbxux91+f3fMf0plUUAAAAAPJizCACA09yrxl7NVbBvef3za5cq4udeN7eurctM/Z4j2xW7ztT7 +eH/t2nGda//YZS7tz1q77DlmAL1SWQQAwCmWBvbv/m3r68/a/j3becb2x+5jDccixTLn9qXm9oc9 +Pq4fi38gRrHKopikvvQvG3vWs+fLxS8yfpEBAOb7DDH9taXX3//ter0u9pP29AvXtu91uXu2c6mP +d6RftsWWdR89FiXsOWZ7zw+ojcmaSaFIZVGqXx5S/nqzd3v37r9fZAAA1sOGd3+/9votPz6msue2 +tz3bWWvgcsaxOLq81tof4EzZK4u2/mq05XVry1/7ZWPLLw4pvlBTbXcNHQS/yAAAOfoae19/u90W +K5zvP3jN9V9S9lf2budaFXlpe6uacrRnquW11P4AZ8paWbT1V6PUy6/h1wO/yPjCBQD6kzNcWqrk +fve61z9792duOTX05e7bkONHyL3tD9CzIreh5f6CWftlo9aORMntzn1Puy9XAKBmr2HDliqSEkHK +7XYTWpx8fmh/gD9+1LhRZ06SfOQLodQEhEe+BN+VYKdc9mtbqCoCAHqVo5/zroJmy5QKqfclV9+x +tr7snvYH6NmPkXe+9nCn1Q6T0AgAiO2LbekjrD3tLKav8lwtErvuPU/KPbKdc/2qVo5diW0+crtd +D+0PkNtfNW7UvQz0tRz0zKdb7Nnu5+2v5YumxPbMlfECALz2tbY+DGTtCbO1PBxky3a21E86eiy2 +PiE4VT+9l/YHKKVIZdHR0s21JyDs/WWjhvmM/CIDAIzouX+3pSpo6fUxfbsSc2nu2c49fdaUUzds +DWy27mOq45dif1K1P0DPslYWbf3VKPXya3uKQ6rt9osMANCDrQ/7qPmhJr3u17uK8b3bnGo/j94F +0Op5BVDSZZqmafObLpdNH55rQcJrBcrWx83HLv/19ak+/Pc+Qn7rdqfc19flbA1+UuwLAGz9rt3R +baFkx/J3H/F+lD59/wPA6T5+96Muv/87pj9VZM6iFGn93mXU8uQGv8gAAAAALShSWQQAcITKokY6 +liqLAKA6eyqLfmg2AADoj2kCANhLWAQAAB0SBgGwl7BohV9kAAAAgJEIi1YIgwAAAICRCIsAAMji +Y6VCGwCo01+aAAAAAIA7lUUAACR10QQA0PZ3+TRN0+Y3XXQBAIDydnRbKNmx1EcEgC76UyqLAAAo +1vkEAOq3KyzSEQAAAADokwmuAQAAAHgQFgEAAADwICwCAAAA4EFYBAAAAMCDsAgAAACAB2ERAAAA +AA/CIgAAAAAehEUAAAAAPAiLAAAAAHgQFgEAAADwICwCAAAA4EFYBAAAAMCDsAgAAACAB2ERAAAA +AA/CIgAAAAAehEUAAAAAPAiLAAAAAHgQFgEAAADwICwCAAAA4EFYBAAAAMCDsAgAAACAB2ERAAAA +AA/CIgAAAAAe/g/10lQlA3JSSwAAAABJRU5ErkJggg== diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index afc8a0dd2601..d2eb79e41a01 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -128,6 +128,26 @@ url="http://www.ijg.org">http://www.ijg.org</ulink>)</corpauthor> <subtitle>Version 1.02</subtitle> </biblioentry> + <biblioentry id="itu-t81"> + <abbrev>ITU-T.81</abbrev> + <authorgroup> + <corpauthor>International Telecommunication Union +(<ulink url="http://www.itu.int">http://www.itu.int</ulink>)</corpauthor> + </authorgroup> + <title>ITU-T Recommendation T.81 +"Information Technology — Digital Compression and Coding of Continous-Tone +Still Images — Requirements and Guidelines"</title> + </biblioentry> + + <biblioentry id="w3c-jpeg-jfif"> + <abbrev>W3C JPEG JFIF</abbrev> + <authorgroup> + <corpauthor>The World Wide Web Consortium (<ulink +url="http://www.w3.org/Graphics/JPEG">http://www.w3.org</ulink>)</corpauthor> + </authorgroup> + <title>JPEG JFIF</title> + </biblioentry> + <biblioentry id="smpte12m"> <abbrev>SMPTE 12M</abbrev> <authorgroup> @@ -158,31 +178,92 @@ 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>NTSC-4: United States RBDS Standard</title> + <title>NRSC-4-B: United States RBDS Standard</title> </biblioentry> - </bibliography> + <biblioentry id="iso12232"> + <abbrev>ISO 12232:2006</abbrev> + <authorgroup> + <corpauthor>International Organization for Standardization +(<ulink url="http://www.iso.org">http://www.iso.org</ulink>)</corpauthor> + </authorgroup> + <title>Photography — Digital still cameras — Determination + of exposure index, ISO speed ratings, standard output sensitivity, and + recommended exposure index</title> + </biblioentry> - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> + <biblioentry id="cea861"> + <abbrev>CEA-861-E</abbrev> + <authorgroup> + <corpauthor>Consumer Electronics Association +(<ulink url="http://www.ce.org">http://www.ce.org</ulink>)</corpauthor> + </authorgroup> + <title>A DTV Profile for Uncompressed High Speed Digital Interfaces</title> + </biblioentry> + + <biblioentry id="vesadmt"> + <abbrev>VESA DMT</abbrev> + <authorgroup> + <corpauthor>Video Electronics Standards Association +(<ulink url="http://www.vesa.org">http://www.vesa.org</ulink>)</corpauthor> + </authorgroup> + <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 a86f7a045529..1ddf354aa997 100644 --- a/Documentation/DocBook/media/v4l/common.xml +++ b/Documentation/DocBook/media/v4l/common.xml @@ -464,14 +464,14 @@ The <structfield>type</structfield> field of the respective <structfield>tuner</structfield> field contains the index number of the tuner.</para> - <para>Radio devices have exactly one tuner with index zero, no + <para>Radio input devices have exactly one tuner with index zero, no video inputs.</para> <para>To query and change tuner properties applications use the &VIDIOC-G-TUNER; and &VIDIOC-S-TUNER; ioctl, respectively. The &v4l2-tuner; returned by <constant>VIDIOC_G_TUNER</constant> also contains signal status information applicable when the tuner of the -current video input, or a radio tuner is queried. Note that +current video or radio input is queried. Note that <constant>VIDIOC_S_TUNER</constant> does not switch the current tuner, when there is more than one at all. The tuner is solely determined by the current video input. Drivers must support both ioctls and set the @@ -491,8 +491,17 @@ the modulator. The <structfield>type</structfield> field of the respective &v4l2-output; returned by the &VIDIOC-ENUMOUTPUT; ioctl is set to <constant>V4L2_OUTPUT_TYPE_MODULATOR</constant> and its <structfield>modulator</structfield> field contains the index number -of the modulator. This specification does not define radio output -devices.</para> +of the modulator.</para> + + <para>Radio output devices have exactly one modulator with index +zero, no video outputs.</para> + + <para>A video or radio device cannot support both a tuner and a +modulator. Two separate device nodes will have to be used for such +hardware, one that supports the tuner functionality and one that supports +the modulator functionality. The reason is a limitation with the +&VIDIOC-S-FREQUENCY; ioctl where you cannot specify whether the frequency +is for a tuner or a modulator.</para> <para>To query and change modulator properties applications use the &VIDIOC-G-MODULATOR; and &VIDIOC-S-MODULATOR; ioctl. Note that @@ -555,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 @@ -579,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> + <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 @@ -617,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); @@ -724,41 +731,35 @@ if (-1 == ioctl (fd, &VIDIOC-S-STD;, &std_id)) { } </programlisting> </example> + </section> <section id="dv-timings"> <title>Digital Video (DV) Timings</title> <para> - The video standards discussed so far has been dealing with Analog TV and the + The video standards discussed so far have been dealing with Analog TV and the corresponding video timings. Today there are many more different hardware interfaces such as High Definition TV interfaces (HDMI), VGA, DVI connectors etc., that carry video signals and there is a need to extend the API to select the video timings for these interfaces. Since it is not possible to extend the &v4l2-std-id; due to -the limited bits available, a new set of IOCTLs is added to set/get video timings at +the limited bits available, a new set of IOCTLs was added to set/get video timings at the input and output: </para><itemizedlist> <listitem> - <para>DV Presets: Digital Video (DV) presets. These are IDs representing a -video timing at the input/output. Presets are pre-defined timings implemented -by the hardware according to video standards. A __u32 data type is used to represent -a preset unlike the bit mask that is used in &v4l2-std-id; allowing future extensions -to support as many different presets as needed.</para> - </listitem> - <listitem> - <para>Custom DV Timings: This will allow applications to define more detailed -custom video timings for the interface. This includes parameters such as width, height, -polarities, frontporch, backporch etc. + <para>DV Timings: This will allow applications to define detailed +video timings for the interface. This includes parameters such as width, height, +polarities, frontporch, backporch etc. 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> </listitem> </itemizedlist> - <para>To enumerate and query the attributes of DV presets supported by a device, -applications use the &VIDIOC-ENUM-DV-PRESETS; ioctl. To get the current DV preset, -applications use the &VIDIOC-G-DV-PRESET; ioctl and to set a preset they use the -&VIDIOC-S-DV-PRESET; ioctl.</para> - <para>To set custom DV timings for the device, applications use the -&VIDIOC-S-DV-TIMINGS; ioctl and to get current custom DV timings they use the -&VIDIOC-G-DV-TIMINGS; ioctl.</para> + <para>To enumerate and query the attributes of the DV timings supported by a device, + applications use the &VIDIOC-ENUM-DV-TIMINGS; and &VIDIOC-DV-TIMINGS-CAP; ioctls. + To set DV timings for the device, applications use the +&VIDIOC-S-DV-TIMINGS; ioctl and to get current DV timings they use the +&VIDIOC-G-DV-TIMINGS; ioctl. To detect the DV timings as seen by the video receiver applications +use the &VIDIOC-QUERY-DV-TIMINGS; ioctl.</para> <para>Applications can make use of the <xref linkend="input-capabilities" /> and <xref linkend="output-capabilities"/> flags to decide what ioctls are available to set the video timings for the device.</para> - </section> </section> &sub-controls; @@ -1168,6 +1169,8 @@ dheight = format.fmt.pix.height; </section> </section> + &sub-selection-api; + <section id="streaming-par"> <title>Streaming Parameters</title> @@ -1195,11 +1198,3 @@ separate parameters for input and output devices.</para> <para>These ioctls are optional, drivers need not implement them. If so, they return the &EINVAL;.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index b68698f96e7f..0c7195e3e093 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -444,7 +444,7 @@ linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR24</constant></link></para></entr <entry><para><link linkend="pixfmt-rgb"><constant>V4L2_PIX_FMT_BGR32</constant></link><footnote> <para>Presumably all V4L RGB formats are -little-endian, although some drivers might interpret them according to machine endianess. V4L2 defines little-endian, big-endian and red/blue +little-endian, although some drivers might interpret them according to machine endianness. V4L2 defines little-endian, big-endian and red/blue swapped variants. For details see <xref linkend="pixfmt-rgb" />.</para> </footnote></para></entry> </row> @@ -823,7 +823,7 @@ standard); 35468950 Hz PAL and SECAM (625-line standards)</entry> <row> <entry>sample_format</entry> <entry>V4L2_PIX_FMT_GREY. The last four bytes (a -machine endianess integer) contain a frame counter.</entry> +machine endianness integer) contain a frame counter.</entry> </row> <row> <entry>start[]</entry> @@ -1082,7 +1082,7 @@ until the time in the timestamp field has arrived. I would like to follow SGI's lead, and adopt a multimedia timestamping system like their UST (Unadjusted System Time). See http://web.archive.org/web/*/http://reality.sgi.com -/cpirazzi_engr/lg/time/intro.html. +/cpirazzi_engr/lg/time/intro.html. UST uses timestamps that are 64-bit signed integers (not struct timeval's) and given in nanosecond units. The UST clock starts at zero when the system is booted and runs continuously and @@ -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> @@ -2254,7 +2254,7 @@ video encoding.</para> <orderedlist> <listitem> <para>The <constant>VIDIOC_G_CHIP_IDENT</constant> ioctl was renamed -to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and &VIDIOC-DBG-G-CHIP-IDENT; +to <constant>VIDIOC_G_CHIP_IDENT_OLD</constant> and <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> was introduced in its place. The old struct <structname>v4l2_chip_ident</structname> was renamed to <structname id="v4l2-chip-ident-old">v4l2_chip_ident_old</structname>.</para> </listitem> @@ -2310,6 +2310,9 @@ more information.</para> <listitem> <para>Added FM Modulator (FM TX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_TX</constant> and their Control IDs.</para> </listitem> +<listitem> + <para>Added FM Receiver (FM RX) Extended Control Class: <constant>V4L2_CTRL_CLASS_FM_RX</constant> and their Control IDs.</para> + </listitem> <listitem> <para>Added Remote Controller chapter, describing the default Remote Controller mapping for media devices.</para> </listitem> @@ -2376,6 +2379,147 @@ that used it. It was originally scheduled for removal in 2.6.35. <listitem> <para>V4L2_CTRL_FLAG_VOLATILE was added to signal volatile controls to userspace.</para> </listitem> + <listitem> + <para>Add selection API for extended control over cropping + and composing. Does not affect the compatibility of current + drivers and applications. See <link + linkend="selection-api"> selection API </link> for + details.</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.3</title> + <orderedlist> + <listitem> + <para>Added <constant>V4L2_CID_ALPHA_COMPONENT</constant> control + to the <link linkend="control">User controls class</link>. + </para> + </listitem> + <listitem> + <para>Added the device_caps field to struct v4l2_capabilities and added the new + V4L2_CAP_DEVICE_CAPS capability.</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.4</title> + <orderedlist> + <listitem> + <para>Added <link linkend="jpeg-controls">JPEG compression control + class</link>.</para> + </listitem> + <listitem> + <para>Extended the DV Timings API: + &VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and + &VIDIOC-DV-TIMINGS-CAP;.</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.5</title> + <orderedlist> + <listitem> + <para>Added integer menus, the new type will be + V4L2_CTRL_TYPE_INTEGER_MENU.</para> + </listitem> + <listitem> + <para>Added selection API for V4L2 subdev interface: + &VIDIOC-SUBDEV-G-SELECTION; and + &VIDIOC-SUBDEV-S-SELECTION;.</para> + </listitem> + <listitem> + <para> Added <constant>V4L2_COLORFX_ANTIQUE</constant>, + <constant>V4L2_COLORFX_ART_FREEZE</constant>, + <constant>V4L2_COLORFX_AQUA</constant>, + <constant>V4L2_COLORFX_SILHOUETTE</constant>, + <constant>V4L2_COLORFX_SOLARIZATION</constant>, + <constant>V4L2_COLORFX_VIVID</constant> and + <constant>V4L2_COLORFX_ARBITRARY_CBCR</constant> menu items + to the <constant>V4L2_CID_COLORFX</constant> control.</para> + </listitem> + <listitem> + <para> Added <constant>V4L2_CID_COLORFX_CBCR</constant> control.</para> + </listitem> + <listitem> + <para> Added camera controls <constant>V4L2_CID_AUTO_EXPOSURE_BIAS</constant>, + <constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant>, + <constant>V4L2_CID_IMAGE_STABILIZATION</constant>, + <constant>V4L2_CID_ISO_SENSITIVITY</constant>, + <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant>, + <constant>V4L2_CID_EXPOSURE_METERING</constant>, + <constant>V4L2_CID_SCENE_MODE</constant>, + <constant>V4L2_CID_3A_LOCK</constant>, + <constant>V4L2_CID_AUTO_FOCUS_START</constant>, + <constant>V4L2_CID_AUTO_FOCUS_STOP</constant>, + <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> and + <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant>. + </para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.6</title> + <orderedlist> + <listitem> + <para>Replaced <structfield>input</structfield> in + <structname>v4l2_buffer</structname> by + <structfield>reserved2</structfield> and removed + <constant>V4L2_BUF_FLAG_INPUT</constant>.</para> + </listitem> + <listitem> + <para>Added V4L2_CAP_VIDEO_M2M and V4L2_CAP_VIDEO_M2M_MPLANE capabilities.</para> + </listitem> + <listitem> + <para>Added support for frequency band enumerations: &VIDIOC-ENUM-FREQ-BANDS;.</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.9</title> + <orderedlist> + <listitem> + <para>Added timestamp types to + <structfield>flags</structfield> field in + <structname>v4l2_buffer</structname>. See <xref + linkend="buffer-flags" />.</para> + </listitem> + <listitem> + <para>Added <constant>V4L2_EVENT_CTRL_CH_RANGE</constant> control event + changes flag. See <xref linkend="changes-flags"/>.</para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.10</title> + <orderedlist> + <listitem> + <para>Removed obsolete and unused DV_PRESET ioctls + VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_QUERY_DV_PRESET and + VIDIOC_ENUM_DV_PRESET. Remove the related v4l2_input/output capability + flags V4L2_IN_CAP_PRESETS and V4L2_OUT_CAP_PRESETS. + </para> + </listitem> + <listitem> + <para>Added new debugging ioctl &VIDIOC-DBG-G-CHIP-INFO;. + </para> + </listitem> + </orderedlist> + </section> + + <section> + <title>V4L2 in Linux 3.11</title> + <orderedlist> + <listitem> + <para>Remove obsolete <constant>VIDIOC_DBG_G_CHIP_IDENT</constant> ioctl. + </para> + </listitem> </orderedlist> </section> @@ -2457,37 +2601,43 @@ 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> + <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; +ioctls.</para> </listitem> <listitem> - <para><constant>V4L2_CAP_VIDEO_OUTPUT_OVERLAY</constant>, -&VIDIOC-QUERYCAP; ioctl, <xref linkend="device-capabilities" />.</para> + <para>&VIDIOC-DBG-G-CHIP-INFO; ioctl.</para> </listitem> <listitem> - <para>&VIDIOC-ENUM-FRAMESIZES; and -&VIDIOC-ENUM-FRAMEINTERVALS; ioctls.</para> + <para>&VIDIOC-ENUM-DV-TIMINGS;, &VIDIOC-QUERY-DV-TIMINGS; and + &VIDIOC-DV-TIMINGS-CAP; ioctls.</para> </listitem> <listitem> - <para>&VIDIOC-G-ENC-INDEX; ioctl.</para> + <para>Flash API. <xref linkend="flash-controls" /></para> </listitem> <listitem> - <para>&VIDIOC-ENCODER-CMD; and &VIDIOC-TRY-ENCODER-CMD; -ioctls.</para> + <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para> </listitem> <listitem> - <para>&VIDIOC-DBG-G-REGISTER; and &VIDIOC-DBG-S-REGISTER; -ioctls.</para> + <para>Selection API. <xref linkend="selection-api" /></para> </listitem> <listitem> - <para>&VIDIOC-DBG-G-CHIP-IDENT; ioctl.</para> + <para>Sub-device selection API: &VIDIOC-SUBDEV-G-SELECTION; + and &VIDIOC-SUBDEV-S-SELECTION; ioctls.</para> </listitem> <listitem> - <para>Flash API. <xref linkend="flash-controls" /></para> + <para>Support for frequency band enumeration: &VIDIOC-ENUM-FREQ-BANDS; ioctl.</para> </listitem> <listitem> - <para>&VIDIOC-CREATE-BUFS; and &VIDIOC-PREPARE-BUF; ioctls.</para> + <para>Vendor and device specific media bus pixel formats. + <xref linkend="v4l2-mbus-vendor-spec-fmts" />.</para> + </listitem> + <listitem> + <para>Importing DMABUF file descriptors as a new IO method described + in <xref linkend="dmabuf" />.</para> + </listitem> + <listitem> + <para>Exporting DMABUF files using &VIDIOC-EXPBUF; ioctl.</para> </listitem> </itemizedlist> </section> @@ -2504,14 +2654,17 @@ interfaces and should not be implemented in new drivers.</para> <constant>VIDIOC_S_MPEGCOMP</constant> ioctls. Use Extended Controls, <xref linkend="extended-controls" />.</para> </listitem> + <listitem> + <para>VIDIOC_G_DV_PRESET, VIDIOC_S_DV_PRESET, VIDIOC_ENUM_DV_PRESETS and + VIDIOC_QUERY_DV_PRESET ioctls. Use the DV Timings API (<xref linkend="dv-timings" />).</para> + </listitem> + <listitem> + <para><constant>VIDIOC_SUBDEV_G_CROP</constant> and + <constant>VIDIOC_SUBDEV_S_CROP</constant> ioctls. Use + <constant>VIDIOC_SUBDEV_G_SELECTION</constant> and + <constant>VIDIOC_SUBDEV_S_SELECTION</constant>, <xref + linkend="vidioc-subdev-g-selection" />.</para> + </listitem> </itemizedlist> </section> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/controls.xml b/Documentation/DocBook/media/v4l/controls.xml index 3bc5ee8b2c74..7a3b49b3cc3b 100644 --- a/Documentation/DocBook/media/v4l/controls.xml +++ b/Documentation/DocBook/media/v4l/controls.xml @@ -203,29 +203,6 @@ and should not be used in new drivers and applications.</entry> <entry>boolean</entry> <entry>Mirror the picture vertically.</entry> </row> - <row> - <entry><constant>V4L2_CID_HCENTER_DEPRECATED</constant> (formerly <constant>V4L2_CID_HCENTER</constant>)</entry> - <entry>integer</entry> - <entry>Horizontal image centering. This control is -deprecated. New drivers and applications should use the <link -linkend="camera-controls">Camera class controls</link> -<constant>V4L2_CID_PAN_ABSOLUTE</constant>, -<constant>V4L2_CID_PAN_RELATIVE</constant> and -<constant>V4L2_CID_PAN_RESET</constant> instead.</entry> - </row> - <row> - <entry><constant>V4L2_CID_VCENTER_DEPRECATED</constant> - (formerly <constant>V4L2_CID_VCENTER</constant>)</entry> - <entry>integer</entry> - <entry>Vertical image centering. Centering is intended to -<emphasis>physically</emphasis> adjust cameras. For image cropping see -<xref linkend="crop" />, for clipping <xref linkend="overlay" />. This -control is deprecated. New drivers and applications should use the -<link linkend="camera-controls">Camera class controls</link> -<constant>V4L2_CID_TILT_ABSOLUTE</constant>, -<constant>V4L2_CID_TILT_RELATIVE</constant> and -<constant>V4L2_CID_TILT_RESET</constant> instead.</entry> - </row> <row id="v4l2-power-line-frequency"> <entry><constant>V4L2_CID_POWER_LINE_FREQUENCY</constant></entry> <entry>enum</entry> @@ -285,18 +262,97 @@ minimum value disables backlight compensation.</entry> <row id="v4l2-colorfx"> <entry><constant>V4L2_CID_COLORFX</constant></entry> <entry>enum</entry> - <entry>Selects a color effect. Possible values for -<constant>enum v4l2_colorfx</constant> are: -<constant>V4L2_COLORFX_NONE</constant> (0), -<constant>V4L2_COLORFX_BW</constant> (1), -<constant>V4L2_COLORFX_SEPIA</constant> (2), -<constant>V4L2_COLORFX_NEGATIVE</constant> (3), -<constant>V4L2_COLORFX_EMBOSS</constant> (4), -<constant>V4L2_COLORFX_SKETCH</constant> (5), -<constant>V4L2_COLORFX_SKY_BLUE</constant> (6), -<constant>V4L2_COLORFX_GRASS_GREEN</constant> (7), -<constant>V4L2_COLORFX_SKIN_WHITEN</constant> (8) and -<constant>V4L2_COLORFX_VIVID</constant> (9).</entry> + <entry>Selects a color effect. The following values are defined: + </entry> + </row><row> + <entry></entry> + <entry></entry> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_COLORFX_NONE</constant> </entry> + <entry>Color effect is disabled.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_ANTIQUE</constant> </entry> + <entry>An aging (old photo) effect.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_ART_FREEZE</constant> </entry> + <entry>Frost color effect.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_AQUA</constant> </entry> + <entry>Water color, cool tone.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_BW</constant> </entry> + <entry>Black and white.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_EMBOSS</constant> </entry> + <entry>Emboss, the highlights and shadows replace light/dark boundaries + and low contrast areas are set to a gray background.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_GRASS_GREEN</constant> </entry> + <entry>Grass green.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_NEGATIVE</constant> </entry> + <entry>Negative.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_SEPIA</constant> </entry> + <entry>Sepia tone.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_SKETCH</constant> </entry> + <entry>Sketch.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_SKIN_WHITEN</constant> </entry> + <entry>Skin whiten.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_SKY_BLUE</constant> </entry> + <entry>Sky blue.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_SOLARIZATION</constant> </entry> + <entry>Solarization, the image is partially reversed in tone, + only color values above or below a certain threshold are inverted. + </entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_SILHOUETTE</constant> </entry> + <entry>Silhouette (outline).</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_VIVID</constant> </entry> + <entry>Vivid colors.</entry> + </row> + <row> + <entry><constant>V4L2_COLORFX_SET_CBCR</constant> </entry> + <entry>The Cb and Cr chroma components are replaced by fixed + coefficients determined by <constant>V4L2_CID_COLORFX_CBCR</constant> + control.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row> + <entry><constant>V4L2_CID_COLORFX_CBCR</constant></entry> + <entry>integer</entry> + <entry>Determines the Cb and Cr coefficients for <constant>V4L2_COLORFX_SET_CBCR</constant> + color effect. Bits [7:0] of the supplied 32 bit value are interpreted as + Cr component, bits [15:8] as Cb component and bits [31:16] must be zero. + </entry> + </row> + <row> + <entry><constant>V4L2_CID_AUTOBRIGHTNESS</constant></entry> + <entry>boolean</entry> + <entry>Enable Automatic Brightness.</entry> </row> <row> <entry><constant>V4L2_CID_ROTATE</constant></entry> @@ -324,12 +380,6 @@ minimum value disables backlight compensation.</entry> (usually a microscope).</entry> </row> <row> - <entry><constant>V4L2_CID_LASTP1</constant></entry> - <entry></entry> - <entry>End of the predefined control IDs (currently -<constant>V4L2_CID_ILLUMINATORS_2</constant> + 1).</entry> - </row> - <row> <entry><constant>V4L2_CID_MIN_BUFFERS_FOR_CAPTURE</constant></entry> <entry>integer</entry> <entry>This is a read-only control that can be read by the application @@ -345,6 +395,25 @@ and used as a hint to determine the number of OUTPUT buffers to pass to REQBUFS. The value is the minimum number of OUTPUT buffers that is necessary for hardware to work.</entry> </row> + <row id="v4l2-alpha-component"> + <entry><constant>V4L2_CID_ALPHA_COMPONENT</constant></entry> + <entry>integer</entry> + <entry> Sets the alpha color component on the capture device or on + the capture buffer queue of a mem-to-mem device. When a mem-to-mem + device produces frame format that includes an alpha component + (e.g. <link linkend="rgb-formats">packed RGB image formats</link>) + and the alpha value is not defined by the mem-to-mem input data + this control lets you select the alpha component value of all + pixels. It is applicable to any pixel format that contains an alpha + component. + </entry> + </row> + <row> + <entry><constant>V4L2_CID_LASTP1</constant></entry> + <entry></entry> + <entry>End of the predefined control IDs (currently + <constant>V4L2_CID_ALPHA_COMPONENT</constant> + 1).</entry> + </row> <row> <entry><constant>V4L2_CID_PRIVATE_BASE</constant></entry> <entry></entry> @@ -653,17 +722,22 @@ for more details.</para> </section> <section id="mpeg-controls"> - <title>MPEG Control Reference</title> + <title>Codec Control Reference</title> - <para>Below all controls within the MPEG control class are + <para>Below all controls within the Codec control class are described. First the generic controls, then controls specific for certain hardware.</para> + <para>Note: These controls are applicable to all codecs and +not just MPEG. The defines are prefixed with V4L2_CID_MPEG/V4L2_MPEG +as the controls were originally made for MPEG codecs and later +extended to cover all encoding formats.</para> + <section> - <title>Generic MPEG Controls</title> + <title>Generic Codec Controls</title> <table pgwide="1" frame="none" id="mpeg-control-id"> - <title>MPEG Control IDs</title> + <title>Codec Control IDs</title> <tgroup cols="4"> <colspec colname="c1" colwidth="1*" /> <colspec colname="c2" colwidth="6*" /> @@ -683,7 +757,7 @@ certain hardware.</para> <row> <entry spanname="id"><constant>V4L2_CID_MPEG_CLASS</constant> </entry> <entry>class</entry> - </row><row><entry spanname="descr">The MPEG class + </row><row><entry spanname="descr">The Codec class descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a description of this control class. This description can be used as the caption of a Tab page in a GUI, for example.</entry> @@ -1273,6 +1347,49 @@ produce a slight hiss, but in the encoder itself, guaranteeing a fixed and reproducible audio bitstream. 0 = unmuted, 1 = muted.</entry> </row> <row><entry></entry></row> + <row id="v4l2-mpeg-audio-dec-playback"> + <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_PLAYBACK</constant> </entry> + <entry>enum v4l2_mpeg_audio_dec_playback</entry> + </row><row><entry spanname="descr">Determines how monolingual audio should be played back. +Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_AUTO</constant> </entry> + <entry>Automatically determines the best playback mode.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_STEREO</constant> </entry> + <entry>Stereo playback.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_LEFT</constant> </entry> + <entry>Left channel playback.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_RIGHT</constant> </entry> + <entry>Right channel playback.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_MONO</constant> </entry> + <entry>Mono playback.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_AUDIO_DEC_PLAYBACK_SWAPPED_STEREO</constant> </entry> + <entry>Stereo playback with swapped left and right channels.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row><entry></entry></row> + <row id="v4l2-mpeg-audio-dec-multilingual-playback"> + <entry spanname="id"><constant>V4L2_CID_MPEG_AUDIO_DEC_MULTILINGUAL_PLAYBACK</constant> </entry> + <entry>enum v4l2_mpeg_audio_dec_playback</entry> + </row><row><entry spanname="descr">Determines how multilingual audio should be played back.</entry> + </row> + <row><entry></entry></row> <row id="v4l2-mpeg-video-encoding"> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_ENCODING</constant> </entry> <entry>enum v4l2_mpeg_video_encoding</entry> @@ -1434,7 +1551,22 @@ of the video. The supplied 32-bit integer is interpreted as follows (bit </tbody> </entrytbl> </row> - + <row><entry></entry></row> + <row id="v4l2-mpeg-video-dec-pts"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_PTS</constant> </entry> + <entry>integer64</entry> + </row><row><entry spanname="descr">This read-only control returns the +33-bit video Presentation Time Stamp as defined in ITU T-REC-H.222.0 and ISO/IEC 13818-1 of +the currently displayed frame. This is the same PTS as is used in &VIDIOC-DECODER-CMD;.</entry> + </row> + <row><entry></entry></row> + <row id="v4l2-mpeg-video-dec-frame"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DEC_FRAME</constant> </entry> + <entry>integer64</entry> + </row><row><entry spanname="descr">This read-only control returns the +frame counter of the frame that is currently displayed (decoded). This value is reset to 0 whenever +the decoder is started.</entry> + </row> <row><entry></entry></row> <row> @@ -1951,7 +2083,7 @@ Possible values are:</entry> <entry>integer</entry> </row> <row><entry spanname="descr">Cyclic intra macroblock refresh. This is the number of continuous macroblocks -refreshed every frame. Each frame a succesive set of macroblocks is refreshed until the cycle completes and starts from the +refreshed every frame. Each frame a successive set of macroblocks is refreshed until the cycle completes and starts from the top of the frame. Applicable to H264, H263 and MPEG4 encoder.</entry> </row> @@ -2111,7 +2243,7 @@ Applicable to the MPEG4 and H264 encoders.</entry> <entry>integer</entry> </row> <row><entry spanname="descr">The Video Buffer Verifier size in kilobytes, it is used as a limitation of frame skip. -The VBV is defined in the standard as a mean to verify that the produced stream will be succesfully decoded. +The VBV is defined in the standard as a mean to verify that the produced stream will be successfully decoded. The standard describes it as "Part of a hypothetical decoder that is conceptually connected to the output of the encoder. Its purpose is to provide a constraint on the variability of the data rate that an encoder or editing process may produce.". @@ -2119,12 +2251,20 @@ Applicable to the MPEG1, MPEG2, MPEG4 encoders.</entry> </row> <row><entry></entry></row> + <row id="v4l2-mpeg-video-vbv-delay"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VBV_DELAY</constant> </entry> + <entry>integer</entry> + </row><row><entry spanname="descr">Sets the initial delay in milliseconds for +VBV buffer control.</entry> + </row> + + <row><entry></entry></row> <row> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_CPB_SIZE</constant> </entry> <entry>integer</entry> </row> <row><entry spanname="descr">The Coded Picture Buffer size in kilobytes, it is used as a limitation of frame skip. -The CPB is defined in the H264 standard as a mean to verify that the produced stream will be succesfully decoded. +The CPB is defined in the H264 standard as a mean to verify that the produced stream will be successfully decoded. Applicable to the H264 encoder.</entry> </row> @@ -2165,6 +2305,12 @@ Possible values are:</entry> </row> <row><entry></entry></row> <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_REPEAT_SEQ_HEADER</constant> </entry> + <entry>boolean</entry> + </row><row><entry spanname="descr">Repeat the video sequence headers. Repeating these +headers makes random access to the video stream easier. Applicable to the MPEG1, 2 and 4 encoder.</entry> + </row> + <row> <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_DECODER_MPEG4_DEBLOCK_FILTER</constant> </entry> <entry>boolean</entry> </row><row><entry spanname="descr">Enabled the deblocking post processing filter for MPEG4 decoder. @@ -2183,6 +2329,265 @@ Applicable to the MPEG4 decoder.</entry> </row><row><entry spanname="descr">vop_time_increment value for MPEG4. Applicable to the MPEG4 encoder.</entry> </row> + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FRAME_PACKING</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Enable generation of frame packing supplemental enhancement information in the encoded bitstream. +The frame packing SEI message contains the arrangement of L and R planes for 3D viewing. Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FP_CURRENT_FRAME_0</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Sets current frame as frame0 in frame packing SEI. +Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row id="v4l2-mpeg-video-h264-sei-fp-arrangement-type"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE</constant> </entry> + <entry>enum v4l2_mpeg_video_h264_sei_fp_arrangement_type</entry> + </row> + <row><entry spanname="descr">Frame packing arrangement type for H264 SEI. +Applicable to the H264 encoder. +Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_CHEKERBOARD</constant> </entry> + <entry>Pixels are alternatively from L and R.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_COLUMN</constant> </entry> + <entry>L and R are interlaced by column.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_ROW</constant> </entry> + <entry>L and R are interlaced by row.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_SIDE_BY_SIDE</constant> </entry> + <entry>L is on the left, R on the right.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TOP_BOTTOM</constant> </entry> + <entry>L is on top, R on bottom.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_SEI_FP_ARRANGEMENT_TYPE_TEMPORAL</constant> </entry> + <entry>One view per frame.</entry> + </row> + </tbody> + </entrytbl> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Enables flexible macroblock ordering in the encoded bitstream. It is a technique +used for restructuring the ordering of macroblocks in pictures. Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row id="v4l2-mpeg-video-h264-fmo-map-type"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_MAP_TYPE</constant> </entry> + <entry>enum v4l2_mpeg_video_h264_fmo_map_type</entry> + </row> + <row><entry spanname="descr">When using FMO, the map type divides the image in different scan patterns of macroblocks. +Applicable to the H264 encoder. +Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_INTERLEAVED_SLICES</constant> </entry> + <entry>Slices are interleaved one after other with macroblocks in run length order.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_SCATTERED_SLICES</constant> </entry> + <entry>Scatters the macroblocks based on a mathematical function known to both encoder and decoder.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_FOREGROUND_WITH_LEFT_OVER</constant> </entry> + <entry>Macroblocks arranged in rectangular areas or regions of interest.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_BOX_OUT</constant> </entry> + <entry>Slice groups grow in a cyclic way from centre to outwards.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_RASTER_SCAN</constant> </entry> + <entry>Slice groups grow in raster scan pattern from left to right.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_WIPE_SCAN</constant> </entry> + <entry>Slice groups grow in wipe scan pattern from top to bottom.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_MAP_TYPE_EXPLICIT</constant> </entry> + <entry>User defined map type.</entry> + </row> + </tbody> + </entrytbl> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_SLICE_GROUP</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Number of slice groups in FMO. +Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row id="v4l2-mpeg-video-h264-fmo-change-direction"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_DIRECTION</constant> </entry> + <entry>enum v4l2_mpeg_video_h264_fmo_change_dir</entry> + </row> + <row><entry spanname="descr">Specifies a direction of the slice group change for raster and wipe maps. +Applicable to the H264 encoder. +Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_RIGHT</constant> </entry> + <entry>Raster scan or wipe right.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_FMO_CHANGE_DIR_LEFT</constant> </entry> + <entry>Reverse raster scan or wipe left.</entry> + </row> + </tbody> + </entrytbl> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_CHANGE_RATE</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Specifies the size of the first slice group for raster and wipe map. +Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_FMO_RUN_LENGTH</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Specifies the number of consecutive macroblocks for the interleaved map. +Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ASO</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Enables arbitrary slice ordering in encoded bitstream. +Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_ASO_SLICE_ORDER</constant> </entry> + <entry>integer</entry> + </row><row><entry spanname="descr">Specifies the slice order in ASO. Applicable to the H264 encoder. +The supplied 32-bit integer is interpreted as follows (bit +0 = least significant bit):</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry>Bit 0:15</entry> + <entry>Slice ID</entry> + </row> + <row> + <entry>Bit 16:32</entry> + <entry>Slice position or order</entry> + </row> + </tbody> + </entrytbl> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING</constant> </entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Enables H264 hierarchical coding. +Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row id="v4l2-mpeg-video-h264-hierarchical-coding-type"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_TYPE</constant> </entry> + <entry>enum v4l2_mpeg_video_h264_hierarchical_coding_type</entry> + </row> + <row><entry spanname="descr">Specifies the hierarchical coding type. +Applicable to the H264 encoder. +Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_B</constant> </entry> + <entry>Hierarchical B coding.</entry> + </row> + <row> + <entry><constant>V4L2_MPEG_VIDEO_H264_HIERARCHICAL_CODING_P</constant> </entry> + <entry>Hierarchical P coding.</entry> + </row> + </tbody> + </entrytbl> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER</constant> </entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Specifies the number of hierarchical coding layers. +Applicable to the H264 encoder.</entry> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_H264_HIERARCHICAL_CODING_LAYER_QP</constant> </entry> + <entry>integer</entry> + </row><row><entry spanname="descr">Specifies a user defined QP for each layer. Applicable to the H264 encoder. +The supplied 32-bit integer is interpreted as follows (bit +0 = least significant bit):</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry>Bit 0:15</entry> + <entry>QP value</entry> + </row> + <row> + <entry>Bit 16:32</entry> + <entry>Layer number</entry> + </row> + </tbody> + </entrytbl> + </row> + </tbody> </tgroup> </table> @@ -2609,6 +3014,159 @@ in by the application. 0 = do not insert, 1 = insert packets.</entry> </tgroup> </table> </section> + + <section> + <title>VPX Control Reference</title> + + <para>The VPX controls include controls for encoding parameters + of VPx video codec.</para> + + <table pgwide="1" frame="none" id="vpx-control-id"> + <title>VPX 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></entry></row> + <row id="v4l2-vpx-num-partitions"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_NUM_PARTITIONS</constant></entry> + <entry>enum v4l2_vp8_num_partitions</entry> + </row> + <row><entry spanname="descr">The number of token partitions to use in VP8 encoder. +Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_1_PARTITION</constant></entry> + <entry>1 coefficient partition</entry> + </row> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_2_PARTITIONS</constant></entry> + <entry>2 coefficient partitions</entry> + </row> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_4_PARTITIONS</constant></entry> + <entry>4 coefficient partitions</entry> + </row> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_8_PARTITIONS</constant></entry> + <entry>8 coefficient partitions</entry> + </row> + </tbody> + </entrytbl> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_IMD_DISABLE_4X4</constant></entry> + <entry>boolean</entry> + </row> + <row><entry spanname="descr">Setting this prevents intra 4x4 mode in the intra mode decision.</entry> + </row> + + <row><entry></entry></row> + <row id="v4l2-vpx-num-ref-frames"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_NUM_REF_FRAMES</constant></entry> + <entry>enum v4l2_vp8_num_ref_frames</entry> + </row> + <row><entry spanname="descr">The number of reference pictures for encoding P frames. +Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_1_REF_FRAME</constant></entry> + <entry>Last encoded frame will be searched</entry> + </row> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_2_REF_FRAME</constant></entry> + <entry>Two frames will be searched among the last encoded frame, the golden frame +and the alternate reference (altref) frame. The encoder implementation will decide which two are chosen.</entry> + </row> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_3_REF_FRAME</constant></entry> + <entry>The last encoded frame, the golden frame and the altref frame will be searched.</entry> + </row> + </tbody> + </entrytbl> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_FILTER_LEVEL</constant></entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Indicates the loop filter level. The adjustment of the loop +filter level is done via a delta value against a baseline loop filter value.</entry> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_FILTER_SHARPNESS</constant></entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">This parameter affects the loop filter. Anything above +zero weakens the deblocking effect on the loop filter.</entry> + </row> + + <row><entry></entry></row> + <row> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD</constant></entry> + <entry>integer</entry> + </row> + <row><entry spanname="descr">Sets the refresh period for the golden frame. The period is defined +in number of frames. For a value of 'n', every nth frame starting from the first key frame will be taken as a golden frame. +For eg. for encoding sequence of 0, 1, 2, 3, 4, 5, 6, 7 where the golden frame refresh period is set as 4, the frames +0, 4, 8 etc will be taken as the golden frames as frame 0 is always a key frame.</entry> + </row> + + <row><entry></entry></row> + <row id="v4l2-vpx-golden-frame-sel"> + <entry spanname="id"><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_SEL</constant></entry> + <entry>enum v4l2_vp8_golden_frame_sel</entry> + </row> + <row><entry spanname="descr">Selects the golden frame for encoding. +Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_PREV</constant></entry> + <entry>Use the (n-2)th frame as a golden frame, current frame index being 'n'.</entry> + </row> + <row> + <entry><constant>V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_USE_REF_PERIOD</constant></entry> + <entry>Use the previous specific frame indicated by +V4L2_CID_MPEG_VIDEO_VPX_GOLDEN_FRAME_REF_PERIOD as a golden frame.</entry> + </row> + </tbody> + </entrytbl> + </row> + + <row><entry></entry></row> + </tbody> + </tgroup> + </table> + + </section> </section> <section id="camera-controls"> @@ -2703,6 +3261,58 @@ remain constant.</entry> <row><entry></entry></row> <row> + <entry spanname="id"><constant>V4L2_CID_EXPOSURE_BIAS</constant> </entry> + <entry>integer menu</entry> + </row><row><entry spanname="descr"> Determines the automatic +exposure compensation, it is effective only when <constant>V4L2_CID_EXPOSURE_AUTO</constant> +control is set to <constant>AUTO</constant>, <constant>SHUTTER_PRIORITY </constant> +or <constant>APERTURE_PRIORITY</constant>. +It is expressed in terms of EV, drivers should interpret the values as 0.001 EV +units, where the value 1000 stands for +1 EV. +<para>Increasing the exposure compensation value is equivalent to decreasing +the exposure value (EV) and will increase the amount of light at the image +sensor. The camera performs the exposure compensation by adjusting absolute +exposure time and/or aperture.</para></entry> + </row> + <row><entry></entry></row> + + <row id="v4l2-exposure-metering"> + <entry spanname="id"><constant>V4L2_CID_EXPOSURE_METERING</constant> </entry> + <entry>enum v4l2_exposure_metering</entry> + </row><row><entry spanname="descr">Determines how the camera measures +the amount of light available for the frame exposure. Possible values are:</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_EXPOSURE_METERING_AVERAGE</constant> </entry> + <entry>Use the light information coming from the entire frame +and average giving no weighting to any particular portion of the metered area. + </entry> + </row> + <row> + <entry><constant>V4L2_EXPOSURE_METERING_CENTER_WEIGHTED</constant> </entry> + <entry>Average the light information coming from the entire frame +giving priority to the center of the metered area.</entry> + </row> + <row> + <entry><constant>V4L2_EXPOSURE_METERING_SPOT</constant> </entry> + <entry>Measure only very small area at the center of the frame.</entry> + </row> + <row> + <entry><constant>V4L2_EXPOSURE_METERING_MATRIX</constant> </entry> + <entry>A multi-zone metering. The light intensity is measured +in several points of the frame and the the results are combined. The +algorithm of the zones selection and their significance in calculating the +final value is device dependent.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row><entry></entry></row> + + <row> <entry spanname="id"><constant>V4L2_CID_PAN_RELATIVE</constant> </entry> <entry>integer</entry> </row><row><entry spanname="descr">This control turns the @@ -2785,13 +3395,107 @@ negative values towards infinity. This is a write-only control.</entry> <row> <entry spanname="id"><constant>V4L2_CID_FOCUS_AUTO</constant> </entry> <entry>boolean</entry> - </row><row><entry spanname="descr">Enables automatic focus -adjustments. The effect of manual focus adjustments while this feature + </row><row><entry spanname="descr">Enables continuous automatic +focus adjustments. The effect of manual focus adjustments while this feature is enabled is undefined, drivers should ignore such requests.</entry> </row> <row><entry></entry></row> <row> + <entry spanname="id"><constant>V4L2_CID_AUTO_FOCUS_START</constant> </entry> + <entry>button</entry> + </row><row><entry spanname="descr">Starts single auto focus process. +The effect of setting this control when <constant>V4L2_CID_FOCUS_AUTO</constant> +is set to <constant>TRUE</constant> (1) is undefined, drivers should ignore +such requests.</entry> + </row> + <row><entry></entry></row> + + <row> + <entry spanname="id"><constant>V4L2_CID_AUTO_FOCUS_STOP</constant> </entry> + <entry>button</entry> + </row><row><entry spanname="descr">Aborts automatic focusing +started with <constant>V4L2_CID_AUTO_FOCUS_START</constant> control. It is +effective only when the continuous autofocus is disabled, that is when +<constant>V4L2_CID_FOCUS_AUTO</constant> control is set to <constant>FALSE +</constant> (0).</entry> + </row> + <row><entry></entry></row> + + <row id="v4l2-auto-focus-status"> + <entry spanname="id"> + <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> </entry> + <entry>bitmask</entry> + </row> + <row><entry spanname="descr">The automatic focus status. This is a read-only + control.</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_AUTO_FOCUS_STATUS_IDLE</constant> </entry> + <entry>Automatic focus is not active.</entry> + </row> + <row> + <entry><constant>V4L2_AUTO_FOCUS_STATUS_BUSY</constant> </entry> + <entry>Automatic focusing is in progress.</entry> + </row> + <row> + <entry><constant>V4L2_AUTO_FOCUS_STATUS_REACHED</constant> </entry> + <entry>Focus has been reached.</entry> + </row> + <row> + <entry><constant>V4L2_AUTO_FOCUS_STATUS_FAILED</constant> </entry> + <entry>Automatic focus has failed, the driver will not + transition from this state until another action is + performed by an application.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row><entry spanname="descr"> +Setting <constant>V4L2_LOCK_FOCUS</constant> lock bit of the <constant>V4L2_CID_3A_LOCK +</constant> control may stop updates of the <constant>V4L2_CID_AUTO_FOCUS_STATUS</constant> +control value.</entry> + </row> + <row><entry></entry></row> + + <row id="v4l2-auto-focus-range"> + <entry spanname="id"> + <constant>V4L2_CID_AUTO_FOCUS_RANGE</constant> </entry> + <entry>enum v4l2_auto_focus_range</entry> + </row> + <row><entry spanname="descr">Determines auto focus distance range +for which lens may be adjusted. </entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_AUTO_FOCUS_RANGE_AUTO</constant> </entry> + <entry>The camera automatically selects the focus range.</entry> + </row> + <row> + <entry><constant>V4L2_AUTO_FOCUS_RANGE_NORMAL</constant> </entry> + <entry>Normal distance range, limited for best automatic focus +performance.</entry> + </row> + <row> + <entry><constant>V4L2_AUTO_FOCUS_RANGE_MACRO</constant> </entry> + <entry>Macro (close-up) auto focus. The camera will +use its minimum possible distance for auto focus.</entry> + </row> + <row> + <entry><constant>V4L2_AUTO_FOCUS_RANGE_INFINITY</constant> </entry> + <entry>The lens is set to focus on an object at infinite distance.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row><entry></entry></row> + + <row> <entry spanname="id"><constant>V4L2_CID_ZOOM_ABSOLUTE</constant> </entry> <entry>integer</entry> </row><row><entry spanname="descr">Specify the objective lens @@ -2860,6 +3564,295 @@ camera sensor on or off, or specify its strength. Such band-stop filters can be used, for example, to filter out the fluorescent light component.</entry> </row> <row><entry></entry></row> + + <row id="v4l2-auto-n-preset-white-balance"> + <entry spanname="id"><constant>V4L2_CID_AUTO_N_PRESET_WHITE_BALANCE</constant> </entry> + <entry>enum v4l2_auto_n_preset_white_balance</entry> + </row><row><entry spanname="descr">Sets white balance to automatic, +manual or a preset. The presets determine color temperature of the light as +a hint to the camera for white balance adjustments resulting in most accurate +color representation. The following white balance presets are listed in order +of increasing color temperature.</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_WHITE_BALANCE_MANUAL</constant> </entry> + <entry>Manual white balance.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_AUTO</constant> </entry> + <entry>Automatic white balance adjustments.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_INCANDESCENT</constant> </entry> + <entry>White balance setting for incandescent (tungsten) lighting. +It generally cools down the colors and corresponds approximately to 2500...3500 K +color temperature range.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_FLUORESCENT</constant> </entry> + <entry>White balance preset for fluorescent lighting. +It corresponds approximately to 4000...5000 K color temperature.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_FLUORESCENT_H</constant> </entry> + <entry>With this setting the camera will compensate for +fluorescent H lighting.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_HORIZON</constant> </entry> + <entry>White balance setting for horizon daylight. +It corresponds approximately to 5000 K color temperature.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_DAYLIGHT</constant> </entry> + <entry>White balance preset for daylight (with clear sky). +It corresponds approximately to 5000...6500 K color temperature.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_FLASH</constant> </entry> + <entry>With this setting the camera will compensate for the flash +light. It slightly warms up the colors and corresponds roughly to 5000...5500 K +color temperature.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_CLOUDY</constant> </entry> + <entry>White balance preset for moderately overcast sky. +This option corresponds approximately to 6500...8000 K color temperature +range.</entry> + </row> + <row> + <entry><constant>V4L2_WHITE_BALANCE_SHADE</constant> </entry> + <entry>White balance preset for shade or heavily overcast +sky. It corresponds approximately to 9000...10000 K color temperature. +</entry> + </row> + </tbody> + </entrytbl> + </row> + <row><entry></entry></row> + + <row id="v4l2-wide-dynamic-range"> + <entry spanname="id"><constant>V4L2_CID_WIDE_DYNAMIC_RANGE</constant></entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Enables or disables the camera's wide dynamic +range feature. This feature allows to obtain clear images in situations where +intensity of the illumination varies significantly throughout the scene, i.e. +there are simultaneously very dark and very bright areas. It is most commonly +realized in cameras by combining two subsequent frames with different exposure +times. <footnote id="ctypeconv"><para> This control may be changed to a menu +control in the future, if more options are required.</para></footnote></entry> + </row> + <row><entry></entry></row> + + <row id="v4l2-image-stabilization"> + <entry spanname="id"><constant>V4L2_CID_IMAGE_STABILIZATION</constant></entry> + <entry>boolean</entry> + </row> + <row> + <entry spanname="descr">Enables or disables image stabilization. + <footnoteref linkend="ctypeconv"/></entry> + </row> + <row><entry></entry></row> + + <row> + <entry spanname="id"><constant>V4L2_CID_ISO_SENSITIVITY</constant> </entry> + <entry>integer menu</entry> + </row><row><entry spanname="descr">Determines ISO equivalent of an +image sensor indicating the sensor's sensitivity to light. The numbers are +expressed in arithmetic scale, as per <xref linkend="iso12232" /> standard, +where doubling the sensor sensitivity is represented by doubling the numerical +ISO value. Applications should interpret the values as standard ISO values +multiplied by 1000, e.g. control value 800 stands for ISO 0.8. Drivers will +usually support only a subset of standard ISO values. The effect of setting +this control while the <constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant> +control is set to a value other than <constant>V4L2_CID_ISO_SENSITIVITY_MANUAL +</constant> is undefined, drivers should ignore such requests.</entry> + </row> + <row><entry></entry></row> + + <row id="v4l2-iso-sensitivity-auto-type"> + <entry spanname="id"><constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant> </entry> + <entry>enum v4l2_iso_sensitivity_type</entry> + </row><row><entry spanname="descr">Enables or disables automatic ISO +sensitivity adjustments.</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_CID_ISO_SENSITIVITY_MANUAL</constant> </entry> + <entry>Manual ISO sensitivity.</entry> + </row> + <row> + <entry><constant>V4L2_CID_ISO_SENSITIVITY_AUTO</constant> </entry> + <entry>Automatic ISO sensitivity adjustments.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row><entry></entry></row> + + <row id="v4l2-scene-mode"> + <entry spanname="id"><constant>V4L2_CID_SCENE_MODE</constant> </entry> + <entry>enum v4l2_scene_mode</entry> + </row><row><entry spanname="descr">This control allows to select +scene programs as the camera automatic modes optimized for common shooting +scenes. Within these modes the camera determines best exposure, aperture, +focusing, light metering, white balance and equivalent sensitivity. The +controls of those parameters are influenced by the scene mode control. +An exact behavior in each mode is subject to the camera specification. + +<para>When the scene mode feature is not used, this control should be set to +<constant>V4L2_SCENE_MODE_NONE</constant> to make sure the other possibly +related controls are accessible. The following scene programs are defined: +</para> +</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_SCENE_MODE_NONE</constant> </entry> + <entry>The scene mode feature is disabled.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_BACKLIGHT</constant> </entry> + <entry>Backlight. Compensates for dark shadows when light is + coming from behind a subject, also by automatically turning + on the flash.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_BEACH_SNOW</constant> </entry> + <entry>Beach and snow. This mode compensates for all-white or +bright scenes, which tend to look gray and low contrast, when camera's automatic +exposure is based on an average scene brightness. To compensate, this mode +automatically slightly overexposes the frames. The white balance may also be +adjusted to compensate for the fact that reflected snow looks bluish rather +than white.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_CANDLELIGHT</constant> </entry> + <entry>Candle light. The camera generally raises the ISO +sensitivity and lowers the shutter speed. This mode compensates for relatively +close subject in the scene. The flash is disabled in order to preserve the +ambiance of the light.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_DAWN_DUSK</constant> </entry> + <entry>Dawn and dusk. Preserves the colors seen in low +natural light before dusk and after down. The camera may turn off the flash, +and automatically focus at infinity. It will usually boost saturation and +lower the shutter speed.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_FALL_COLORS</constant> </entry> + <entry>Fall colors. Increases saturation and adjusts white +balance for color enhancement. Pictures of autumn leaves get saturated reds +and yellows.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_FIREWORKS</constant> </entry> + <entry>Fireworks. Long exposure times are used to capture +the expanding burst of light from a firework. The camera may invoke image +stabilization.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_LANDSCAPE</constant> </entry> + <entry>Landscape. The camera may choose a small aperture to +provide deep depth of field and long exposure duration to help capture detail +in dim light conditions. The focus is fixed at infinity. Suitable for distant +and wide scenery.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_NIGHT</constant> </entry> + <entry>Night, also known as Night Landscape. Designed for low +light conditions, it preserves detail in the dark areas without blowing out bright +objects. The camera generally sets itself to a medium-to-high ISO sensitivity, +with a relatively long exposure time, and turns flash off. As such, there will be +increased image noise and the possibility of blurred image.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_PARTY_INDOOR</constant> </entry> + <entry>Party and indoor. Designed to capture indoor scenes +that are lit by indoor background lighting as well as the flash. The camera +usually increases ISO sensitivity, and adjusts exposure for the low light +conditions.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_PORTRAIT</constant> </entry> + <entry>Portrait. The camera adjusts the aperture so that the +depth of field is reduced, which helps to isolate the subject against a smooth +background. Most cameras recognize the presence of faces in the scene and focus +on them. The color hue is adjusted to enhance skin tones. The intensity of the +flash is often reduced.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_SPORTS</constant> </entry> + <entry>Sports. Significantly increases ISO and uses a fast +shutter speed to freeze motion of rapidly-moving subjects. Increased image +noise may be seen in this mode.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_SUNSET</constant> </entry> + <entry>Sunset. Preserves deep hues seen in sunsets and +sunrises. It bumps up the saturation.</entry> + </row> + <row> + <entry><constant>V4L2_SCENE_MODE_TEXT</constant> </entry> + <entry>Text. It applies extra contrast and sharpness, it is +typically a black-and-white mode optimized for readability. Automatic focus +may be switched to close-up mode and this setting may also involve some +lens-distortion correction.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row><entry></entry></row> + + <row> + <entry spanname="id"><constant>V4L2_CID_3A_LOCK</constant></entry> + <entry>bitmask</entry> + </row> + <row> + <entry spanname="descr">This control locks or unlocks the automatic +focus, exposure and white balance. The automatic adjustments can be paused +independently by setting the corresponding lock bit to 1. The camera then retains +the settings until the lock bit is cleared. The following lock bits are defined: +</entry> + </row> + <row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_LOCK_EXPOSURE</constant></entry> + <entry>Automatic exposure adjustments lock.</entry> + </row> + <row> + <entry><constant>V4L2_LOCK_WHITE_BALANCE</constant></entry> + <entry>Automatic white balance adjustments lock.</entry> + </row> + <row> + <entry><constant>V4L2_LOCK_FOCUS</constant></entry> + <entry>Automatic focus lock.</entry> + </row> + </tbody> + </entrytbl> + </row> + <row><entry spanname="descr"> +When a given algorithm is not enabled, drivers should ignore requests +to lock it and should return no error. An example might be an application +setting bit <constant>V4L2_LOCK_WHITE_BALANCE</constant> when the +<constant>V4L2_CID_AUTO_WHITE_BALANCE</constant> control is set to +<constant>FALSE</constant>. The value of this control may be changed +by exposure, white balance or focus controls.</entry> + </row> + <row><entry></entry></row> + </tbody> </tgroup> </table> @@ -2926,7 +3919,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 @@ -2940,7 +3933,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> @@ -3026,7 +4019,7 @@ in Hz. The range and step are driver-specific.</entry> </row> <row> <entry spanname="id"><constant>V4L2_CID_TUNE_PREEMPHASIS</constant> </entry> - <entry>integer</entry> + <entry>enum v4l2_preemphasis</entry> </row> <row id="v4l2-preemphasis"><entry spanname="descr">Configures the pre-emphasis value for broadcasting. A pre-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. @@ -3071,7 +4064,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"> @@ -3138,12 +4131,241 @@ 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> + </section> - <table pgwide="1" frame="none" id="flash-control-id"> - <title>Flash Control IDs</title> + <section id="jpeg-controls"> + <title>JPEG Control Reference</title> + <para>The JPEG class includes controls for common features of JPEG + encoders and decoders. Currently it includes features for codecs + implementing progressive baseline DCT compression process with + Huffman entrophy coding.</para> + <table pgwide="1" frame="none" id="jpeg-control-id"> + <title>JPEG Control IDs</title> <tgroup cols="4"> <colspec colname="c1" colwidth="1*" /> @@ -3162,193 +4384,473 @@ interface and may change in the future.</para> <tbody valign="top"> <row><entry></entry></row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_CLASS</constant></entry> + <entry spanname="id"><constant>V4L2_CID_JPEG_CLASS</constant> </entry> <entry>class</entry> + </row><row><entry spanname="descr">The JPEG class descriptor. Calling + &VIDIOC-QUERYCTRL; for this control will return a description of this + control 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 spanname="id"><constant>V4L2_CID_JPEG_CHROMA_SUBSAMPLING</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 id="v4l2-jpeg-chroma-subsampling"> + <entry spanname="descr">The chroma subsampling factors describe how + each component of an input image is sampled, in respect to maximum + sample rate in each spatial dimension. See <xref linkend="itu-t81"/>, + clause A.1.1. for more details. The <constant> + V4L2_CID_JPEG_CHROMA_SUBSAMPLING</constant> control determines how + Cb and Cr components are downsampled after coverting an input image + from RGB to Y'CbCr color space. + </entry> </row> <row> <entrytbl spanname="descr" cols="2"> <tbody valign="top"> <row> - <entry><constant>V4L2_FLASH_LED_MODE_NONE</constant></entry> - <entry>Off.</entry> + <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_444</constant> + </entry><entry>No chroma subsampling, each pixel has + Y, Cr and Cb values.</entry> + </row> + <row> + <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_422</constant> + </entry><entry>Horizontally subsample Cr, Cb components + by a factor of 2.</entry> </row> <row> - <entry><constant>V4L2_FLASH_LED_MODE_FLASH</constant></entry> - <entry>Flash mode.</entry> + <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_420</constant> + </entry><entry>Subsample Cr, Cb components horizontally + and vertically by 2.</entry> </row> <row> - <entry><constant>V4L2_FLASH_LED_MODE_TORCH</constant></entry> - <entry>Torch mode. See V4L2_CID_FLASH_TORCH_INTENSITY.</entry> + <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_411</constant> + </entry><entry>Horizontally subsample Cr, Cb components + by a factor of 4.</entry> + </row> + <row> + <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_410</constant> + </entry><entry>Subsample Cr, Cb components horizontally + by 4 and vertically by 2.</entry> + </row> + <row> + <entry><constant>V4L2_JPEG_CHROMA_SUBSAMPLING_GRAY</constant> + </entry><entry>Use only luminance component.</entry> </row> </tbody> </entrytbl> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_SOURCE</constant></entry> - <entry>menu</entry> + <entry spanname="id"><constant>V4L2_CID_JPEG_RESTART_INTERVAL</constant> + </entry><entry>integer</entry> + </row> + <row><entry spanname="descr"> + The restart interval determines an interval of inserting RSTm + markers (m = 0..7). The purpose of these markers is to additionally + reinitialize the encoder process, in order to process blocks of + an image independently. + For the lossy compression processes the restart interval unit is + MCU (Minimum Coded Unit) and its value is contained in DRI + (Define Restart Interval) marker. If <constant> + V4L2_CID_JPEG_RESTART_INTERVAL</constant> control is set to 0, + DRI and RSTm markers will not be inserted. + </entry> + </row> + <row id="jpeg-quality-control"> + <entry spanname="id"><constant>V4L2_CID_JPEG_COMPRESSION_QUALITY</constant></entry> + <entry>integer</entry> + </row> + <row> + <entry spanname="descr"> + <constant>V4L2_CID_JPEG_COMPRESSION_QUALITY</constant> control + determines trade-off between image quality and size. + It provides simpler method for applications to control image quality, + without a need for direct reconfiguration of luminance and chrominance + quantization tables. + + In cases where a driver uses quantization tables configured directly + by an application, using interfaces defined elsewhere, <constant> + V4L2_CID_JPEG_COMPRESSION_QUALITY</constant> control should be set + by driver to 0. + + <para>The value range of this control is driver-specific. Only + positive, non-zero values are meaningful. The recommended range + is 1 - 100, where larger values correspond to better image quality. + </para> + </entry> + </row> + <row id="jpeg-active-marker-control"> + <entry spanname="id"><constant>V4L2_CID_JPEG_ACTIVE_MARKER</constant></entry> + <entry>bitmask</entry> </row> - <row id="v4l2-flash-strobe-source"><entry - spanname="descr">Defines the source of the flash LED - strobe.</entry> + <row> + <entry spanname="descr">Specify which JPEG markers are included + in compressed stream. This control is valid only for encoders. + </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> + <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP0</constant></entry> + <entry>Application data segment APP<subscript>0</subscript>.</entry> + </row><row> + <entry><constant>V4L2_JPEG_ACTIVE_MARKER_APP1</constant></entry> + <entry>Application data segment APP<subscript>1</subscript>.</entry> + </row><row> + <entry><constant>V4L2_JPEG_ACTIVE_MARKER_COM</constant></entry> + <entry>Comment segment.</entry> + </row><row> + <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DQT</constant></entry> + <entry>Quantization tables segment.</entry> + </row><row> + <entry><constant>V4L2_JPEG_ACTIVE_MARKER_DHT</constant></entry> + <entry>Huffman tables segment.</entry> </row> </tbody> </entrytbl> </row> + <row><entry></entry></row> + </tbody> + </tgroup> + </table> + <para>For more details about JPEG specification, refer + to <xref linkend="itu-t81"/>, <xref linkend="jfif"/>, + <xref linkend="w3c-jpeg-jfif"/>.</para> + </section> + + <section id="image-source-controls"> + <title>Image Source 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 Image Source control class is intended for low-level + control of image source devices such as image sensors. The + devices feature an analogue to digital converter and a bus + transmitter to transmit the image data out of the device. + </para> + + <table pgwide="1" frame="none" id="image-source-control-id"> + <title>Image Source 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"><constant>V4L2_CID_FLASH_STROBE</constant></entry> - <entry>button</entry> + <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="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> + <entry spanname="id"><constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant></entry> + <entry>class</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> + <entry spanname="descr">The IMAGE_SOURCE class descriptor.</entry> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_STROBE_STATUS</constant></entry> - <entry>boolean</entry> + <entry spanname="id"><constant>V4L2_CID_VBLANK</constant></entry> + <entry>integer</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> + <entry spanname="descr">Vertical blanking. The idle period + after every frame during which no image data is produced. + The unit of vertical blanking is a line. Every line has + length of the image width plus horizontal blanking at the + pixel rate defined by + <constant>V4L2_CID_PIXEL_RATE</constant> control in the + same sub-device.</entry> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_TIMEOUT</constant></entry> + <entry spanname="id"><constant>V4L2_CID_HBLANK</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> + <entry spanname="descr">Horizontal blanking. The idle + period after every line of image data during which no + image data is produced. The unit of horizontal blanking is + pixels.</entry> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_INTENSITY</constant></entry> + <entry spanname="id"><constant>V4L2_CID_ANALOGUE_GAIN</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> + <entry spanname="descr">Analogue gain is gain affecting + all colour components in the pixel matrix. The gain + operation is performed in the analogue domain before A/D + conversion. + </entry> + </row> + <row><entry></entry></row> + </tbody> + </tgroup> + </table> + + </section> + + <section id="image-process-controls"> + <title>Image Process 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 Image Source control class is intended for low-level control of + image processing functions. Unlike + <constant>V4L2_CID_IMAGE_SOURCE_CLASS</constant>, the controls in + this class affect processing the image, and do not control capturing + of it. + </para> + + <table pgwide="1" frame="none" id="image-process-control-id"> + <title>Image Source 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_IMAGE_PROC_CLASS</constant></entry> + <entry>class</entry> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_TORCH_INTENSITY</constant></entry> - <entry>integer</entry> + <entry spanname="descr">The IMAGE_PROC class descriptor.</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> + <entry spanname="id"><constant>V4L2_CID_LINK_FREQ</constant></entry> + <entry>integer menu</entry> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_INDICATOR_INTENSITY</constant></entry> - <entry>integer</entry> + <entry spanname="descr">Data bus frequency. Together with the + media bus pixel code, bus type (clock cycles per sample), the + data bus frequency defines the pixel rate + (<constant>V4L2_CID_PIXEL_RATE</constant>) in the + pixel array (or possibly elsewhere, if the device is not an + image sensor). The frame rate can be calculated from the pixel + clock, image width and height and horizontal and vertical + blanking. While the pixel rate control may be defined elsewhere + than in the subdev containing the pixel array, the frame rate + cannot be obtained from that information. This is because only + on the pixel array it can be assumed that the vertical and + horizontal blanking information is exact: no other blanking is + allowed in the pixel array. The selection of frame rate is + performed by selecting the desired horizontal and vertical + blanking. The unit of this control is Hz. </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_PIXEL_RATE</constant></entry> + <entry>64-bit integer</entry> + </row> + <row> + <entry spanname="descr">Pixel rate in the source pads of + the subdev. This control is read-only and its unit is + pixels / second. + </entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TEST_PATTERN</constant></entry> + <entry>menu</entry> + </row> + <row id="v4l2-test-pattern"> + <entry spanname="descr"> Some capture/display/sensor devices have + the capability to generate test pattern images. These hardware + specific test patterns can be used to test if a device is working + properly.</entry> + </row> + <row><entry></entry></row> + </tbody> + </tgroup> + </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">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> + <entry spanname="descr">The Digital Video class descriptor.</entry> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_FAULT</constant></entry> + <entry spanname="id"><constant>V4L2_CID_DV_TX_HOTPLUG</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> + <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> - <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> - </tbody> - </entrytbl> + <entry spanname="id"><constant>V4L2_CID_DV_TX_RXSENSE</constant></entry> + <entry>bitmask</entry> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_CHARGE</constant></entry> - <entry>boolean</entry> + <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="descr">Enable or disable charging of the xenon - flash capacitor.</entry> + <row> + <entry spanname="id"><constant>V4L2_CID_DV_TX_EDID_PRESENT</constant></entry> + <entry>bitmask</entry> </row> <row> - <entry spanname="id"><constant>V4L2_CID_FLASH_READY</constant></entry> - <entry>boolean</entry> + <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">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> + <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> @@ -3356,12 +4858,76 @@ interface and may change in the future.</para> </table> </section> -</section> - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "common.sgml" -indent-tabs-mode: nil -End: - --> + <section id="fm-rx-controls"> + <title>FM Receiver Control Reference</title> + + <para>The FM Receiver (FM_RX) class includes controls for common features of + FM Reception capable devices.</para> + + <table pgwide="1" frame="none" id="fm-rx-control-id"> + <title>FM_RX 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_FM_RX_CLASS</constant> </entry> + <entry>class</entry> + </row><row><entry spanname="descr">The FM_RX class +descriptor. Calling &VIDIOC-QUERYCTRL; for this control will return a +description of this control class.</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_RDS_RECEPTION</constant> </entry> + <entry>boolean</entry> + </row><row><entry spanname="descr">Enables/disables RDS + reception by the radio tuner</entry> + </row> + <row> + <entry spanname="id"><constant>V4L2_CID_TUNE_DEEMPHASIS</constant> </entry> + <entry>enum v4l2_deemphasis</entry> + </row> + <row id="v4l2-deemphasis"><entry spanname="descr">Configures the de-emphasis value for reception. +A de-emphasis filter is applied to the broadcast to accentuate the high audio frequencies. +Depending on the region, a time constant of either 50 or 75 useconds is used. The enum v4l2_deemphasis +defines possible values for de-emphasis. Here they are:</entry> + </row><row> + <entrytbl spanname="descr" cols="2"> + <tbody valign="top"> + <row> + <entry><constant>V4L2_DEEMPHASIS_DISABLED</constant> </entry> + <entry>No de-emphasis is applied.</entry> + </row> + <row> + <entry><constant>V4L2_DEEMPHASIS_50_uS</constant> </entry> + <entry>A de-emphasis of 50 uS is used.</entry> + </row> + <row> + <entry><constant>V4L2_DEEMPHASIS_75_uS</constant> </entry> + <entry>A de-emphasis of 75 uS is used.</entry> + </row> + </tbody> + </entrytbl> + + </row> + <row><entry></entry></row> + </tbody> + </tgroup> + </table> + + </section> +</section> diff --git a/Documentation/DocBook/media/v4l/dev-capture.xml b/Documentation/DocBook/media/v4l/dev-capture.xml index 2237c661f26a..e1c5f9406d6a 100644 --- a/Documentation/DocBook/media/v4l/dev-capture.xml +++ b/Documentation/DocBook/media/v4l/dev-capture.xml @@ -108,11 +108,3 @@ linkend="mmap">memory mapping</link> or <link linkend="userp">user pointer</link>) I/O. See <xref linkend="io" /> for details.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-codec.xml b/Documentation/DocBook/media/v4l/dev-codec.xml index 6e156dc45b94..ff44c16fc080 100644 --- a/Documentation/DocBook/media/v4l/dev-codec.xml +++ b/Documentation/DocBook/media/v4l/dev-codec.xml @@ -1,26 +1,27 @@ <title>Codec Interface</title> - <note> - <title>Suspended</title> - - <para>This interface has been be suspended from the V4L2 API -implemented in Linux 2.6 until we have more experience with codec -device interfaces.</para> - </note> - <para>A V4L2 codec can compress, decompress, transform, or otherwise -convert video data from one format into another format, in memory. -Applications send data to be converted to the driver through a -&func-write; call, and receive the converted data through a -&func-read; call. For efficiency a driver may also support streaming -I/O.</para> +convert video data from one format into another format, in memory. Typically +such devices are memory-to-memory devices (i.e. devices with the +<constant>V4L2_CAP_VIDEO_M2M</constant> or <constant>V4L2_CAP_VIDEO_M2M_MPLANE</constant> +capability set). +</para> + + <para>A memory-to-memory video node acts just like a normal video node, but it +supports both output (sending frames from memory to the codec hardware) and +capture (receiving the processed frames from the codec hardware into memory) +stream I/O. An application will have to setup the stream +I/O for both sides and finally call &VIDIOC-STREAMON; for both capture and output +to start the codec.</para> - <para>[to do]</para> + <para>Video compression codecs use the MPEG controls to setup their codec parameters +(note that the MPEG controls actually support many more codecs than just MPEG). +See <xref linkend="mpeg-controls"></xref>.</para> - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> + <para>Memory-to-memory devices can often be used as a shared resource: you can +open the video node multiple times, each application setting up their own codec properties +that are local to the file handle, and each can use it independently from the others. +The driver will arbitrate access to the codec and reprogram it whenever another file +handler gets access. This is different from the usual video node behavior where the video properties +are global to the device (i.e. changing something through one file handle is visible +through another file handle).</para> diff --git a/Documentation/DocBook/media/v4l/dev-effect.xml b/Documentation/DocBook/media/v4l/dev-effect.xml index 9c243beba0e6..2350a67c0710 100644 --- a/Documentation/DocBook/media/v4l/dev-effect.xml +++ b/Documentation/DocBook/media/v4l/dev-effect.xml @@ -15,11 +15,3 @@ receive the result data either with &func-read; and &func-write; functions, or through the streaming I/O mechanism.</para> <para>[to do]</para> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-event.xml b/Documentation/DocBook/media/v4l/dev-event.xml index f14ae3fe107c..19f4becfae34 100644 --- a/Documentation/DocBook/media/v4l/dev-event.xml +++ b/Documentation/DocBook/media/v4l/dev-event.xml @@ -41,11 +41,3 @@ intermediate step leading up to that information. See the documentation for the event you want to subscribe to whether this is applicable for that event or not.</para> </listitem> </orderedlist></para> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-osd.xml b/Documentation/DocBook/media/v4l/dev-osd.xml index c9a68a2ccd33..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 @@ -154,11 +147,3 @@ data flow. For more information see <xref linkend="crop" />.</para> however the framebuffer interface of the driver may support the <constant>FBIOBLANK</constant> ioctl.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-output.xml b/Documentation/DocBook/media/v4l/dev-output.xml index 919e22c53854..9130a3dc7880 100644 --- a/Documentation/DocBook/media/v4l/dev-output.xml +++ b/Documentation/DocBook/media/v4l/dev-output.xml @@ -104,11 +104,3 @@ linkend="mmap">memory mapping</link> or <link linkend="userp">user pointer</link>) I/O. See <xref linkend="io" /> for details.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-overlay.xml b/Documentation/DocBook/media/v4l/dev-overlay.xml index 92513cf79150..40d1d7681439 100644 --- a/Documentation/DocBook/media/v4l/dev-overlay.xml +++ b/Documentation/DocBook/media/v4l/dev-overlay.xml @@ -369,11 +369,3 @@ reasons. <!-- video4linux-list@redhat.com on 22 Oct 2002 subject <para>To start or stop the frame buffer overlay applications call the &VIDIOC-OVERLAY; ioctl.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-radio.xml b/Documentation/DocBook/media/v4l/dev-radio.xml index 73aa90b45b34..3e6ac73b36af 100644 --- a/Documentation/DocBook/media/v4l/dev-radio.xml +++ b/Documentation/DocBook/media/v4l/dev-radio.xml @@ -47,11 +47,3 @@ depending on the selected frequency. The &VIDIOC-G-TUNER; or &VIDIOC-G-MODULATOR; ioctl reports the supported frequency range.</para> </section> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml index c5a70bdfaf27..b788c72c885e 100644 --- a/Documentation/DocBook/media/v4l/dev-raw-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-raw-vbi.xml @@ -337,11 +337,3 @@ an &EBUSY; if the required hardware resources are temporarily unavailable, for example the device is already in use by another process.</para> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-rds.xml b/Documentation/DocBook/media/v4l/dev-rds.xml index 2427f54397e7..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 @@ -29,10 +29,10 @@ returned by the &VIDIOC-QUERYCAP; ioctl. Any tuner that supports RDS will set the <constant>V4L2_TUNER_CAP_RDS</constant> flag in the <structfield>capability</structfield> field of &v4l2-tuner;. If the driver only passes RDS blocks without interpreting the data -the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be +the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set, see <link linkend="reading-rds-data">Reading RDS data</link>. For future use the -flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> has also been +flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> has also been defined. However, a driver for a radio tuner with this capability does not yet exist, so if you are planning to write such a driver you should discuss this on the linux-media mailing list: &v4l-ml;.</para> @@ -52,9 +52,9 @@ field of &v4l2-modulator;. In order to enable the RDS transmission one must set the <constant>V4L2_TUNER_SUB_RDS</constant> bit in the <structfield>txsubchans</structfield> field of &v4l2-modulator;. If the driver only passes RDS blocks without interpreting the data -the <constant>V4L2_TUNER_SUB_RDS_BLOCK_IO</constant> flag has to be set. If the +the <constant>V4L2_TUNER_CAP_RDS_BLOCK_IO</constant> flag has to be set. If the tuner is capable of handling RDS entities like program identification codes and radio -text, the flag <constant>V4L2_TUNER_SUB_RDS_CONTROLS</constant> should be set, +text, the flag <constant>V4L2_TUNER_CAP_RDS_CONTROLS</constant> should be set, see <link linkend="writing-rds-data">Writing RDS data</link> and <link linkend="fm-tx-controls">FM Transmitter Control Reference</link>.</para> </section> @@ -194,11 +194,3 @@ as follows:</para> </tgroup> </table> </section> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml index 69e789fa7f7b..548f8ea28dee 100644 --- a/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml +++ b/Documentation/DocBook/media/v4l/dev-sliced-vbi.xml @@ -697,12 +697,3 @@ Sliced VBI services</link> for a description of the line payload.</entry> </section> </section> - - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index 0916a7343a16..d15aaf83f56f 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -76,11 +76,12 @@ <wordasword>format</wordasword> means the combination of media bus data format, frame width and frame height.</para></note> - <para>Image formats are typically negotiated on video capture and output - devices using the <link linkend="crop">cropping and scaling</link> ioctls. - The driver is responsible for configuring every block in the video pipeline - according to the requested format at the pipeline input and/or - output.</para> + <para>Image formats are typically negotiated on video capture and + output devices using the format and <link + linkend="vidioc-subdev-g-selection">selection</link> ioctls. The + driver is responsible for configuring every block in the video + pipeline according to the requested format at the pipeline input + and/or output.</para> <para>For complex devices, such as often found in embedded systems, identical image sizes at the output of a pipeline can be achieved using @@ -275,12 +276,12 @@ </para> </section> - <section> - <title>Cropping and scaling</title> + <section id="v4l2-subdev-selections"> + <title>Selections: cropping, scaling and composition</title> <para>Many sub-devices support cropping frames on their input or output pads (or possible even on both). Cropping is used to select the area of - interest in an image, typically on a video sensor or video decoder. It can + interest in an image, typically on an image sensor or a video decoder. It can also be used as part of digital zoom implementations to select the area of the image that will be scaled up.</para> @@ -288,26 +289,179 @@ &v4l2-rect; by the coordinates of the top left corner and the rectangle size. Both the coordinates and sizes are expressed in pixels.</para> - <para>The crop rectangle is retrieved and set using the - &VIDIOC-SUBDEV-G-CROP; and &VIDIOC-SUBDEV-S-CROP; ioctls. Like for pad - formats, drivers store try and active crop rectangles. The format - negotiation mechanism applies to crop settings as well.</para> - - <para>On input pads, cropping is applied relatively to the current pad - format. The pad format represents the image size as received by the - sub-device from the previous block in the pipeline, and the crop rectangle - represents the sub-image that will be transmitted further inside the - sub-device for processing. The crop rectangle be entirely containted - inside the input image size.</para> - - <para>Input crop rectangle are reset to their default value when the input - image format is modified. Drivers should use the input image size as the - crop rectangle default value, but hardware requirements may prevent this. - </para> + <para>As for pad formats, drivers store try and active + rectangles for the selection targets <xref + linkend="v4l2-selections-common" />.</para> + + <para>On sink pads, cropping is applied relative to the + current pad format. The pad format represents the image size as + received by the sub-device from the previous block in the + pipeline, and the crop rectangle represents the sub-image that + will be transmitted further inside the sub-device for + processing.</para> + + <para>The scaling operation changes the size of the image by + scaling it to new dimensions. The scaling ratio isn't specified + explicitly, but is implied from the original and scaled image + sizes. Both sizes are represented by &v4l2-rect;.</para> + + <para>Scaling support is optional. When supported by a subdev, + the crop rectangle on the subdev's sink pad is scaled to the + size configured using the &VIDIOC-SUBDEV-S-SELECTION; IOCTL + using <constant>V4L2_SEL_TGT_COMPOSE</constant> + selection target on the same pad. If the subdev supports scaling + but not composing, the top and left values are not used and must + always be set to zero.</para> + + <para>On source pads, cropping is similar to sink pads, with the + exception that the source size from which the cropping is + performed, is the COMPOSE rectangle on the sink pad. In both + sink and source pads, the crop rectangle must be entirely + contained inside the source image size for the crop + operation.</para> + + <para>The drivers should always use the closest possible + rectangle the user requests on all selection targets, unless + specifically told otherwise. + <constant>V4L2_SEL_FLAG_GE</constant> and + <constant>V4L2_SEL_FLAG_LE</constant> flags may be + used to round the image size either up or down. <xref + linkend="v4l2-selection-flags" /></para> + </section> + + <section> + <title>Types of selection targets</title> - <para>Cropping behaviour on output pads is not defined.</para> + <section> + <title>Actual targets</title> + + <para>Actual targets (without a postfix) reflect the actual + hardware configuration at any point of time. There is a BOUNDS + target corresponding to every actual target.</para> + </section> + + <section> + <title>BOUNDS targets</title> + + <para>BOUNDS targets is the smallest rectangle that contains all + valid actual rectangles. It may not be possible to set the actual + rectangle as large as the BOUNDS rectangle, however. This may be + because e.g. a sensor's pixel array is not rectangular but + cross-shaped or round. The maximum size may also be smaller than the + BOUNDS rectangle.</para> + </section> </section> + + <section> + <title>Order of configuration and format propagation</title> + + <para>Inside subdevs, the order of image processing steps will + always be from the sink pad towards the source pad. This is also + reflected in the order in which the configuration must be + performed by the user: the changes made will be propagated to + any subsequent stages. If this behaviour is not desired, the + user must set + <constant>V4L2_SEL_FLAG_KEEP_CONFIG</constant> flag. This + flag causes no propagation of the changes are allowed in any + circumstances. This may also cause the accessed rectangle to be + adjusted by the driver, depending on the properties of the + underlying hardware.</para> + + <para>The coordinates to a step always refer to the actual size + of the previous step. The exception to this rule is the source + compose rectangle, which refers to the sink compose bounds + rectangle --- if it is supported by the hardware.</para> + + <orderedlist> + <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.</para></listitem> + + <listitem><para>Sink pad actual crop selection. The sink pad crop + defines the crop performed to the sink pad format.</para></listitem> + + <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.</para></listitem> + + <listitem><para>Source pad actual crop selection. Crop on the source + pad defines crop performed to the image in the sink compose + bounds rectangle.</para></listitem> + + <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.</para></listitem> + </orderedlist> + + <para>Accessing any of the above rectangles not supported by the + subdev will return <constant>EINVAL</constant>. Any rectangle + referring to a previous unsupported rectangle coordinates will + instead refer to the previous supported rectangle. For example, + if sink crop is not supported, the compose selection will refer + to the sink pad format dimensions instead.</para> + + <figure id="subdev-image-processing-crop"> + <title>Image processing in subdevs: simple crop example</title> + <mediaobject> + <imageobject> + <imagedata fileref="subdev-image-processing-crop.svg" + format="SVG" scale="200" /> + </imageobject> + </mediaobject> + </figure> + + <para>In the above example, the subdev supports cropping on its + sink pad. To configure it, the user sets the media bus format on + the subdev's sink pad. Now the actual crop rectangle can be set + on the sink pad --- the location and size of this rectangle + reflect the location and size of a rectangle to be cropped from + the sink format. The size of the sink crop rectangle will also + be the size of the format of the subdev's source pad.</para> + + <figure id="subdev-image-processing-scaling-multi-source"> + <title>Image processing in subdevs: scaling with multiple sources</title> + <mediaobject> + <imageobject> + <imagedata fileref="subdev-image-processing-scaling-multi-source.svg" + format="SVG" scale="200" /> + </imageobject> + </mediaobject> + </figure> + + <para>In this example, the subdev is capable of first cropping, + then scaling and finally cropping for two source pads + individually from the resulting scaled image. The location of + the scaled image in the cropped image is ignored in sink compose + target. Both of the locations of the source crop rectangles + refer to the sink scaling rectangle, independently cropping an + area at location specified by the source crop rectangle from + it.</para> + + <figure id="subdev-image-processing-full"> + <title>Image processing in subdevs: scaling and composition + with multiple sinks and sources</title> + <mediaobject> + <imageobject> + <imagedata fileref="subdev-image-processing-full.svg" + format="SVG" scale="200" /> + </imageobject> + </mediaobject> + </figure> + + <para>The subdev driver supports two sink pads and two source + pads. The images from both of the sink pads are individually + cropped, then scaled and further composed on the composition + bounds rectangle. From that, two independent streams are cropped + and sent out of the subdev from the source pads.</para> + + </section> + </section> &sub-subdev-formats; diff --git a/Documentation/DocBook/media/v4l/dev-teletext.xml b/Documentation/DocBook/media/v4l/dev-teletext.xml index 414b1cfff9f4..bd21c64d70f3 100644 --- a/Documentation/DocBook/media/v4l/dev-teletext.xml +++ b/Documentation/DocBook/media/v4l/dev-teletext.xml @@ -27,11 +27,3 @@ kernel 2.6.37.</para> <para>Modern devices all use the <link linkend="raw-vbi">raw</link> or <link linkend="sliced">sliced</link> VBI API.</para> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/driver.xml b/Documentation/DocBook/media/v4l/driver.xml index 1f7eea5c4ec3..7c6638bacedb 100644 --- a/Documentation/DocBook/media/v4l/driver.xml +++ b/Documentation/DocBook/media/v4l/driver.xml @@ -116,7 +116,7 @@ my_suspend (struct pci_dev * pci_dev, return 0; /* a negative value on error, 0 on success. */ } -static void __devexit +static void my_remove (struct pci_dev * pci_dev) { my_device *my = pci_get_drvdata (pci_dev); @@ -124,7 +124,7 @@ my_remove (struct pci_dev * pci_dev) /* Describe me. */ } -static int __devinit +static int my_probe (struct pci_dev * pci_dev, const struct pci_device_id * pci_id) { @@ -157,7 +157,7 @@ my_pci_driver = { .id_table = my_pci_device_ids, .probe = my_probe, - .remove = __devexit_p (my_remove), + .remove = my_remove, /* Power management functions. */ .suspend = my_suspend, @@ -198,11 +198,3 @@ devices with the videodev module.</para> <para>to do</para> </section> --> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-close.xml b/Documentation/DocBook/media/v4l/func-close.xml index dfb41cbbbec3..232920d2f3c6 100644 --- a/Documentation/DocBook/media/v4l/func-close.xml +++ b/Documentation/DocBook/media/v4l/func-close.xml @@ -60,11 +60,3 @@ descriptor.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-ioctl.xml b/Documentation/DocBook/media/v4l/func-ioctl.xml index 2de64be706f5..4394184a1a6d 100644 --- a/Documentation/DocBook/media/v4l/func-ioctl.xml +++ b/Documentation/DocBook/media/v4l/func-ioctl.xml @@ -69,11 +69,3 @@ their respective function and parameters are specified in <xref the parameter remains unmodified.</para> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-mmap.xml b/Documentation/DocBook/media/v4l/func-mmap.xml index 786732b64bbd..f31ad71bf301 100644 --- a/Documentation/DocBook/media/v4l/func-mmap.xml +++ b/Documentation/DocBook/media/v4l/func-mmap.xml @@ -181,11 +181,3 @@ complete the request.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-munmap.xml b/Documentation/DocBook/media/v4l/func-munmap.xml index e2c4190f9bb6..860d49ca54a5 100644 --- a/Documentation/DocBook/media/v4l/func-munmap.xml +++ b/Documentation/DocBook/media/v4l/func-munmap.xml @@ -74,11 +74,3 @@ mapped yet.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-open.xml b/Documentation/DocBook/media/v4l/func-open.xml index 7595d07a8c72..cf64e207c3ee 100644 --- a/Documentation/DocBook/media/v4l/func-open.xml +++ b/Documentation/DocBook/media/v4l/func-open.xml @@ -111,11 +111,3 @@ system has been reached.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-poll.xml b/Documentation/DocBook/media/v4l/func-poll.xml index ec3c718f5963..85cad8bff5ba 100644 --- a/Documentation/DocBook/media/v4l/func-poll.xml +++ b/Documentation/DocBook/media/v4l/func-poll.xml @@ -117,11 +117,3 @@ than <constant>OPEN_MAX</constant>.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-read.xml b/Documentation/DocBook/media/v4l/func-read.xml index a5089bf8873d..e218bbfbd362 100644 --- a/Documentation/DocBook/media/v4l/func-read.xml +++ b/Documentation/DocBook/media/v4l/func-read.xml @@ -179,11 +179,3 @@ type of device.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-select.xml b/Documentation/DocBook/media/v4l/func-select.xml index b6713623181f..e12a60d9bd85 100644 --- a/Documentation/DocBook/media/v4l/func-select.xml +++ b/Documentation/DocBook/media/v4l/func-select.xml @@ -128,11 +128,3 @@ zero or greater than <constant>FD_SETSIZE</constant>.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/func-write.xml b/Documentation/DocBook/media/v4l/func-write.xml index 2c09c09371c3..575207885726 100644 --- a/Documentation/DocBook/media/v4l/func-write.xml +++ b/Documentation/DocBook/media/v4l/func-write.xml @@ -126,11 +126,3 @@ type of device.</para> </variablelist> </refsect1> </refentry> - -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> 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 3f47df1aa54a..2c4c068dde83 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -331,7 +331,7 @@ application until one or more buffers can be dequeued. By default outgoing queue. When the <constant>O_NONBLOCK</constant> flag was given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> returns immediately with an &EAGAIN; when no buffer is available. The -&func-select; or &func-poll; function are always available.</para> +&func-select; or &func-poll; functions are always available.</para> <para>To start and stop capturing or output applications call the &VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctl. Note @@ -472,6 +472,165 @@ rest should be evident.</para> </footnote></para> </section> + <section id="dmabuf"> + <title>Streaming I/O (DMA buffer importing)</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 DMABUF framework provides a generic method for sharing buffers +between multiple devices. Device drivers that support DMABUF can export a DMA +buffer to userspace as a file descriptor (known as the exporter role), import a +DMA buffer from userspace using a file descriptor previously exported for a +different or the same device (known as the importer role), or both. This +section describes the DMABUF importer role API in V4L2.</para> + + <para>Refer to <link linkend="vidioc-expbuf">DMABUF exporting</link> for +details about exporting V4L2 buffers as DMABUF file descriptors.</para> + +<para>Input and output devices support the streaming I/O method when the +<constant>V4L2_CAP_STREAMING</constant> flag in the +<structfield>capabilities</structfield> field of &v4l2-capability; returned by +the &VIDIOC-QUERYCAP; ioctl is set. Whether importing DMA buffers through +DMABUF file descriptors is supported is determined by calling the +&VIDIOC-REQBUFS; ioctl with the memory type set to +<constant>V4L2_MEMORY_DMABUF</constant>.</para> + + <para>This I/O method is dedicated to sharing DMA buffers between different +devices, which may be V4L devices or other video-related devices (e.g. DRM). +Buffers (planes) are allocated by a driver on behalf of an application. Next, +these buffers are exported to the application as file descriptors using an API +which is specific for an allocator driver. Only such file descriptor are +exchanged. The descriptors and meta-information are passed in &v4l2-buffer; (or +in &v4l2-plane; in the multi-planar API case). The driver must be switched +into DMABUF I/O mode by calling the &VIDIOC-REQBUFS; with the desired buffer +type.</para> + + <example> + <title>Initiating streaming I/O with DMABUF file descriptors</title> + + <programlisting> +&v4l2-requestbuffers; reqbuf; + +memset(&reqbuf, 0, sizeof (reqbuf)); +reqbuf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; +reqbuf.memory = V4L2_MEMORY_DMABUF; +reqbuf.count = 1; + +if (ioctl(fd, &VIDIOC-REQBUFS;, &reqbuf) == -1) { + if (errno == EINVAL) + printf("Video capturing or DMABUF streaming is not supported\n"); + else + perror("VIDIOC_REQBUFS"); + + exit(EXIT_FAILURE); +} + </programlisting> + </example> + + <para>The buffer (plane) file descriptor is passed on the fly with the +&VIDIOC-QBUF; ioctl. In case of multiplanar buffers, every plane can be +associated with a different DMABUF descriptor. Although buffers are commonly +cycled, applications can pass a different DMABUF descriptor at each +<constant>VIDIOC_QBUF</constant> call.</para> + + <example> + <title>Queueing DMABUF using single plane API</title> + + <programlisting> +int buffer_queue(int v4lfd, int index, int dmafd) +{ + &v4l2-buffer; buf; + + memset(&buf, 0, sizeof buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE; + buf.memory = V4L2_MEMORY_DMABUF; + buf.index = index; + buf.m.fd = dmafd; + + if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { + perror("VIDIOC_QBUF"); + return -1; + } + + return 0; +} + </programlisting> + </example> + + <example> + <title>Queueing DMABUF using multi plane API</title> + + <programlisting> +int buffer_queue_mp(int v4lfd, int index, int dmafd[], int n_planes) +{ + &v4l2-buffer; buf; + &v4l2-plane; planes[VIDEO_MAX_PLANES]; + int i; + + memset(&buf, 0, sizeof buf); + buf.type = V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE; + buf.memory = V4L2_MEMORY_DMABUF; + buf.index = index; + buf.m.planes = planes; + buf.length = n_planes; + + memset(&planes, 0, sizeof planes); + + for (i = 0; i < n_planes; ++i) + buf.m.planes[i].m.fd = dmafd[i]; + + if (ioctl(v4lfd, &VIDIOC-QBUF;, &buf) == -1) { + perror("VIDIOC_QBUF"); + return -1; + } + + return 0; +} + </programlisting> + </example> + + <para>Captured or displayed buffers are dequeued with the +&VIDIOC-DQBUF; ioctl. The driver can unlock the buffer at any +time between the completion of the DMA and this ioctl. The memory is +also unlocked when &VIDIOC-STREAMOFF; is called, &VIDIOC-REQBUFS;, or +when the device is closed.</para> + + <para>For capturing applications it is customary to enqueue a +number of empty buffers, to start capturing and enter the read loop. +Here the application waits until a filled buffer can be dequeued, and +re-enqueues the buffer when the data is no longer needed. Output +applications fill and enqueue buffers, when enough buffers are stacked +up output is started. In the write loop, when the application +runs out of free buffers it must wait until an empty buffer can be +dequeued and reused. Two methods exist to suspend execution of the +application until one or more buffers can be dequeued. By default +<constant>VIDIOC_DQBUF</constant> blocks when no buffer is in the +outgoing queue. When the <constant>O_NONBLOCK</constant> flag was +given to the &func-open; function, <constant>VIDIOC_DQBUF</constant> +returns immediately with an &EAGAIN; when no buffer is available. The +&func-select; and &func-poll; functions are always available.</para> + + <para>To start and stop capturing or displaying applications call the +&VIDIOC-STREAMON; and &VIDIOC-STREAMOFF; ioctls. Note that +<constant>VIDIOC_STREAMOFF</constant> removes all buffers from both queues and +unlocks all buffers as a side effect. Since there is no notion of doing +anything "now" on a multitasking system, if an application needs to synchronize +with another event it should examine the &v4l2-buffer; +<structfield>timestamp</structfield> of captured buffers, or set the field +before enqueuing buffers for output.</para> + + <para>Drivers implementing DMABUF importing I/O must support the +<constant>VIDIOC_REQBUFS</constant>, <constant>VIDIOC_QBUF</constant>, +<constant>VIDIOC_DQBUF</constant>, <constant>VIDIOC_STREAMON</constant> and +<constant>VIDIOC_STREAMOFF</constant> ioctls, and the +<function>select()</function> and <function>poll()</function> functions.</para> + + </section> + <section id="async"> <title>Asynchronous I/O</title> @@ -543,12 +702,13 @@ and can range from zero to the number of buffers allocated with the &VIDIOC-REQBUFS; ioctl (&v4l2-requestbuffers; <structfield>count</structfield>) minus one.</entry> </row> <row> - <entry>&v4l2-buf-type;</entry> + <entry>__u32</entry> <entry><structfield>type</structfield></entry> <entry></entry> <entry>Type of the buffer, same as &v4l2-format; <structfield>type</structfield> or &v4l2-requestbuffers; -<structfield>type</structfield>, set by the application.</entry> +<structfield>type</structfield>, set by the application. See <xref +linkend="v4l2-buf-type" /></entry> </row> <row> <entry>__u32</entry> @@ -568,7 +728,7 @@ refers to an input stream, applications when an output stream.</entry> linkend="buffer-flags" />.</entry> </row> <row> - <entry>&v4l2-field;</entry> + <entry>__u32</entry> <entry><structfield>field</structfield></entry> <entry></entry> <entry>Indicates the field order of the image in the @@ -581,17 +741,19 @@ applications when an output stream.</entry> <entry>struct timeval</entry> <entry><structfield>timestamp</structfield></entry> <entry></entry> - <entry><para>For input streams this is the -system time (as returned by the <function>gettimeofday()</function> -function) when the first data byte was captured. For output streams -the data will not be displayed before this time, secondary to the -nominal frame rate determined by the current video standard in -enqueued order. Applications can for example zero this field to -display frames as soon as possible. The driver stores the time at -which the first data byte was actually sent out in the -<structfield>timestamp</structfield> field. This permits -applications to monitor the drift between the video and system -clock.</para></entry> + <entry><para>For input streams this is time when the first data + byte was captured, as returned by the + <function>clock_gettime()</function> function for the relevant + clock id; see <constant>V4L2_BUF_FLAG_TIMESTAMP_*</constant> in + <xref linkend="buffer-flags" />. For output streams the data + will not be displayed before this time, secondary to the nominal + frame rate determined by the current video standard in enqueued + order. Applications can for example zero this field to display + frames as soon as possible. The driver stores the time at which + the first data byte was actually sent out in the + <structfield>timestamp</structfield> field. This permits + applications to monitor the drift between the video and system + clock.</para></entry> </row> <row> <entry>&v4l2-timecode;</entry> @@ -612,8 +774,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 @@ -630,11 +792,12 @@ bandwidth. These devices identify by not enumerating any video standards, see <xref linkend="standard" />.</para></entry> </row> <row> - <entry>&v4l2-memory;</entry> + <entry>__u32</entry> <entry><structfield>memory</structfield></entry> <entry></entry> <entry>This field must be set by applications and/or drivers -in accordance with the selected I/O method.</entry> +in accordance with the selected I/O method. See <xref linkend="v4l2-memory" + /></entry> </row> <row> <entry>union</entry> @@ -671,32 +834,36 @@ memory, set by the application. See <xref linkend="userp" /> for details. <structname>v4l2_buffer</structname> structure.</entry> </row> <row> + <entry></entry> + <entry>int</entry> + <entry><structfield>fd</structfield></entry> + <entry>For the single-plane API and when +<structfield>memory</structfield> is <constant>V4L2_MEMORY_DMABUF</constant> this +is the file descriptor associated with a DMABUF buffer.</entry> + </row> + <row> <entry>__u32</entry> <entry><structfield>length</structfield></entry> <entry></entry> <entry>Size of the buffer (not the payload) in bytes for the - single-planar API. For the multi-planar API should contain the - number of elements in the <structfield>planes</structfield> array. + single-planar API. For the multi-planar API the application sets + this to the number of elements in the <structfield>planes</structfield> + array. The driver will fill in the actual number of valid elements in + that array. </entry> </row> <row> <entry>__u32</entry> - <entry><structfield>input</structfield></entry> + <entry><structfield>reserved2</structfield></entry> <entry></entry> - <entry>Some video capture drivers support rapid and -synchronous video input changes, a function useful for example in -video surveillance applications. For this purpose applications set the -<constant>V4L2_BUF_FLAG_INPUT</constant> flag, and this field to the -number of a video input as in &v4l2-input; field -<structfield>index</structfield>.</entry> + <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> @@ -738,7 +905,7 @@ should set this to 0.</entry> </row> <row> <entry></entry> - <entry>__unsigned long</entry> + <entry>unsigned long</entry> <entry><structfield>userptr</structfield></entry> <entry>When the memory type in the containing &v4l2-buffer; is <constant>V4L2_MEMORY_USERPTR</constant>, this is a userspace @@ -746,6 +913,15 @@ should set this to 0.</entry> </entry> </row> <row> + <entry></entry> + <entry>int</entry> + <entry><structfield>fd</structfield></entry> + <entry>When the memory type in the containing &v4l2-buffer; is + <constant>V4L2_MEMORY_DMABUF</constant>, this is a file + descriptor associated with a DMABUF buffer, similar to the + <structfield>fd</structfield> field in &v4l2-buffer;.</entry> + </row> + <row> <entry>__u32</entry> <entry><structfield>data_offset</structfield></entry> <entry></entry> @@ -827,14 +1003,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> @@ -921,13 +1090,6 @@ Drivers set or clear this flag when the <constant>VIDIOC_DQBUF</constant> ioctl is called.</entry> </row> <row> - <entry><constant>V4L2_BUF_FLAG_INPUT</constant></entry> - <entry>0x0200</entry> - <entry>The <structfield>input</structfield> field is valid. -Applications set or clear this flag before calling the -<constant>VIDIOC_QBUF</constant> ioctl.</entry> - </row> - <row> <entry><constant>V4L2_BUF_FLAG_PREPARED</constant></entry> <entry>0x0400</entry> <entry>The buffer has been prepared for I/O and can be queued by the @@ -939,7 +1101,7 @@ application. Drivers set or clear this flag when the </row> <row> <entry><constant>V4L2_BUF_FLAG_NO_CACHE_INVALIDATE</constant></entry> - <entry>0x0400</entry> + <entry>0x0800</entry> <entry>Caches do not have to be invalidated for this buffer. Typically applications shall use this flag if the data captured in the buffer is not going to be touched by the CPU, instead the buffer will, probably, be @@ -948,12 +1110,47 @@ passed on to a DMA-capable hardware unit for further processing or output. </row> <row> <entry><constant>V4L2_BUF_FLAG_NO_CACHE_CLEAN</constant></entry> - <entry>0x0800</entry> + <entry>0x1000</entry> <entry>Caches do not have to be cleaned for this buffer. Typically applications shall use this flag for output buffers if the data in this buffer has not been created by the CPU but by some DMA-capable unit, in which case caches have not been used.</entry> </row> + <row> + <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MASK</constant></entry> + <entry>0xe000</entry> + <entry>Mask for timestamp types below. To test the + timestamp type, mask out bits not belonging to timestamp + type by performing a logical and operation with buffer + flags and timestamp mask.</entry> + </row> + <row> + <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_UNKNOWN</constant></entry> + <entry>0x0000</entry> + <entry>Unknown timestamp type. This type is used by + drivers before Linux 3.9 and may be either monotonic (see + below) or realtime (wall clock). Monotonic clock has been + favoured in embedded systems whereas most of the drivers + use the realtime clock. Either kinds of timestamps are + available in user space via + <function>clock_gettime(2)</function> using clock IDs + <constant>CLOCK_MONOTONIC</constant> and + <constant>CLOCK_REALTIME</constant>, respectively.</entry> + </row> + <row> + <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_MONOTONIC</constant></entry> + <entry>0x2000</entry> + <entry>The buffer timestamp has been taken from the + <constant>CLOCK_MONOTONIC</constant> clock. To access the + same clock outside V4L2, use + <function>clock_gettime(2)</function> .</entry> + </row> + <row> + <entry><constant>V4L2_BUF_FLAG_TIMESTAMP_COPY</constant></entry> + <entry>0x4000</entry> + <entry>The CAPTURE buffer timestamp has been taken from the + corresponding OUTPUT buffer. This flag applies only to mem2mem devices.</entry> + </row> </tbody> </tgroup> </table> @@ -980,6 +1177,12 @@ pointer</link> I/O.</entry> <entry>3</entry> <entry>[to do]</entry> </row> + <row> + <entry><constant>V4L2_MEMORY_DMABUF</constant></entry> + <entry>4</entry> + <entry>The buffer is used for <link linkend="dmabuf">DMA shared +buffer</link> I/O.</entry> + </row> </tbody> </tgroup> </table> @@ -1282,11 +1485,3 @@ line, top field first. The bottom field is transmitted first.</entry> </mediaobject> </figure> </section> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/libv4l.xml b/Documentation/DocBook/media/v4l/libv4l.xml index 3cb10ec51929..d3b71e20003c 100644 --- a/Documentation/DocBook/media/v4l/libv4l.xml +++ b/Documentation/DocBook/media/v4l/libv4l.xml @@ -158,10 +158,3 @@ still don't use libv4l.</para> </section> </section> -<!-- -Local Variables: -mode: sgml -sgml-parent-document: "v4l2.sgml" -indent-tabs-mode: nil -End: ---> diff --git a/Documentation/DocBook/media/v4l/lirc_device_interface.xml b/Documentation/DocBook/media/v4l/lirc_device_interface.xml index 8d7eb6bf6312..34cada2ca710 100644 --- a/Documentation/DocBook/media/v4l/lirc_device_interface.xml +++ b/Documentation/DocBook/media/v4l/lirc_device_interface.xml @@ -46,7 +46,9 @@ describing an IR signal are read from the chardev.</para> values. Pulses and spaces are only marked implicitly by their position. The data must start and end with a pulse, therefore, the data must always include an uneven number of samples. The write function must block until the data has -been transmitted by the hardware.</para> +been transmitted by the hardware. If more data is provided than the hardware +can send, the driver returns EINVAL.</para> + </section> <section id="lirc_ioctl"> diff --git a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml index 576b68b33f2c..116c301656e0 100644 --- a/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml +++ b/Documentation/DocBook/media/v4l/media-ioc-enum-entities.xml @@ -272,6 +272,16 @@ <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_LENS</constant></entry> <entry>Lens controller</entry> </row> + <row> + <entry><constant>MEDIA_ENT_T_V4L2_SUBDEV_DECODER</constant></entry> + <entry>Video decoder, the basic function of the video decoder is to + accept analogue video from a wide variety of sources such as + broadcast, DVD players, cameras and video cassette recorders, in + either NTSC, PAL or HD format and still occasionally SECAM, separate + it into its component parts, luminance and chrominance, and output + it in some digital video standard, with appropriate embedded timing + signals.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/pixfmt-grey.xml b/Documentation/DocBook/media/v4l/pixfmt-grey.xml index 3b72bc6b2de7..bee970d3f76d 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-grey.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-grey.xml @@ -60,11 +60,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-m420.xml b/Documentation/DocBook/media/v4l/pixfmt-m420.xml index ce4bc019e5c0..aadae92c5d04 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-m420.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-m420.xml @@ -137,11 +137,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12.xml index 873f67035181..84dd4fd7cb80 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv12.xml @@ -141,11 +141,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml index c9e166d9ded8..f3a3d459fcdf 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv12m.xml @@ -1,11 +1,13 @@ - <refentry id="V4L2-PIX-FMT-NV12M"> + <refentry> <refmeta> - <refentrytitle>V4L2_PIX_FMT_NV12M ('NV12M')</refentrytitle> + <refentrytitle>V4L2_PIX_FMT_NV12M ('NM12'), V4L2_PIX_FMT_NV21M ('NM21'), V4L2_PIX_FMT_NV12MT_16X16</refentrytitle> &manvol; </refmeta> <refnamediv> - <refname> <constant>V4L2_PIX_FMT_NV12M</constant></refname> - <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> with planes + <refname id="V4L2-PIX-FMT-NV12M"><constant>V4L2_PIX_FMT_NV12M</constant></refname> + <refname id="V4L2-PIX-FMT-NV21M"><constant>V4L2_PIX_FMT_NV21M</constant></refname> + <refname id="V4L2-PIX-FMT-NV12MT-16X16"><constant>V4L2_PIX_FMT_NV12MT_16X16</constant></refname> + <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV12</constant> and <constant>V4L2_PIX_FMT_NV21</constant> with planes non contiguous in memory. </refpurpose> </refnamediv> <refsect1> @@ -22,7 +24,12 @@ The CbCr plane is the same width, in bytes, as the Y plane (and of the image), but is half as tall in pixels. Each CbCr pair belongs to four pixels. For example, Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, -Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. </para> +Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. +<constant>V4L2_PIX_FMT_NV12MT_16X16</constant> is the tiled version of +<constant>V4L2_PIX_FMT_NV12M</constant> with 16x16 macroblock tiles. Here pixels +are arranged in 16x16 2D tiles and tiles are arranged in linear order in memory. +<constant>V4L2_PIX_FMT_NV21M</constant> is the same as <constant>V4L2_PIX_FMT_NV12M</constant> +except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> <para><constant>V4L2_PIX_FMT_NV12M</constant> is intended to be used only in drivers and applications that support the multi-planar API, @@ -144,11 +151,3 @@ CbCr plane has as many pad bytes after its rows.</para> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml b/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml index 7a2855a526c1..8a70a1707b7a 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv12mt.xml @@ -24,7 +24,7 @@ into 64x32 macroblocks. The CbCr plane has the same width, in bytes, as the Y plane (and the image), but is half as tall in pixels. The chroma plane is also grouped into 64x32 macroblocks.</para> <para>Width of the buffer has to be aligned to the multiple of 128, and -height alignment is 32. Every four adjactent buffers - two horizontally and two +height alignment is 32. Every four adjacent buffers - two horizontally and two vertically are grouped together and are located in memory in Z or flipped Z order. </para> <para>Layout of macroblocks in memory is presented in the following @@ -64,11 +64,3 @@ layout of macroblocks</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv16.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16.xml index 26094035fc04..8ae1f8a810d0 100644 --- a/Documentation/DocBook/media/v4l/pixfmt-nv16.xml +++ b/Documentation/DocBook/media/v4l/pixfmt-nv16.xml @@ -164,11 +164,3 @@ pixel image</title> </example> </refsect1> </refentry> - - <!-- -Local Variables: -mode: sgml -sgml-parent-document: "pixfmt.sgml" -indent-tabs-mode: nil -End: - --> diff --git a/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml b/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml new file mode 100644 index 000000000000..c51d5a4cda09 --- /dev/null +++ b/Documentation/DocBook/media/v4l/pixfmt-nv16m.xml @@ -0,0 +1,171 @@ + <refentry> + <refmeta> + <refentrytitle>V4L2_PIX_FMT_NV16M ('NM16'), V4L2_PIX_FMT_NV61M ('NM61')</refentrytitle> + &manvol; + </refmeta> + <refnamediv> + <refname id="V4L2-PIX-FMT-NV16M"><constant>V4L2_PIX_FMT_NV16M</constant></refname> + <refname id="V4L2-PIX-FMT-NV61M"><constant>V4L2_PIX_FMT_NV61M</constant></refname> + <refpurpose>Variation of <constant>V4L2_PIX_FMT_NV16</constant> and <constant>V4L2_PIX_FMT_NV61</constant> with planes + non contiguous in memory. </refpurpose> + </refnamediv> + <refsect1> + <title>Description</title> + + <para>This is a multi-planar, two-plane version of the YUV 4:2:0 format. +The three components are separated into two sub-images or planes. +<constant>V4L2_PIX_FMT_NV16M</constant> differs from <constant>V4L2_PIX_FMT_NV16 +</constant> in that the two planes are non-contiguous in memory, i.e. the chroma +plane does not necessarily immediately follows the luma plane. +The luminance data occupies the first plane. The Y plane has one byte per pixel. +In the second plane there is chrominance data with alternating chroma samples. +The CbCr plane is the same width and height, in bytes, as the Y plane. +Each CbCr pair belongs to four pixels. For example, +Cb<subscript>0</subscript>/Cr<subscript>0</subscript> belongs to +Y'<subscript>00</subscript>, Y'<subscript>01</subscript>, +Y'<subscript>10</subscript>, Y'<subscript>11</subscript>. +<constant>V4L2_PIX_FMT_NV61M</constant> is the same as <constant>V4L2_PIX_FMT_NV16M</constant> +except the Cb and Cr bytes are swapped, the CrCb plane starts with a Cr byte.</para> + + <para><constant>V4L2_PIX_FMT_NV16M</constant> and +<constant>V4L2_PIX_FMT_NV61M</constant> are 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_NV16M</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>Cb<subscript>00</subscript></entry> + <entry>Cr<subscript>00</subscript></entry> + <entry>Cb<subscript>02</subscript></entry> + <entry>Cr<subscript>02</subscript></entry> + </row> + <row> + <entry>start1 + 4:</entry> + <entry>Cb<subscript>10</subscript></entry> + <entry>Cr<subscript>10</subscript></entry> + <entry>Cb<subscript>12</subscript></entry> + <entry>Cr<subscript>12</subscript></entry> + </row> + <row> + <entry>start1 + 8:</entry> + <entry>Cb<subscript>20</subscript></entry> + <entry>Cr<subscript>20</subscript></entry> + <entry>Cb<subscript>22</subscript></entry> + <entry>Cr<subscript>22</subscript></entry> + </row> + <row> + <entry>start1 + 12:</entry> + <entry>Cb<subscript>30</subscript></entry> + <entry>Cr<subscript>30</subscript></entry> + <entry>Cb<subscript>32</subscript></entry> + <entry>Cr<subscript>32</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></e |
