bindings: Add device-tree bindings for QTI crypto drivers

* QTI Over the Air (OTA) Crypto device used in FSM9xxx target

Required properties:

- compatible : Should be "qcom,qcota"

- reg        : Offset and length of the register set for the device

Optional property:

Example:

	qcom_cedev: qcota@1de0000 {

		compatible = "qcom,qcedev";

		reg = <0x1de0000 0x20000>,

			<0x1dc4000 0x24000>;

	};

Introduction:

=============

The QTI crypto engine (qce) driver is a module that

provides common services for accessing the QTI crypto device.

Currently, the two main clients of qce are

-qcrypto driver (module provided for accessing CE HW by kernel space apps)

-qcedev driver (module provided for accessing CE HW by user space apps)

The crypto engine (qce) driver is a client to the DMA driver for the QTI

DMA device - Application Data Mover (ADM). ADM is used to provide the DMA

transfer capability between QTI crypto device hardware and DDR memory

for crypto operations.

  Figure 1.

  ---------

  Linux kernel

  (ex:IPSec)<-----*  QTI crypto driver----+

			(qcrypto)	  |

		   (for kernel space app) |

					  |

					  +-->|

					      |

					      | *qce   <----> QTI

					      | driver        ADM driver <---> ADM HW

					  +-->|			|		|

					  |			|		|

					  |			|		|

					  |			|		|

   Linux kernel				  |			|		|

   misc device  <--- *QCEDEV Driver-------+			|		|

   interface             (qcedev) 			(Reg interface)	 (DMA interface)

			(for user space app)			\		/

								 \	       /

								  \	      /

								   \	     /

								    \	    /

								     \	   /

								      \	  /

								QTI crypto CE3 HW

 The entities marked with (*) in the Figure 1, are the software components of

 the Linux QTI crypto modules.

===============

IMPORTANT NOTE:

===============

(1) The CE hardware can be accessed either from user space OR kernel space,

    at one time. Both user space and kernel space clients cannot access the

    qce driver (and the CE hardware) at the same time.

	- If your device has user space apps that needs to access the crypto

	  hardware, make sure to have the qcrypto module disabled/unloaded.

	  This will result in the kernel space apps to use the registered

	  software implementation of the crypto algorithms.

	- If your device has kernel space apps that needs to access the

	  crypto hardware, make sure to have qcedev module disabled/unloaded

	  and implement your user space application to use the software

	  implementation (ex: openssl/crypto) of the crypto algorithms.

(2) If your device has Playready(Windows Media DRM) application enabled and

    uses the qcedev module to access the crypto hardware accelerator,

    please be informed that for performance reasons, the CE hardware will need

    to be dedicated to playready application.  Any other user space application

    should be implemented to use the SW implementation (ex: openssl/crypto)

    of the crypto algorithms.

Hardware description:

=====================

QTI Crypto HW device family provides a series of algorithms implemented

in the device hardware.

Crypto 2 hardware provides hashing - SHA-1, SHA-256, ciphering - DES, 3DES, AES

algorithms, and concurrent operations of hashing, and ciphering.

In addition to those functions provided by Crypto 2 HW, Crypto 3 HW provides

fast AES algorithms.

In addition to those functions provided by Crypto 3 HW, Crypto 3E provides

HMAC-SHA1 hashing algorithm, and Over The Air (OTA) f8/f9 algorithms as

defined by the 3GPP forum.

Software description

====================

The crypto device is defined as a platform device. The driver is

independent of the platform. The driver supports multiple instances of

crypto HW.

All the platform specific parameters are defined in the board init

file, eg. arch/arm/mach-msm/board-msm7x30.c for MSM7x30.

The qce driver provide the common services of HW crypto

access to the two drivers as listed above (qcedev, qcrypto. It sets up

the crypto HW device for the operation, then it requests ADM driver for

the DMA of the crypto operation.

Two ADM channels and two command lists (one command list for each

channel) are involved in an operation.

The setting up of the command lists and the procedure of the operation

of the crypto device are described in the following sections.

The command list for the first DMA channel is set up as follows:

  1st command of the list is for the DMA transfer from DDR memory to the

  crypto device to input data to crypto device. The dst crci of the command

  is set for crci-in for this crypto device.

  2nd command is for the DMA transfer is from crypto device to DDR memory for

  the authentication result. The src crci is set as crci-hash-done of the

  crypto device. If authentication is not required in the operation,

  the 2nd command is not used.

The command list for the second DMA channel is set up as follows:

  One command to DMA data from crypto device to DDR memory for encryption or

  decryption output from crypto device.

To accomplish ciphering and authentication concurrent operations, the driver

performs the following steps:

    (a). set up HW crypto device

    (b). hit the crypto go register.

    (c). issue the DMA command of first channel to the ADM driver,

    (d). issue the DMA command of 2nd channel to the ADM driver.

SHA1/SHA256 is an authentication/integrity hash algorithm. To accomplish

hash operation (or any authentication only algorithm), 2nd DMA channel is

not required. Only steps (a) to (c) are performed.

At the completion of the DMA operation (for (c) and (d)) ADM driver

invokes the callback registered to the DMA driver. This signifies the end of

the DMA operation(s). The driver reads the status and other information from

the CE hardware register and then invokes the callback to the qce driver client.

This signal the completion and the results of the DMA along with the status of

the CE hardware to the qce driver client. This completes a crypto operation.

In the qce driver initialization, memory for the two command lists, descriptor

lists for each crypto device are allocated out of coherent memory, using Linux

DMA API. The driver pre-configures most of the two ADM command lists

in the initialization. During each crypto operation, minimal set up is required.

src_dscr or/and dst_dscr descriptor list of the ADM command are populated

from the information obtained from the corresponding data structure. eg: for

AEAD request, the following data structure provides the information:

    struct aead_request *req

      ......

    req->assoc

    req->src

    req->dst

The DMA address of a scatter list will be retrieved and set up in the

descriptor list of an ADM command.

Power Management

================

  none

Interface:

==========

The interface is defined in qce.h

The clients qcrypto, qcedev drivers are the clients using

the interfaces.

The following services are provided by the qce driver -

     qce_open(), qce_close(), qce_ablk_cipher_req(),

     qce_hw_support(), qce_process_sha_req()

  qce_open() is the first request from the client, ex. QTI crypto

  driver (qcedev, qcrypto), to open a crypto engine. It is normally

  called at the probe function of the client for a device. During the

  probe,

  - ADM command list structure will be set up

  - Crypto device will be initialized.

  - Resource associated with the crypto engine is retrieved by doing

    platform_get_resource() or platform_get_resource_byname().

 The resources for a device are

    - crci-in, crci-out, crci-hash-done

    - two DMA channel IDs, one for encryption and decryption input, one for

      output.

    - base address of the HW crypto device.

  qce_close() is the last request from the client. Normally, it is

  called from the remove function of the client.

  qce_hw_support() allows the client to query what is supported

  by the crypto engine hardware.

  qce_ablk_cipher_req() provides ciphering service to the client.

  qce_process_sha_req() provide hashing service to the client.

  qce_aead_req() provide aead service to the client.

Module parameters:

==================

The following module parameters are defined in the board init file.

-CE hardware base register address

-Data mover channel used for transfer to/from CE hardware

These parameters differ in each platform.

Dependencies:

=============

Existing DMA driver.

The transfers are DMA'ed between the crypto hardware and DDR memory via the

data mover, ADM. The data transfers are set up to use the existing dma driver.

User space utilities:

=====================

  n/a

Known issues:

=============

  n/a

To do:

======

  n/a

Introduction:

=============

This driver provides IOCTLS for user space application to access crypto

engine hardware for the qcedev crypto services. The driver supports the

following crypto algorithms

- AES-128, AES-256 (ECB, CBC and CTR mode)

- AES-192, (ECB, CBC and CTR mode)

  (support exists on platform supporting CE 3.x hardware)

- SHA1/SHA256

- AES-128, AES-256 (XTS), AES CMAC, SHA1/SHA256 HMAC

  (support exists on platform supporting CE 4.x hardware)

Device tree settings:

==============

Required properties:

- compatible : Should be "qcom,qcedev"

- reg        : Offset and length of the register set for the device

- interconnect-names: interconnect names

- interconnects: interconnect setting defines belong to which NoC device

- qcom_cedev_ns_cb compatible: Should be "qcom,qcedev,context-bank"

- qcom_cedev_s_cb compatible: Should be "qcom,qcedev,context-bank"

Optional property:

Example:

	qcom_cedev: qcedev@1de0000 {

		compatible = "qcom,qcedev";

		reg = <0x1de0000 0x20000>,

			<0x1dc4000 0x24000>;

		reg-names = "crypto-base","crypto-bam-base";

		interrupts = <GIC_SPI 272 IRQ_TYPE_LEVEL_HIGH>;

		qcom,bam-pipe-pair = <3>;

		qcom,ce-hw-instance = <0>;

		qcom,ce-device = <0>;

		qcom,ce-hw-shared;

		qcom,bam-ee = <0>;

		interconnect-names = "data_path";

		interconnects = <&gem_noc MASTER_APPSS_PROC &config_noc SLAVE_HWKM>;

		qcom,smmu-s1-enable;

		qcom,no-clock-support;

		iommus = <&apps_smmu 0x0586 0x0011>,

			 <&apps_smmu 0x0596 0x0011>;

		qcom,iommu-dma = "atomic";

		qcom_cedev_ns_cb {

			compatible = "qcom,qcedev,context-bank";

			label = "ns_context";

			iommus = <&apps_smmu 0x592 0>,

				 <&apps_smmu 0x598 0>,

				 <&apps_smmu 0x599 0>,

				 <&apps_smmu 0x59F 0>;

		};

		qcom_cedev_s_cb {

			compatible = "qcom,qcedev,context-bank";

			label = "secure_context";

			iommus = <&apps_smmu 0x593 0>,

				 <&apps_smmu 0x59C 0>,

				 <&apps_smmu 0x59D 0>,

				 <&apps_smmu 0x59E 0>;

			qcom,iommu-vmid = <0x9>; /* VMID_CP_BITSTREAM */

			qcom,secure-context-bank;

		};

	};

Hardware description:

=====================

Crypto 3E provides cipher and hash algorithms as defined in the

3GPP forum specifications.

Software description

====================

The driver is a Linux platform device driver. For an msm target,

there can be multiple crypto devices assigned for QCEDEV.

The driver is a misc device driver as well.

The following operations are registered in the driver,

-qcedev_ioctl()

-qcedev_open()

-qcedev_release()

The following IOCTLS are available to the user space application(s)-

  Cipher IOCTLs:

  --------------

    QCEDEV_IOCTL_ENC_REQ is for encrypting data.

    QCEDEV_IOCTL_DEC_REQ is for decrypting data.

  Hashing/HMAC IOCTLs

  -------------------

    QCEDEV_IOCTL_SHA_INIT_REQ is for initializing a hash/hmac request.

    QCEDEV_IOCTL_SHA_UPDATE_REQ is for updating hash/hmac.

    QCEDEV_IOCTL_SHA_FINAL_REQ is for ending the hash/mac request.

    QCEDEV_IOCTL_GET_SHA_REQ is for retrieving the hash/hmac for data

	packet of known size.

    QCEDEV_IOCTL_GET_CMAC_REQ is for retrieving the MAC (using AES CMAC

	algorithm) for data packet of known size.

The requests are synchronous. The driver will put the process to

sleep, waiting for the completion of the requests using wait_for_completion().

Since the requests are coming out of user space application, before giving

the requests to the low level qce driver, the ioctl requests and the

associated input/output buffer will have to be safe checked, and copied

to/from kernel space.

The extra copying of requests/buffer can affect the performance. The issue

with copying the data buffer is resolved by having the client use PMEM

allocated buffers.

NOTE:  Using memory allocated via PMEM is supported only for in place

       operations where source and destination buffers point to the same

       location. Support for different source and destination buffers

       is not supported currently.

       Furthermore, when using PMEM, and in AES CTR mode, when issuing an

       encryption or decryption request, a non-zero byteoffset is not

       supported.

The design of the driver is to allow multiple open, and multiple requests

to be issued from application(s). Therefore, the driver will internally queue

the requests, and serialize the requests to the low level qce (or qce40) driver.

On an IOCTL request from an application, if there is no outstanding

request, a the driver will issue a "qce" request, otherwise,

the request is queued in the driver queue.  The process is suspended

waiting for completion.

On completion of a request by the low level qce driver, the internal

tasklet (done_tasklet) is scheduled. The sole purpose of done_tasklet is

to call the completion of the current active request (complete()), and

issue more requests to the qce, if any.

When the process wakes up from wait_for_completion(), it will collect the

return code, and return the ioctl.

A spin lock is used to protect the critical section of internal queue to

be accessed from multiple tasks, SMP, and completion callback

from qce.

The driver maintains a set of statistics using debug fs. The files are

in /debug/qcedev/stats1, /debug/qcedev/stats2, /debug/qcedev/stats3;

one for each instance of device. Reading the file associated with

a device will retrieve the driver statistics for that device.

Any write to the file will clear the statistics.

Power Management

================

n/a

Interface:

==========

Linux user space applications will need to open a handle

(file descriptor) to the qcedev device.  This is achieved by doing

the following to retrieve a file descriptor to the device.

     fd = open("/dev/qce", O_RDWR);

     ..

     ioctl(fd, ...);

Once a valid fd is retrieved, user can call the following ioctls with

the fd as the first parameter and a pointer to an appropriate data

structure, qcedev_cipher_op_req or qcedev_sha_op_req (depending on

cipher/hash functionality) as the second parameter.

The following IOCTLS are available to the user space application(s)-

  Cipher IOCTLs:

  --------------

    QCEDEV_IOCTL_ENC_REQ is for encrypting data.

    QCEDEV_IOCTL_DEC_REQ is for decrypting data.

	The caller of the IOCTL passes a pointer to the structure shown

	below, as the second parameter.

	struct	qcedev_cipher_op_req {

		int				use_pmem;

		union{

			struct qcedev_pmem_info pmem;

			struct qcedev_vbuf_info vbuf;

		};

		uint32_t			entries;

		uint32_t			data_len;

		uint8_t				in_place_op;

		uint8_t				enckey[QCEDEV_MAX_KEY_SIZE];

		uint32_t			encklen;

		uint8_t				iv[QCEDEV_MAX_IV_SIZE];

		uint32_t			ivlen;

		uint32_t			byteoffset;

		enum qcedev_cipher_alg_enum	alg;

		enum qcedev_cipher_mode_enum	mode;

		enum qcedev_oper_enum		op;

	};

  Hashing/HMAC IOCTLs

  -------------------

    QCEDEV_IOCTL_SHA_INIT_REQ is for initializing a hash/hmac request.

    QCEDEV_IOCTL_SHA_UPDATE_REQ is for updating hash/hmac.

    QCEDEV_IOCTL_SHA_FINAL_REQ is for ending the hash/mac request.

    QCEDEV_IOCTL_GET_SHA_REQ is for retrieving the hash/hmac for data

	packet of known size.

    QCEDEV_IOCTL_GET_CMAC_REQ is for retrieving the MAC (using AES CMAC

	algorithm) for data packet of known size.

	The caller of the IOCTL passes a pointer to the structure shown

	below, as the second parameter.

	struct	qcedev_sha_op_req {

		struct buf_info			data[QCEDEV_MAX_BUFFERS];

		uint32_t			entries;

		uint32_t			data_len;

		uint8_t				digest[QCEDEV_MAX_SHA_DIGEST];

		uint32_t			diglen;

		uint8_t				*authkey;

		uint32_t			authklen;

		enum qcedev_sha_alg_enum	alg;

		struct qcedev_sha_ctxt		ctxt;

	};

The IOCTLs and associated request data structures are defined in qcedev.h

Module parameters:

==================

The following module parameters are defined in the board init file.

-CE hardware nase register address

-Data mover channel used for transfer to/from CE hardware

These parameters differ in each platform.

Dependencies:

=============

qce driver. Please see Documentation/arm/msm/qce.txt.

User space utilities:

=====================

none

Known issues:

=============

none.

To do:

======

  Enhance Cipher functionality:

  (1) Add support for handling > 32KB for ciphering functionality when

  - operation is not an "in place" operation (source != destination).

    (when using PMEM allocated memory)

Limitations:

============

  (1) In case of cipher functionality, Driver does not support

      a combination of different memory sources for source/destination.

      In other words,  memory pointed to by  src and dst,

      must BOTH (src/dst) be "pmem" or BOTH(src/dst) be "vbuf".

  (2) In case of hash functionality, driver does not support handling data

      buffers allocated via PMEM.

  (3) Do not load this driver if your device already has kernel space apps

      that need to access the crypto hardware.

      Make sure to have qcedev module disabled/unloaded and implement your user

      space application to use the software implementation (ex: openssl/crypto)

      of the crypto algorithms.

      (NOTE:  Please refer to details on the limitations listed in qce.txt)

  (4) If your device has Playready (Windows Media DRM) application enabled

      and uses the qcedev module to access the crypto hardware accelerator,

      please be informed that for performance reasons, the CE hardware will

      need to be dedicated to playready application.  Any other user space

      application should be implemented to use the software implementation

      (ex: openssl/crypto) of the crypto algorithms.

Introduction:

=============

QTI Crypto (qcrypto) driver is a Linux crypto driver which interfaces

with the Linux kernel crypto API layer to provide the HW crypto functions.

This driver is accessed by kernel space apps via the kernel crypto API layer.

At present there is no means for user space apps to access this module.

Device tree settings:

==============

Required properties:

- compatible : Should be "qcom,qcrypto"

- reg        : Offset and length of the register set for the device

- interconnect-names: interconnect names

- interconnects: interconnect setting defines belong to which NoC device

Optional property:

Example:

	qcom_crypto: qcrypto@1de0000 {

		compatible = "qcom,qcrypto";

		reg = <0x1de0000 0x20000>,

			 <0x1dc4000 0x24000>;

		reg-names = "crypto-base","crypto-bam-base";

		interrupts = <GIC_SPI 272 IRQ_TYPE_LEVEL_HIGH>;

		qcom,bam-pipe-pair = <2>;

		qcom,ce-hw-instance = <0>;

		qcom,ce-device = <0>;

		qcom,bam-ee = <0>;

		qcom,ce-hw-shared;

		qcom,clk-mgmt-sus-res;

		interconnect-names = "data_path";

		interconnects = <&gem_noc MASTER_APPSS_PROC &config_noc SLAVE_HWKM>;

		qcom,use-sw-aes-cbc-ecb-ctr-algo;

		qcom,use-sw-aes-xts-algo;

		qcom,use-sw-aes-ccm-algo;

		qcom,use-sw-ahash-algo;

		qcom,use-sw-aead-algo;

		qcom,use-sw-hmac-algo;

		qcom,smmu-s1-enable;

		qcom,no-clock-support;

		iommus = <&apps_smmu 0x0584 0x0011>,

			 <&apps_smmu 0x0594 0x0011>;

		qcom,iommu-dma = "atomic";

	};

Hardware description:

=====================

QTI Crypto HW device family provides a series of algorithms implemented

in the device.

Crypto 2 hardware provides hashing - SHA-1, SHA-256, ciphering - DES, 3DES, AES

algorithms, and concurrent operations of hashing, and ciphering.

In addition to those functions provided by Crypto 2 HW, Crypto 3 provides fast

AES algorithms.

In addition to those functions provided by Crypto 3 HW, Crypto 3E provides

HMAC-SHA1 hashing algorithm.

In addition to those functions provided by Crypto 3 HW, Crypto 4.0 provides

HMAC-SHA1/SHA256, AES CBC-MAC hashing algorithm and AES XTS/CCM cipher

algorithms.

Software description

====================

The module init function (_qcrypto_init()), does a platform_register(),

to register the driver. As the result, the driver probe function,

_qcrypto_probe(), will be invoked for each registered device.

In the probe function, driver opens the low level CE (qce_open), and

registers the supported algorithms to the kernel crypto API layer.

Currently, qcrypto supports the following algorithms.

      ablkcipher -

          cbc(aes),ecb(aes),ctr(aes)

      ahash -

          sha1, sha256

      aead -

          authenc(hmac(sha1),cbc(aes))

      The hmac(sha1), hmac(sha256, authenc(hmac(sha1),cbc(aes)), ccm(aes)

      and xts(aes) algorithms are registered for some platforms that

      support these in the CE hardware

The HW device  can support various algorithms. However, the most important

algorithms to gain the performance using a HW crypto accelerator are

AEAD, and ABLKCIPHER.

AEAD stands for "authentication encryption with association data".

ABLKCIPHER stands of "asynchronous block cipher".

The AEAD structure is described in the following header file aead.h

The design of the driver is to allow multiple requests

issued from kernel client SW (eg IPSec).

Therefore, the driver will have to internally queue the requests, and

serialize the requests to the low level qce driver.

When a request is received from the client, if there is no outstanding

request, a qce (or qce40) request is issued, otherwise, the request is

queued in the driver queue.

On completion of a request, the qce (or qce40) invokes the registered

callback from the qcrypto.  The internal tasklet (done_tasklet) is scheduled

in this callback function. The sole purpose of done_tasklet is

to call the completion of the current active request, and

issue more requests to the qce (or qce40), if any exists.

A spin lock is used to protect the critical section of internal queue to

be accessed from multiple tasks, SMP, and completion callback

from qce.

The driver maintains a set of statistics using debug fs. The files are

in /debug/qcrypto/stats1, /debug/qcrypto/stats2, /debug/qcrypto/stats3;

one for each instance of device. Reading the file associated with

a device will retrieve the driver statistics for that device.

Any write to the file will clear the statistics.

Test vectors for  authenc(hmac(sha1),cbc(aes)) algorithm are

developed offline, and imported to crypto/testmgr.c, and crypto/testmgr.h.

Power Management

================

  none

Interface:

==========

The kernel interface is defined in crypto.h.

Module parameters:

==================

All the platform specific parameters are defined in the board init

file, eg. arch/arm/mach-msm/board-mssm7x30.c for msm7x30.

Dependencies:

=============

qce driver.

User space utilities:

=====================

  n/a

Known issues:

=============

  n/a

To do:

======

  Add Hashing algorithms.

Limitations:

===============

(1) Each packet transfer size (for cipher and hash) is limited to maximum of

    32KB.  This is a limitation in the crypto engine hardware. Client will

    have to break packets larger than 32KB into multiple requests of smaller

    size data packets.

(2) Do not load this driver if your device has user space apps that needs to

    access the crypto hardware. Please make sure to have the qcrypto module

    disabled/unloaded.

    Not having the driver loaded, will result in the kernel space apps to use

    the registered software implementation of the crypto algorithms.

(3) If your device has Playready application enabled and uses the qcedev module

    to access the crypto hardware accelerator, please be informed that for

    performance reasons, the CE hardware will need to be dedicated to playready

    application.  Any other user space or kernel application should be implemented

    to use the software implementation of the crypto algorithms.

    (NOTE:  Please refer to details on the limitations listed in qce/40.txt)