Documentation/crypto/msm/qcedev.txt

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)

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.