1 /** 2 * @file hi_dma.h 3 * 4 * Copyright (c) 2020 HiSilicon (Shanghai) Technologies CO., LIMITED. 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 * 描述：DMA module. CNcomment:DMA调用接口。CNend 18 * @li The DMA transfer is realized by calling internal DMA driver. 19 CNcomment:通过调用内部DMA驱动实现DMA传输CNend 20 * @li Supports four transmission modes: Memory to storage, memory to peripheral, peripheral to memory, 21 and peripheral to peripheral.CNcomment:支持存储器到存储器、存储器到外设、外设到存储器、 22 外设到外设四种传输方式CNend 23 * @li The DMA has four channels. If there is no idle channel, the HI_ERR_DMA_BUSY error is returned. 24 CNcomment:DMA共有4通道，无空闲通道时返回HI_ERR_DMA_BUSY错误CNend 25 * @li The callback function is executed in the interrupt context, so you need to comply with the programming 26 precautions for the interrupt context.CNcomment:回调函数执行在中断上下文， 27 因此需要遵守中断上下文的编程注意事项。CNend 28 * @li Before enabling the DMA channel, you need to set the channel parameters. After the channel parameters 29 are enabled and then modified, an unpredictable result is generated.CNcomment:在DMA通道使能前需设置完通道参数， 30 使能通道后再修改通道参数会产生无法预知的结果。CNend \n 31 */ 32 33 /** @defgroup iot_dma DMA 34 * @ingroup drivers 35 */ 36 37 #ifndef _HI_DMA_H 38 #define _HI_DMA_H 39 40 #include <hi_types.h> 41 #include "hi_mdm_types.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 47 /** 48 * @ingroup iot_dma 49 * 50 * DMA Interruption type. CNcomment: DMA 中断类型。CNend 51 */ 52 /* 传输完成中断类型 */ 53 #define DMA_INT_TC 1 54 /* 传输错误中断类型 */ 55 #define DMA_INT_ERR 2 56 57 /** 58 * @ingroup iot_dma 59 * 60 * DMA transfer bit width. CNcomment:DMA传输位宽。CNend 61 */ 62 typedef enum { 63 WIDTH_BIT8 = 0, 64 WIDTH_BIT16, 65 WIDTH_BIT32, 66 } hi_dma_data_width; 67 68 /** 69 * @ingroup iot_dma 70 * 71 * DMA configuration structure transferred. CNcomment:用户传入的DMA设置结构体。CNend 72 */ 73 typedef struct hi_dma_user_para { 74 hi_u32 ch_idx; /* 接收DMA传输使用的channel id，不需用户设置, 通道申请成功时赋值 */ 75 uintptr_t src_addr; /* 源地址，源地址必须4字节对齐 */ 76 uintptr_t dst_addr; /* 目标地址，目的地址必须4字节对齐 */ 77 hi_u32 size_bytes; /* 传输长度，以BYTE单位 */ 78 hi_void (*cb)(hi_u32); /* 传输结束回调，参数为传输完成或传输错误 #DMA_INT_XXX */ 79 } hi_dma_user_para; 80 81 /** 82 * @ingroup iot_dma 83 * @brief Create the dma transmission linked list. CNcomment:创建dma传输链表。CNend 84 * 85 * @par 描述: 86 * Create the dma transmission linked list. CNcomment:创建dma传输链表，分配通道。CNend 87 * After the command is executed successfully, the channel resources are allocated. 88 * If the channel resources are not transmitted, the hi_dma_ch_close(usr_para->ch_idx) is invoked to 89 * release the channels. CNcomment:执行成功后会分配通道资源，如果没有实际进行传输需要调用 90 hi_dma_ch_close(usr_para->ch_idx)释放通道。CNend 91 * 92 * @attention 93 * @param usr_para [IN/OUT] type #hi_dma_user_para，Transfer DMA transfer parameter settings 94 CNcomment:传入DMA传输参数设置。CNend 95 * 96 * @retval #HI_ERR_SUCCESS Success. 97 * @retval #Other values Failure. For details, see hi_errno.h. 98 * @par 依赖: 99 * @li hi_dma.h： Describes DMA driver APIs. CNcomment:DMA驱动实现接口。CNend 100 * @see None 101 */ 102 hi_u32 hi_dma_create_link_list(hi_dma_user_para *usr_para); 103 104 /** 105 * @ingroup iot_dma 106 * @brief Insert the DMA transmission linked list at behind. CNcomment:dma传输链表末尾添加结点。CNend 107 * 108 * @par 描述: 109 * Insert the DMA transmission linked list at behind. CNcomment:dma传输链表末尾添加结点CNend 110 * 111 * @attention 112 * @param usr_para [IN] type #const hi_dma_user_para，Transfer DMA transfer parameter settings. 113 CNcomment:传入DMA传输参数设置。CNend 114 * 115 * @retval #HI_ERR_SUCCESS Success. 116 * @retval #Other values Failure. For details, see hi_errno.h. 117 * @par 依赖: 118 * @li hi_dma.h： Describes DMA driver APIs. CNcomment:DMA驱动实现接口。CNend 119 * @see None 120 */ 121 hi_u32 hi_dma_add_link_list_item(const hi_dma_user_para *usr_para); 122 123 /** 124 * @ingroup iot_dma 125 * @brief Start DMA linked list transmission. CNcomment:启动dma链表传输。CNend 126 * 127 * @par 描述: 128 * Start DMA linked list transmission, channel would be released, no matter about the result. 129 CNcomment:启动dma链表传输，成功或失败后会释放通道。CNend 130 * 131 * @attention 132 * @param ch_num [IN] type #hi_u32，Linked list transmission channel. 133 This parameter is assigned by the API when a linked list is created. 134 CNcomment:链表传输通道，创建链表时API内部赋值。CNend 135 * @param block [IN] type #hi_bool，Indicates whether to block waiting for transmission completion. 136 CNcomment:是否阻塞等待传输完成。CNend 137 * 138 * @retval #HI_ERR_SUCCESS Success. 139 * @retval #Other values Failure. For details, see hi_errno.h. 140 * @par 依赖: 141 * @li hi_dma.h： Describes DMA driver APIs. CNcomment:DMA驱动实现接口。CNend 142 * @see None 143 */ 144 hi_u32 hi_dma_link_list_transfer(hi_u32 ch_num, hi_bool block); 145 146 /** 147 * @ingroup iot_dma 148 * @brief Data transmission from the memory to the memory through DMA. 149 CNcomment:通过DMA进行存储器到存储器数据传输。CNend 150 * 151 * @par 描述: 152 * Data transmission from the memory to the memory through DMA. 153 CNcomment:通过DMA进行存储器到存储器数据传输。CNend 154 * 155 * @attention 156 * @param dst_addr [IN] type #hi_u32，Destination address, which must be 4-byte-aligned. 157 CNcomment:目标地址，需4字节对齐。CNend 158 * @param src_addr [IN] type #hi_u32，Source address, which must be 4-byte-aligned. 159 CNcomment:源地址，需4字节对齐。CNend 160 * @param size_bytes [IN] type #hi_u32，Transmission length, in bytes. 161 CNcomment:传输长度，以BYTE为单位。CNend 162 * @param block [IN] type #hi_bool，Indicates whether to block waiting for transmission completion. 163 CNcomment:是否阻塞等待传输完成。CNend 164 * @param cb_func [IN] type #hi_void，Callback function for non-blocking transmission. 165 The parameter is the DMA interrupt type. Set this parameter to HI_NULL when blocking transmission. 166 CNcomment:非阻塞传输的回调函数，参数为DMA中断类型，阻塞传输时设为HI_NULL。CNend 167 * 168 * @retval #HI_ERR_SUCCESS Success. 169 * @retval #HI_ERR_DMA_BUSY Channel busy. CNcomment:通道全忙。CNend 170 * @retval #Other values Failure. For details, see hi_errno.h. 171 * @par 依赖: 172 * @li hi_dma.h： Describes DMA driver APIs. CNcomment:DMA驱动实现接口。CNend 173 * @see None 174 */ 175 hi_u32 hi_dma_mem2mem_transfer(hi_u32 dst_addr, hi_u32 src_addr, hi_u32 size_bytes, 176 hi_bool block, hi_void (*cb_func)(hi_u32 int_type)); 177 178 /** 179 * @ingroup iot_dma 180 * @brief Disables the DMA specified channel. CNcomment:关闭DMA指定通道。CNend 181 * 182 * @par 描述: 183 * Disables the DMA specified channel and release rource. 184 CNcomment:关闭DMA指定通道并释放资源。CNend 185 * 186 * @attention None 187 * @param ch_num [IN] type #hi_u32，DMA channel ID. Value range: 0-3. 188 CNcomment:DMA通道ID 取值0~3。CNend 189 * 190 * @retval #HI_ERR_SUCCESS Success. 191 * @retval #Other values Failure. For details, see hi_errno.h. 192 * @par 依赖: 193 * @li hi_dma.h： Describes DMA driver APIs. CNcomment:DMA驱动实现接口。CNend 194 * @see hi_dma_create_link_list。 195 */ 196 hi_u32 hi_dma_ch_close(hi_u32 ch_num); 197 198 /** 199 * @ingroup iot_dma 200 * @brief DMA module initialization.CNcomment:DMA模块初始化。CNend 201 * 202 * @par 描述: 203 * DMA module initialization, apply for rources. CNcomment:DMA模块初始化, 申请资源。CNend 204 * 205 * @attention None 206 * @param None 207 * 208 * @retval #HI_ERR_SUCCESS Success. 209 * @retval #Other values Failure. For details, see hi_errno.h. 210 * @par 依赖: 211 * @li hi_dma.h： Describes DMA driver APIs. CNcomment:DMA驱动实现接口。CNend 212 * @see None 213 */ 214 hi_u32 hi_dma_init(hi_void); 215 216 /** 217 * @ingroup iot_dma 218 * @brief Deinitializes the DMA module. CNcomment:DMA模块去初始化。CNend 219 * 220 * @par 描述: 221 * Deinitializes the DMA module and release rources. CNcomment:DMA模块去初始化，释放资源。CNend 222 * 223 * @attention None 224 * @param None 225 * 226 * @retval None 227 * @par 依赖: 228 * @li hi_dma.h： Describes DMA driver APIs. CNcomment:DMA驱动实现接口。CNend 229 * @see None 230 */ 231 hi_void hi_dma_deinit(hi_void); 232 233 /** 234 * @ingroup iot_dma 235 * @brief Judge is DMA module init. CNcomment:DMA模块是否初始化。CNend 236 * 237 * @par 描述: 238 * Is DMA module init. CNcomment:DMA模块是否初始化。CNend 239 * 240 * @attention None 241 * @param None 242 * 243 * @retval #HI_TURE dma has been initialized. 244 * @retval #HI_FALSE DMA has not been initialized. 245 * @par 依赖: 246 * @li hi_dma.h： Describes DMA driver APIs. CNcomment:DMA驱动实现接口。CNend 247 * @see None 248 */ 249 hi_bool hi_dma_is_init(hi_void); 250 251 #ifdef __cplusplus 252 } 253 #endif 254 255 #endif 256