diff options
author | Daniel Vetter <daniel.vetter@ffwll.ch> | 2015-01-12 23:07:46 +0100 |
---|---|---|
committer | Daniel Vetter <daniel.vetter@ffwll.ch> | 2015-01-12 23:07:46 +0100 |
commit | 0a87a2db485a1456b7427914969c0e8195a1bbda (patch) | |
tree | 8d0186672af22c6ee76118c471881cd66a36502d /Documentation/DocBook | |
parent | 7226572d8ed48f7e1aa9de5383d919490d6e9a0c (diff) | |
parent | fcf3aac5fc307f0cae429f5844ddc25761662858 (diff) |
Merge tag 'topic/i915-hda-componentized-2015-01-12' into drm-intel-next-queued
Conflicts:
drivers/gpu/drm/i915/intel_runtime_pm.c
Separate branch so that Takashi can also pull just this refactoring
into sound-next.
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
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 | 39 | ||||
-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 | 12 | ||||
-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 |
17 files changed, 2721 insertions, 523 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); |