diff options
Diffstat (limited to 'Documentation/DocBook')
| -rw-r--r-- | Documentation/DocBook/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/alsa-driver-api.tmpl | 31 | ||||
| -rw-r--r-- | Documentation/DocBook/crypto-API.tmpl | 1253 | ||||
| -rw-r--r-- | Documentation/DocBook/drm.tmpl | 434 | ||||
| -rw-r--r-- | Documentation/DocBook/media/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/media/dvb/dvbproperty.xml | 4 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/biblio.xml | 85 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/compat.xml | 16 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/dev-subdev.xml | 109 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/io.xml | 5 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/pixfmt.xml | 1310 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/selections-common.xml | 16 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/subdev-formats.xml | 326 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/v4l2.xml | 11 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-enuminput.xml | 8 | ||||
| -rw-r--r-- | Documentation/DocBook/media/v4l/vidioc-enumoutput.xml | 8 | ||||
| -rw-r--r-- | Documentation/DocBook/uio-howto.tmpl | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/writing-an-alsa-driver.tmpl | 23 |
18 files changed, 2986 insertions, 659 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index bec06659e0eb..9c7d92d03f62 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -15,7 +15,7 @@ DOCBOOKS := z8530book.xml device-drivers.xml \ 80211.xml debugobjects.xml sh.xml regulator.xml \ alsa-driver-api.xml writing-an-alsa-driver.xml \ tracepoint.xml drm.xml media_api.xml w1.xml \ - writing_musb_glue_layer.xml + writing_musb_glue_layer.xml crypto-API.xml include Documentation/DocBook/media/Makefile diff --git a/Documentation/DocBook/alsa-driver-api.tmpl b/Documentation/DocBook/alsa-driver-api.tmpl index 0230a96f0564..71f9246127ec 100644 --- a/Documentation/DocBook/alsa-driver-api.tmpl +++ b/Documentation/DocBook/alsa-driver-api.tmpl @@ -57,6 +57,7 @@ !Esound/core/pcm.c !Esound/core/pcm_lib.c !Esound/core/pcm_native.c +!Iinclude/sound/pcm.h </sect1> <sect1><title>PCM Format Helpers</title> !Esound/core/pcm_misc.c @@ -64,6 +65,10 @@ <sect1><title>PCM Memory Management</title> !Esound/core/pcm_memory.c </sect1> + <sect1><title>PCM DMA Engine API</title> +!Esound/core/pcm_dmaengine.c +!Iinclude/sound/dmaengine_pcm.h + </sect1> </chapter> <chapter><title>Control/Mixer API</title> <sect1><title>General Control Interface</title> @@ -91,12 +96,38 @@ !Esound/core/info.c </sect1> </chapter> + <chapter><title>Compress Offload</title> + <sect1><title>Compress Offload API</title> +!Esound/core/compress_offload.c +!Iinclude/uapi/sound/compress_offload.h +!Iinclude/uapi/sound/compress_params.h +!Iinclude/sound/compress_driver.h + </sect1> + </chapter> + <chapter><title>ASoC</title> + <sect1><title>ASoC Core API</title> +!Iinclude/sound/soc.h +!Esound/soc/soc-core.c +!Esound/soc/soc-cache.c +!Esound/soc/soc-devres.c +!Esound/soc/soc-io.c +!Esound/soc/soc-pcm.c + </sect1> + <sect1><title>ASoC DAPM API</title> +!Esound/soc/soc-dapm.c + </sect1> + <sect1><title>ASoC DMA Engine API</title> +!Esound/soc/soc-generic-dmaengine-pcm.c + </sect1> + </chapter> <chapter><title>Miscellaneous Functions</title> <sect1><title>Hardware-Dependent Devices API</title> !Esound/core/hwdep.c </sect1> <sect1><title>Jack Abstraction Layer API</title> +!Iinclude/sound/jack.h !Esound/core/jack.c +!Esound/soc/soc-jack.c </sect1> <sect1><title>ISA DMA Helpers</title> !Esound/core/isadma.c diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl new file mode 100644 index 000000000000..c763d30f4893 --- /dev/null +++ b/Documentation/DocBook/crypto-API.tmpl @@ -0,0 +1,1253 @@ +<?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="KernelCryptoAPI"> + <bookinfo> + <title>Linux Kernel Crypto API</title> + + <authorgroup> + <author> + <firstname>Stephan</firstname> + <surname>Mueller</surname> + <affiliation> + <address> + <email>smueller@chronox.de</email> + </address> + </affiliation> + </author> + <author> + <firstname>Marek</firstname> + <surname>Vasut</surname> + <affiliation> + <address> + <email>marek@denx.de</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2014</year> + <holder>Stephan Mueller</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>Kernel Crypto API Interface Specification</title> + + <sect1><title>Introduction</title> + + <para> + The kernel crypto API offers a rich set of cryptographic ciphers as + well as other data transformation mechanisms and methods to invoke + these. This document contains a description of the API and provides + example code. + </para> + + <para> + To understand and properly use the kernel crypto API a brief + explanation of its structure is given. Based on the architecture, + the API can be separated into different components. Following the + architecture specification, hints to developers of ciphers are + provided. Pointers to the API function call documentation are + given at the end. + </para> + + <para> + The kernel crypto API refers to all algorithms as "transformations". + Therefore, a cipher handle variable usually has the name "tfm". + Besides cryptographic operations, the kernel crypto API also knows + compression transformations and handles them the same way as ciphers. + </para> + + <para> + The kernel crypto API serves the following entity types: + + <itemizedlist> + <listitem> + <para>consumers requesting cryptographic services</para> + </listitem> + <listitem> + <para>data transformation implementations (typically ciphers) + that can be called by consumers using the kernel crypto + API</para> + </listitem> + </itemizedlist> + </para> + + <para> + This specification is intended for consumers of the kernel crypto + API as well as for developers implementing ciphers. This API + specification, however, does not discusses all API calls available + to data transformation implementations (i.e. implementations of + ciphers and other transformations (such as CRC or even compression + algorithms) that can register with the kernel crypto API). + </para> + + <para> + Note: The terms "transformation" and cipher algorithm are used + interchangably. + </para> + </sect1> + + <sect1><title>Terminology</title> + <para> + The transformation implementation is an actual code or interface + to hardware which implements a certain transformation with precisely + defined behavior. + </para> + + <para> + The transformation object (TFM) is an instance of a transformation + implementation. There can be multiple transformation objects + associated with a single transformation implementation. Each of + those transformation objects is held by a crypto API consumer or + another transformation. Transformation object is allocated when a + crypto API consumer requests a transformation implementation. + The consumer is then provided with a structure, which contains + a transformation object (TFM). + </para> + + <para> + The structure that contains transformation objects may also be + referred to as a "cipher handle". Such a cipher handle is always + subject to the following phases that are reflected in the API calls + applicable to such a cipher handle: + </para> + + <orderedlist> + <listitem> + <para>Initialization of a cipher handle.</para> + </listitem> + <listitem> + <para>Execution of all intended cipher operations applicable + for the handle where the cipher handle must be furnished to + every API call.</para> + </listitem> + <listitem> + <para>Destruction of a cipher handle.</para> + </listitem> + </orderedlist> + + <para> + When using the initialization API calls, a cipher handle is + created and returned to the consumer. Therefore, please refer + to all initialization API calls that refer to the data + structure type a consumer is expected to receive and subsequently + to use. The initialization API calls have all the same naming + conventions of crypto_alloc_*. + </para> + + <para> + The transformation context is private data associated with + the transformation object. + </para> + </sect1> + </chapter> + + <chapter id="Architecture"><title>Kernel Crypto API Architecture</title> + <sect1><title>Cipher algorithm types</title> + <para> + The kernel crypto API provides different API calls for the + following cipher types: + + <itemizedlist> + <listitem><para>Symmetric ciphers</para></listitem> + <listitem><para>AEAD ciphers</para></listitem> + <listitem><para>Message digest, including keyed message digest</para></listitem> + <listitem><para>Random number generation</para></listitem> + <listitem><para>User space interface</para></listitem> + </itemizedlist> + </para> + </sect1> + + <sect1><title>Ciphers And Templates</title> + <para> + The kernel crypto API provides implementations of single block + ciphers and message digests. In addition, the kernel crypto API + provides numerous "templates" that can be used in conjunction + with the single block ciphers and message digests. Templates + include all types of block chaining mode, the HMAC mechanism, etc. + </para> + + <para> + Single block ciphers and message digests can either be directly + used by a caller or invoked together with a template to form + multi-block ciphers or keyed message digests. + </para> + + <para> + A single block cipher may even be called with multiple templates. + However, templates cannot be used without a single cipher. + </para> + + <para> + See /proc/crypto and search for "name". For example: + + <itemizedlist> + <listitem><para>aes</para></listitem> + <listitem><para>ecb(aes)</para></listitem> + <listitem><para>cmac(aes)</para></listitem> + <listitem><para>ccm(aes)</para></listitem> + <listitem><para>rfc4106(gcm(aes))</para></listitem> + <listitem><para>sha1</para></listitem> + <listitem><para>hmac(sha1)</para></listitem> + <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem> + </itemizedlist> + </para> + + <para> + In these examples, "aes" and "sha1" are the ciphers and all + others are the templates. + </para> + </sect1> + + <sect1><title>Synchronous And Asynchronous Operation</title> + <para> + The kernel crypto API provides synchronous and asynchronous + API operations. + </para> + + <para> + When using the synchronous API operation, the caller invokes + a cipher operation which is performed synchronously by the + kernel crypto API. That means, the caller waits until the + cipher operation completes. Therefore, the kernel crypto API + calls work like regular function calls. For synchronous + operation, the set of API calls is small and conceptually + similar to any other crypto library. + </para> + + <para> + Asynchronous operation is provided by the kernel crypto API + which implies that the invocation of a cipher operation will + complete almost instantly. That invocation triggers the + cipher operation but it does not signal its completion. Before + invoking a cipher operation, the caller must provide a callback + function the kernel crypto API can invoke to signal the + completion of the cipher operation. Furthermore, the caller + must ensure it can handle such asynchronous events by applying + appropriate locking around its data. The kernel crypto API + does not perform any special serialization operation to protect + the caller's data integrity. + </para> + </sect1> + + <sect1><title>Crypto API Cipher References And Priority</title> + <para> + A cipher is referenced by the caller with a string. That string + has the following semantics: + + <programlisting> + template(single block cipher) + </programlisting> + + where "template" and "single block cipher" is the aforementioned + template and single block cipher, respectively. If applicable, + additional templates may enclose other templates, such as + + <programlisting> + template1(template2(single block cipher))) + </programlisting> + </para> + + <para> + The kernel crypto API may provide multiple implementations of a + template or a single block cipher. For example, AES on newer + Intel hardware has the following implementations: AES-NI, + assembler implementation, or straight C. Now, when using the + string "aes" with the kernel crypto API, which cipher + implementation is used? The answer to that question is the + priority number assigned to each cipher implementation by the + kernel crypto API. When a caller uses the string to refer to a + cipher during initialization of a cipher handle, the kernel + crypto API looks up all implementations providing an + implementation with that name and selects the implementation + with the highest priority. + </para> + + <para> + Now, a caller may have the need to refer to a specific cipher + implementation and thus does not want to rely on the + priority-based selection. To accommodate this scenario, the + kernel crypto API allows the cipher implementation to register + a unique name in addition to common names. When using that + unique name, a caller is therefore always sure to refer to + the intended cipher implementation. + </para> + + <para> + The list of available ciphers is given in /proc/crypto. However, + that list does not specify all possible permutations of + templates and ciphers. Each block listed in /proc/crypto may + contain the following information -- if one of the components + listed as follows are not applicable to a cipher, it is not + displayed: + </para> + + <itemizedlist> + <listitem> + <para>name: the generic name of the cipher that is subject + to the priority-based selection -- this name can be used by + the cipher allocation API calls (all names listed above are + examples for such generic names)</para> + </listitem> + <listitem> + <para>driver: the unique name of the cipher -- this name can + be used by the cipher allocation API calls</para> + </listitem> + <listitem> + <para>module: the kernel module providing the cipher + implementation (or "kernel" for statically linked ciphers)</para> + </listitem> + <listitem> + <para>priority: the priority value of the cipher implementation</para> + </listitem> + <listitem> + <para>refcnt: the reference count of the respective cipher + (i.e. the number of current consumers of this cipher)</para> + </listitem> + <listitem> + <para>selftest: specification whether the self test for the + cipher passed</para> + </listitem> + <listitem> + <para>type: + <itemizedlist> + <listitem> + <para>blkcipher for synchronous block ciphers</para> + </listitem> + <listitem> + <para>ablkcipher for asynchronous block ciphers</para> + </listitem> + <listitem> + <para>cipher for single block ciphers that may be used with + an additional template</para> + </listitem> + <listitem> + <para>shash for synchronous message digest</para> + </listitem> + <listitem> + <para>ahash for asynchronous message digest</para> + </listitem> + <listitem> + <para>aead for AEAD cipher type</para> + </listitem> + <listitem> + <para>compression for compression type transformations</para> + </listitem> + <listitem> + <para>rng for random number generator</para> + </listitem> + <listitem> + <para>givcipher for cipher with associated IV generator + (see the geniv entry below for the specification of the + IV generator type used by the cipher implementation)</para> + </listitem> + </itemizedlist> + </para> + </listitem> + <listitem> + <para>blocksize: blocksize of cipher in bytes</para> + </listitem> + <listitem> + <para>keysize: key size in bytes</para> + </listitem> + <listitem> + <para>ivsize: IV size in bytes</para> + </listitem> + <listitem> + <para>seedsize: required size of seed data for random number + generator</para> + </listitem> + <listitem> + <para>digestsize: output size of the message digest</para> + </listitem> + <listitem> + <para>geniv: IV generation type: + <itemizedlist> + <listitem> + <para>eseqiv for encrypted sequence number based IV + generation</para> + </listitem> + <listitem> + <para>seqiv for sequence number based IV generation</para> + </listitem> + <listitem> + <para>chainiv for chain iv generation</para> + </listitem> + <listitem> + <para><builtin> is a marker that the cipher implements + IV generation and handling as it is specific to the given + cipher</para> + </listitem> + </itemizedlist> + </para> + </listitem> + </itemizedlist> + </sect1> + + <sect1><title>Key Sizes</title> + <para> + When allocating a cipher handle, the caller only specifies the + cipher type. Symmetric ciphers, however, typically support + multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). + These key sizes are determined with the length of the provided + key. Thus, the kernel crypto API does not provide a separate + way to select the particular symmetric cipher key size. + </para> + </sect1> + + <sect1><title>Cipher Allocation Type And Masks</title> + <para> + The different cipher handle allocation functions allow the + specification of a type and mask flag. Both parameters have + the following meaning (and are therefore not covered in the + subsequent sections). + </para> + + <para> + The type flag specifies the type of the cipher algorithm. + The caller usually provides a 0 when the caller wants the + default handling. Otherwise, the caller may provide the + following selections which match the the aforementioned + cipher types: + </para> + + <itemizedlist> + <listitem> + <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with + Associated Data (MAC)</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block + cipher packed together with an IV generator (see geniv field + in the /proc/crypto listing for the known IV generators)</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> + </listitem> + <listitem> + <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of + CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / + decompression instead of performing the operation on one + segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace + CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para> + </listitem> + </itemizedlist> + + <para> + The mask flag restricts the type of cipher. The only allowed + flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function + to asynchronous ciphers. Usually, a caller provides a 0 for the + mask flag. + </para> + + <para> + When the caller provides a mask and type specification, the + caller limits the search the kernel crypto API can perform for + a suitable cipher implementation for the given cipher name. + That means, even when a caller uses a cipher name that exists + during its initialization call, the kernel crypto API may not + select it due to the used type and mask field. + </para> + </sect1> + </chapter> + + <chapter id="Development"><title>Developing Cipher Algorithms</title> + <sect1><title>Registering And Unregistering Transformation</title> + <para> + There are three distinct types of registration functions in + the Crypto API. One is used to register a generic cryptographic + transformation, while the other two are specific to HASH + transformations and COMPRESSion. We will discuss the latter + two in a separate chapter, here we will only look at the + generic ones. + </para> + + <para> + Before discussing the register functions, the data structure + to be filled with each, struct crypto_alg, must be considered + -- see below for a description of this data structure. + </para> + + <para> + The generic registration functions can be found in + include/linux/crypto.h and their definition can be seen below. + The former function registers a single transformation, while + the latter works on an array of transformation descriptions. + The latter is useful when registering transformations in bulk. + </para> + + <programlisting> + int crypto_register_alg(struct crypto_alg *alg); + int crypto_register_algs(struct crypto_alg *algs, int count); + </programlisting> + + <para> + The counterparts to those functions are listed below. + </para> + + <programlisting> + int crypto_unregister_alg(struct crypto_alg *alg); + int crypto_unregister_algs(struct crypto_alg *algs, int count); + </programlisting> + + <para> + Notice that both registration and unregistration functions + do return a value, so make sure to handle errors. A return + code of zero implies success. Any return code < 0 implies + an error. + </para> + + <para> + The bulk registration / unregistration functions require + that struct crypto_alg is an array of count size. These + functions simply loop over that array and register / + unregister each individual algorithm. If an error occurs, + the loop is terminated at the offending algorithm definition. + That means, the algorithms prior to the offending algorithm + are successfully registered. Note, the caller has no way of + knowing which cipher implementations have successfully + registered. If this is important to know, the caller should + loop through the different implementations using the single + instance *_alg functions for each individual implementation. + </para> + </sect1> + + <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title> + <para> + Example of transformations: aes, arc4, ... + </para> + + <para> + This section describes the simplest of all transformation + implementations, that being the CIPHER type used for symmetric + ciphers. The CIPHER type is used for transformations which + operate on exactly one block at a time and there are no + dependencies between blocks at all. + </para> + + <sect2><title>Registration specifics</title> + <para> + The registration of [CIPHER] algorithm is specific in that + struct crypto_alg field .cra_type is empty. The .cra_u.cipher + has to be filled in with proper callbacks to implement this + transformation. + </para> + + <para> + See struct cipher_alg below. + </para> + </sect2> + + <sect2><title>Cipher Definition With struct cipher_alg</title> + <para> + Struct cipher_alg defines a single block cipher. + </para> + + <para> + Here are schematics of how these functions are called when + operated from other part of the kernel. Note that the + .cia_setkey() call might happen before or after any of these + schematics happen, but must not happen during any of these + are in-flight. + </para> + + <para> + <programlisting> + KEY ---. PLAINTEXT ---. + v v + .cia_setkey() -> .cia_encrypt() + | + '-----> CIPHERTEXT + </programlisting> + </para> + + <para> + Please note that a pattern where .cia_setkey() is called + multiple times is also valid: + </para> + + <para> + <programlisting> + + KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. + v v v v + .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() + | | + '---> CIPHERTEXT1 '---> CIPHERTEXT2 + </programlisting> + </para> + + </sect2> + </sect1> + + <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title> + <para> + Example of transformations: cbc(aes), ecb(arc4), ... + </para> + + <para> + This section describes the multi-block cipher transformation + implementations for both synchronous [BLKCIPHER] and + asynchronous [ABLKCIPHER] case. The multi-block ciphers are + used for transformations which operate on scatterlists of + data supplied to the transformation functions. They output + the result into a scatterlist of data as well. + </para> + + <sect2><title>Registration Specifics</title> + + <para> + The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms + is one of the most standard procedures throughout the crypto API. + </para> + + <para> + Note, if a cipher implementation requires a proper alignment + of data, the caller should use the functions of + crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask() + respectively to identify a memory alignment mask. The kernel + crypto API is able to process requests that are unaligned. + This implies, however, additional overhead as the kernel + crypto API needs to perform the realignment of the data which + may imply moving of data. + </para> + </sect2> + + <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title> + <para> + Struct blkcipher_alg defines a synchronous block cipher whereas + struct ablkcipher_alg defines an asynchronous block cipher. + </para> + + <para> + Please refer to the single block cipher description for schematics + of the block cipher usage. The usage patterns are exactly the same + for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER]. + </para> + </sect2> + + <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> + <para> + There are a couple of specifics to the [ABLKCIPHER] interface. + </para> + + <para> + First of all, some of the drivers will want to use the + Generic ScatterWalk in case the hardware needs to be fed + separate chunks of the scatterlist which contains the + plaintext and will contain the ciphertext. Please refer + to the ScatterWalk interface offered by the Linux kernel + scatter / gather list implementation. + </para> + </sect2> + </sect1> + + <sect1><title>Hashing [HASH]</title> + + <para> + Example of transformations: crc32, md5, sha1, sha256,... + </para> + + <sect2><title>Registering And Unregistering The Transformation</title> + + <para> + There are multiple ways to register a HASH transformation, + depending on whether the transformation is synchronous [SHASH] + or asynchronous [AHASH] and the amount of HASH transformations + we are registering. You can find the prototypes defined in + include/crypto/internal/hash.h: + </para> + + <programlisting> + int crypto_register_ahash(struct ahash_alg *alg); + + int crypto_register_shash(struct shash_alg *alg); + int crypto_register_shashes(struct shash_alg *algs, int count); + </programlisting> + + <para> + The respective counterparts for unregistering the HASH + transformation are as follows: + </para> + + <programlisting> + int crypto_unregister_ahash(struct ahash_alg *alg); + + int crypto_unregister_shash(struct shash_alg *alg); + int crypto_unregister_shashes(struct shash_alg *algs, int count); + </programlisting> + </sect2> + + <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title> + <para> + Here are schematics of how these functions are called when + operated from other part of the kernel. Note that the .setkey() + call might happen before or after any of these schematics happen, + but must not happen during any of these are in-flight. Please note + that calling .init() followed immediately by .finish() is also a + perfectly valid transformation. + </para> + + <programlisting> + I) DATA -----------. + v + .init() -> .update() -> .final() ! .update() might not be called + ^ | | at all in this scenario. + '----' '---> HASH + + II) DATA -----------.-----------. + v v + .init() -> .update() -> .finup() ! .update() may not be called + ^ | | at all in this scenario. + '----' '---> HASH + + III) DATA -----------. + v + .digest() ! The entire process is handled + | by the .digest() call. + '---------------> HASH + </programlisting> + + <para> + Here is a schematic of how the .export()/.import() functions are + called when used from another part of the kernel. + </para> + + <programlisting> + KEY--. DATA--. + v v ! .update() may not be called + .setkey() -> .init() -> .update() -> .export() at all in this scenario. + ^ | | + '-----' '--> PARTIAL_HASH + + ----------- other transformations happen here ----------- + + PARTIAL_HASH--. DATA1--. + v v + .import -> .update() -> .final() ! .update() may not be called + ^ | | at all in this scenario. + '----' '--> HASH1 + + PARTIAL_HASH--. DATA2-. + v v + .import -> .finup() + | + '---------------> HASH2 + </programlisting> + </sect2> + + <sect2><title>Specifics Of Asynchronous HASH Transformation</title> + <para> + Some of the drivers will want to use the Generic ScatterWalk + in case the implementation needs to be fed separate chunks of the + scatterlist which contains the input data. The buffer containing + the resulting hash will always be properly aligned to + .cra_alignmask so there is no need to worry about this. + </para> + </sect2> + </sect1> + </chapter> + + <chapter id="API"><title>Programming Interface</title> + <sect1><title>Block Cipher Context Data Structures</title> +!Pinclude/linux/crypto.h Block Cipher Context Data Structures +!Finclude/linux/crypto.h aead_request + </sect1> + <sect1><title>Block Cipher Algorithm Definitions</title> +!Pinclude/linux/crypto.h Block Cipher Algorithm Definitions +!Finclude/linux/crypto.h crypto_alg +!Finclude/linux/crypto.h ablkcipher_alg +!Finclude/linux/crypto.h aead_alg +!Finclude/linux/crypto.h blkcipher_alg +!Finclude/linux/crypto.h cipher_alg +!Finclude/linux/crypto.h rng_alg + </sect1> + <sect1><title>Asynchronous Block Cipher API</title> +!Pinclude/linux/crypto.h Asynchronous Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_ablkcipher +!Finclude/linux/crypto.h crypto_free_ablkcipher +!Finclude/linux/crypto.h crypto_has_ablkcipher +!Finclude/linux/crypto.h crypto_ablkcipher_ivsize +!Finclude/linux/crypto.h crypto_ablkcipher_blocksize +!Finclude/linux/crypto.h crypto_ablkcipher_setkey +!Finclude/linux/crypto.h crypto_ablkcipher_reqtfm +!Finclude/linux/crypto.h crypto_ablkcipher_encrypt +!Finclude/linux/crypto.h crypto_ablkcipher_decrypt + </sect1> + <sect1><title>Asynchronous Cipher Request Handle</title> +!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle +!Finclude/linux/crypto.h crypto_ablkcipher_reqsize +!Finclude/linux/crypto.h ablkcipher_request_set_tfm +!Finclude/linux/crypto.h ablkcipher_request_alloc +!Finclude/linux/crypto.h ablkcipher_request_free +!Finclude/linux/crypto.h ablkcipher_request_set_callback +!Finclude/linux/crypto.h ablkcipher_request_set_crypt + </sect1> + <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> +!Pinclude/linux/crypto.h Authenticated Encryption With Associated Data (AEAD) Cipher API +!Finclude/linux/crypto.h crypto_alloc_aead +!Finclude/linux/crypto.h crypto_free_aead +!Finclude/linux/crypto.h crypto_aead_ivsize +!Finclude/linux/crypto.h crypto_aead_authsize +!Finclude/linux/crypto.h crypto_aead_blocksize +!Finclude/linux/crypto.h crypto_aead_setkey +!Finclude/linux/crypto.h crypto_aead_setauthsize +!Finclude/linux/crypto.h crypto_aead_encrypt +!Finclude/linux/crypto.h crypto_aead_decrypt + </sect1> + <sect1><title>Asynchronous AEAD Request Handle</title> +!Pinclude/linux/crypto.h Asynchronous AEAD Request Handle +!Finclude/linux/crypto.h crypto_aead_reqsize +!Finclude/linux/crypto.h aead_request_set_tfm +!Finclude/linux/crypto.h aead_request_alloc +!Finclude/linux/crypto.h aead_request_free +!Finclude/linux/crypto.h aead_request_set_callback +!Finclude/linux/crypto.h aead_request_set_crypt +!Finclude/linux/crypto.h aead_request_set_assoc + </sect1> + <sect1><title>Synchronous Block Cipher API</title> +!Pinclude/linux/crypto.h Synchronous Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_blkcipher +!Finclude/linux/crypto.h crypto_free_blkcipher +!Finclude/linux/crypto.h crypto_has_blkcipher +!Finclude/linux/crypto.h crypto_blkcipher_name +!Finclude/linux/crypto.h crypto_blkcipher_ivsize +!Finclude/linux/crypto.h crypto_blkcipher_blocksize +!Finclude/linux/crypto.h crypto_blkcipher_setkey +!Finclude/linux/crypto.h crypto_blkcipher_encrypt +!Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv +!Finclude/linux/crypto.h crypto_blkcipher_decrypt +!Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv +!Finclude/linux/crypto.h crypto_blkcipher_set_iv +!Finclude/linux/crypto.h crypto_blkcipher_get_iv + </sect1> + <sect1><title>Single Block Cipher API</title> +!Pinclude/linux/crypto.h Single Block Cipher API +!Finclude/linux/crypto.h crypto_alloc_cipher +!Finclude/linux/crypto.h crypto_free_cipher +!Finclude/linux/crypto.h crypto_has_cipher +!Finclude/linux/crypto.h crypto_cipher_blocksize +!Finclude/linux/crypto.h crypto_cipher_setkey +!Finclude/linux/crypto.h crypto_cipher_encrypt_one +!Finclude/linux/crypto.h crypto_cipher_decrypt_one + </sect1> + <sect1><title>Synchronous Message Digest API</title> +!Pinclude/linux/crypto.h Synchronous Message Digest API +!Finclude/linux/crypto.h crypto_alloc_hash +!Finclude/linux/crypto.h crypto_free_hash +!Finclude/linux/crypto.h crypto_has_hash +!Finclude/linux/crypto.h crypto_hash_blocksize +!Finclude/linux/crypto.h crypto_hash_digestsize +!Finclude/linux/crypto.h crypto_hash_init +!Finclude/linux/crypto.h crypto_hash_update +!Finclude/linux/crypto.h crypto_hash_final +!Finclude/linux/crypto.h crypto_hash_digest +!Finclude/linux/crypto.h crypto_hash_setkey + </sect1> + <sect1><title>Message Digest Algorithm Definitions</title> +!Pinclude/crypto/hash.h Message Digest Algorithm Definitions +!Finclude/crypto/hash.h hash_alg_common +!Finclude/crypto/hash.h ahash_alg +!Finclude/crypto/hash.h shash_alg + </sect1> + <sect1><title>Asynchronous Message Digest API</title> +!Pinclude/crypto/hash.h Asynchronous Message Digest API +!Finclude/crypto/hash.h crypto_alloc_ahash +!Finclude/crypto/hash.h crypto_free_ahash +!Finclude/crypto/hash.h crypto_ahash_init +!Finclude/crypto/hash.h crypto_ahash_digestsize +!Finclude/crypto/hash.h crypto_ahash_reqtfm +!Finclude/crypto/hash.h crypto_ahash_reqsize +!Finclude/crypto/hash.h crypto_ahash_setkey +!Finclude/crypto/hash.h crypto_ahash_finup +!Finclude/crypto/hash.h crypto_ahash_final +!Finclude/crypto/hash.h crypto_ahash_digest +!Finclude/crypto/hash.h crypto_ahash_export +!Finclude/crypto/hash.h crypto_ahash_import + </sect1> + <sect1><title>Asynchronous Hash Request Handle</title> +!Pinclude/crypto/hash.h Asynchronous Hash Request Handle +!Finclude/crypto/hash.h ahash_request_set_tfm +!Finclude/crypto/hash.h ahash_request_alloc +!Finclude/crypto/hash.h ahash_request_free +!Finclude/crypto/hash.h ahash_request_set_callback +!Finclude/crypto/hash.h ahash_request_set_crypt + </sect1> + <sect1><title>Synchronous Message Digest API</title> +!Pinclude/crypto/hash.h Synchronous Message Digest API +!Finclude/crypto/hash.h crypto_alloc_shash +!Finclude/crypto/hash.h crypto_free_shash +!Finclude/crypto/hash.h crypto_shash_blocksize +!Finclude/crypto/hash.h crypto_shash_digestsize +!Finclude/crypto/hash.h crypto_shash_descsize +!Finclude/crypto/hash.h crypto_shash_setkey +!Finclude/crypto/hash.h crypto_shash_digest +!Finclude/crypto/hash.h crypto_shash_export +!Finclude/crypto/hash.h crypto_shash_import +!Finclude/crypto/hash.h crypto_shash_init +!Finclude/crypto/hash.h crypto_shash_update +!Finclude/crypto/hash.h crypto_shash_final +!Finclude/crypto/hash.h crypto_shash_finup + </sect1> + <sect1><title>Crypto API Random Number API</title> +!Pinclude/crypto/rng.h Random number generator API +!Finclude/crypto/rng.h crypto_alloc_rng +!Finclude/crypto/rng.h crypto_rng_alg +!Finclude/crypto/rng.h crypto_free_rng +!Finclude/crypto/rng.h crypto_rng_get_bytes +!Finclude/crypto/rng.h crypto_rng_reset +!Finclude/crypto/rng.h crypto_rng_seedsize +!Cinclude/crypto/rng.h + </sect1> + </chapter> + + <chapter id="Code"><title>Code Examples</title> + <sect1><title>Code Example For Asynchronous Block Cipher Operation</title> + <programlisting> + +struct tcrypt_result { + struct completion completion; + int err; +}; + +/* tie all data structures together */ +struct ablkcipher_def { + struct scatterlist sg; + struct crypto_ablkcipher *tfm; + struct ablkcipher_request *req; + struct tcrypt_result result; +}; + +/* Callback function */ +static void test_ablkcipher_cb(struct crypto_async_request *req, int error) +{ + struct tcrypt_result *result = req->data; + + if (error == -EINPROGRESS) + return; + result->err = error; + complete(&result->completion); + pr_info("Encryption finished successfully\n"); +} + +/* Perform cipher operation */ +static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, + int enc) +{ + int rc = 0; + + if (enc) + rc = crypto_ablkcipher_encrypt(ablk->req); + else + rc = crypto_ablkcipher_decrypt(ablk->req); + + switch (rc) { + case 0: + break; + case -EINPROGRESS: + case -EBUSY: + rc = wait_for_completion_interruptible( + &ablk->result.completion); + if (!rc && !ablk->result.err) { + reinit_completion(&ablk->result.completion); + break; + } + default: + pr_info("ablkcipher encrypt returned with %d result %d\n", + rc, ablk->result.err); + break; + } + init_completion(&ablk->result.completion); + + return rc; +} + +/* Initialize and trigger cipher operation */ +static int test_ablkcipher(void) +{ + struct ablkcipher_def ablk; + struct crypto_ablkcipher *ablkcipher = NULL; + struct ablkcipher_request *req = NULL; + char *scratchpad = NULL; + char *ivdata = NULL; + unsigned char key[32]; + int ret = -EFAULT; + + ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0); + if (IS_ERR(ablkcipher)) { + pr_info("could not allocate ablkcipher handle\n"); + return PTR_ERR(ablkcipher); + } + + req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL); + if (IS_ERR(req)) { + pr_info("could not allocate request queue\n"); + ret = PTR_ERR(req); + goto out; + } + + ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, + test_ablkcipher_cb, + &ablk.result); + + /* AES 256 with random key */ + get_random_bytes(&key, 32); + if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) { + pr_info("key could not be set\n"); + ret = -EAGAIN; + goto out; + } + + /* IV will be random */ + ivdata = kmalloc(16, GFP_KERNEL); + if (!ivdata) { + pr_info("could not allocate ivdata\n"); + goto out; + } + get_random_bytes(ivdata, 16); + + /* Input data will be random */ + scratchpad = kmalloc(16, GFP_KERNEL); + if (!scratchpad) { + pr_info("could not allocate scratchpad\n"); + goto out; + } + get_random_bytes(scratchpad, 16); + + ablk.tfm = ablkcipher; + ablk.req = req; + + /* We encrypt one block */ + sg_init_one(&ablk.sg, scratchpad, 16); + ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); + init_completion(&ablk.result.completion); + + /* encrypt data */ + ret = test_ablkcipher_encdec(&ablk, 1); + if (ret) + goto out; + + pr_info("Encryption triggered successfully\n"); + +out: + if (ablkcipher) + crypto_free_ablkcipher(ablkcipher); + if (req) + ablkcipher_request_free(req); + if (ivdata) + kfree(ivdata); + if (scratchpad) + kfree(scratchpad); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Synchronous Block Cipher Operation</title> + <programlisting> + +static int test_blkcipher(void) +{ + struct crypto_blkcipher *blkcipher = NULL; + char *cipher = "cbc(aes)"; + // AES 128 + charkey = +"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; + chariv = +"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; + unsigned int ivsize = 0; + char *scratchpad = NULL; // holds plaintext and ciphertext + struct scatterlist sg; + struct blkcipher_desc desc; + int ret = -EFAULT; + + blkcipher = crypto_alloc_blkcipher(cipher, 0, 0); + if (IS_ERR(blkcipher)) { + printk("could not allocate blkcipher handle for %s\n", cipher); + return -PTR_ERR(blkcipher); + } + + if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) { + printk("key could not be set\n"); + ret = -EAGAIN; + goto out; + } + + ivsize = crypto_blkcipher_ivsize(blkcipher); + if (ivsize) { + if (ivsize != strlen(iv)) + printk("IV length differs from expected length\n"); + crypto_blkcipher_set_iv(blkcipher, iv, ivsize); + } + + scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL); + if (!scratchpad) { + printk("could not allocate scratchpad for %s\n", cipher); + goto out; + } + /* get some random data that we want to encrypt */ + get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher)); + + desc.flags = 0; + desc.tfm = blkcipher; + sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); + + /* encrypt data in place */ + crypto_blkcipher_encrypt(&desc, &sg, &sg, + crypto_blkcipher_blocksize(blkcipher)); + + /* decrypt data in place + * crypto_blkcipher_decrypt(&desc, &sg, &sg, + */ crypto_blkcipher_blocksize(blkcipher)); + + + printk("Cipher operation completed\n"); + return 0; + +out: + if (blkcipher) + crypto_free_blkcipher(blkcipher); + if (scratchpad) + kzfree(scratchpad); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> + <programlisting> + +struct sdesc { + struct shash_desc shash; + char ctx[]; +}; + +static struct sdescinit_sdesc(struct crypto_shash *alg) +{ + struct sdescsdesc; + int size; + + size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); + sdesc = kmalloc(size, GFP_KERNEL); + if (!sdesc) + return ERR_PTR(-ENOMEM); + sdesc->shash.tfm = alg; + sdesc->shash.flags = 0x0; + return sdesc; +} + +static int calc_hash(struct crypto_shashalg, + const unsigned chardata, unsigned int datalen, + unsigned chardigest) { + struct sdescsdesc; + int ret; + + sdesc = init_sdesc(alg); + if (IS_ERR(sdesc)) { + pr_info("trusted_key: can't alloc %s\n", hash_alg); + return PTR_ERR(sdesc); + } + + ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); + kfree(sdesc); + return ret; +} + </programlisting> + </sect1> + + <sect1><title>Code Example For Random Number Generator Usage</title> + <programlisting> + +static int get_random_numbers(u8 *buf, unsigned int len) +{ + struct crypto_rngrng = NULL; + chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ + int ret; + + if (!buf || !len) { + pr_debug("No output buffer provided\n"); + return -EINVAL; + } + + rng = crypto_alloc_rng(drbg, 0, 0); + if (IS_ERR(rng)) { + pr_debug("could not allocate RNG handle for %s\n", drbg); + return -PTR_ERR(rng); + } + + ret = crypto_rng_get_bytes(rng, buf, len); + if (ret < 0) + pr_debug("generation of random numbers failed\n"); + else if (ret == 0) + pr_debug("RNG returned no data"); + else + pr_debug("RNG returned %d bytes of data\n", ret); + +out: + crypto_free_rng(rng); + return ret; +} + </programlisting> + </sect1> + </chapter> + </book> diff --git a/Documentation/DocBook/drm.tmpl b/Documentation/DocBook/drm.tmpl index be35bc328b77..4b592ffbafee 100644 --- a/Documentation/DocBook/drm.tmpl +++ b/Documentation/DocBook/drm.tmpl @@ -492,10 +492,10 @@ char *date;</synopsis> <sect2> <title>The Translation Table Manager (TTM)</title> <para> - TTM design background and information belongs here. + TTM design background and information belongs here. </para> <sect3> - <title>TTM initialization</title> + <title>TTM initialization</title> <warning><para>This section is outdated.</para></warning> <para> Drivers wishing to support TTM must fill out a drm_bo_driver @@ -503,42 +503,42 @@ char *date;</synopsis> 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: - </para> - <programlisting> - struct ttm_global_reference { - enum ttm_global_types global_type; - size_t size; - void *object; - int (*init) (struct ttm_global_reference *); - void (*release) (struct ttm_global_reference *); - }; - </programlisting> - <para> - There should be one global reference structure for your memory - manager as a whole, and there will be others for each object - created by the memory manager at runtime. Your global TTM should - have a type of TTM_GLOBAL_TTM_MEM. The size field for the global - object should be sizeof(struct ttm_mem_global), and the init and - release hooks should point at your driver-specific init and - release routines, which probably eventually call - ttm_mem_global_init and ttm_mem_global_release, respectively. - </para> - <para> - Once your global TTM accounting structure is set up and initialized - by calling ttm_global_item_ref() on it, - you need to create a buffer object TTM to - provide a pool for buffer object allocation by clients and the - kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, - and its size should be sizeof(struct ttm_bo_global). Again, - driver-specific init and release functions may be provided, - likely eventually calling ttm_bo_global_init() and - ttm_bo_global_release(), respectively. Also, like the previous - object, ttm_global_item_ref() is used to create an initial reference - count for the TTM, which will call your initialization function. - </para> + </para> + <para> + The ttm_global_reference structure is made up of several fields: + </para> + <programlisting> + struct ttm_global_reference { + enum ttm_global_types global_type; + size_t size; + void *object; + int (*init) (struct ttm_global_reference *); + void (*release) (struct ttm_global_reference *); + }; + </programlisting> + <para> + There should be one global reference structure for your memory + manager as a whole, and there will be others for each object + created by the memory manager at runtime. Your global TTM should + have a type of TTM_GLOBAL_TTM_MEM. The size field for the global + object should be sizeof(struct ttm_mem_global), and the init and + release hooks should point at your driver-specific init and + release routines, which probably eventually call + ttm_mem_global_init and ttm_mem_global_release, respectively. + </para> + <para> + Once your global TTM accounting structure is set up and initialized + by calling ttm_global_item_ref() on it, + you need to create a buffer object TTM to + provide a pool for buffer object allocation by clients and the + kernel itself. The type of this object should be TTM_GLOBAL_TTM_BO, + and its size should be sizeof(struct ttm_bo_global). Again, + driver-specific init and release functions may be provided, + likely eventually calling ttm_bo_global_init() and + ttm_bo_global_release(), respectively. Also, like the previous + object, ttm_global_item_ref() is used to create an initial reference + count for the TTM, which will call your initialization function. + </para> </sect3> </sect2> <sect2 id="drm-gem"> @@ -566,19 +566,19 @@ char *date;</synopsis> 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 + 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 + read & write, mapping, and domain ownership transfers are left to driver-specific ioctls. </para> <sect3> @@ -738,16 +738,16 @@ char *date;</synopsis> respectively. The conversion is handled by the DRM core without any driver-specific support. </para> - <para> - GEM also supports buffer sharing with dma-buf file descriptors through - PRIME. GEM-based drivers must use the provided helpers functions to - implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. - Since sharing file descriptors is inherently more secure than the - easily guessable and global GEM names it is the preferred buffer - sharing mechanism. Sharing buffers through GEM names is only supported - for legacy userspace. Furthermore PRIME also allows cross-device - buffer sharing since it is based on dma-bufs. - </para> + <para> + GEM also supports buffer sharing with dma-buf file descriptors through + PRIME. GEM-based drivers must use the provided helpers functions to + implement the exporting and importing correctly. See <xref linkend="drm-prime-support" />. + Since sharing file descriptors is inherently more secure than the + easily guessable and global GEM names it is the preferred buffer + sharing mechanism. Sharing buffers through GEM names is only supported + for legacy userspace. Furthermore PRIME also allows cross-device + buffer sharing since it is based on dma-bufs. + </para> </sect3> <sect3 id="drm-gem-objects-mapping"> <title>GEM Objects Mapping</title> @@ -852,7 +852,7 @@ char *date;</synopsis> <sect3> <title>Command Execution</title> <para> - Perhaps the most important GEM function for GPU devices is providing a + 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 @@ -874,95 +874,101 @@ char *date;</synopsis> <title>GEM Function Reference</title> !Edrivers/gpu/drm/drm_gem.c </sect3> - </sect2> - <sect2> - <title>VMA Offset Manager</title> + </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> - <sect2 id="drm-prime-support"> - <title>PRIME Buffer Sharing</title> - <para> - PRIME is the cross device buffer sharing framework in drm, originally - created for the OPTIMUS range of multi-gpu platforms. To userspace - PRIME buffers are dma-buf based file descriptors. - </para> - <sect3> - <title>Overview and Driver Interface</title> - <para> - Similar to GEM global names, PRIME file descriptors are - also used to share buffer 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 the 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); + </sect2> + <sect2 id="drm-prime-support"> + <title>PRIME Buffer Sharing</title> + <para> + PRIME is the cross device buffer sharing framework in drm, originally + created for the OPTIMUS range of multi-gpu platforms. To userspace + PRIME buffers are dma-buf based file descriptors. + </para> + <sect3> + <title>Overview and Driver Interface</title> + <para> + Similar to GEM global names, PRIME file descriptors are + also used to share buffer 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 the 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. Similar to the mode setting - API PRIME is agnostic to the underlying buffer object manager, as - long as handles are 32bit unsigned integers. - </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_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. Similar to the mode setting + API PRIME is agnostic to the underlying buffer object manager, as + long as handles are 32bit unsigned integers. + </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 - PRIME. - </para> - </sect3> - <sect3> - <title>PRIME Helper Functions</title> -!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + struct dma_buf *dma_buf);</synopsis> + These two operations are mandatory for GEM drivers that support + PRIME. + </para> </sect3> - </sect2> - <sect2> - <title>PRIME Function References</title> + <sect3> + <title>PRIME Helper Functions</title> +!Pdrivers/gpu/drm/drm_prime.c PRIME Helpers + </sect3> + </sect2> + <sect2> + <title>PRIME Function References</title> !Edrivers/gpu/drm/drm_prime.c - </sect2> - <sect2> - <title>DRM MM Range Allocator</title> - <sect3> - <title>Overview</title> + </sect2> + <sect2> + <title>DRM MM Range Allocator</title> + <sect3> + <title>Overview</title> !Pdrivers/gpu/drm/drm_mm.c Overview - </sect3> - <sect3> - <title>LRU Scan/Eviction Support</title> + </sect3> + <sect3> + <title>LRU Scan/Eviction Support</title> !Pdrivers/gpu/drm/drm_mm.c lru scan roaster - </sect3> + </sect3> </sect2> - <sect2> - <title>DRM MM Range Allocator Function References</title> + <sect2> + <title>DRM MM Range Allocator Function References</title> !Edrivers/gpu/drm/drm_mm.c !Iinclude/drm/drm_mm.h - </sect2> + </sect2> + <sect2> + <title>CMA Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_gem_cma_helper.c cma helpers +!Edrivers/gpu/drm/drm_gem_cma_helper.c +!Iinclude/drm/drm_gem_cma_helper.h + </sect2> </sect1> <!-- Internals: mode setting --> @@ -996,6 +1002,10 @@ int max_width, max_height;</synopsis> !Edrivers/gpu/drm/drm_modes.c </sect2> <sect2> + <title>Atomic Mode Setting Function Reference</title> +!Edrivers/gpu/drm/drm_atomic.c + </sect2> + <sect2> <title>Frame Buffer Creation</title> <synopsis>struct drm_framebuffer *(*fb_create)(struct drm_device *dev, struct drm_file *file_priv, @@ -1827,6 +1837,10 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_crtc.c </sect2> <sect2> + <title>KMS Data Structures</title> +!Iinclude/drm/drm_crtc.h + </sect2> + <sect2> <title>KMS Locking</title> !Pdrivers/gpu/drm/drm_modeset_lock.c kms locking !Iinclude/drm/drm_modeset_lock.h @@ -1933,10 +1947,16 @@ void intel_crt_init(struct drm_device *dev) and then retrieves a list of modes by calling the connector <methodname>get_modes</methodname> helper operation. </para> + <para> + If the helper operation returns no mode, and if the connector status + is connector_status_connected, standard VESA DMT modes up to + 1024x768 are automatically added to the modes list by a call to + <function>drm_add_modes_noedid</function>. + </para> <para> - The function filters out modes larger than + The function then filters out modes larger than <parameter>max_width</parameter> and <parameter>max_height</parameter> - if specified. It then calls the optional connector + if specified. It finally calls the optional 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> @@ -2076,12 +2096,20 @@ void intel_crt_init(struct drm_device *dev) <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 + by parsing EDID data with <function>drm_add_edid_modes</function>, + adding standard VESA DMT modes with <function>drm_add_modes_noedid</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> + Note that the caller function will automatically add standard VESA + DMT modes up to 1024x768 if the <methodname>get_modes</methodname> + helper operation returns no mode and if the connector status is + connector_status_connected. There is no need to call + <function>drm_add_edid_modes</function> manually in that case. + </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> @@ -2278,7 +2306,7 @@ void intel_crt_init(struct drm_device *dev) <function>drm_helper_probe_single_connector_modes</function>. </para> <para> - When parsing EDID data, <function>drm_add_edid_modes</function> fill the + When parsing EDID data, <function>drm_add_edid_modes</function> fills the connector <structfield>display_info</structfield> <structfield>width_mm</structfield> and <structfield>height_mm</structfield> fields. When creating modes @@ -2316,8 +2344,26 @@ void intel_crt_init(struct drm_device *dev) </itemizedlist> </sect2> <sect2> + <title>Atomic Modeset Helper Functions Reference</title> + <sect3> + <title>Overview</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c overview + </sect3> + <sect3> + <title>Implementing Asynchronous Atomic Commit</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c implementing async commit + </sect3> + <sect3> + <title>Atomic State Reset and Initialization</title> +!Pdrivers/gpu/drm/drm_atomic_helper.c atomic state reset and initialization + </sect3> +!Iinclude/drm/drm_atomic_helper.h +!Edrivers/gpu/drm/drm_atomic_helper.c + </sect2> + <sect2> <title>Modeset Helper Functions Reference</title> !Edrivers/gpu/drm/drm_crtc_helper.c +!Pdrivers/gpu/drm/drm_crtc_helper.c overview </sect2> <sect2> <title>Output Probing Helper Functions Reference</title> @@ -2343,6 +2389,12 @@ void intel_crt_init(struct drm_device *dev) !Edrivers/gpu/drm/drm_dp_mst_topology.c </sect2> <sect2> + <title>MIPI DSI Helper Functions Reference</title> +!Pdrivers/gpu/drm/drm_mipi_dsi.c dsi helpers +!Iinclude/drm/drm_mipi_dsi.h +!Edrivers/gpu/drm/drm_mipi_dsi.c + </sect2> + <sect2> <title>EDID Helper Functions Reference</title> !Edrivers/gpu/drm/drm_edid.c </sect2> @@ -2371,7 +2423,12 @@ void intel_crt_init(struct drm_device *dev) </sect2> <sect2> <title id="drm-kms-planehelpers">Plane Helper Reference</title> -!Edrivers/gpu/drm/drm_plane_helper.c Plane Helpers +!Edrivers/gpu/drm/drm_plane_helper.c +!Pdrivers/gpu/drm/drm_plane_helper.c overview + </sect2> + <sect2> + <title>Tile group</title> +!Pdrivers/gpu/drm/drm_crtc.c Tile group </sect2> </sect1> @@ -2507,8 +2564,8 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >Description/Restrictions</td> </tr> <tr> - <td rowspan="21" valign="top" >DRM</td> - <td rowspan="2" valign="top" >Generic</td> + <td rowspan="25" valign="top" >DRM</td> + <td rowspan="4" valign="top" >Generic</td> <td valign="top" >“EDID”</td> <td valign="top" >BLOB | IMMUTABLE</td> <td valign="top" >0</td> @@ -2523,6 +2580,20 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >Contains DPMS operation mode value.</td> </tr> <tr> + <td valign="top" >“PATH”</td> + <td valign="top" >BLOB | IMMUTABLE</td> + <td valign="top" >0</td> + <td valign="top" >Connector</td> + <td valign="top" >Contains topology path to a connector.</td> + </tr> + <tr> + <td valign="top" >“TILE”</td> + <td valign="top" >BLOB | IMMUTABLE</td> + <td valign="top" >0</td> + <td valign="top" >Connector</td> + <td valign="top" >Contains tiling information for a connector.</td> + </tr> + <tr> <td rowspan="1" valign="top" >Plane</td> <td valign="top" >“type”</td> <td valign="top" >ENUM | IMMUTABLE</td> @@ -2638,6 +2709,21 @@ void intel_crt_init(struct drm_device *dev) <td valign="top" >TBD</td> </tr> <tr> + <td rowspan="2" valign="top" >Virtual GPU</td> + <td valign="top" >“suggested X”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffffff</td> + <td valign="top" >Connector</td> + <td valign="top" >property to suggest an X offset for a connector</td> + </tr> + <tr> + <td valign="top" >“suggested Y”</td> + <td valign="top" >RANGE</td> + <td valign="top" >Min=0, Max=0xffffffff</td> + <td valign="top" >Connector</td> + <td valign="top" >property to suggest an Y offset for a connector</td> + </tr> + <tr> <td rowspan="3" valign="top" >Optional</td> <td valign="top" >“scaling mode”</td> <td valign="top" >ENUM</td> @@ -3788,6 +3874,26 @@ int num_ioctls;</synopsis> those have basic support through the gma500 drm driver. </para> <sect1> + <title>Core Driver Infrastructure</title> + <para> + This section covers core driver infrastructure used by both the display + and the GEM parts of the driver. + </para> + <sect2> + <title>Runtime Power Management</title> +!Pdrivers/gpu/drm/i915/intel_runtime_pm.c runtime pm +!Idrivers/gpu/drm/i915/intel_runtime_pm.c + </sect2> + <sect2> + <title>Interrupt Handling</title> +!Pdrivers/gpu/drm/i915/i915_irq.c interrupt handling +!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_init intel_irq_init_hw intel_hpd_init +!Fdrivers/gpu/drm/i915/i915_irq.c intel_irq_fini +!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_disable_interrupts +!Fdrivers/gpu/drm/i915/i915_irq.c intel_runtime_pm_enable_interrupts + </sect2> + </sect1> + <sect1> <title>Display Hardware Handling</title> <para> This section covers everything related to the display hardware including @@ -3804,6 +3910,18 @@ int num_ioctls;</synopsis> </para> </sect2> <sect2> + <title>Frontbuffer Tracking</title> +!Pdrivers/gpu/drm/i915/intel_frontbuffer.c frontbuffer tracking +!Idrivers/gpu/drm/i915/intel_frontbuffer.c +!Fdrivers/gpu/drm/i915/intel_drv.h intel_frontbuffer_flip +!Fdrivers/gpu/drm/i915/i915_gem.c i915_gem_track_fb + </sect2> + <sect2> + <title>Display FIFO Underrun Reporting</title> +!Pdrivers/gpu/drm/i915/intel_fifo_underrun.c fifo underrun handling +!Idrivers/gpu/drm/i915/intel_fifo_underrun.c + </sect2> + <sect2> <title>Plane Configuration</title> <para> This section covers plane configuration and composition with the @@ -3823,6 +3941,16 @@ int num_ioctls;</synopsis> </para> </sect2> <sect2> + <title>High Definition Audio</title> +!Pdrivers/gpu/drm/i915/intel_audio.c High Definition Audio over HDMI and Display Port +!Idrivers/gpu/drm/i915/intel_audio.c + </sect2> + <sect2> + <title>Panel Self Refresh PSR (PSR/SRD)</title> +!Pdrivers/gpu/drm/i915/intel_psr.c Panel Self Refresh (PSR/SRD) +!Idrivers/gpu/drm/i915/intel_psr.c + </sect2> + <sect2> <title>DPIO</title> !Pdrivers/gpu/drm/i915/i915_reg.h DPIO <table id="dpiox2"> @@ -3931,6 +4059,28 @@ int num_ioctls;</synopsis> !Idrivers/gpu/drm/i915/intel_lrc.c </sect2> </sect1> + + <sect1> + <title> Tracing </title> + <para> + This sections covers all things related to the tracepoints implemented in + the i915 driver. + </para> + <sect2> + <title> i915_ppgtt_create and i915_ppgtt_release </title> +!Pdrivers/gpu/drm/i915/i915_trace.h i915_ppgtt_create and i915_ppgtt_release tracepoints + </sect2> + <sect2> + <title> i915_context_create and i915_context_free </title> +!Pdrivers/gpu/drm/i915/i915_trace.h i915_context_create and i915_context_free tracepoints + </sect2> + <sect2> + <title> switch_mm </title> +!Pdrivers/gpu/drm/i915/i915_trace.h switch_mm tracepoint + </sect2> + </sect1> + </chapter> +!Cdrivers/gpu/drm/i915/i915_irq.c </part> </book> diff --git a/Documentation/DocBook/media/Makefile b/Documentation/DocBook/media/Makefile index df2962d9e11e..8bf7c6191296 100644 --- a/Documentation/DocBook/media/Makefile +++ b/Documentation/DocBook/media/Makefile @@ -25,7 +25,7 @@ GENFILES := $(addprefix $(MEDIA_OBJ_DIR)/, $(MEDIA_TEMP)) PHONY += cleanmediadocs cleanmediadocs: - -@rm `find $(MEDIA_OBJ_DIR) -type l` $(GENFILES) $(OBJIMGFILES) 2>/dev/null + -@rm -f `find $(MEDIA_OBJ_DIR) -type l` $(GENFILES) $(OBJIMGFILES) 2>/dev/null $(obj)/media_api.xml: $(GENFILES) FORCE diff --git a/Documentation/DocBook/media/dvb/dvbproperty.xml b/Documentation/DocBook/media/dvb/dvbproperty.xml index 948ddaab592e..3018564ddfd9 100644 --- a/Documentation/DocBook/media/dvb/dvbproperty.xml +++ b/Documentation/DocBook/media/dvb/dvbproperty.xml @@ -120,8 +120,8 @@ struct dtv_properties { </para> <informaltable><tgroup cols="1"><tbody><row><entry align="char"> -<para>This ioctl call sets one or more frontend properties. This call only - requires read-only access to the device.</para> +<para>This ioctl call sets one or more frontend properties. This call + requires read/write access to the device.</para> </entry> </row></tbody></tgroup></informaltable> <para>SYNOPSIS diff --git a/Documentation/DocBook/media/v4l/biblio.xml b/Documentation/DocBook/media/v4l/biblio.xml index d2eb79e41a01..7ff01a23c2fe 100644 --- a/Documentation/DocBook/media/v4l/biblio.xml +++ b/Documentation/DocBook/media/v4l/biblio.xml @@ -178,6 +178,75 @@ Signal - NTSC for Studio Applications"</title> 1125-Line High-Definition Production"</title> </biblioentry> + <biblioentry id="srgb"> + <abbrev>sRGB</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-1 ed1.0 "Multimedia systems and equipment - Colour measurement +and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title> + </biblioentry> + + <biblioentry id="sycc"> + <abbrev>sYCC</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-1-am1 ed1.0 "Amendment 1 - Multimedia systems and equipment - Colour measurement +and management - Part 2-1: Colour management - Default RGB colour space - sRGB"</title> + </biblioentry> + + <biblioentry id="xvycc"> + <abbrev>xvYCC</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-4 ed1.0 "Multimedia systems and equipment - Colour measurement +and management - Part 2-4: Colour management - Extended-gamut YCC colour space for video +applications - xvYCC"</title> + </biblioentry> + + <biblioentry id="adobergb"> + <abbrev>AdobeRGB</abbrev> + <authorgroup> + <corpauthor>Adobe Systems Incorporated (<ulink url="http://www.adobe.com">http://www.adobe.com</ulink>)</corpauthor> + </authorgroup> + <title>Adobe© RGB (1998) Color Image Encoding Version 2005-05</title> + </biblioentry> + + <biblioentry id="oprgb"> + <abbrev>opRGB</abbrev> + <authorgroup> + <corpauthor>International Electrotechnical Commission +(<ulink url="http://www.iec.ch">http://www.iec.ch</ulink>)</corpauthor> + </authorgroup> + <title>IEC 61966-2-5 "Multimedia systems and equipment - Colour measurement +and management - Part 2-5: Colour management - Optional RGB colour space - opRGB"</title> + </biblioentry> + + <biblioentry id="itu2020"> + <abbrev>ITU BT.2020</abbrev> + <authorgroup> + <corpauthor>International Telecommunication Union (<ulink +url="http://www.itu.ch">http://www.itu.ch</ulink>)</corpauthor> + </authorgroup> + <title>ITU-R Recommendation BT.2020 (08/2012) "Parameter values for ultra-high +definition television systems for production and international programme exchange" +</title> + </biblioentry> + + <biblioentry id="tech3213"> + <abbrev>EBU Tech 3213</abbrev> + <authorgroup> + <corpauthor>European Broadcast Union (<ulink +url="http://www.ebu.ch">http://www.ebu.ch</ulink>)</corpauthor> + </authorgroup> + <title>E.B.U. Standard for Chromaticity Tolerances for Studio Monitors"</title> + </biblioentry> + <biblioentry id="iec62106"> <abbrev>IEC 62106</abbrev> <authorgroup> @@ -266,4 +335,20 @@ in the frequency range from 87,5 to 108,0 MHz</title> <subtitle>Version 1, Revision 2</subtitle> </biblioentry> + <biblioentry id="poynton"> + <abbrev>poynton</abbrev> + <authorgroup> + <corpauthor>Charles Poynton</corpauthor> + </authorgroup> + <title>Digital Video and HDTV, Algorithms and Interfaces</title> + </biblioentry> + + <biblioentry id="colimg"> + <abbrev>colimg</abbrev> + <authorgroup> + <corpauthor>Erik Reinhard et al.</corpauthor> + </authorgroup> + <title>Color Imaging: Fundamentals and Applications</title> + </biblioentry> + </bibliography> diff --git a/Documentation/DocBook/media/v4l/compat.xml b/Documentation/DocBook/media/v4l/compat.xml index 07ffc76553ba..350dfb3d71ea 100644 --- a/Documentation/DocBook/media/v4l/compat.xml +++ b/Documentation/DocBook/media/v4l/compat.xml @@ -2566,6 +2566,10 @@ fields changed from _s32 to _u32. <para>Added compound control types and &VIDIOC-QUERY-EXT-CTRL;. </para> </listitem> + </orderedlist> + </section> + + <section> <title>V4L2 in Linux 3.18</title> <orderedlist> <listitem> @@ -2575,6 +2579,18 @@ fields changed from _s32 to _u32. </orderedlist> </section> + <section> + <title>V4L2 in Linux 3.19</title> + <orderedlist> + <listitem> + <para>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; +and &v4l2-quantization; fields to &v4l2-pix-format;, &v4l2-pix-format-mplane; +and &v4l2-mbus-framefmt;. + </para> + </listitem> + </orderedlist> + </section> + <section id="other"> <title>Relation of V4L2 to other Linux multimedia APIs</title> diff --git a/Documentation/DocBook/media/v4l/dev-subdev.xml b/Documentation/DocBook/media/v4l/dev-subdev.xml index d15aaf83f56f..4f0ba58c9bd9 100644 --- a/Documentation/DocBook/media/v4l/dev-subdev.xml +++ b/Documentation/DocBook/media/v4l/dev-subdev.xml @@ -195,53 +195,59 @@ <title>Sample Pipeline Configuration</title> <tgroup cols="3"> <colspec colname="what"/> - <colspec colname="sensor-0" /> - <colspec colname="frontend-0" /> - <colspec colname="frontend-1" /> - <colspec colname="scaler-0" /> - <colspec colname="scaler-1" /> + <colspec colname="sensor-0 format" /> + <colspec colname="frontend-0 format" /> + <colspec colname="frontend-1 format" /> + <colspec colname="scaler-0 format" /> + <colspec colname="scaler-0 compose" /> + <colspec colname="scaler-1 format" /> <thead> <row> <entry></entry> - <entry>Sensor/0</entry> - <entry>Frontend/0</entry> - <entry>Frontend/1</entry> - <entry>Scaler/0</entry> - <entry>Scaler/1</entry> + <entry>Sensor/0 format</entry> + <entry>Frontend/0 format</entry> + <entry>Frontend/1 format</entry> + <entry>Scaler/0 format</entry> + <entry>Scaler/0 compose selection rectangle</entry> + <entry>Scaler/1 format</entry> </row> </thead> <tbody valign="top"> <row> <entry>Initial state</entry> - <entry>2048x1536</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> - <entry>-</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> </row> <row> - <entry>Configure frontend input</entry> - <entry>2048x1536</entry> - <entry><emphasis>2048x1536</emphasis></entry> - <entry><emphasis>2046x1534</emphasis></entry> - <entry>-</entry> - <entry>-</entry> + <entry>Configure frontend sink format</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry><emphasis>2048x1536/SGRBG8_1X8</emphasis></entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> + <entry>(default)</entry> + <entry>(default)</entry> + <entry>(default)</entry> </row> <row> - <entry>Configure scaler input</entry> - <entry>2048x1536</entry> - <entry>2048x1536</entry> - <entry>2046x1534</entry> - <entry><emphasis>2046x1534</emphasis></entry> - <entry><emphasis>2046x1534</emphasis></entry> + <entry>Configure scaler sink format</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> + <entry><emphasis>0,0/2046x1534</emphasis></entry> + <entry><emphasis>2046x1534/SGRBG8_1X8</emphasis></entry> </row> <row> - <entry>Configure scaler output</entry> - <entry>2048x1536</entry> - <entry>2048x1536</entry> - <entry>2046x1534</entry> - <entry>2046x1534</entry> - <entry><emphasis>1280x960</emphasis></entry> + <entry>Configure scaler sink compose selection</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2048x1536/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry>2046x1534/SGRBG8_1X8</entry> + <entry><emphasis>0,0/1280x960</emphasis></entry> + <entry><emphasis>1280x960/SGRBG8_1X8</emphasis></entry> </row> </tbody> </tgroup> @@ -249,19 +255,30 @@ <para> <orderedlist> - <listitem><para>Initial state. The sensor output is set to its native 3MP - resolution. Resolutions on the host frontend and scaler input and output - pads are undefined.</para></listitem> - <listitem><para>The application configures the frontend input pad resolution to - 2048x1536. The driver propagates the format to the frontend output pad. - Note that the propagated output format can be different, as in this case, - than the input format, as the hardware might need to crop pixels (for - instance when converting a Bayer filter pattern to RGB or YUV).</para></listitem> - <listitem><para>The application configures the scaler input pad resolution to - 2046x1534 to match the frontend output resolution. The driver propagates - the format to the scaler output pad.</para></listitem> - <listitem><para>The application configures the scaler output pad resolution to - 1280x960.</para></listitem> + <listitem><para>Initial state. The sensor source pad format is + set to its native 3MP size and V4L2_MBUS_FMT_SGRBG8_1X8 + media bus code. Formats on the host frontend and scaler sink + and source pads have the default values, as well as the + compose rectangle on the scaler's sink pad.</para></listitem> + + <listitem><para>The application configures the frontend sink + pad format's size to 2048x1536 and its media bus code to + V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the format to + the frontend source pad.</para></listitem> + + <listitem><para>The application configures the scaler sink pad + format's size to 2046x1534 and the media bus code to + V4L2_MBUS_FMT_SGRBG_1X8 to match the frontend source size and + media bus code. The media bus code on the sink pad is set to + V4L2_MBUS_FMT_SGRBG_1X8. The driver propagates the size to the + compose selection rectangle on the scaler's sink pad, and the + format to the scaler source pad.</para></listitem> + + <listitem><para>The application configures the size of the compose + selection rectangle of the scaler's sink pad 1280x960. The driver + propagates the size to the scaler's source pad + format.</para></listitem> + </orderedlist> </para> diff --git a/Documentation/DocBook/media/v4l/io.xml b/Documentation/DocBook/media/v4l/io.xml index e5e8325aa3d7..1c17f802b471 100644 --- a/Documentation/DocBook/media/v4l/io.xml +++ b/Documentation/DocBook/media/v4l/io.xml @@ -1422,7 +1422,10 @@ one of the <constant>V4L2_FIELD_NONE</constant>, <constant>V4L2_FIELD_BOTTOM</constant>, or <constant>V4L2_FIELD_INTERLACED</constant> formats is acceptable. Drivers choose depending on hardware capabilities or e. g. the -requested image size, and return the actual field order. &v4l2-buffer; +requested image size, and return the actual field order. Drivers must +never return <constant>V4L2_FIELD_ANY</constant>. If multiple +field orders are possible the driver must choose one of the possible +field orders during &VIDIOC-S-FMT; or &VIDIOC-TRY-FMT;. &v4l2-buffer; <structfield>field</structfield> can never be <constant>V4L2_FIELD_ANY</constant>.</entry> </row> diff --git a/Documentation/DocBook/media/v4l/pixfmt.xml b/Documentation/DocBook/media/v4l/pixfmt.xml index df5b23d46552..d5eca4b8f74b 100644 --- a/Documentation/DocBook/media/v4l/pixfmt.xml +++ b/Documentation/DocBook/media/v4l/pixfmt.xml @@ -138,9 +138,25 @@ applicable values.</para></entry> <row> <entry>__u32</entry> <entry><structfield>flags</structfield></entry> - <entry>Flags set by the application or driver, see <xref + <entry>Flags set by the application or driver, see <xref linkend="format-flags" />.</entry> </row> + <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> </tbody> </tgroup> </table> @@ -232,9 +248,25 @@ codes can be used.</entry> <entry>Flags set by the application or driver, see <xref linkend="format-flags" />.</entry> </row> + <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> <row> <entry>__u8</entry> - <entry><structfield>reserved[10]</structfield></entry> + <entry><structfield>reserved[8]</structfield></entry> <entry>Reserved for future extensions. Should be zeroed by the application.</entry> </row> @@ -296,345 +328,1005 @@ in the 2-planar version or with each component in its own buffer in the <section id="colorspaces"> <title>Colorspaces</title> - <para>[intro]</para> + <para>'Color' is a very complex concept and depends on physics, chemistry and +biology. Just because you have three numbers that describe the 'red', 'green' +and 'blue' components of the color of a pixel does not mean that you can accurately +display that color. A colorspace defines what it actually <emphasis>means</emphasis> +to have an RGB value of e.g. (255, 0, 0). That is, which color should be +reproduced on the screen in a perfectly calibrated environment.</para> - <!-- See proposal by Billy Biggs, video4linux-list@redhat.com -on 11 Oct 2002, subject: "Re: [V4L] Re: v4l2 api", and -http://vektor.theorem.ca/graphics/ycbcr/ and -http://www.poynton.com/notes/colour_and_gamma/ColorFAQ.html --> + <para>In order to do that we first need to have a good definition of +color, i.e. some way to uniquely and unambiguously define a color so that someone +else can reproduce it. Human color vision is trichromatic since the human eye has +color receptors that are sensitive to three different wavelengths of light. Hence +the need to use three numbers to describe color. Be glad you are not a mantis shrimp +as those are sensitive to 12 different wavelengths, so instead of RGB we would be +using the ABCDEFGHIJKL colorspace...</para> - <para> - <variablelist> - <varlistentry> - <term>Gamma Correction</term> - <listitem> - <para>[to do]</para> - <para>E'<subscript>R</subscript> = f(R)</para> - <para>E'<subscript>G</subscript> = f(G)</para> - <para>E'<subscript>B</subscript> = f(B)</para> - </listitem> - </varlistentry> - <varlistentry> - <term>Construction of luminance and color-difference -signals</term> - <listitem> - <para>[to do]</para> - <para>E'<subscript>Y</subscript> = -Coeff<subscript>R</subscript> E'<subscript>R</subscript> -+ Coeff<subscript>G</subscript> E'<subscript>G</subscript> -+ Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - <para>(E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = E'<subscript>R</subscript> -- Coeff<subscript>R</subscript> E'<subscript>R</subscript> -- Coeff<subscript>G</subscript> E'<subscript>G</subscript> -- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - <para>(E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = E'<subscript>B</subscript> -- Coeff<subscript>R</subscript> E'<subscript>R</subscript> -- Coeff<subscript>G</subscript> E'<subscript>G</subscript> -- Coeff<subscript>B</subscript> E'<subscript>B</subscript></para> - </listitem> - </varlistentry> - <varlistentry> - <term>Re-normalized color-difference signals</term> - <listitem> - <para>The color-difference signals are scaled back to unity -range [-0.5;+0.5]:</para> - <para>K<subscript>B</subscript> = 0.5 / (1 - Coeff<subscript>B</subscript>)</para> - <para>K<subscript>R</subscript> = 0.5 / (1 - Coeff<subscript>R</subscript>)</para> - <para>P<subscript>B</subscript> = -K<subscript>B</subscript> (E'<subscript>B</subscript> - E'<subscript>Y</subscript>) = - 0.5 (Coeff<subscript>R</subscript> / Coeff<subscript>B</subscript>) E'<subscript>R</subscript> -+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>B</subscript>) E'<subscript>G</subscript> -+ 0.5 E'<subscript>B</subscript></para> - <para>P<subscript>R</subscript> = -K<subscript>R</subscript> (E'<subscript>R</subscript> - E'<subscript>Y</subscript>) = - 0.5 E'<subscript>R</subscript> -+ 0.5 (Coeff<subscript>G</subscript> / Coeff<subscript>R</subscript>) E'<subscript>G</subscript> -+ 0.5 (Coeff<subscript>B</subscript> / Coeff<subscript>R</subscript>) E'<subscript>B</subscript></para> - </listitem> - </varlistentry> - <varlistentry> - <term>Quantization</term> - <listitem> - <para>[to do]</para> - <para>Y' = (Lum. Levels - 1) · E'<subscript>Y</subscript> + Lum. Offset</para> - <para>C<subscript>B</subscript> = (Chrom. Levels - 1) -· P<subscript>B</subscript> + Chrom. Offset</para> - <para>C<subscript>R</subscript> = (Chrom. Levels - 1) -· P<subscript>R</subscript> + Chrom. Offset</para> - <para>Rounding to the nearest integer and clamping to the range -[0;255] finally yields the digital color components Y'CbCr -stored in YUV images.</para> - </listitem> - </varlistentry> - </variablelist> - </para> - - <example> - <title>ITU-R Rec. BT.601 color conversion</title> - - <para>Forward Transformation</para> - - <programlisting> -int ER, EG, EB; /* gamma corrected RGB input [0;255] */ -int Y1, Cb, Cr; /* output [0;255] */ - -double r, g, b; /* temporaries */ -double y1, pb, pr; - -int -clamp (double x) -{ - int r = x; /* round to nearest */ - - if (r < 0) return 0; - else if (r > 255) return 255; - else return r; -} - -r = ER / 255.0; -g = EG / 255.0; -b = EB / 255.0; - -y1 = 0.299 * r + 0.587 * g + 0.114 * b; -pb = -0.169 * r - 0.331 * g + 0.5 * b; -pr = 0.5 * r - 0.419 * g - 0.081 * b; - -Y1 = clamp (219 * y1 + 16); -Cb = clamp (224 * pb + 128); -Cr = clamp (224 * pr + 128); - -/* or shorter */ - -y1 = 0.299 * ER + 0.587 * EG + 0.114 * EB; - -Y1 = clamp ( (219 / 255.0) * y1 + 16); -Cb = clamp (((224 / 255.0) / (2 - 2 * 0.114)) * (EB - y1) + 128); -Cr = clamp (((224 / 255.0) / (2 - 2 * 0.299)) * (ER - y1) + 128); - </programlisting> - - <para>Inverse Transformation</para> - - <programlisting> -int Y1, Cb, Cr; /* gamma pre-corrected input [0;255] */ -int ER, EG, EB; /* output [0;255] */ - -double r, g, b; /* temporaries */ -double y1, pb, pr; - -int -clamp (double x) -{ - int r = x; /* round to nearest */ - - if (r < 0) return 0; - else if (r > 255) return 255; - else return r; -} - -y1 = (Y1 - 16) / 219.0; -pb = (Cb - 128) / 224.0; -pr = (Cr - 128) / 224.0; - -r = 1.0 * y1 + 0 * pb + 1.402 * pr; -g = 1.0 * y1 - 0.344 * pb - 0.714 * pr; -b = 1.0 * y1 + 1.772 * pb + 0 * pr; - -ER = clamp (r * 255); /* [ok? one should prob. limit y1,pb,pr] */ -EG = clamp (g * 255); -EB = clamp (b * 255); - </programlisting> - </example> - - <table pgwide="1" id="v4l2-colorspace" orient="land"> - <title>enum v4l2_colorspace</title> - <tgroup cols="11" align="center"> - <colspec align="left" /> - <colspec align="center" /> - <colspec align="left" /> - <colspec colname="cr" /> - <colspec colname="cg" /> - <colspec colname="cb" /> - <colspec colname="wp" /> - <colspec colname="gc" /> - <colspec colname="lum" /> - <colspec colname="qy" /> - <colspec colname="qc" /> - <spanspec namest="cr" nameend="cb" spanname="chrom" /> - <spanspec namest="qy" nameend="qc" spanname="quant" /> - <spanspec namest="lum" nameend="qc" spanname="spam" /> + <para>Color exists only in the eye and brain and is the result of how strongly +color receptors are stimulated. This is based on the Spectral +Power Distribution (SPD) which is a graph showing the intensity (radiant power) +of the light at wavelengths covering the visible spectrum as it enters the eye. +The science of colorimetry is about the relationship between the SPD and color as +perceived by the human brain.</para> + + <para>Since the human eye has only three color receptors it is perfectly +possible that different SPDs will result in the same stimulation of those receptors +and are perceived as the same color, even though the SPD of the light is +different.</para> + + <para>In the 1920s experiments were devised to determine the relationship +between SPDs and the perceived color and that resulted in the CIE 1931 standard +that defines spectral weighting functions that model the perception of color. +Specifically that standard defines functions that can take an SPD and calculate +the stimulus for each color receptor. After some further mathematical transforms +these stimuli are known as the <emphasis>CIE XYZ tristimulus</emphasis> values +and these X, Y and Z values describe a color as perceived by a human unambiguously. +These X, Y and Z values are all in the range [0…1].</para> + + <para>The Y value in the CIE XYZ colorspace corresponds to luminance. Often +the CIE XYZ colorspace is transformed to the normalized CIE xyY colorspace:</para> + + <para>x = X / (X + Y + Z)</para> + <para>y = Y / (X + Y + Z)</para> + + <para>The x and y values are the chromaticity coordinates and can be used to +define a color without the luminance component Y. It is very confusing to +have such similar names for these colorspaces. Just be aware that if colors +are specified with lower case 'x' and 'y', then the CIE xyY colorspace is +used. Upper case 'X' and 'Y' refer to the CIE XYZ colorspace. Also, y has nothing +to do with luminance. Together x and y specify a color, and Y the luminance. +That is really all you need to remember from a practical point of view. At +the end of this section you will find reading resources that go into much more +detail if you are interested. +</para> + + <para>A monitor or TV will reproduce colors by emitting light at three +different wavelengths, the combination of which will stimulate the color receptors +in the eye and thus cause the perception of color. Historically these wavelengths +were defined by the red, green and blue phosphors used in the displays. These +<emphasis>color primaries</emphasis> are part of what defines a colorspace.</para> + + <para>Different display devices will have different primaries and some +primaries are more suitable for some display technologies than others. This has +resulted in a variety of colorspaces that are used for different display +technologies or uses. To define a colorspace you need to define the three +color primaries (these are typically defined as x, y chromaticity coordinates +from the CIE xyY colorspace) but also the white reference: that is the color obtained +when all three primaries are at maximum power. This determines the relative power +or energy of the primaries. This is usually chosen to be close to daylight which has +been defined as the CIE D65 Illuminant.</para> + + <para>To recapitulate: the CIE XYZ colorspace uniquely identifies colors. +Other colorspaces are defined by three chromaticity coordinates defined in the +CIE xyY colorspace. Based on those a 3x3 matrix can be constructed that +transforms CIE XYZ colors to colors in the new colorspace. +</para> + + <para>Both the CIE XYZ and the RGB colorspace that are derived from the +specific chromaticity primaries are linear colorspaces. But neither the eye, +nor display technology is linear. Doubling the values of all components in +the linear colorspace will not be perceived as twice the intensity of the color. +So each colorspace also defines a transfer function that takes a linear color +component value and transforms it to the non-linear component value, which is a +closer match to the non-linear performance of both the eye and displays. Linear +component values are denoted RGB, non-linear are denoted as R'G'B'. In general +colors used in graphics are all R'G'B', except in openGL which uses linear RGB. +Special care should be taken when dealing with openGL to provide linear RGB colors +or to use the built-in openGL support to apply the inverse transfer function.</para> + + <para>The final piece that defines a colorspace is a function that +transforms non-linear R'G'B' to non-linear Y'CbCr. This function is determined +by the so-called luma coefficients. There may be multiple possible Y'CbCr +encodings allowed for the same colorspace. Many encodings of color +prefer to use luma (Y') and chroma (CbCr) instead of R'G'B'. Since the human +eye is more sensitive to differences in luminance than in color this encoding +allows one to reduce the amount of color information compared to the luma +data. Note that the luma (Y') is unrelated to the Y in the CIE XYZ colorspace. +Also note that Y'CbCr is often called YCbCr or YUV even though these are +strictly speaking wrong.</para> + + <para>Sometimes people confuse Y'CbCr as being a colorspace. This is not +correct, it is just an encoding of an R'G'B' color into luma and chroma +values. The underlying colorspace that is associated with the R'G'B' color +is also associated with the Y'CbCr color.</para> + + <para>The final step is how the RGB, R'G'B' or Y'CbCr values are +quantized. The CIE XYZ colorspace where X, Y and Z are in the range +[0…1] describes all colors that humans can perceive, but the transform to +another colorspace will produce colors that are outside the [0…1] range. +Once clamped to the [0…1] range those colors can no longer be reproduced +in that colorspace. This clamping is what reduces the extent or gamut of the +colorspace. How the range of [0…1] is translated to integer values in the +range of [0…255] (or higher, depending on the color depth) is called the +quantization. This is <emphasis>not</emphasis> part of the colorspace +definition. In practice RGB or R'G'B' values are full range, i.e. they +use the full [0…255] range. Y'CbCr values on the other hand are limited +range with Y' using [16…235] and Cb and Cr using [16…240].</para> + + <para>Unfortunately, in some cases limited range RGB is also used +where the components use the range [16…235]. And full range Y'CbCr also exists +using the [0…255] range.</para> + + <para>In order to correctly interpret a color you need to know the +quantization range, whether it is R'G'B' or Y'CbCr, the used Y'CbCr encoding +and the colorspace. +From that information you can calculate the corresponding CIE XYZ color +and map that again to whatever colorspace your display device uses.</para> + + <para>The colorspace definition itself consists of the three +chromaticity primaries, the white reference chromaticity, a transfer +function and the luma coefficients needed to transform R'G'B' to Y'CbCr. While +some colorspace standards correctly define all four, quite often the colorspace +standard only defines some, and you have to rely on other standards for +the missing pieces. The fact that colorspaces are often a mix of different +standards also led to very confusing naming conventions where the name of +a standard was used to name a colorspace when in fact that standard was +part of various other colorspaces as well.</para> + + <para>If you want to read more about colors and colorspaces, then the +following resources are useful: <xref linkend="poynton" /> is a good practical +book for video engineers, <xref linkend="colimg" /> has a much broader scope and +describes many more aspects of color (physics, chemistry, biology, etc.). +The <ulink url="http://www.brucelindbloom.com">http://www.brucelindbloom.com</ulink> +website is an excellent resource, especially with respect to the mathematics behind +colorspace conversions. The wikipedia <ulink url="http://en.wikipedia.org/wiki/CIE_1931_color_space#CIE_xy_chromaticity_diagram_and_the_CIE_xyY_color_space">CIE 1931 colorspace</ulink> article +is also very useful.</para> + </section> + + <section> + <title>Defining Colorspaces in V4L2</title> + <para>In V4L2 colorspaces are defined by three values. The first is the colorspace +identifier (&v4l2-colorspace;) which defines the chromaticities, the transfer +function, the default Y'CbCr encoding and the default quantization method. The second +is the Y'CbCr encoding identifier (&v4l2-ycbcr-encoding;) to specify non-standard +Y'CbCr encodings and the third is the quantization identifier (&v4l2-quantization;) +to specify non-standard quantization methods. Most of the time only the colorspace +field of &v4l2-pix-format; or &v4l2-pix-format-mplane; needs to be filled in. Note +that the default R'G'B' quantization is always full range for all colorspaces, +so this won't be mentioned explicitly for each colorspace description.</para> + + <table pgwide="1" frame="none" id="v4l2-colorspace"> + <title>V4L2 Colorspaces</title> + <tgroup cols="2" align="left"> + &cs-def; <thead> <row> - <entry morerows="1">Identifier</entry> - <entry morerows="1">Value</entry> - <entry morerows="1">Description</entry> - <entry spanname="chrom">Chromaticities<footnote> - <para>The coordinates of the color primaries are -given in the CIE system (1931)</para> - </footnote></entry> - <entry morerows="1">White Point</entry> - <entry morerows="1">Gamma Correction</entry> - <entry morerows="1">Luminance E'<subscript>Y</subscript></entry> - <entry spanname="quant">Quantization</entry> - </row> - <row> - <entry>Red</entry> - <entry>Green</entry> - <entry>Blue</entry> - <entry>Y'</entry> - <entry>Cb, Cr</entry> + <entry>Identifier</entry> + <entry>Details</entry> </row> </thead> <tbody valign="top"> <row> <entry><constant>V4L2_COLORSPACE_SMPTE170M</constant></entry> - <entry>1</entry> - <entry>NTSC/PAL according to <xref linkend="smpte170m" />, -<xref linkend="itu601" /></entry> - <entry>x = 0.630, y = 0.340</entry> - <entry>x = 0.310, y = 0.595</entry> - <entry>x = 0.155, y = 0.070</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-smpte-170m" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> - <entry>2</entry> - <entry>1125-Line (US) HDTV, see <xref -linkend="smpte240m" /></entry> - <entry>x = 0.630, y = 0.340</entry> - <entry>x = 0.310, y = 0.595</entry> - <entry>x = 0.155, y = 0.070</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4 I for I ≤0.0228, -1.1115 I<superscript>0.45</superscript> - 0.1115 for 0.0228 < I</entry> - <entry>0.212 E'<subscript>R</subscript> -+ 0.701 E'<subscript>G</subscript> -+ 0.087 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> + <entry>See <xref linkend="col-rec709" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_REC709</constant></entry> - <entry>3</entry> - <entry>HDTV and modern devices, see <xref -linkend="itu709" /></entry> - <entry>x = 0.640, y = 0.330</entry> - <entry>x = 0.300, y = 0.600</entry> - <entry>x = 0.150, y = 0.060</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry>0.2125 E'<subscript>R</subscript> -+ 0.7154 E'<subscript>G</subscript> -+ 0.0721 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> + <entry>See <xref linkend="col-srgb" />.</entry> </row> <row> - <entry><constant>V4L2_COLORSPACE_BT878</constant></entry> - <entry>4</entry> - <entry>Broken Bt878 extents<footnote> - <para>The ubiquitous Bt878 video capture chip -quantizes E'<subscript>Y</subscript> to 238 levels, yielding a range -of Y' = 16 … 253, unlike Rec. 601 Y' = 16 … -235. This is not a typo in the Bt878 documentation, it has been -implemented in silicon. The chroma extents are unclear.</para> - </footnote>, <xref linkend="itu601" /></entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry><emphasis>237</emphasis> E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128 (probably)</entry> + <entry><constant>V4L2_COLORSPACE_ADOBERGB</constant></entry> + <entry>See <xref linkend="col-adobergb" />.</entry> + </row> + <row> + <entry><constant>V4L2_COLORSPACE_BT2020</constant></entry> + <entry>See <xref linkend="col-bt2020" />.</entry> + </row> + <row> + <entry><constant>V4L2_COLORSPACE_SMPTE240M</constant></entry> + <entry>See <xref linkend="col-smpte-240m" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_470_SYSTEM_M</constant></entry> - <entry>5</entry> - <entry>M/NTSC<footnote> - <para>No identifier exists for M/PAL which uses -the chromaticities of M/NTSC, the remaining parameters are equal to B and -G/PAL.</para> - </footnote> according to <xref linkend="itu470" />, <xref - linkend="itu601" /></entry> - <entry>x = 0.67, y = 0.33</entry> - <entry>x = 0.21, y = 0.71</entry> - <entry>x = 0.14, y = 0.08</entry> - <entry>x = 0.310, y = 0.316, Illuminant C</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-sysm" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant></entry> - <entry>6</entry> - <entry>625-line PAL and SECAM systems according to <xref -linkend="itu470" />, <xref linkend="itu601" /></entry> - <entry>x = 0.64, y = 0.33</entry> - <entry>x = 0.29, y = 0.60</entry> - <entry>x = 0.15, y = 0.06</entry> - <entry>x = 0.313, y = 0.329, -Illuminant D<subscript>65</subscript></entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>219 E'<subscript>Y</subscript> + 16</entry> - <entry>224 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-sysbg" />.</entry> </row> <row> <entry><constant>V4L2_COLORSPACE_JPEG</constant></entry> - <entry>7</entry> - <entry>JPEG Y'CbCr, see <xref linkend="jfif" />, <xref linkend="itu601" /></entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>?</entry> - <entry>0.299 E'<subscript>R</subscript> -+ 0.587 E'<subscript>G</subscript> -+ 0.114 E'<subscript>B</subscript></entry> - <entry>256 E'<subscript>Y</subscript> + 16<footnote> - <para>Note JFIF quantizes -Y'P<subscript>B</subscript>P<subscript>R</subscript> in range [0;+1] and -[-0.5;+0.5] to <emphasis>257</emphasis> levels, however Y'CbCr signals -are still clamped to [0;255].</para> - </footnote></entry> - <entry>256 P<subscript>B,R</subscript> + 128</entry> + <entry>See <xref linkend="col-jpeg" />.</entry> </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="v4l2-ycbcr-encoding"> + <title>V4L2 Y'CbCr Encodings</title> + <tgroup cols="2" align="left"> + &cs-def; + <thead> <row> - <entry><constant>V4L2_COLORSPACE_SRGB</constant></entry> - <entry>8</entry> - <entry>[?]</entry> - <entry>x = 0.640, y = 0.330</entry> - <entry>x = 0.300, y = 0.600</entry> - <entry>x = 0.150, y = 0.060</entry> - <entry>x = 0.3127, y = 0.3290, - Illuminant D<subscript>65</subscript></entry> - <entry>E' = 4.5 I for I ≤0.018, -1.099 I<superscript>0.45</superscript> - 0.099 for 0.018 < I</entry> - <entry spanname="spam">n/a</entry> + <entry>Identifier</entry> + <entry>Details</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_YCBCR_ENC_DEFAULT</constant></entry> + <entry>Use the default Y'CbCr encoding as defined by the colorspace.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_601</constant></entry> + <entry>Use the BT.601 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_709</constant></entry> + <entry>Use the Rec. 709 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_XV601</constant></entry> + <entry>Use the extended gamut xvYCC BT.601 encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_XV709</constant></entry> + <entry>Use the extended gamut xvYCC Rec. 709 encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_SYCC</constant></entry> + <entry>Use the extended gamut sYCC encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_BT2020</constant></entry> + <entry>Use the default non-constant luminance BT.2020 Y'CbCr encoding.</entry> + </row> + <row> + <entry><constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant></entry> + <entry>Use the constant luminance BT.2020 Yc'CbcCrc encoding.</entry> + </row> + </tbody> + </tgroup> + </table> + + <table pgwide="1" frame="none" id="v4l2-quantization"> + <title>V4L2 Quantization Methods</title> + <tgroup cols="2" align="left"> + &cs-def; + <thead> + <row> + <entry>Identifier</entry> + <entry>Details</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry><constant>V4L2_QUANTIZATION_DEFAULT</constant></entry> + <entry>Use the default quantization encoding as defined by the colorspace. +This is always full range for R'G'B' and usually limited range for Y'CbCr.</entry> + </row> + <row> + <entry><constant>V4L2_QUANTIZATION_FULL_RANGE</constant></entry> + <entry>Use the full range quantization encoding. I.e. the range [0…1] +is mapped to [0…255] (with possible clipping to [1…254] to avoid the +0x00 and 0xff values). Cb and Cr are mapped from [-0.5…0.5] to [0…255] +(with possible clipping to [1…254] to avoid the 0x00 and 0xff values).</entry> + </row> + <row> + <entry><constant>V4L2_QUANTIZATION_LIM_RANGE</constant></entry> + <entry>Use the limited range quantization encoding. I.e. the range [0…1] +is mapped to [16…235]. Cb and Cr are mapped from [-0.5…0.5] to [16…240]. +</entry> </row> </tbody> </tgroup> </table> </section> + <section> + <title>Detailed Colorspace Descriptions</title> + <section> + <title id="col-smpte-170m">Colorspace SMPTE 170M (<constant>V4L2_COLORSPACE_SMPTE170M</constant>)</title> + <para>The <xref linkend="smpte170m" /> standard defines the colorspace used by NTSC and PAL and by SDTV +in general. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and +the white reference are:</para> + <table frame="none"> + <title>SMPTE 170M Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.630</entry> + <entry>0.340</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.310</entry> + <entry>0.595</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.155</entry> + <entry>0.070</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The red, green and blue chromaticities are also often referred to +as the SMPTE C set, so this colorspace is sometimes called SMPTE C as well.</para> + <variablelist> + <varlistentry> + <term>The transfer function defined for SMPTE 170M is the same as the +one defined in Rec. 709. Normally L is in the range [0…1], but for the extended +gamut xvYCC encoding values outside that range are allowed.</term> + <listitem> + <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> + <para>L' = 4.5L for -0.018 < L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> + <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with +the following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. This conversion to Y'CbCr is identical to the one +defined in the <xref linkend="itu601" /> standard and this colorspace is sometimes called BT.601 as well, even +though BT.601 does not mention any color primaries.</para> + <para>The default quantization is limited range, but full range is possible although +rarely seen.</para> + <para>The <constant>V4L2_YCBCR_ENC_601</constant> encoding as described above is the +default for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_709</constant>, +in which case the Rec. 709 Y'CbCr encoding is used.</para> + <variablelist> + <varlistentry> + <term>The xvYCC 601 encoding (<constant>V4L2_YCBCR_ENC_XV601</constant>, <xref linkend="xvycc" />) is similar +to the BT.601 encoding, but it allows for R', G' and B' values that are outside the range +[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> + <listitem> + <para>Y' = (219 / 255) * (0.299R' + 0.587G' + 0.114B') + (16 / 255)</para> + <para>Cb = (224 / 255) * (-0.169R' - 0.331G' + 0.5B')</para> + <para>Cr = (224 / 255) * (0.5R' - 0.419G' - 0.081B')</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The non-standard xvYCC 709 encoding can also be used by selecting +<constant>V4L2_YCBCR_ENC_XV709</constant>. The xvYCC encodings always use full range +quantization.</para> + </section> + + <section> + <title id="col-rec709">Colorspace Rec. 709 (<constant>V4L2_COLORSPACE_REC709</constant>)</title> + <para>The <xref linkend="itu709" /> standard defines the colorspace used by HDTV in general. The default +Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_709</constant>. The default Y'CbCr quantization is +limited range. The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>Rec. 709 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.640</entry> + <entry>0.330</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.300</entry> + <entry>0.600</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.150</entry> + <entry>0.060</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>The full name of this standard is Rec. ITU-R BT.709-5.</para> + <variablelist> + <varlistentry> + <term>Transfer function. Normally L is in the range [0…1], but for the extended +gamut xvYCC encoding values outside that range are allowed.</term> + <listitem> + <para>L' = -1.099(-L)<superscript>0.45</superscript> + 0.099 for L ≤ -0.018</para> + <para>L' = 4.5L for -0.018 < L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for L ≥ 0.018</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((L' - 0.099) / -1.099)<superscript>1/0.45</superscript> for L' ≤ -0.081</para> + <para>L = L' / 4.5 for -0.081 < L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following +<constant>V4L2_YCBCR_ENC_709</constant> encoding:</term> + <listitem> + <para>Y' = 0.2126R' + 0.7152G' + 0.0722B'</para> + <para>Cb = -0.1146R' - 0.3854G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4542G' - 0.0458B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5].</para> + <para>The default quantization is limited range, but full range is possible although +rarely seen.</para> + <para>The <constant>V4L2_YCBCR_ENC_709</constant> encoding described above is the default +for this colorspace, but it can be overridden with <constant>V4L2_YCBCR_ENC_601</constant>, in which +case the BT.601 Y'CbCr encoding is used.</para> + <variablelist> + <varlistentry> + <term>The xvYCC 709 encoding (<constant>V4L2_YCBCR_ENC_XV709</constant>, <xref linkend="xvycc" />) +is similar to the Rec. 709 encoding, but it allows for R', G' and B' values that are outside the range +[0…1]. The resulting Y', Cb and Cr values are scaled and offset:</term> + <listitem> + <para>Y' = (219 / 255) * (0.2126R' + 0.7152G' + 0.0722B') + (16 / 255)</para> + <para>Cb = (224 / 255) * (-0.1146R' - 0.3854G' + 0.5B')</para> + <para>Cr = (224 / 255) * (0.5R' - 0.4542G' - 0.0458B')</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The non-standard xvYCC 601 encoding can also be used by +selecting <constant>V4L2_YCBCR_ENC_XV601</constant>. The xvYCC encodings always use full +range quantization.</para> + </section> + + <section> + <title id="col-srgb">Colorspace sRGB (<constant>V4L2_COLORSPACE_SRGB</constant>)</title> + <para>The <xref linkend="srgb" /> standard defines the colorspace used by most webcams and computer graphics. The +default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SYCC</constant>. The default Y'CbCr quantization +is full range. The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>sRGB Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.640</entry> + <entry>0.330</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.300</entry> + <entry>0.600</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.150</entry> + <entry>0.060</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>These chromaticities are identical to the Rec. 709 colorspace.</para> + <variablelist> + <varlistentry> + <term>Transfer function. Note that negative values for L are only used by the Y'CbCr conversion.</term> + <listitem> + <para>L' = -1.055(-L)<superscript>1/2.4</superscript> + 0.055 for L < -0.0031308</para> + <para>L' = 12.92L for -0.0031308 ≤ L ≤ 0.0031308</para> + <para>L' = 1.055L<superscript>1/2.4</superscript> - 0.055 for 0.0031308 < L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = -((-L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' < -0.04045</para> + <para>L = L' / 12.92 for -0.04045 ≤ L' ≤ 0.04045</para> + <para>L = ((L' + 0.055) / 1.055)<superscript>2.4</superscript> for L' > 0.04045</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the following +<constant>V4L2_YCBCR_ENC_SYCC</constant> encoding as defined by <xref linkend="sycc" />:</term> + <listitem> + <para>Y' = 0.2990R' + 0.5870G' + 0.1140B'</para> + <para>Cb = -0.1687R' - 0.3313G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4187G' - 0.0813B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are clamped +to the range [-0.5…0.5]. The <constant>V4L2_YCBCR_ENC_SYCC</constant> quantization is always +full range. Although this Y'CbCr encoding looks very similar to the <constant>V4L2_YCBCR_ENC_XV601</constant> +encoding, it is not. The <constant>V4L2_YCBCR_ENC_XV601</constant> scales and offsets the Y'CbCr +values before quantization, but this encoding does not do that.</para> + </section> + + <section> + <title id="col-adobergb">Colorspace Adobe RGB (<constant>V4L2_COLORSPACE_ADOBERGB</constant>)</title> + <para>The <xref linkend="adobergb" /> standard defines the colorspace used by computer graphics +that use the AdobeRGB colorspace. This is also known as the <xref linkend="oprgb" /> standard. +The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr +quantization is limited range. The chromaticities of the primary colors and the white reference +are:</para> + <table frame="none"> + <title>Adobe RGB Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.6400</entry> + <entry>0.3300</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.2100</entry> + <entry>0.7100</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.1500</entry> + <entry>0.0600</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>Transfer function:</term> + <listitem> + <para>L' = L<superscript>1/2.19921875</superscript></para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L'<superscript>2.19921875</superscript></para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. This transform is identical to one defined in +SMPTE 170M/BT.601. The Y'CbCr quantization is limited range.</para> + </section> + + <section> + <title id="col-bt2020">Colorspace BT.2020 (<constant>V4L2_COLORSPACE_BT2020</constant>)</title> + <para>The <xref linkend="itu2020" /> standard defines the colorspace used by Ultra-high definition +television (UHDTV). The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_BT2020</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and +the white reference are:</para> + <table frame="none"> + <title>BT.2020 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.708</entry> + <entry>0.292</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.170</entry> + <entry>0.797</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.131</entry> + <entry>0.046</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>Transfer function (same as Rec. 709):</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_BT2020</constant> encoding:</term> + <listitem> + <para>Y' = 0.2627R' + 0.6789G' + 0.0593B'</para> + <para>Cb = -0.1396R' - 0.3604G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4598G' - 0.0402B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> + <para>There is also an alternate constant luminance R'G'B' to Yc'CbcCrc +(<constant>V4L2_YCBCR_ENC_BT2020_CONST_LUM</constant>) encoding:</para> + <variablelist> + <varlistentry> + <term>Luma:</term> + <listitem> + <para>Yc' = (0.2627R + 0.6789G + 0.0593B)'</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>B' - Yc' ≤ 0:</term> + <listitem> + <para>Cbc = (B' - Y') / 1.9404</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>B' - Yc' > 0:</term> + <listitem> + <para>Cbc = (B' - Y') / 1.5816</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>R' - Yc' ≤ 0:</term> + <listitem> + <para>Crc = (R' - Y') / 1.7184</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>R' - Yc' > 0:</term> + <listitem> + <para>Crc = (R' - Y') / 0.9936</para> + </listitem> + </varlistentry> + </variablelist> + <para>Yc' is clamped to the range [0…1] and Cbc and Crc are +clamped to the range [-0.5…0.5]. The Yc'CbcCrc quantization is limited range.</para> + </section> + + <section> + <title id="col-smpte-240m">Colorspace SMPTE 240M (<constant>V4L2_COLORSPACE_SMPTE240M</constant>)</title> + <para>The <xref linkend="smpte240m" /> standard was an interim standard used during the early days of HDTV (1988-1998). +It has been superseded by Rec. 709. The default Y'CbCr encoding is <constant>V4L2_YCBCR_ENC_SMPTE240M</constant>. +The default Y'CbCr quantization is limited range. The chromaticities of the primary colors and the +white reference are:</para> + <table frame="none"> + <title>SMPTE 240M Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.630</entry> + <entry>0.340</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.310</entry> + <entry>0.595</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.155</entry> + <entry>0.070</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <para>These chromaticities are identical to the SMPTE 170M colorspace.</para> + <variablelist> + <varlistentry> + <term>Transfer function:</term> + <listitem> + <para>L' = 4L for 0 ≤ L < 0.0228</para> + <para>L' = 1.1115L<superscript>0.45</superscript> - 0.1115 for 0.0228 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4 for 0 ≤ L' < 0.0913</para> + <para>L = ((L' + 0.1115) / 1.1115)<superscript>1/0.45</superscript> for L' ≥ 0.0913</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_SMPTE240M</constant> encoding:</term> + <listitem> + <para>Y' = 0.2122R' + 0.7013G' + 0.0865B'</para> + <para>Cb = -0.1161R' - 0.3839G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.4451G' - 0.0549B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Yc' is clamped to the range [0…1] and Cbc and Crc are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range.</para> + </section> + + <section> + <title id="col-sysm">Colorspace NTSC 1953 (<constant>V4L2_COLORSPACE_470_SYSTEM_M</constant>)</title> + <para>This standard defines the colorspace used by NTSC in 1953. In practice this +colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding +is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>NTSC 1953 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.67</entry> + <entry>0.33</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.21</entry> + <entry>0.71</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.14</entry> + <entry>0.08</entry> + </row> + <row> + <entry>White Reference (C)</entry> + <entry>0.310</entry> + <entry>0.316</entry> + </row> + </tbody> + </tgroup> + </table> + <para>Note that this colorspace uses Illuminant C instead of D65 as the +white reference. To correctly convert an image in this colorspace to another +that uses D65 you need to apply a chromatic adaptation algorithm such as the +Bradford method.</para> + <variablelist> + <varlistentry> + <term>The transfer function was never properly defined for NTSC 1953. The +Rec. 709 transfer function is recommended in the literature:</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. +This transform is identical to one defined in SMPTE 170M/BT.601.</para> + </section> + + <section> + <title id="col-sysbg">Colorspace EBU Tech. 3213 (<constant>V4L2_COLORSPACE_470_SYSTEM_BG</constant>)</title> + <para>The <xref linkend="tech3213" /> standard defines the colorspace used by PAL/SECAM in 1975. In practice this +colorspace is obsolete and SMPTE 170M should be used instead. The default Y'CbCr encoding +is <constant>V4L2_YCBCR_ENC_601</constant>. The default Y'CbCr quantization is limited range. +The chromaticities of the primary colors and the white reference are:</para> + <table frame="none"> + <title>EBU Tech. 3213 Chromaticities</title> + <tgroup cols="3" align="left"> + &cs-str; + <thead> + <row> + <entry>Color</entry> + <entry>x</entry> + <entry>y</entry> + </row> + </thead> + <tbody valign="top"> + <row> + <entry>Red</entry> + <entry>0.64</entry> + <entry>0.33</entry> + </row> + <row> + <entry>Green</entry> + <entry>0.29</entry> + <entry>0.60</entry> + </row> + <row> + <entry>Blue</entry> + <entry>0.15</entry> + <entry>0.06</entry> + </row> + <row> + <entry>White Reference (D65)</entry> + <entry>0.3127</entry> + <entry>0.3290</entry> + </row> + </tbody> + </tgroup> + </table> + <variablelist> + <varlistentry> + <term>The transfer function was never properly defined for this colorspace. +The Rec. 709 transfer function is recommended in the literature:</term> + <listitem> + <para>L' = 4.5L for 0 ≤ L < 0.018</para> + <para>L' = 1.099L<superscript>0.45</superscript> - 0.099 for 0.018 ≤ L ≤ 1</para> + </listitem> + </varlistentry> + <varlistentry> + <term>Inverse Transfer function:</term> + <listitem> + <para>L = L' / 4.5 for L' < 0.081</para> + <para>L = ((L' + 0.099) / 1.099)<superscript>1/0.45</superscript> for L' ≥ 0.081</para> + </listitem> + </varlistentry> + </variablelist> + <variablelist> + <varlistentry> + <term>The luminance (Y') and color difference (Cb and Cr) are obtained with the +following <constant>V4L2_YCBCR_ENC_601</constant> encoding:</term> + <listitem> + <para>Y' = 0.299R' + 0.587G' + 0.114B'</para> + <para>Cb = -0.169R' - 0.331G' + 0.5B'</para> + <para>Cr = 0.5R' - 0.419G' - 0.081B'</para> + </listitem> + </varlistentry> + </variablelist> + <para>Y' is clamped to the range [0…1] and Cb and Cr are +clamped to the range [-0.5…0.5]. The Y'CbCr quantization is limited range. +This transform is identical to one defined in SMPTE 170M/BT.601.</para> + </section> + + <section> + <title id="col-jpeg">Colorspace JPEG (<constant>V4L2_COLORSPACE_JPEG</constant>)</title> + <para>This colorspace defines the colorspace used by most (Motion-)JPEG formats. The chromaticities +of the primary colors and the white reference are identical to sRGB. The Y'CbCr encoding is +<constant>V4L2_YCBCR_ENC_601</constant> with full range quantization where +Y' is scaled to [0…255] and Cb/Cr are scaled to [-128…128] and +then clipped to [-128…127].</para> + <para>Note that the JPEG standard does not actually store colorspace information. +So if something other than sRGB is used, then the driver will have to set that information +explicitly. Effectively <constant>V4L2_COLORSPACE_JPEG</constant> can be considered to be +an abbreviation for <constant>V4L2_COLORSPACE_SRGB</constant>, <constant>V4L2_YCBCR_ENC_601</constant> +and <constant>V4L2_QUANTIZATION_FULL_RANGE</constant>.</para> + </section> + + </section> + <section id="pixfmt-indexed"> <title>Indexed Format</title> diff --git a/Documentation/DocBook/media/v4l/selections-common.xml b/Documentation/DocBook/media/v4l/selections-common.xml index 7502f784b8cc..d6d56fb6f9c0 100644 --- a/Documentation/DocBook/media/v4l/selections-common.xml +++ b/Documentation/DocBook/media/v4l/selections-common.xml @@ -63,6 +63,22 @@ <entry>Yes</entry> </row> <row> + <entry><constant>V4L2_SEL_TGT_NATIVE_SIZE</constant></entry> + <entry>0x0003</entry> + <entry>The native size of the device, e.g. a sensor's + pixel array. <structfield>left</structfield> and + <structfield>top</structfield> fields are zero for this + target. Setting the native size will generally only make + sense for memory to memory devices where the software can + create a canvas of a given size in which for example a + video frame can be composed. In that case + V4L2_SEL_TGT_NATIVE_SIZE can be used to configure the size + of that canvas. + </entry> + <entry>Yes</entry> + <entry>Yes</entry> + </row> + <row> <entry><constant>V4L2_SEL_TGT_COMPOSE</constant></entry> <entry>0x0100</entry> <entry>Compose rectangle. Used to configure scaling diff --git a/Documentation/DocBook/media/v4l/subdev-formats.xml b/Documentation/DocBook/media/v4l/subdev-formats.xml index b2d5a0363cba..c5ea868e3909 100644 --- a/Documentation/DocBook/media/v4l/subdev-formats.xml +++ b/Documentation/DocBook/media/v4l/subdev-formats.xml @@ -34,8 +34,24 @@ <xref linkend="colorspaces" /> for details.</entry> </row> <row> + <entry>&v4l2-ycbcr-encoding;</entry> + <entry><structfield>ycbcr_enc</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> + <entry>&v4l2-quantization;</entry> + <entry><structfield>quantization</structfield></entry> + <entry>This information supplements the +<structfield>colorspace</structfield> and must be set by the driver for +capture streams and by the application for output streams, +see <xref linkend="colorspaces" />.</entry> + </row> + <row> <entry>__u32</entry> - <entry><structfield>reserved</structfield>[7]</entry> + <entry><structfield>reserved</structfield>[6]</entry> <entry>Reserved for future extensions. Applications and drivers must set the array to zero.</entry> </row> @@ -86,7 +102,7 @@ green and 5-bit blue values padded on the high bit, transferred as 2 8-bit samples per pixel with the most significant bits (padding, red and half of the green value) transferred first will be named - <constant>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</constant>. + <constant>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</constant>. </para> <para>The following tables list existing packed RGB formats.</para> @@ -176,8 +192,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_BE</entry> <entry>0x1001</entry> <entry></entry> &dash-ent-24; @@ -204,8 +220,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB444-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_RGB444_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-RGB444-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_RGB444_2X8_PADHI_LE</entry> <entry>0x1002</entry> <entry></entry> &dash-ent-24; @@ -232,8 +248,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_BE</entry> <entry>0x1003</entry> <entry></entry> &dash-ent-24; @@ -260,8 +276,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB555-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_RGB555_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-RGB555-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_RGB555_2X8_PADHI_LE</entry> <entry>0x1004</entry> <entry></entry> &dash-ent-24; @@ -288,8 +304,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-BGR565-2X8-BE"> - <entry>V4L2_MBUS_FMT_BGR565_2X8_BE</entry> + <row id="MEDIA-BUS-FMT-BGR565-2X8-BE"> + <entry>MEDIA_BUS_FMT_BGR565_2X8_BE</entry> <entry>0x1005</entry> <entry></entry> &dash-ent-24; @@ -316,8 +332,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-BGR565-2X8-LE"> - <entry>V4L2_MBUS_FMT_BGR565_2X8_LE</entry> + <row id="MEDIA-BUS-FMT-BGR565-2X8-LE"> + <entry>MEDIA_BUS_FMT_BGR565_2X8_LE</entry> <entry>0x1006</entry> <entry></entry> &dash-ent-24; @@ -344,8 +360,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB565-2X8-BE"> - <entry>V4L2_MBUS_FMT_RGB565_2X8_BE</entry> + <row id="MEDIA-BUS-FMT-RGB565-2X8-BE"> + <entry>MEDIA_BUS_FMT_RGB565_2X8_BE</entry> <entry>0x1007</entry> <entry></entry> &dash-ent-24; @@ -372,8 +388,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB565-2X8-LE"> - <entry>V4L2_MBUS_FMT_RGB565_2X8_LE</entry> + <row id="MEDIA-BUS-FMT-RGB565-2X8-LE"> + <entry>MEDIA_BUS_FMT_RGB565_2X8_LE</entry> <entry>0x1008</entry> <entry></entry> &dash-ent-24; @@ -400,8 +416,8 @@ <entry>g<subscript>4</subscript></entry> <entry>g<subscript>3</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB666-1X18"> - <entry>V4L2_MBUS_FMT_RGB666_1X18</entry> + <row id="MEDIA-BUS-FMT-RGB666-1X18"> + <entry>MEDIA_BUS_FMT_RGB666_1X18</entry> <entry>0x1009</entry> <entry></entry> &dash-ent-14; @@ -424,8 +440,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-1X24"> - <entry>V4L2_MBUS_FMT_RGB888_1X24</entry> + <row id="MEDIA-BUS-FMT-RGB888-1X24"> + <entry>MEDIA_BUS_FMT_RGB888_1X24</entry> <entry>0x100a</entry> <entry></entry> &dash-ent-8; @@ -454,8 +470,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-2X12-BE"> - <entry>V4L2_MBUS_FMT_RGB888_2X12_BE</entry> + <row id="MEDIA-BUS-FMT-RGB888-2X12-BE"> + <entry>MEDIA_BUS_FMT_RGB888_2X12_BE</entry> <entry>0x100b</entry> <entry></entry> &dash-ent-20; @@ -490,8 +506,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-RGB888-2X12-LE"> - <entry>V4L2_MBUS_FMT_RGB888_2X12_LE</entry> + <row id="MEDIA-BUS-FMT-RGB888-2X12-LE"> + <entry>MEDIA_BUS_FMT_RGB888_2X12_LE</entry> <entry>0x100c</entry> <entry></entry> &dash-ent-20; @@ -526,8 +542,8 @@ <entry>g<subscript>5</subscript></entry> <entry>g<subscript>4</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-ARGB888-1X32"> - <entry>V4L2_MBUS_FMT_ARGB888_1X32</entry> + <row id="MEDIA-BUS-FMT-ARGB888-1X32"> + <entry>MEDIA_BUS_FMT_ARGB888_1X32</entry> <entry>0x100d</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -600,7 +616,7 @@ <para>For instance, a format with uncompressed 10-bit Bayer components arranged in a red, green, green, blue pattern transferred as 2 8-bit samples per pixel with the least significant bits transferred first will - be named <constant>V4L2_MBUS_FMT_SRGGB10_2X8_PADHI_LE</constant>. + be named <constant>MEDIA_BUS_FMT_SRGGB10_2X8_PADHI_LE</constant>. </para> <figure id="bayer-patterns"> @@ -663,8 +679,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-SBGGR8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR8_1X8</entry> <entry>0x3001</entry> <entry></entry> <entry>-</entry> @@ -680,8 +696,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG8_1X8</entry> <entry>0x3013</entry> <entry></entry> <entry>-</entry> @@ -697,8 +713,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG8_1X8</entry> <entry>0x3002</entry> <entry></entry> <entry>-</entry> @@ -714,8 +730,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB8_1X8</entry> <entry>0x3014</entry> <entry></entry> <entry>-</entry> @@ -731,8 +747,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR10_ALAW8_1X8</entry> <entry>0x3015</entry> <entry></entry> <entry>-</entry> @@ -748,8 +764,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG10_ALAW8_1X8</entry> <entry>0x3016</entry> <entry></entry> <entry>-</entry> @@ -765,8 +781,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG10_ALAW8_1X8</entry> <entry>0x3017</entry> <entry></entry> <entry>-</entry> @@ -782,8 +798,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-ALAW8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB10_ALAW8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-ALAW8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB10_ALAW8_1X8</entry> <entry>0x3018</entry> <entry></entry> <entry>-</entry> @@ -799,8 +815,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SBGGR10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SBGGR10_DPCM8_1X8</entry> <entry>0x300b</entry> <entry></entry> <entry>-</entry> @@ -816,8 +832,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SGBRG10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SGBRG10_DPCM8_1X8</entry> <entry>0x300c</entry> <entry></entry> <entry>-</entry> @@ -833,8 +849,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SGRBG10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SGRBG10_DPCM8_1X8</entry> <entry>0x3009</entry> <entry></entry> <entry>-</entry> @@ -850,8 +866,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-DPCM8-1X8"> - <entry>V4L2_MBUS_FMT_SRGGB10_DPCM8_1X8</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-DPCM8-1X8"> + <entry>MEDIA_BUS_FMT_SRGGB10_DPCM8_1X8</entry> <entry>0x300d</entry> <entry></entry> <entry>-</entry> @@ -867,8 +883,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-BE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_BE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-BE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_BE</entry> <entry>0x3003</entry> <entry></entry> <entry>-</entry> @@ -901,8 +917,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADHI-LE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADHI_LE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADHI-LE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADHI_LE</entry> <entry>0x3004</entry> <entry></entry> <entry>-</entry> @@ -935,8 +951,8 @@ <entry>b<subscript>9</subscript></entry> <entry>b<subscript>8</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-BE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_BE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-BE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_BE</entry> <entry>0x3005</entry> <entry></entry> <entry>-</entry> @@ -969,8 +985,8 @@ <entry>0</entry> <entry>0</entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-2X8-PADLO-LE"> - <entry>V4L2_MBUS_FMT_SBGGR10_2X8_PADLO_LE</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-2X8-PADLO-LE"> + <entry>MEDIA_BUS_FMT_SBGGR10_2X8_PADLO_LE</entry> <entry>0x3006</entry> <entry></entry> <entry>-</entry> @@ -1003,8 +1019,8 @@ <entry>b<subscript>3</subscript></entry> <entry>b<subscript>2</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR10-1X10"> - <entry>V4L2_MBUS_FMT_SBGGR10_1X10</entry> + <row id="MEDIA-BUS-FMT-SBGGR10-1X10"> + <entry>MEDIA_BUS_FMT_SBGGR10_1X10</entry> <entry>0x3007</entry> <entry></entry> <entry>-</entry> @@ -1020,8 +1036,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG10-1X10"> - <entry>V4L2_MBUS_FMT_SGBRG10_1X10</entry> + <row id="MEDIA-BUS-FMT-SGBRG10-1X10"> + <entry>MEDIA_BUS_FMT_SGBRG10_1X10</entry> <entry>0x300e</entry> <entry></entry> <entry>-</entry> @@ -1037,8 +1053,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG10-1X10"> - <entry>V4L2_MBUS_FMT_SGRBG10_1X10</entry> + <row id="MEDIA-BUS-FMT-SGRBG10-1X10"> + <entry>MEDIA_BUS_FMT_SGRBG10_1X10</entry> <entry>0x300a</entry> <entry></entry> <entry>-</entry> @@ -1054,8 +1070,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB10-1X10"> - <entry>V4L2_MBUS_FMT_SRGGB10_1X10</entry> + <row id="MEDIA-BUS-FMT-SRGGB10-1X10"> + <entry>MEDIA_BUS_FMT_SRGGB10_1X10</entry> <entry>0x300f</entry> <entry></entry> <entry>-</entry> @@ -1071,8 +1087,8 @@ <entry>r<subscript>1</subscript></entry> <entry>r<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SBGGR12-1X12"> - <entry>V4L2_MBUS_FMT_SBGGR12_1X12</entry> + <row id="MEDIA-BUS-FMT-SBGGR12-1X12"> + <entry>MEDIA_BUS_FMT_SBGGR12_1X12</entry> <entry>0x3008</entry> <entry></entry> <entry>b<subscript>11</subscript></entry> @@ -1088,8 +1104,8 @@ <entry>b<subscript>1</subscript></entry> <entry>b<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGBRG12-1X12"> - <entry>V4L2_MBUS_FMT_SGBRG12_1X12</entry> + <row id="MEDIA-BUS-FMT-SGBRG12-1X12"> + <entry>MEDIA_BUS_FMT_SGBRG12_1X12</entry> <entry>0x3010</entry> <entry></entry> <entry>g<subscript>11</subscript></entry> @@ -1105,8 +1121,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SGRBG12-1X12"> - <entry>V4L2_MBUS_FMT_SGRBG12_1X12</entry> + <row id="MEDIA-BUS-FMT-SGRBG12-1X12"> + <entry>MEDIA_BUS_FMT_SGRBG12_1X12</entry> <entry>0x3011</entry> <entry></entry> <entry>g<subscript>11</subscript></entry> @@ -1122,8 +1138,8 @@ <entry>g<subscript>1</subscript></entry> <entry>g<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-SRGGB12-1X12"> - <entry>V4L2_MBUS_FMT_SRGGB12_1X12</entry> + <row id="MEDIA-BUS-FMT-SRGGB12-1X12"> + <entry>MEDIA_BUS_FMT_SRGGB12_1X12</entry> <entry>0x3012</entry> <entry></entry> <entry>r<subscript>11</subscript></entry> @@ -1175,7 +1191,7 @@ <para>For instance, a format where pixels are encoded as 8-bit YUV values downsampled to 4:2:2 and transferred as 2 8-bit bus samples per pixel in the - U, Y, V, Y order will be named <constant>V4L2_MBUS_FMT_UYVY8_2X8</constant>. + U, Y, V, Y order will be named <constant>MEDIA_BUS_FMT_UYVY8_2X8</constant>. </para> <para><xref linkend="v4l2-mbus-pixelcode-yuv8"/> lists existing packed YUV @@ -1280,8 +1296,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-Y8-1X8"> - <entry>V4L2_MBUS_FMT_Y8_1X8</entry> + <row id="MEDIA-BUS-FMT-Y8-1X8"> + <entry>MEDIA_BUS_FMT_Y8_1X8</entry> <entry>0x2001</entry> <entry></entry> &dash-ent-24; @@ -1294,8 +1310,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UV8-1X8"> - <entry>V4L2_MBUS_FMT_UV8_1X8</entry> + <row id="MEDIA-BUS-FMT-UV8-1X8"> + <entry>MEDIA_BUS_FMT_UV8_1X8</entry> <entry>0x2015</entry> <entry></entry> &dash-ent-24; @@ -1322,8 +1338,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-1_5X8"> - <entry>V4L2_MBUS_FMT_UYVY8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-UYVY8-1_5X8"> + <entry>MEDIA_BUS_FMT_UYVY8_1_5X8</entry> <entry>0x2002</entry> <entry></entry> &dash-ent-24; @@ -1406,8 +1422,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-1_5X8"> - <entry>V4L2_MBUS_FMT_VYUY8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-VYUY8-1_5X8"> + <entry>MEDIA_BUS_FMT_VYUY8_1_5X8</entry> <entry>0x2003</entry> <entry></entry> &dash-ent-24; @@ -1490,8 +1506,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-1_5X8"> - <entry>V4L2_MBUS_FMT_YUYV8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-YUYV8-1_5X8"> + <entry>MEDIA_BUS_FMT_YUYV8_1_5X8</entry> <entry>0x2004</entry> <entry></entry> &dash-ent-24; @@ -1574,8 +1590,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-1_5X8"> - <entry>V4L2_MBUS_FMT_YVYU8_1_5X8</entry> + <row id="MEDIA-BUS-FMT-YVYU8-1_5X8"> + <entry>MEDIA_BUS_FMT_YVYU8_1_5X8</entry> <entry>0x2005</entry> <entry></entry> &dash-ent-24; @@ -1658,8 +1674,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-2X8"> - <entry>V4L2_MBUS_FMT_UYVY8_2X8</entry> + <row id="MEDIA-BUS-FMT-UYVY8-2X8"> + <entry>MEDIA_BUS_FMT_UYVY8_2X8</entry> <entry>0x2006</entry> <entry></entry> &dash-ent-24; @@ -1714,8 +1730,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-2X8"> - <entry>V4L2_MBUS_FMT_VYUY8_2X8</entry> + <row id="MEDIA-BUS-FMT-VYUY8-2X8"> + <entry>MEDIA_BUS_FMT_VYUY8_2X8</entry> <entry>0x2007</entry> <entry></entry> &dash-ent-24; @@ -1770,8 +1786,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-2X8"> - <entry>V4L2_MBUS_FMT_YUYV8_2X8</entry> + <row id="MEDIA-BUS-FMT-YUYV8-2X8"> + <entry>MEDIA_BUS_FMT_YUYV8_2X8</entry> <entry>0x2008</entry> <entry></entry> &dash-ent-24; @@ -1826,8 +1842,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-2X8"> - <entry>V4L2_MBUS_FMT_YVYU8_2X8</entry> + <row id="MEDIA-BUS-FMT-YVYU8-2X8"> + <entry>MEDIA_BUS_FMT_YVYU8_2X8</entry> <entry>0x2009</entry> <entry></entry> &dash-ent-24; @@ -1882,8 +1898,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-Y10-1X10"> - <entry>V4L2_MBUS_FMT_Y10_1X10</entry> + <row id="MEDIA-BUS-FMT-Y10-1X10"> + <entry>MEDIA_BUS_FMT_Y10_1X10</entry> <entry>0x200a</entry> <entry></entry> &dash-ent-22; @@ -1898,8 +1914,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY10-2X10"> - <entry>V4L2_MBUS_FMT_UYVY10_2X10</entry> + <row id="MEDIA-BUS-FMT-UYVY10-2X10"> + <entry>MEDIA_BUS_FMT_UYVY10_2X10</entry> <entry>0x2018</entry> <entry></entry> &dash-ent-22; @@ -1962,8 +1978,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY10-2X10"> - <entry>V4L2_MBUS_FMT_VYUY10_2X10</entry> + <row id="MEDIA-BUS-FMT-VYUY10-2X10"> + <entry>MEDIA_BUS_FMT_VYUY10_2X10</entry> <entry>0x2019</entry> <entry></entry> &dash-ent-22; @@ -2026,8 +2042,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV10-2X10"> - <entry>V4L2_MBUS_FMT_YUYV10_2X10</entry> + <row id="MEDIA-BUS-FMT-YUYV10-2X10"> + <entry>MEDIA_BUS_FMT_YUYV10_2X10</entry> <entry>0x200b</entry> <entry></entry> &dash-ent-22; @@ -2090,8 +2106,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU10-2X10"> - <entry>V4L2_MBUS_FMT_YVYU10_2X10</entry> + <row id="MEDIA-BUS-FMT-YVYU10-2X10"> + <entry>MEDIA_BUS_FMT_YVYU10_2X10</entry> <entry>0x200c</entry> <entry></entry> &dash-ent-22; @@ -2154,8 +2170,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-Y12-1X12"> - <entry>V4L2_MBUS_FMT_Y12_1X12</entry> + <row id="MEDIA-BUS-FMT-Y12-1X12"> + <entry>MEDIA_BUS_FMT_Y12_1X12</entry> <entry>0x2013</entry> <entry></entry> &dash-ent-20; @@ -2172,8 +2188,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY8-1X16"> - <entry>V4L2_MBUS_FMT_UYVY8_1X16</entry> + <row id="MEDIA-BUS-FMT-UYVY8-1X16"> + <entry>MEDIA_BUS_FMT_UYVY8_1X16</entry> <entry>0x200f</entry> <entry></entry> &dash-ent-16; @@ -2216,8 +2232,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY8-1X16"> - <entry>V4L2_MBUS_FMT_VYUY8_1X16</entry> + <row id="MEDIA-BUS-FMT-VYUY8-1X16"> + <entry>MEDIA_BUS_FMT_VYUY8_1X16</entry> <entry>0x2010</entry> <entry></entry> &dash-ent-16; @@ -2260,8 +2276,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV8-1X16"> - <entry>V4L2_MBUS_FMT_YUYV8_1X16</entry> + <row id="MEDIA-BUS-FMT-YUYV8-1X16"> + <entry>MEDIA_BUS_FMT_YUYV8_1X16</entry> <entry>0x2011</entry> <entry></entry> &dash-ent-16; @@ -2304,8 +2320,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU8-1X16"> - <entry>V4L2_MBUS_FMT_YVYU8_1X16</entry> + <row id="MEDIA-BUS-FMT-YVYU8-1X16"> + <entry>MEDIA_BUS_FMT_YVYU8_1X16</entry> <entry>0x2012</entry> <entry></entry> &dash-ent-16; @@ -2348,8 +2364,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YDYUYDYV8-1X16"> - <entry>V4L2_MBUS_FMT_YDYUYDYV8_1X16</entry> + <row id="MEDIA-BUS-FMT-YDYUYDYV8-1X16"> + <entry>MEDIA_BUS_FMT_YDYUYDYV8_1X16</entry> <entry>0x2014</entry> <entry></entry> &dash-ent-16; @@ -2436,8 +2452,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY10-1X20"> - <entry>V4L2_MBUS_FMT_UYVY10_1X20</entry> + <row id="MEDIA-BUS-FMT-UYVY10-1X20"> + <entry>MEDIA_BUS_FMT_UYVY10_1X20</entry> <entry>0x201a</entry> <entry></entry> &dash-ent-12; @@ -2488,8 +2504,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY10-1X20"> - <entry>V4L2_MBUS_FMT_VYUY10_1X20</entry> + <row id="MEDIA-BUS-FMT-VYUY10-1X20"> + <entry>MEDIA_BUS_FMT_VYUY10_1X20</entry> <entry>0x201b</entry> <entry></entry> &dash-ent-12; @@ -2540,8 +2556,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV10-1X20"> - <entry>V4L2_MBUS_FMT_YUYV10_1X20</entry> + <row id="MEDIA-BUS-FMT-YUYV10-1X20"> + <entry>MEDIA_BUS_FMT_YUYV10_1X20</entry> <entry>0x200d</entry> <entry></entry> &dash-ent-12; @@ -2592,8 +2608,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU10-1X20"> - <entry>V4L2_MBUS_FMT_YVYU10_1X20</entry> + <row id="MEDIA-BUS-FMT-YVYU10-1X20"> + <entry>MEDIA_BUS_FMT_YVYU10_1X20</entry> <entry>0x200e</entry> <entry></entry> &dash-ent-12; @@ -2644,8 +2660,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUV10-1X30"> - <entry>V4L2_MBUS_FMT_YUV10_1X30</entry> + <row id="MEDIA-BUS-FMT-YUV10-1X30"> + <entry>MEDIA_BUS_FMT_YUV10_1X30</entry> <entry>0x2016</entry> <entry></entry> <entry>-</entry> @@ -2681,8 +2697,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-AYUV8-1X32"> - <entry>V4L2_MBUS_FMT_AYUV8_1X32</entry> + <row id="MEDIA-BUS-FMT-AYUV8-1X32"> + <entry>MEDIA_BUS_FMT_AYUV8_1X32</entry> <entry>0x2017</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -2718,8 +2734,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY12-2X12"> - <entry>V4L2_MBUS_FMT_UYVY12_2X12</entry> + <row id="MEDIA-BUS-FMT-UYVY12-2X12"> + <entry>MEDIA_BUS_FMT_UYVY12_2X12</entry> <entry>0x201c</entry> <entry></entry> &dash-ent-20; @@ -2790,8 +2806,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY12-2X12"> - <entry>V4L2_MBUS_FMT_VYUY12_2X12</entry> + <row id="MEDIA-BUS-FMT-VYUY12-2X12"> + <entry>MEDIA_BUS_FMT_VYUY12_2X12</entry> <entry>0x201d</entry> <entry></entry> &dash-ent-20; @@ -2862,8 +2878,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV12-2X12"> - <entry>V4L2_MBUS_FMT_YUYV12_2X12</entry> + <row id="MEDIA-BUS-FMT-YUYV12-2X12"> + <entry>MEDIA_BUS_FMT_YUYV12_2X12</entry> <entry>0x201e</entry> <entry></entry> &dash-ent-20; @@ -2934,8 +2950,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU12-2X12"> - <entry>V4L2_MBUS_FMT_YVYU12_2X12</entry> + <row id="MEDIA-BUS-FMT-YVYU12-2X12"> + <entry>MEDIA_BUS_FMT_YVYU12_2X12</entry> <entry>0x201f</entry> <entry></entry> &dash-ent-20; @@ -3006,8 +3022,8 @@ <entry>u<subscript>1</subscript></entry> <entry>u<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-UYVY12-1X24"> - <entry>V4L2_MBUS_FMT_UYVY12_1X24</entry> + <row id="MEDIA-BUS-FMT-UYVY12-1X24"> + <entry>MEDIA_BUS_FMT_UYVY12_1X24</entry> <entry>0x2020</entry> <entry></entry> &dash-ent-8; @@ -3066,8 +3082,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-VYUY12-1X24"> - <entry>V4L2_MBUS_FMT_VYUY12_1X24</entry> + <row id="MEDIA-BUS-FMT-VYUY12-1X24"> + <entry>MEDIA_BUS_FMT_VYUY12_1X24</entry> <entry>0x2021</entry> <entry></entry> &dash-ent-8; @@ -3126,8 +3142,8 @@ <entry>y<subscript>1</subscript></entry> <entry>y<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YUYV12-1X24"> - <entry>V4L2_MBUS_FMT_YUYV12_1X24</entry> + <row id="MEDIA-BUS-FMT-YUYV12-1X24"> + <entry>MEDIA_BUS_FMT_YUYV12_1X24</entry> <entry>0x2022</entry> <entry></entry> &dash-ent-8; @@ -3186,8 +3202,8 @@ <entry>v<subscript>1</subscript></entry> <entry>v<subscript>0</subscript></entry> </row> - <row id="V4L2-MBUS-FMT-YVYU12-1X24"> - <entry>V4L2_MBUS_FMT_YVYU12_1X24</entry> + <row id="MEDIA-BUS-FMT-YVYU12-1X24"> + <entry>MEDIA_BUS_FMT_YVYU12_1X24</entry> <entry>0x2023</entry> <entry></entry> &dash-ent-8; @@ -3366,8 +3382,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-AHSV8888-1X32"> - <entry>V4L2_MBUS_FMT_AHSV8888_1X32</entry> + <row id="MEDIA-BUS-FMT-AHSV8888-1X32"> + <entry>MEDIA_BUS_FMT_AHSV8888_1X32</entry> <entry>0x6001</entry> <entry></entry> <entry>a<subscript>7</subscript></entry> @@ -3422,7 +3438,7 @@ </para> <para>For instance, for a JPEG baseline process and an 8-bit bus width - the format will be named <constant>V4L2_MBUS_FMT_JPEG_1X8</constant>. + the format will be named <constant>MEDIA_BUS_FMT_JPEG_1X8</constant>. </para> <para>The following table lists existing JPEG compressed formats.</para> @@ -3441,8 +3457,8 @@ </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-JPEG-1X8"> - <entry>V4L2_MBUS_FMT_JPEG_1X8</entry> + <row id="MEDIA-BUS-FMT-JPEG-1X8"> + <entry>MEDIA_BUS_FMT_JPEG_1X8</entry> <entry>0x4001</entry> <entry>Besides of its usage for the parallel bus this format is recommended for transmission of JPEG data over MIPI CSI bus @@ -3484,8 +3500,8 @@ interface and may change in the future.</para> </row> </thead> <tbody valign="top"> - <row id="V4L2-MBUS-FMT-S5C-UYVY-JPEG-1X8"> - <entry>V4L2_MBUS_FMT_S5C_UYVY_JPEG_1X8</entry> + <row id="MEDIA-BUS-FMT-S5C-UYVY-JPEG-1X8"> + <entry>MEDIA_BUS_FMT_S5C_UYVY_JPEG_1X8</entry> <entry>0x5001</entry> <entry> Interleaved raw UYVY and JPEG image format with embedded diff --git a/Documentation/DocBook/media/v4l/v4l2.xml b/Documentation/DocBook/media/v4l/v4l2.xml index 7cfe618f754d..ac0f8d9d2a49 100644 --- a/Documentation/DocBook/media/v4l/v4l2.xml +++ b/Documentation/DocBook/media/v4l/v4l2.xml @@ -152,6 +152,15 @@ structs, ioctls) must be noted in more detail in the history chapter applications. --> <revision> + <revnumber>3.19</revnumber> + <date>2014-12-05</date> + <authorinitials>hv</authorinitials> + <revremark>Rewrote Colorspace chapter, added new &v4l2-ycbcr-encoding; and &v4l2-quantization; fields +to &v4l2-pix-format;, &v4l2-pix-format-mplane; and &v4l2-mbus-framefmt;. + </revremark> + </revision> + + <revision> <revnumber>3.17</revnumber> <date>2014-08-04</date> <authorinitials>lp, hv</authorinitials> @@ -539,7 +548,7 @@ and discussions on the V4L mailing list.</revremark> </partinfo> <title>Video for Linux Two API Specification</title> - <subtitle>Revision 3.17</subtitle> + <subtitle>Revision 3.19</subtitle> <chapter id="common"> &sub-common; diff --git a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml index 493a39a8ef21..603fecef9083 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enuminput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enuminput.xml @@ -287,6 +287,14 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>0x00000004</entry> <entry>This input supports setting the TV standard by using VIDIOC_S_STD.</entry> </row> + <row> + <entry><constant>V4L2_IN_CAP_NATIVE_SIZE</constant></entry> + <entry>0x00000008</entry> + <entry>This input supports setting the native size using + the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant> + selection target, see <xref + linkend="v4l2-selections-common"/>.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml index 2654e097df39..773fb1258c24 100644 --- a/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml +++ b/Documentation/DocBook/media/v4l/vidioc-enumoutput.xml @@ -172,6 +172,14 @@ input/output interface to linux-media@vger.kernel.org on 19 Oct 2009. <entry>0x00000004</entry> <entry>This output supports setting the TV standard by using VIDIOC_S_STD.</entry> </row> + <row> + <entry><constant>V4L2_OUT_CAP_NATIVE_SIZE</constant></entry> + <entry>0x00000008</entry> + <entry>This output supports setting the native size using + the <constant>V4L2_SEL_TGT_NATIVE_SIZE</constant> + selection target, see <xref + linkend="v4l2-selections-common"/>.</entry> + </row> </tbody> </tgroup> </table> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl index bbe9c1fd5cef..1fdc246e4256 100644 --- a/Documentation/DocBook/uio-howto.tmpl +++ b/Documentation/DocBook/uio-howto.tmpl @@ -540,7 +540,7 @@ appears in sysfs. </para></listitem> <listitem><para> -<varname>unsigned long size</varname>: Fill in the size of the +<varname>resource_size_t size</varname>: Fill in the size of the memory block that <varname>addr</varname> points to. If <varname>size</varname> is zero, the mapping is considered unused. Note that you <emphasis>must</emphasis> initialize <varname>size</varname> with zero for diff --git a/Documentation/DocBook/writing-an-alsa-driver.tmpl b/Documentation/DocBook/writing-an-alsa-driver.tmpl index 784793df81ed..84ef6a90131c 100644 --- a/Documentation/DocBook/writing-an-alsa-driver.tmpl +++ b/Documentation/DocBook/writing-an-alsa-driver.tmpl @@ -3658,6 +3658,29 @@ struct _snd_pcm_runtime { </para> <para> + The above callback can be simplified with a helper function, + <function>snd_ctl_enum_info</function>. The final code + looks like below. + (You can pass ARRAY_SIZE(texts) instead of 4 in the third + argument; it's a matter of taste.) + + <informalexample> + <programlisting> +<![CDATA[ + static int snd_myctl_enum_info(struct snd_kcontrol *kcontrol, + struct snd_ctl_elem_info *uinfo) + { + static char *texts[4] = { + "First", "Second", "Third", "Fourth" + }; + return snd_ctl_enum_info(uinfo, 1, 4, texts); + } +]]> + </programlisting> + </informalexample> + </para> + + <para> Some common info callbacks are available for your convenience: <function>snd_ctl_boolean_mono_info()</function> and <function>snd_ctl_boolean_stereo_info()</function>. |