K230 DMA API Reference#
Overview#
Overview#
GSDMA: DMA stands for Direct Memory Access, which means direct memory access, copying data from one address space to another address space, providing high-speed data transmission between memory and memory. GDMA, the full name of Graphic Direct Memory Access, is responsible for copying images in memory to another memory, and can also complete functions such as image rotation and mirroring. SDMA stands for System Direct Memory Access, which is responsible for copying data in memory to another memory, which is DMA in the traditional sense.
The software code provides various functions of GSDMA hardware to users in the form of API, helping users to quickly implement image transmission, rotation, mirroring, 2D functions and data transmission functions. At the same time, functions such as module status information statistics are implemented.
Functional Description#
Abstract the dma hardware into a device with eight channels, among which channel 0~3 is the gdma channel and channel 4~7 is the sdma channel.
gdma#
Users use gdma to implement rotation and mirroring of images. The main calling process is as follows:
Configure dma device attributes;
Start the dma device. After calling this function, the driver will automatically apply for VB space as the data buffer of the destination address;
Configure gdma channel attributes;
Start gdma channel;
The user applies for VB space as a data buffer for source data in user mode, and calls kd_mpi_dma_send_frame to send the source address of the data to gdma;
The driver will transfer the data in the source address to the destination address data buffer applied for in step 2;
The user calls kd_mpi_dma_get_frame to obtain the data address in the destination address.
sdma#
Users implement data migration through sdma. The main calling process is as follows:
Configure dma device attributes;
Start the dma device. After calling this function, the driver will automatically apply for VB space as the data buffer of the destination address;
Configure sdma channel attributes;
Start sdma channel;
The user applies for VB space in user mode as a data buffer for source data, and calls kd_mpi_dma_send_frame to send the source address of the data to sdma;
The driver will transfer the data in the source address to the destination address data buffer applied for in step 2;
The user calls kd_mpi_dma_get_frame to obtain the data address in the destination address.
API Reference#
DMA uses#
This function module provides the following APIs:
kd_mpi_dma_set_dev_attr#
Description
Configure dma device properties
Syntax
k_s32 kd_mpi_dma_set_dev_attr(k_dma_dev_attr_t *attr);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
attr |
dma device attribute structure pointer. |
Input |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None.
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
None
Example
None
Related Topics
kd_mpi_dma_get_dev_attr#
Description
Get the configured dma device properties.
Syntax
k_s32 kd_mpi_dma_get_dev_attr(k_dma_dev_attr_t *attr);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
attr |
dma device attribute structure pointer |
Input |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
You need to configure the dma device properties before you can obtain the dma device properties.
Example
None
Related Topics
kd_mpi_dma_start_dev#
Description
Start the dma device.
Syntax
k_s32 kd_mpi_dma_start_dev();
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
None |
None |
None |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
You need to configure the dma device properties before you can call this function to start dma
Example
None
Related Topics
None
kd_mpi_dma_stop_dev#
Description
Stop the dma device.
Syntax
kd_mpi_dma_stop_dev();
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
None |
None |
None |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
This function can be called to stop a dma device only after the dma device has been started.
Example
None
Related Topics
None
kd_mpi_dma_set_chn_attr#
Description
Configure dma channel properties.
Syntax
k_s32 kd_mpi_dma_set_chn_attr(k_u8 chn_num, k_dma_chn_attr_u *attr);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
chn_num |
Channel number |
Input |
attr |
dma channel attributes, this parameter is a combination, you can choose to configure gdma channel attributes, you can also choose to configure sdma channel attributes. Channel 0~3 is gdma, channel 4~7 is sdma |
Input |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
None
Example
None
Related Topics
kd_mpi_dma_get_chn_attr#
Description
Get the configured dma channel properties.
Syntax
k_s32 kd_mpi_dma_get_chn_attr(k_u8 chn_num, k_dma_chn_attr_u *attr);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
chn_num |
Channel number |
Input |
attr |
dma channel attribute, this parameter is a combination, you can choose to get the gdma channel attribute, you can also choose to get the sdma channel attribute. Channel 0~3 is gdma, channel 4~7 is sdma |
Output |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
You need to configure the dma channel attributes before you can obtain the dma channel attributes.
Example
None
Related Topics
kd_mpi_dma_start_chn#
Description
Start the dma channel.
Syntax
k_s32 kd_mpi_dma_start_chn(k_u8 chn_num);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
chn_num |
Channel number. |
Input |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
The DMA channel can be started only after configuring the DMA device and configuring the DMA channel properties.
Example
None
Related Topics
None
kd_mpi_dma_stop_chn#
Description
pause dma channel
Syntax
k_s32 kd_mpi_dma_stop_chn(k_u8 chn_num);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
chn_num |
Channel number. |
Input |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
This function can be called to stop a dma channel only after the dma channel has been started.
Example
None
Related Topics
None
kd_mpi_dma_send_frame#
Description
Send data from user space to the destination address.
Syntax
k_s32 kd_mpi_dma_send_frame(k_u8 chn_num, k_video_frame_info *df_info, k_s32 millisec);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
chn_num |
Channel number. |
Input |
df_info |
Address information for sending data. |
Input |
millisec |
Waiting time. When this parameter is set to -1, it is blocking; when this parameter is set to 0, it is non-blocking; when this parameter is set to a value greater than 0, it will wait for the corresponding time until the data is successfully sent. If the data is not sent successfully after the timeout, failure is returned. |
Input |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
None
Example
None
Related Topics
kd_mpi_dma_get_frame#
Description
Get the data after dma transfer.
Syntax
k_s32 kd_mpi_dma_get_frame(k_u8 chn_num, k_video_frame_info *df_info, k_s32 millisec);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
chn_num |
Channel number. |
Input |
df_info |
Get the address information of the data. |
Output |
millisec |
Waiting time. When this parameter is set to -1, it is blocking; when this parameter is set to 0, it is non-blocking; when this parameter is set to a value greater than 0, it will wait for the corresponding time until the data is successfully obtained. If the data is not successfully sent after the timeout, a failure is returned. |
Input |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
None
Example
None
Related Topics
kd_mpi_dma_release_frame#
Description
Release the acquired dma data.
Syntax
k_s32 kd_mpi_dma_release_frame(k_u8 chn_num, k_video_frame_info *df_info);
Parameters
Parameter Name |
Description |
Input/Output |
|---|---|---|
chn_num |
Channel number. |
Input |
df_info |
Data to be released. |
Input |
Return Value
Return Value |
Description |
|---|---|
0 |
Success |
non-0 |
Failure, please refer to the error code for its value. |
Chip differences
None
Requirements
Header File: mpi_dma_api.h
Library File: libdma.a
Notes
In the current design, the dma output buffer is 3. If you obtain 3 frames of data without calling this function to release it, you cannot continue to input data. Therefore, users should obtain data and release it promptly after use.
Example
None
Related Topics
data type#
public data type#
DMA_MAX_DEV_NUMS#
Description
DMA maximum number of devices
definition
#define DMA_MAX_DEV_NUMS (1)
Notes
None
Related Data Types and Interfaces
None
DMA_MAX_CHN_NUMS#
Description
DMA maximum number of channels
definition
#define DMA_MAX_CHN_NUMS (8)
Notes
None
Related Data Types and Interfaces
None
k_dma_mode_e#
Description
Define dma working mode.
definition
typedef enum
{
DMA_BIND,
DMA_UNBIND,
} k_dma_mode_e;
member
member name |
Description |
|---|---|
BIND |
Binding mode. |
UNBIND |
Unbound mode |
Notes
None
Related Data Types and Interfaces
k_dma_dev_attr_t#
Description
Define dma device properties.
definition
typedef struct
{
k_u8 burst_len;
k_u8 outstanding;
k_bool ckg_bypass;
} k_dma_dev_attr_t;
member
member name |
Description |
|---|---|
burst_len |
Configure the burst length of dma |
outstanding |
Configure dma outstanding |
ckg_bypass |
Configure clock gate bypass |
Notes
None
Related Data Types and Interfaces
k_dma_chn_attr_u#
Description
Define dma channel properties.
definition
typedef union
{
k_gdma_chn_attr_t gdma_attr;
k_sdma_chn_attr_t sdma_attr;
} k_dma_chn_attr_u;
member
member name |
Description |
|---|---|
gdma_attr |
gdma channel properties |
sdma_attr |
sdma channel properties |
ckg_bypass |
Configure clock gate bypass |
Notes
None
Related Data Types and Interfaces
k_gdma_chn_attr_t k_sdma_chn_attr_t kd_mpi_dma_set_chn_attr kd_mpi_dma_get_chn_attr
k_video_frame_info#
Description
Define dma data address.
definition
typedef struct
{
k_video_frame v_frame; /**< Video picture frame */
k_u32 pool_id; /**< VB pool ID */
k_mod_id mod_id; /**< Logical unit for generating video frames */
} k_video_frame_info;
member
member name |
Description |
|---|---|
v_frame |
Timestamp, valid in binding mode. |
pool_id |
The pool id of the data vb pool. |
mod_id |
module id |
Notes
None
Related Data Types and Interfaces
kd_mpi_dma_send_frame kd_mpi_dma_get_frame kd_mpi_dma_release_frame
k_video_frame#
Description
Define dma data address. Using the public data structure k_video_frame, only some of its members are used.
definition
typedef struct
{
k_u64 phys_addr[3];
k_u64 virt_addr[3];
k_u32 time_ref;
k_u64 pts;
} k_video_frame;
member
member name |
Description |
|---|---|
phys_addr |
The physical address of the image. If it is a single-channel image, you only need to configure the first physical address; if it is a dual-channel image, you only need to configure the first two physical addresses; if it is a three-channel image, you need to configure three physical addresses. |
virt_addr |
The virtual address of the image. If it is a single-channel image, you only need to configure the first virtual address; if it is a dual-channel image, you only need to configure the first two virtual addresses; if it is a three-channel image, you need to configure three virtual addresses. |
time_ref |
The frame number of transparent transmission is input by the previous stage in binding mode. |
pts |
The transparently transmitted timestamp is input by the previous stage in binding mode. |
Notes
None
Related Data Types and Interfaces
gdma channel data type#
This module has the following data types
GDMA_MAX_CHN_NUMS#
Description
GDMA maximum number of channels
definition
define GDMA_MAX_CHN_NUMS (4)
Notes
None
Related Data Types and Interfaces
None
k_gdma_rotation_e#
Description
Define gdma channel rotation angle.
definition
typedef enum
{
DEGREE_0, /**< Rotate 0 degrees */
DEGREE_90, /**< Rotate 90 degrees */
DEGREE_180, /**< Rotate 180 degrees */
DEGREE_270, /**< Rotate 270 degrees */
} k_gdma_rotation_e;
Notes
None
Related Data Types and Interfaces
k_pixel_format_dma_e#
Description
Defines gdma image format.
definition
typedef enum
{
DMA_PIXEL_FORMAT_RGB_444 = 0,
DMA_PIXEL_FORMAT_RGB_555,
DMA_PIXEL_FORMAT_RGB_565,
DMA_PIXEL_FORMAT_RGB_888,
DMA_PIXEL_FORMAT_BGR_444,
DMA_PIXEL_FORMAT_BGR_555,
DMA_PIXEL_FORMAT_BGR_565,
DMA_PIXEL_FORMAT_BGR_888,
DMA_PIXEL_FORMAT_ARGB_1555,
DMA_PIXEL_FORMAT_ARGB_4444,
DMA_PIXEL_FORMAT_ARGB_8565,
DMA_PIXEL_FORMAT_ARGB_8888,
DMA_PIXEL_FORMAT_ABGR_1555,
DMA_PIXEL_FORMAT_ABGR_4444,
DMA_PIXEL_FORMAT_ABGR_8565,
DMA_PIXEL_FORMAT_ABGR_8888,
DMA_PIXEL_FORMAT_YVU_PLANAR_420_8BIT,
DMA_PIXEL_FORMAT_YVU_PLANAR_420_10BIT,
DMA_PIXEL_FORMAT_YVU_PLANAR_420_16BIT,
DMA_PIXEL_FORMAT_YVU_PLANAR_444_8BIT,
DMA_PIXEL_FORMAT_YVU_PLANAR_444_10BIT,
DMA_PIXEL_FORMAT_YUV_PLANAR_420_8BIT,
DMA_PIXEL_FORMAT_YUV_PLANAR_420_10BIT,
DMA_PIXEL_FORMAT_YUV_PLANAR_420_16BIT,
DMA_PIXEL_FORMAT_YVU_SEMIPLANAR_420_8BIT,
DMA_PIXEL_FORMAT_YVU_SEMIPLANAR_420_10BIT,
DMA_PIXEL_FORMAT_YVU_SEMIPLANAR_420_16BIT,
DMA_PIXEL_FORMAT_YUV_SEMIPLANAR_420_8BIT,
DMA_PIXEL_FORMAT_YUV_SEMIPLANAR_420_10BIT,
DMA_PIXEL_FORMAT_YUV_SEMIPLANAR_420_16BIT,
DMA_PIXEL_FORMAT_YUV_400_8BIT,
DMA_PIXEL_FORMAT_YUV_400_10BIT,
DMA_PIXEL_FORMAT_YUV_400_12BIT,
DMA_PIXEL_FORMAT_YUV_400_16BIT,
DMA_PIXEL_FORMAT_YUV_PACKED_444_8BIT,
DMA_PIXEL_FORMAT_YUV_PACKED_444_10BIT,
/* SVP data format */
DMA_PIXEL_FORMAT_BGR_888_PLANAR,
} k_pixel_format_dma_e;
k_gdma_chn_attr_t#
Description
Define gdma channel properties.
definition
typedef struct
{
k_u8 buffer_num;
k_gdma_rotation_e rotation;
k_bool x_mirror;
k_bool y_mirror;
k_u16 width;
k_u16 height;
k_u16 src_stride[3];
k_u16 dst_stride[3];
k_dma_mode_e work_mode;
k_pixel_format_dma_e pixel_format;
} k_gdma_chn_attr_t;
member
member name |
Description |
|---|---|
buffer_num |
Number of gdma channel buffers, at least 1. |
rotation |
gdma channel rotation angle. |
x_mirror |
Whether the gdma channel performs horizontal mirroring |
y_mirror |
Whether the gdma channel performs vertical mirroring |
width |
gdma channel width in pixels. |
height |
Gdma channel height in pixels. |
src_stride |
gdma source data stride. If the image format is single-channel mode, you only need to configure |
dst_stride |
gdma destination data stride. If the image format is single-channel mode, you only need to configure |
work_mode |
Working mode, you can choose binding mode or non-binding mode. |
pixel_format |
Image format. |
Notes
None.
Related Data Types and Interfaces
sdma channel data type#
This module has the following data types
SDMA_MAX_CHN_NUMS#
Description
SDMA maximum number of channels
definition
#define SDMA_MAX_CHN_NUMS (4)
Notes
None
Related Data Types and Interfaces
None
k_sdma_data_mode_e#
Description
Define the mode for sdma channel to transmit data
definition
typedef enum
{
DIMENSION1,
DIMENSION2,
} k_sdma_data_mode_e;
member
member name |
Description |
|---|---|
DIMENSION1 |
one-dimensional dma transfer mode |
DIMENSION1 |
2D DMA transfer mode |
Notes
None
Related Data Types and Interfaces
k_sdma_chn_attr_t#
Description
Define sdma channel properties.
definition
typedef struct
{
k_u8 buffer_num;
k_u32 line_size;
k_u16 line_num;
k_u16 line_space;
k_sdma_data_mode_e data_mode;
k_dma_mode_e work_mode;
} k_sdma_chn_attr_t;
member
member name |
Description |
|---|---|
buffer_num |
Number of sdma channel buffers, at least 1. |
line_size |
For 1d mode, it is the total length of transmitted data; for 2d mode, it is the length of a single line of data. |
line_num |
For 1d mode, this member is invalid; for 2d mode, it is the number of rows transferred. |
line_space |
For 1d mode, this member has no effect; for 2d mode, it is the space between rows. |
data_mode |
sdma data transmission mode, including 1d mode and 2d mode. |
work_mode |
Working mode, you can choose binding mode or non-binding mode. |
Notes
None
Related Data Types and Interfaces
error code#
dma error code#
Table 41
error code |
Macro definition |
Description |
|---|---|---|
0xa0148001 |
K_ERR_DMA_INVALID_DEVID |
Invalid device number |
0xa0148002 |
K_ERR_DMA_INVALID_CHNID |
Invalid channel number |
0xa0148003 |
K_ERR_DMA_ILLEGAL_PARAM |
Parameter error |
0xa0148004 |
K_ERR_DMA_EXIST |
DMA device already exists |
0xa0148005 |
K_ERR_DMA_UNEXIST |
DMA device does not exist |
0xa0148006 |
K_ERR_DMA_NULL_PTR |
Null pointer error |
0xa0148007 |
K_ERR_DMA_NOT_CONFIG |
DMA not configured yet |
0xa0148008 |
K_ERR_DMA_NOT_SUPPORT |
Unsupported features |
0xa0148009 |
K_ERR_DMA_NOT_PERM |
Operation not allowed |
0xa014800c |
K_ERR_DMA_NOMEM |
Failed to allocate memory, such as insufficient system memory |
0xa014800d |
K_ERR_DMA_NOBUF |
Not enough BUFF |
0xa014800e |
K_ERR_DMA_BUF_EMPTY |
BUFF is empty |
0xa014800f |
K_ERR_DMA_BUF_FULL |
BUFF is full |
0xa0148010 |
K_ERR_DMA_NOTREADY |
Device is not ready |
0xa0148011 |
K_ERR_DMA_BADADDR |
wrong address |
0xa0148012 |
K_ERR_DMA_BUSY |
DMA is in busy state |
debugging information#
Overview#
The debugging information uses the proc file system, which can reflect the current running status of the system in real time. The recorded information can be used for problem location and analysis.
File directory
/proc/
Document list
File name |
Description |
|---|---|
umap/dma |
Record the current usage of dma module |
System binding#
System binding debugging information#
debugging information
msh /\>cat /proc/umap/dma
-------------------------------dma dev attr info---------------------------------
DevId burst_len outstanding ckg_bypass
0 0 0 0
-------------------------------dma chn 0\~3 attr info-------------------------------
ChnId rotation x_mirror y_mirror width height work_mode
0 0 false false 0 0 BIND
1 0 false false 0 0 BIND
2 0 false false 0 0 BIND
3 0 false false 0 0 BIND
-------------------------------dma chn 4\~7 attr info-------------------------------
ChnId line_size line_num line_space data_mode work_mode
4 0 0 0 1 DIMENSION BIND
5 0 0 0 1 DIMENSION BIND
6 0 0 0 1 DIMENSION BIND
7 0 0 0 1 DIMENSION BIND
Debugging information analysis
Record the current usage of dma module
Equipment parameter description
parameter |
describe |
|---|---|
DevId |
Device number |
burst_len |
dma burst length |
outstanding |
dma outstanding |
gdma channel parameter description
parameter |
describe |
|---|---|
ChnId |
Channel number |
rotation |
Degrees of rotation |
x_mirror |
Whether horizontal mirroring is performed |
y_mirror |
Whether vertical mirroring is performed |
width |
Image width in pixels |
height |
Image height in pixels |
work_mode |
working mode |
sdma channel parameter description
parameter |
describe |
|---|---|
ChnId |
Channel number |
line_size |
For 1d mode, it is the total length of transmitted data; for 2d mode, it is the length of a single line of data. |
ine_num |
For 1d mode, this member is invalid; for 2d mode, it is the number of rows transferred. |
line_space |
For 1d mode, this member has no effect; for 2d mode, it is the space between rows. |
data_mode |
sdma data transmission mode, including 1d mode and 2d mode |
work_mode |
Working mode, you can choose binding mode or non-binding mode. |
demo description#
Unbound mode demo#
The non-binding mode demo is located in /bin/sample_dma.elf. After executing /bin/sample_dma.elf, it starts to run in a loop. Press e + Enter to end the run.
The demo mainly implements the following functions:
Use channel 0 to transport images with a resolution of 1920*1080, 8bit, YUV400 single channel, and output after gdma rotation 90 degrees;
Use channel 1 to transport images with a resolution of 1280*720, 8bit, YUV420 dual channels, and output after gdma rotation 180 degrees;
Use channel 2 to transport images with a resolution of 1280*720, 10bit, and YUV420 three channels. Gdma performs horizontal and vertical mirroring and outputs;
Use channel 4 to transport data, sdma uses 1d mode to transport;
Use channel 5 to carry data, sdma uses 2d mode to carry.
Binding mode demo#
The binding mode demo is located in /bin/sample_dma_bind.elf. After executing /bin/sample_dma_bind.elf, it starts to run in a loop. Press e + Enter to end the run.
The demo mainly implements the following functions:
Use the vvi module as the simulation input of the gsdma front-end binding to implement the testing of the binding function;
The two channels input images with a resolution of 640*320, 8bit, and YUV400 single channel respectively. The gdma output is rotated by 90 degrees and 180 degrees respectively.
