Note

This is the documentation for the latest development branch and may refer to features that are not available in released versions. If you are looking for the documentation for a specific release, use the drop-down menu on the left and select the desired version.

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:

  1. Configure dma device attributes;

  2. Start the dma device. After calling this function, the driver will automatically apply for VB space as the data buffer of the destination address;

  3. Configure gdma channel attributes;

  4. Start gdma channel;

  5. 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;

  6. The driver will transfer the data in the source address to the destination address data buffer applied for in step 2;

  7. 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:

  1. Configure dma device attributes;

  2. Start the dma device. After calling this function, the driver will automatically apply for VB space as the data buffer of the destination address;

  3. Configure sdma channel attributes;

  4. Start sdma channel;

  5. 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;

  6. The driver will transfer the data in the source address to the destination address data buffer applied for in step 2;

  7. 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

k_dma_dev_attr_t

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

k_dma_dev_attr_t

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

k_dma_chn_attr_u

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

k_dma_chn_attr_u

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

k_video_frame_info

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

k_video_frame_info

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

k_video_frame_info

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_gdma_chn_attr_t k_sdma_chn_attr_t

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

kd_mpi_dma_set_dev_attr kd_mpi_dma_get_dev_attr

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

kd_mpi_dma_send_frame kd_mpi_dma_get_frame

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_gdma_chn_attr_t

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 src_stride[0]; if the image format is dual-channel mode, you need to configure src_stride[0], src_stride[1]; if the image format is three-channel mode, you need to configure src_stride[0], src_stride[1], src_stride[2].

dst_stride

gdma destination data stride. If the image format is single-channel mode, you only need to configure dst_stride[0]; if the image format is dual-channel mode, you need to configure dst_stride[0], dst_stride[1]; if the image format is three-channel mode, you need to configure dst_stride[0], dst_stride[1], dst_stride[2].

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

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

k_dma_chn_attr_u

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.

Comments list
Comments
Log in