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.
19CNcomment:通过调用内部DMA驱动实现DMA传输CNend
20* @li Supports four transmission modes: Memory to storage, memory to peripheral, peripheral to memory,
21and 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.
24CNcomment: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
26precautions 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
29are 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
44extern "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 */
62typedef 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 */
73typedef 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:执行成功后会分配通道资源，如果没有实际进行传输需要调用
90hi_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
94CNcomment:传入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 */
102hi_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.
113CNcomment:传入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 */
121hi_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.
129CNcomment:启动dma链表传输，成功或失败后会释放通道。CNend
130*
131* @attention
132* @param  ch_num           [IN]     type #hi_u32，Linked list transmission channel.
133This parameter is assigned by the API when a linked list is created.
134CNcomment:链表传输通道，创建链表时API内部赋值。CNend
135* @param  block            [IN]     type #hi_bool，Indicates whether to block waiting for transmission completion.
136CNcomment:是否阻塞等待传输完成。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 */
144hi_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.
149CNcomment:通过DMA进行存储器到存储器数据传输。CNend
150*
151* @par 描述:
152*           Data transmission from the memory to the memory through DMA.
153CNcomment:通过DMA进行存储器到存储器数据传输。CNend
154*
155* @attention
156* @param  dst_addr         [IN]     type #hi_u32，Destination address, which must be 4-byte-aligned.
157CNcomment:目标地址，需4字节对齐。CNend
158* @param  src_addr         [IN]     type #hi_u32，Source address, which must be 4-byte-aligned.
159CNcomment:源地址，需4字节对齐。CNend
160* @param  size_bytes       [IN]     type #hi_u32，Transmission length, in bytes.
161CNcomment:传输长度，以BYTE为单位。CNend
162* @param  block            [IN]     type #hi_bool，Indicates whether to block waiting for transmission completion.
163CNcomment:是否阻塞等待传输完成。CNend
164* @param  cb_func          [IN]     type #hi_void，Callback function for non-blocking transmission.
165The parameter is the DMA interrupt type. Set this parameter to HI_NULL when blocking transmission.
166CNcomment:非阻塞传输的回调函数，参数为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 */
175hi_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.
184CNcomment:关闭DMA指定通道并释放资源。CNend
185*
186* @attention None
187* @param  ch_num           [IN]     type #hi_u32，DMA channel ID. Value range: 0-3.
188CNcomment: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 */
196hi_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 */
214hi_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*/
231hi_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 */
249hi_bool hi_dma_is_init(hi_void);
250
251#ifdef __cplusplus
252}
253#endif
254
255#endif
256