AnilKumar Chimata | e78789a | 2017-04-07 12:18:46 -0700 | [diff] [blame] | 1 | Introduction: |
| 2 | ============= |
| 3 | |
| 4 | QTI Crypto (qcrypto) driver is a Linux crypto driver which interfaces |
| 5 | with the Linux kernel crypto API layer to provide the HW crypto functions. |
| 6 | This driver is accessed by kernel space apps via the kernel crypto API layer. |
| 7 | At present there is no means for user space apps to access this module. |
| 8 | |
| 9 | Hardware description: |
| 10 | ===================== |
| 11 | |
| 12 | QTI Crypto HW device family provides a series of algorithms implemented |
| 13 | in the device. |
| 14 | |
| 15 | Crypto 2 hardware provides hashing - SHA-1, SHA-256, ciphering - DES, 3DES, AES |
| 16 | algorithms, and concurrent operations of hashing, and ciphering. |
| 17 | |
| 18 | In addition to those functions provided by Crypto 2 HW, Crypto 3 provides fast |
| 19 | AES algorithms. |
| 20 | |
| 21 | In addition to those functions provided by Crypto 3 HW, Crypto 3E provides |
| 22 | HMAC-SHA1 hashing algorithm. |
| 23 | |
| 24 | In addition to those functions provided by Crypto 3 HW, Crypto 4.0 provides |
| 25 | HMAC-SHA1/SHA256, AES CBC-MAC hashing algorithm and AES XTS/CCM cipher |
| 26 | algorithms. |
| 27 | |
| 28 | |
| 29 | Software description |
| 30 | ==================== |
| 31 | |
| 32 | The module init function (_qcrypto_init()), does a platform_register(), |
| 33 | to register the driver. As the result, the driver probe function, |
| 34 | _qcrypto_probe(), will be invoked for each registered device. |
| 35 | |
| 36 | In the probe function, driver opens the low level CE (qce_open), and |
| 37 | registers the supported algorithms to the kernel crypto API layer. |
| 38 | Currently, qcrypto supports the following algorithms. |
| 39 | |
| 40 | ablkcipher - |
| 41 | cbc(aes),ecb(aes),ctr(aes) |
| 42 | ahash - |
| 43 | sha1, sha256 |
| 44 | aead - |
| 45 | authenc(hmac(sha1),cbc(aes)) |
| 46 | |
| 47 | The hmac(sha1), hmac(sha256, authenc(hmac(sha1),cbc(aes)), ccm(aes) |
| 48 | and xts(aes) algorithms are registered for some platforms that |
| 49 | support these in the CE hardware |
| 50 | |
| 51 | The HW device can support various algorithms. However, the most important |
| 52 | algorithms to gain the performance using a HW crypto accelerator are |
| 53 | AEAD, and ABLKCIPHER. |
| 54 | |
| 55 | AEAD stands for "authentication encryption with association data". |
| 56 | ABLKCIPHER stands of "asynchronous block cipher". |
| 57 | |
| 58 | The AEAD structure is described in the following header file aead.h |
| 59 | |
| 60 | The design of the driver is to allow multiple requests |
| 61 | issued from kernel client SW (eg IPSec). |
| 62 | Therefore, the driver will have to internally queue the requests, and |
| 63 | serialize the requests to the low level qce driver. |
| 64 | |
| 65 | When a request is received from the client, if there is no outstanding |
| 66 | request, a qce (or qce40) request is issued, otherwise, the request is |
| 67 | queued in the driver queue. |
| 68 | |
| 69 | On completion of a request, the qce (or qce40) invokes the registered |
| 70 | callback from the qcrypto. The internal tasklet (done_tasklet) is scheduled |
| 71 | in this callback function. The sole purpose of done_tasklet is |
| 72 | to call the completion of the current active request, and |
| 73 | issue more requests to the qce (or qce40), if any exists. |
| 74 | |
| 75 | A spin lock is used to protect the critical section of internal queue to |
| 76 | be accessed from multiple tasks, SMP, and completion callback |
| 77 | from qce. |
| 78 | |
| 79 | The driver maintains a set of statistics using debug fs. The files are |
| 80 | in /debug/qcrypto/stats1, /debug/qcrypto/stats2, /debug/qcrypto/stats3; |
| 81 | one for each instance of device. Reading the file associated with |
| 82 | a device will retrieve the driver statistics for that device. |
| 83 | Any write to the file will clear the statistics. |
| 84 | |
| 85 | Test vectors for authenc(hmac(sha1),cbc(aes)) algorithm are |
| 86 | developed offline, and imported to crypto/testmgr.c, and crypto/testmgr.h. |
| 87 | |
| 88 | |
| 89 | Power Management |
| 90 | ================ |
| 91 | none |
| 92 | |
| 93 | |
| 94 | Interface: |
| 95 | ========== |
| 96 | The kernel interface is defined in crypto.h. |
| 97 | |
| 98 | |
| 99 | Module parameters: |
| 100 | ================== |
| 101 | |
| 102 | All the platform specific parameters are defined in the board init |
| 103 | file, eg. arch/arm/mach-msm/board-mssm7x30.c for msm7x30. |
| 104 | |
| 105 | Dependencies: |
| 106 | ============= |
| 107 | qce driver. |
| 108 | |
| 109 | |
| 110 | User space utilities: |
| 111 | ===================== |
| 112 | n/a |
| 113 | |
| 114 | Known issues: |
| 115 | ============= |
| 116 | n/a |
| 117 | |
| 118 | To do: |
| 119 | ====== |
| 120 | Add Hashing algorithms. |
| 121 | |
| 122 | |
| 123 | Limitations: |
| 124 | =============== |
| 125 | (1) Each packet transfer size (for cipher and hash) is limited to maximum of |
| 126 | 32KB. This is a limitation in the crypto engine hardware. Client will |
| 127 | have to break packets larger than 32KB into multiple requests of smaller |
| 128 | size data packets. |
| 129 | |
| 130 | (2) Do not load this driver if your device has user space apps that needs to |
| 131 | access the crypto hardware. Please make sure to have the qcrypto module |
| 132 | disabled/unloaded. |
| 133 | Not having the driver loaded, will result in the kernel space apps to use |
| 134 | the registered software implementation of the crypto algorithms. |
| 135 | |
| 136 | (3) If your device has Playready application enabled and uses the qcedev module |
| 137 | to access the crypto hardware accelerator, please be informed that for |
| 138 | performance reasons, the CE hardware will need to be dedicated to playready |
| 139 | application. Any other user space or kernel application should be implemented |
| 140 | to use the software implementation of the crypto algorithms. |
| 141 | |
| 142 | (NOTE: Please refer to details on the limitations listed in qce/40.txt) |