1*4882a593Smuzhiyun.. SPDX-License-Identifier: GPL-2.0 2*4882a593Smuzhiyun 3*4882a593SmuzhiyunCrypto Engine 4*4882a593Smuzhiyun============= 5*4882a593Smuzhiyun 6*4882a593SmuzhiyunOverview 7*4882a593Smuzhiyun-------- 8*4882a593SmuzhiyunThe crypto engine (CE) API is a crypto queue manager. 9*4882a593Smuzhiyun 10*4882a593SmuzhiyunRequirement 11*4882a593Smuzhiyun----------- 12*4882a593SmuzhiyunYou must put, at the start of your transform context your_tfm_ctx, the structure 13*4882a593Smuzhiyuncrypto_engine: 14*4882a593Smuzhiyun 15*4882a593Smuzhiyun:: 16*4882a593Smuzhiyun 17*4882a593Smuzhiyun struct your_tfm_ctx { 18*4882a593Smuzhiyun struct crypto_engine engine; 19*4882a593Smuzhiyun ... 20*4882a593Smuzhiyun }; 21*4882a593Smuzhiyun 22*4882a593SmuzhiyunThe crypto engine only manages asynchronous requests in the form of 23*4882a593Smuzhiyuncrypto_async_request. It cannot know the underlying request type and thus only 24*4882a593Smuzhiyunhas access to the transform structure. It is not possible to access the context 25*4882a593Smuzhiyunusing container_of. In addition, the engine knows nothing about your 26*4882a593Smuzhiyunstructure "``struct your_tfm_ctx``". The engine assumes (requires) the placement 27*4882a593Smuzhiyunof the known member ``struct crypto_engine`` at the beginning. 28*4882a593Smuzhiyun 29*4882a593SmuzhiyunOrder of operations 30*4882a593Smuzhiyun------------------- 31*4882a593SmuzhiyunYou are required to obtain a struct crypto_engine via ``crypto_engine_alloc_init()``. 32*4882a593SmuzhiyunStart it via ``crypto_engine_start()``. When finished with your work, shut down the 33*4882a593Smuzhiyunengine using ``crypto_engine_stop()`` and destroy the engine with 34*4882a593Smuzhiyun``crypto_engine_exit()``. 35*4882a593Smuzhiyun 36*4882a593SmuzhiyunBefore transferring any request, you have to fill the context enginectx by 37*4882a593Smuzhiyunproviding functions for the following: 38*4882a593Smuzhiyun 39*4882a593Smuzhiyun* ``prepare_crypt_hardware``: Called once before any prepare functions are 40*4882a593Smuzhiyun called. 41*4882a593Smuzhiyun 42*4882a593Smuzhiyun* ``unprepare_crypt_hardware``: Called once after all unprepare functions have 43*4882a593Smuzhiyun been called. 44*4882a593Smuzhiyun 45*4882a593Smuzhiyun* ``prepare_cipher_request``/``prepare_hash_request``: Called before each 46*4882a593Smuzhiyun corresponding request is performed. If some processing or other preparatory 47*4882a593Smuzhiyun work is required, do it here. 48*4882a593Smuzhiyun 49*4882a593Smuzhiyun* ``unprepare_cipher_request``/``unprepare_hash_request``: Called after each 50*4882a593Smuzhiyun request is handled. Clean up / undo what was done in the prepare function. 51*4882a593Smuzhiyun 52*4882a593Smuzhiyun* ``cipher_one_request``/``hash_one_request``: Handle the current request by 53*4882a593Smuzhiyun performing the operation. 54*4882a593Smuzhiyun 55*4882a593SmuzhiyunNote that these functions access the crypto_async_request structure 56*4882a593Smuzhiyunassociated with the received request. You are able to retrieve the original 57*4882a593Smuzhiyunrequest by using: 58*4882a593Smuzhiyun 59*4882a593Smuzhiyun:: 60*4882a593Smuzhiyun 61*4882a593Smuzhiyun container_of(areq, struct yourrequesttype_request, base); 62*4882a593Smuzhiyun 63*4882a593SmuzhiyunWhen your driver receives a crypto_request, you must to transfer it to 64*4882a593Smuzhiyunthe crypto engine via one of: 65*4882a593Smuzhiyun 66*4882a593Smuzhiyun* crypto_transfer_aead_request_to_engine() 67*4882a593Smuzhiyun 68*4882a593Smuzhiyun* crypto_transfer_akcipher_request_to_engine() 69*4882a593Smuzhiyun 70*4882a593Smuzhiyun* crypto_transfer_hash_request_to_engine() 71*4882a593Smuzhiyun 72*4882a593Smuzhiyun* crypto_transfer_skcipher_request_to_engine() 73*4882a593Smuzhiyun 74*4882a593SmuzhiyunAt the end of the request process, a call to one of the following functions is needed: 75*4882a593Smuzhiyun 76*4882a593Smuzhiyun* crypto_finalize_aead_request() 77*4882a593Smuzhiyun 78*4882a593Smuzhiyun* crypto_finalize_akcipher_request() 79*4882a593Smuzhiyun 80*4882a593Smuzhiyun* crypto_finalize_hash_request() 81*4882a593Smuzhiyun 82*4882a593Smuzhiyun* crypto_finalize_skcipher_request() 83