Documentation/crypto/msm/qce.txt - kernel/msm - Git at Google

 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:
	=============

	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