1 /* 2 * Copyright (c) 2001-2019, Arm Limited and Contributors. All rights reserved. 3 * 4 * SPDX-License-Identifier: BSD-3-Clause 5 */ 6 7 8 9 #ifndef _CC_PAL_DMA_H 10 #define _CC_PAL_DMA_H 11 12 /*! 13 @file 14 @brief This file contains definitions that are used for DMA-related APIs. The implementation of these functions 15 need to be replaced according to the platform and OS. 16 @defgroup ssi_pal_dma CryptoCell PAL DMA related APIs 17 @{ 18 @ingroup ssi_pal 19 20 */ 21 22 #ifdef __cplusplus 23 extern "C" 24 { 25 #endif 26 27 #include "cc_pal_types.h" 28 #include "cc_pal_dma_plat.h" 29 #include "cc_pal_dma_defs.h" 30 31 /*! User buffer scatter information. */ 32 typedef struct { 33 CCDmaAddr_t blockPhysAddr; /*!< The physical address of the user buffer.*/ 34 uint32_t blockSize; /*!< The block size of the user buffer.*/ 35 }CCPalDmaBlockInfo_t; 36 37 #ifdef BIG__ENDIAN 38 /*! Definition for big to little endian. */ 39 #define SET_WORD_LE(val) cpu_to_le32(val) 40 #else 41 /*! Definition for big to little endian. */ 42 #define SET_WORD_LE 43 #endif 44 45 /** 46 * @brief This function is called by the CryptoCell runtime library before the HW is used. 47 * It maps a given data buffer (virtual address) for CryptoCell HW DMA use (physical address), and returns the list of 48 * one or more DMA-able (physical) blocks. Once it is called, 49 * only CryptoCell HW access to the buffer is allowed, until it is unmapped. 50 * \note If the data buffer was already mapped by the secure OS prior to calling the CryptoCell runtime library, 51 * this API does not have to perform any actual mapping operation, but only return the list of DMA-able blocks. 52 * 53 * @return A non-zero value in case of failure. 54 */ 55 uint32_t CC_PalDmaBufferMap( 56 uint8_t *pDataBuffer, /*!< [in] The address of the buffer to map. */ 57 uint32_t buffSize, /*!< [in] The buffer size in Bytes. */ 58 CCPalDmaBufferDirection_t copyDirection, /*!< [in] The copy direction of the buffer, according to ::CCPalDmaBufferDirection_t: 59 <ul><li>TO_DEVICE - the original buffer is the input to the operation, 60 and this function should copy it to the temporary buffer, 61 prior to the activating the HW on the temporary buffer.</li> 62 <li>FROM_DEVICE - not relevant for this API.</li> 63 <li>BI_DIRECTION - used when the cryptographic operation is "in-place", that is, 64 the result of encryption or decryption is written over the original data 65 at the same address. Should be treated by this API same as 66 TO_DEVICE. </li></ul> */ 67 uint32_t *pNumOfBlocks, /*!< [in/out] <ul><li> In - The maximal number of blocks to fill.</li><li>Out - the actual number of blocks.</li></ul> */ 68 CCPalDmaBlockInfo_t *pDmaBlockList, /*!< [out] The list of DMA-able blocks that the buffer maps to. */ 69 CC_PalDmaBufferHandle *dmaBuffHandle /*!< [out] A handle to the private resources of the mapped buffer.*/ ); 70 71 72 /** 73 * @brief This function is called by the CryptoCell runtime library after the HW is used. 74 * It unmaps a given buffer and frees its associated resources, if needed. It may unlock the buffer and flush it for CPU use. 75 * Once it is called, CryptoCell HW does not require any further access to this buffer. 76 * \note If the data buffer was already unmapped by the secure OS prior to calling the CryptoCell runtime library, 77 * this API does not have to perform any unmapping operation, and the actual unmapping can be done by the secure OS 78 * outside the context of the CryptoCell runtime library. 79 * @return A non-zero value in case of failure. 80 */ 81 uint32_t CC_PalDmaBufferUnmap(uint8_t *pDataBuffer, /*!< [in] The address of the buffer to unmap. */ 82 uint32_t buffSize, /*!< [in] The buffer size in Bytes. */ 83 CCPalDmaBufferDirection_t copyDirection, /*!< [in] The copy direction of the buffer, according to ::CCPalDmaBufferDirection_t: 84 <ul><li>TO_DEVICE - not relevant for this API. </li> 85 <li>FROM_DEVICE - the temporary buffer holds the output of the HW, and this 86 API should copy it to the actual output buffer.</li> 87 <li>BI_DIRECTION - used when the cryptographic operation is "in-place", that is, 88 the result of encryption or decryption is written over the original data 89 at the same address. Should be treated by this API same as 90 FROM_DEVICE.</li></ul> */ 91 uint32_t numOfBlocks, /*!< [in] The number of DMA-able blocks that the buffer maps to. */ 92 CCPalDmaBlockInfo_t *pDmaBlockList, /*!< [in] The list of DMA-able blocks that the buffer maps to. */ 93 CC_PalDmaBufferHandle dmaBuffHandle /*!< [in] A handle to the private resources of the mapped buffer. */); 94 95 96 /** 97 * @brief Allocates a DMA-contiguous buffer for CPU use, and returns its virtual address. 98 * Before passing the buffer to the CryptoCell HW, ::CC_PalDmaBufferMap should be called. 99 * \note The returned address must be aligned to 32bits. 100 * 101 * 102 * @return A non-zero value in case of failure. 103 */ 104 uint32_t CC_PalDmaContigBufferAllocate(uint32_t buffSize, /*!< [in] The buffer size in Bytes.*/ 105 uint8_t **ppVirtBuffAddr /*!< [out] The virtual address of the allocated buffer.*/); 106 107 108 109 /** 110 * @brief Frees resources previously allocated by ::CC_PalDmaContigBufferAllocate. 111 * 112 * 113 * @return A non-zero value in case of failure. 114 */ 115 uint32_t CC_PalDmaContigBufferFree(uint32_t buffSize, /*!< [in] The buffer size in Bytes. */ 116 uint8_t *pVirtBuffAddr /*!< [in] The virtual address of the buffer to free. */); 117 118 119 120 /** 121 * @brief Checks whether the buffer is guaranteed to be a single contiguous DMA block. 122 * 123 * 124 * @return TRUE if the buffer is guaranteed to be a single contiguous DMA block. 125 * @return FALSE otherwise. 126 */ 127 uint32_t CC_PalIsDmaBufferContiguous(uint8_t *pDataBuffer, /*!< [in] The address of the user buffer. */ 128 uint32_t buffSize /*!< [in] The size of the user buffer. */); 129 130 131 #ifdef __cplusplus 132 } 133 #endif 134 /** 135 @} 136 */ 137 #endif 138 139 140
