K230 System Control API Reference

K230 System Control API Reference#

Preface#

Overview#

This document mainly introduces the functions and usage of the system control module in the media subsystem. The functions and usage of other modules will be discussed in separate documents.

Audience#

This document (this guide) is mainly intended for the following personnel:

Technical Support Engineers
Software Development Engineers

Abbreviation Definitions#

Abbreviation	Description
mpp	Media Process Platform
vb	Video Buffer

Revision History#

Document Version	Description	Author	Date
V1.0	Initial Version	Haibo Hao	2023/3/4

1. Overview#

1.1 Overview#

System control, based on the characteristics of the K230 chip, completes the reset and basic initialization of various hardware components. It is also responsible for initializing and de-initializing modules such as MPP (Media Process Platform) system memory management, log management, and binding management.

1.2 Function Description#

1.2.1 Video Buffer Pool#

The video buffer pool is a group of buffers (not just one), mainly provided for use by multimedia hardware devices and circulated between these devices. The buffer pool is divided into public and private buffer pools. The public buffer pool is mainly for VI, and the size of the buffer blocks must be determined according to the image parameters of VI before using it, and then a certain number of buffer blocks are applied for to form a buffer pool. Generally, for the original image input by VI, the size of one frame corresponds to the size of one buffer block, and multiple buffer blocks provide a multi-frame buffering mechanism for VI. These public buffer blocks can also be used by VO or VENC. Private buffer pools often represent data stored in memory that is closely related to the multimedia device itself. For example, the encoded bitstream data is quite different from the actual image pixel composition of the video stream. These bitstreams are only available to the codec, and VB provides dedicated buffer pools for these devices. The following diagram shows the process of virtual VI and virtual VO using VB to circulate buffer blocks.

Diagram

1.2.2 System Binding#

System binding establishes an association between the data receiver and the data source (only allowing the data receiver to bind the data source). After binding, the data generated by the data source will be automatically sent to the receiver. The major voice and video processing of K230 is divided into several major modules as follows:

Voice: Audio Input (AI), Audio Encoder (AENC), Audio Recognize (AREC), Audio Decoder (ADEC), Audio Output (AO)

Image: Video Input (VI), Video Encoder (VENC), Image Rotation (handled by GSDMA), Depth Process Unit (DPU), Video Decoder (VDEC), Video Output (VO), Virtual Video Input (VVI), Virtual Video Output (VVO)

The binding relationships supported by K230 are as follows:

Table 11

Data Source	Data Receiver	Description
VI (Video Input)	GSDMA	VI data can be sent to GSDMA for rotation processing
	VO	VI data can be directly sent to VO for display
	DPU	VI data can be directly sent to DPU for processing
	VENC	VI data can be directly sent to VENC for processing
GSDMA (Image Rotation)	VO	GSDMA processed data can be directly sent to VO for display
	DPU	GSDMA processed data can be directly sent to DPU for processing
	VENC	VPROC processed data can be directly sent to VENC for encoding
VDEC (Video Decoder)	GSDMA	VDEC data will eventually be played locally, may need rotation before playback
	VO	VDEC data will eventually be played locally
DPU (Depth Processing Unit)	None	DPU is the endpoint of video data, does not support binding relationships
VENC (Video Encoder)	None	Does not support binding relationships
VO (Video Output)	None	VO is the endpoint of video data, does not support binding relationships
AI (Audio Input)	AREC	AI processed data can be directly sent to the audio recognition module for recognition
	AENC	AI processed data can be directly sent to the audio encoding module for encoding
	AO	AI processed data can be directly played
ADEC (Audio Decoder)	AO	ADEC processed data can be directly played
AENC (Audio Encoder)	None	Does not support binding relationships
AO (Audio Output)	None	AO is the endpoint of audio data, does not support binding relationships

2. API Reference#

2.1 Multimedia Memory Management#

This functional module provides the following APIs:

2.1.1 kd_mpi_sys_mmz_alloc#

Description:

Allocate MMZ memory in user space.

Syntax:

k_s32 kd_mpi_sys_mmz_alloc(k_u64* phy_addr, void** virt_addr, const k_char* mmb, const k_char* zone, k_u32 len);

Parameters:

Parameter Name	Description	Input/Output
phy_addr	Pointer to the physical address.	Output
virt_addr	Pointer to the virtual address pointer.	Output
mmb	String pointer to the MMB name.	Input
zone	String pointer to the MMZ zone name.	Input
len	Size of the memory block.	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None.

Requirements:

Header file: mpi_sys_api.h
Library file: libsys.a

Notes:

MMZ consists of multiple zones, each zone has multiple MMBs. You can call this MPI to allocate a memory block of size len in the *zone of MMZ. In this case, pointers to the physical address and user-mode virtual address are returned. If there is an anonymous zone in MMZ, set *zone to null. If *mmb is set to null, the created MMB is named null.

Example:

None.

Related Topics:

None.

2.1.2 kd_mpi_sys_mmz_alloc_cached#

Description:

Allocate cached MMZ memory in user space.

Syntax:

k_s32 kd_mpi_sys_mmz_alloc_cached(k_u64* phy_addr, void** virt_addr, const k_char* mmb, const k_char* zone, k_u32 len);

Parameters:

Parameter Name	Description	Input/Output
phy_addr	Pointer to the physical address.	Output
virt_addr	Pointer to the virtual address pointer.	Output
mmb	String pointer to the MMB name.	Input
zone	String pointer to the MMZ zone name.	Input
len	Size of the memory block.	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None.

Requirements:

Header file: mpi_sys_api.h
Library file: libsys.a

Notes:

The difference between kd_mpi_sys_mmz_alloc_cached and kd_mpi_sys_mmz_alloc: Memory allocated by calling kd_mpi_sys_mmz_alloc_cached supports caching. If the memory to be allocated will be frequently used, it is recommended to use kd_mpi_sys_mmz_alloc_cached. This can improve CPU read/write efficiency and system performance.
When the CPU accesses the memory allocated by this interface, the data in the memory will be placed in the cache. Hardware devices can only access physical memory, not the cache. In this case, kd_mpi_sys_mmz_flush_cache needs to be called to synchronize the data.

Example:

None.

Related Topics:

None.

2.1.3 kd_mpi_sys_mmap#

Description: Description:

Memory mapping interface.

Syntax:

void *kd_mpi_sys_mmap(k_u64 phy_addr, k_u32 size);

Parameters:

Parameter Name	Description	Input/Output
phy_addr	Starting address of the memory unit to be mapped	Input
size	Number of bytes to map	Input

Return Values:

Return Value	Description
0	Invalid address
Non-0	Valid address

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h
Library file: libsys.a

Notes:

Only the physical addresses obtained through MMZ allocation can be mapped using this API.
If the address range belongs to a VB, the size of the mapping must be smaller than the size of the VB pool.

Example:

None

Related Topics:

kd_mpi_sys_munmap()

2.1.4 kd_mpi_sys_mmap_cached#

Description:

Memory mapping interface with cache.

Syntax:

void *kd_mpi_sys_mmap_cached(k_u64 phy_addr, k_u32 size);

Parameters:

Parameter Name	Description	Input/Output
phy_addr	Starting address of the memory unit to be mapped	Input
size	Number of bytes to map	Input

Return Values:

Return Value	Description
0	Invalid address
Non-0	Valid address

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h
Library file: libsys.a

Notes:

Only the physical addresses obtained through MMZ allocation can be mapped using this API.
If the address range belongs to a VB, the size of the mapping must be smaller than the size of the VB pool.

Example:

None

Related Topics:

None

2.1.5 kd_mpi_sys_munmap#

Description:

Memory unmapping interface.

Syntax:

void *kd_mpi_sys_munmap(void *virt_addr, k_u32 size);

Parameters:

Parameter Name	Description	Input/Output
virt_addr	Virtual address returned by mmap	Input
size	Number of bytes to unmap	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h
Library file: libsys.a

Notes:

None

Example:

None

Related Topics:

kd_mpi_sys_mmap
kd_mpi_sys_mmap_cached

2.1.6 kd_mpi_sys_mmz_flush_cache#

Description:

Flush the contents of the cache to memory and invalidate the cache contents.

Syntax:

k_s32 kd_mpi_sys_mmz_flush_cache(k_u64 phy_addr, void* virt_addr, k_u32 size);

Parameters:

Parameter Name	Description	Input/Output
phy_addr	Starting physical address of the data to operate on	Input
virt_addr	Starting virtual address pointer of the data to operate on. Cannot be NULL	Input
size	Size of the data to operate on	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h
Library file: libsys.a

Notes:

If the cache contains the latest data, you need to call this MPI to synchronize the data to memory. This ensures that hardware that cannot directly access the cache can obtain the correct data.
You must call kd_mpi_sys_mmz_alloc_cached before using this MPI.
If phy_addr is set to 0, it means to operate on the entire cache area. (Not supported currently)
You need to ensure that the parameters passed are valid.
Ensure that kd_mpi_sys_mmz_free is not called to free the memory being flushed; otherwise, unpredictable exceptions may occur.

Example:

None

Related Topics:

kd_mpi_sys_mmz_alloc_cached
kd_mpi_sys_mmap_cached

2.1.7 kd_mpi_sys_mmz_free#

Description:

Free MMZ memory in user space.

Syntax:

k_s32 kd_mpi_sys_mmz_free(k_u64 phy_addr, void* virt_addr);

Parameters:

Parameter Name	Description	Input/Output
phy_addr	Physical address	Input
virt_addr	Virtual address pointer	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h
Library file: libsys.a

Notes:

The input address must be a valid physical address, and the virtual address pointer can be set to NULL.
Do not free memory that is undergoing a flush operation, as it may cause unpredictable exceptions.

Example:

None

Related Topics:

kd_mpi_sys_mmz_alloc
kd_mpi_sys_mmz_alloc_cached

2.1.8 kd_mpi_sys_get_virmem_info#

Description:

Get the memory information corresponding to the virtual address, including the physical address and cached attributes.

Syntax:

k_s32 kd_mpi_sys_get_virmem_info(const void* virt_addr, k_sys_virmem_info* mem_info);

Parameters:

Parameter Name	Description	Input/Output
virt_addr	Virtual address pointer	Input
mem_info	Memory information corresponding to the virtual address, including physical address, cached attributes, etc.	Output

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_mmz_comm.h
Library file: libsys.a

Notes:

The input must be a user-space virtual address.
Cross-process use is not supported.

Example:

None

Related Topics:

kd_mpi_sys_mmz_alloc
kd_mpi_sys_mmz_alloc_cached

2.1.9 kd_mpi_vb_set_config#

Description:

Set MPP video buffer pool attributes.

Syntax:

k_s32 kd_mpi_vb_set_config(const [k_vb_config](#323-k_vb_config) *config);

Parameters:

Parameter Name	Description	Input/Output
config	Pointer to the video buffer pool attributes	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

The buffer pool attributes can only be set when the system is uninitialized; otherwise, the function will return failure.
The size of each buffer block in the common buffer pool should vary according to the current image pixel format and whether the image is compressed. For specific allocation sizes, refer to the description in the k_vb_config structure.

Example:

None

Related Topics:

kd_mpi_vb_get_config

2.1.10 kd_mpi_vb_get_config#

Description:

Get MPP video buffer pool attributes.

Syntax:

k_s32 kd_mpi_vb_get_config(const [k_vb_config](#323-k_vb_config) *config);

Parameters:

Parameter Name	Description	Input/Output
config	Pointer to the video buffer pool attributes	Output

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

You must first call kd_mpi_vb_set_config to set the MPP video buffer pool attributes before getting the attributes.

Example:

None

Related Topics:

kd_mpi_vb_set_config

2.1.11 kd_mpi_vb_init#

Description:

Initialize the MPP video buffer pool.

Syntax:

k_s32 kd_mpi_vb_init(void);

Parameters:

None

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

You must first call kd_mpi_vb_set_config to set the MPP video buffer pool attributes before initializing the buffer pool; otherwise, it will fail.
Initialization can be repeated without returning failure.

Example:

None

Related Topics:

kd_mpi_vb_exit

2.1.12 kd_mpi_vb_exit#

Description:

Deinitialize the MPP video buffer pool.

Syntax:

k_s32 kd_mpi_vb_exit(void);

Parameters:

None

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

Deinitialization does not clear previous buffer pool configurations.
Deinitialization can be repeated without returning failure.
Before exiting the VB pool, ensure that no VB in the VB pool is occupied; otherwise, it cannot be exited.

Example:

None

Related Topics:

kd_mpi_vb_init

2.1.13 kd_mpi_vb_create_pool#

Description:

Create a video buffer pool.

Syntax:

k_s32 kd_mpi_vb_create_pool([k_vb_pool_config](#324-k_vb_pool_config) *config);

Parameters:

Parameter Name	Description	Input/Output
config	Pointer to the buffer pool configuration attributes	Input

Return Values:

Return Value	Description
Non VB_INVALID_POOLID	Valid buffer pool ID
VB_INVALID_POOLID	Failed to create buffer pool, possibly due to illegal parameters or insufficient reserved memory

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

None

Example:

None

Related Topics:

kd_mpi_vb_destory_pool

2.1.14 kd_mpi_vb_destory_pool#

Description:

Destroy a video buffer pool.

Syntax:

k_s32 kd_mpi_vb_destory_pool(k_u32 pool_id);

Parameters:

Parameter Name	Description	Input/Output
pool_id	Buffer pool ID. Value range: [0, VB_MAX_POOLS)	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

Destroying a non-existent buffer pool will return K_ERR_VB_UNEXIST.
Only buffer pools created by kd_mpi_vb_create_pool can be destroyed.

Example:

None

Related Topics:

kd_mpi_vb_create_pool

2.1.15 kd_mpi_vb_get_block#

Description:

Acquire a buffer block in user mode.

Syntax:

k_vb_blk_handle kd_mpi_vb_get_block(k_u32 pool_id, k_u64 blk_size, const k_char *mmz_name);

Parameters:

Parameter Name	Description	Input/Output
pool_id	Buffer pool ID. Range: [0, VB_MAX_POOLS)	Input
blk_size	Buffer block size in bytes. Range: full data type range	Input
mmz_name	Name of the DDR where the buffer pool is located	Input

Return Values:

Return Value	Description
Non VB_INVALID_HANDLE	Valid buffer block handle
VB_INVALID_HANDLE	Failed to get buffer block

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

Users can call this interface to get a buffer block from a created buffer pool by setting the first parameter pool_id to the created buffer pool ID. When getting a buffer block from a specified buffer pool, the mmz_name parameter is invalid.
If users need to get a buffer block of a specified size from any common buffer pool, they can set the first parameter pool_id to an invalid ID (VB_INVALID_POOLID), set the second parameter blk_size to the required buffer block size, and specify which DDR’s common buffer pool to get the buffer block from. If there is no common buffer pool on the specified DDR, no buffer block will be obtained. If mmz_name is NULL, it means to get the buffer block from the anonymous DDR’s common buffer pool.

Example:

None

Related Topics:

Description:ase_block](#2116-kd_mpi_vb_release_block)

2.1.16 kd_mpi_vb_release_block#

Description:

Release a buffer block in user mode.

Syntax:

k_s32 kd_mpi_vb_release_block(k_vb_blk_handle block);

Parameters:

Parameter Name	Description	Input/Output
block	Buffer block handle	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

The acquired buffer block should be released using this interface after use.

Example:

None

Related Topics:

Description:block](#2115-kd_mpi_vb_get_block)

2.1.17 kd_mpi_vb_phyaddr_to_handle#

Description:

Get the handle of a buffer block through its physical address in user mode.

Syntax:

k_vb_blk_handle kd_mpi_vb_phyaddr_to_handle(k_u64 phys_addr);

Parameters:

Parameter Name	Description	Input/Output
phys_addr	Physical address	Input

Return Values:

Return Value	Description
Non VB_INVALID_HANDLE	Valid buffer block handle
VB_INVALID_HANDLE	Failed to get buffer block handle

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

The physical address should be the address of a valid buffer block obtained from the MPP video buffer pool.

Example:

None

Related Topics:

Description:

2.1.18 kd_mpi_vb_handle_to_phyaddr#

Description:

Get the physical address of a buffer block in user mode.

Syntax:

k_u64 kd_mpi_vb_handle_to_phyaddr(k_vb_blk_handle block);

Parameters:

Parameter Name	Description	Input/Output
block	Buffer block handle	Input

Return Values:

Return Value	Description
0	Invalid return value, illegal buffer block handle
Non-0	Valid physical address

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

The specified buffer block should be a valid buffer block obtained from the MPP video buffer pool.

Example:

None

Related Topics:

Description:

2.1.19 kd_mpi_vb_handle_to_pool_id#

Description:

Get the ID of the buffer pool where a frame buffer block is located in user mode.

Syntax:

k_s32 kd_mpi_vb_handle_to_pool_id(k_vb_blk_handle block);

Parameters:

Parameter Name	Description	Input/Output
block	Buffer block handle	Input

Return Values:

Return Value	Description
Non VB_INVALID_POOLID	Valid buffer pool ID
VB_INVALID_POOLID	Failed to get buffer pool ID

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

The specified buffer block should be a valid buffer block obtained from the MPP video buffer pool.

Example:

None

Related Topics:

Description:

2.1.20 kd_mpi_vb_inquire_user_cnt#

Description:

Query the usage count information of a buffer block.

Syntax:

k_s32 kd_mpi_vb_inquire_user_cnt(k_vb_blk_handle block);

Parameters:

Parameter Name	Description	Input/Output
block	Buffer block handle	Input

Return Values:

Return Value	Description
K_FAILED	Query failed
Other values	Buffer block usage count

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

None

Example:

None

Related Topics:

Description:

2.1.21 kd_mpi_vb_get_supplement_attr#

Description:

Get the supplementary information of VB Block memory.

Syntax:

k_s32 kd_mpi_vb_get_supplement_attr(k_vb_blk_handle block, k_video_supplement *supplement);

Parameters:

Parameter Name	Description	Input/Output
block	Buffer block handle	Input
supplement	Supplementary information of VB block memory, such as ISP information, DCF information, etc.	Output

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

The virtual address information of the DCF and ISP stored in Supplement is the kernel-mode virtual address.

Example:

None

Related Topics:

Description:

2.1.22 kd_mpi_vb_set_supplement_config#

Description:

Set the supplementary information of VB memory.

Syntax:

k_s32 kd_mpi_vb_set_supplement_config(const k_vb_supplement_config *supplement_config);

Parameters:

Parameter Name	Description	Input/Output
supplement_config	VB memory supplementary information control structure for supplementary information memory allocation	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

Currently, two types of VB memory supplementary information are supported:
- DCF information, corresponding to the structure k_jpeg_dcf. The corresponding MASK is VB_SUPPLEMENT_JPEG_MASK.
- ISP information, corresponding to the structure k_isp_frame_info. The corresponding MASK is VB_SUPPLEMENT_ISPINFO_MASK.
This interface needs to be called before kd_mpi_vb_init for the supplementary information to take effect.

Example:

None

Related Topics:

Description:supplement_config](#2123-kd_mpi_vb_get_supplement_config)

2.1.23 kd_mpi_vb_get_supplement_config#

Description:

Get the supplementary information of VB memory.

Syntax:

k_s32 kd_mpi_vb_get_supplement_config(const k_vb_supplement_config *supplement_config);

Parameters:

Parameter Name	Description	Input/Output
supplement_config	VB memory supplementary information control structure for supplementary information memory allocation	Output

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

None

Example:

None

Related Topics:

Description:supplement_config](#2122-kd_mpi_vb_set_supplement_config)

2.1.24 kd_mpi_vb_set_mod_pool_config#

Description:

Set the attributes of the module’s common video buffer pool.

Syntax:

k_s32 kd_mpi_vb_set_mod_pool_config(k_vb_uid vb_uid, const k_vb_config *config);

Parameters:

Parameter Name	Description	Input/Output
vb_uid	Module ID using the common video buffer pool	Input
config	Pointer to video buffer pool attributes	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

The configuration of the module’s common video buffer pool should be based on actual needs, otherwise it may cause memory waste.
If the module VB has already been created, reconfiguration will return the error code KD_ERR_VB_BUSY.

Example:

None

Related Topics:

Description:mod_pool_config](#2125-kd_mpi_vb_get_mod_pool_config)

2.1.25 kd_mpi_vb_get_mod_pool_config#

Description:

Get the attributes of the module’s common video buffer pool.

Syntax:

k_s32 kd_mpi_vb_get_mod_pool_config(k_vb_uid vb_uid, k_vb_config *config);

Parameters:

Parameter Name	Description	Input/Output
vb_uid	Module ID using the common video buffer pool	Input
config	Pointer to video buffer pool attributes	Output

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

You must call kd_mpi_vb_set_mod_pool_config to set the attributes of the module’s common video buffer pool before getting the attributes.

Example:

None

Related Topics:

Description:mod_pool_config](#2124-kd_mpi_vb_set_mod_pool_config)

2.1.26 kd_mpi_vb_init_mod_common_pool#

Description:

Initialize the module’s common video buffer pool.

Syntax:

k_s32 kd_mpi_vb_init_mod_common_pool(k_vb_uid vb_uid);

Parameters:

Parameter Name	Description	Input/Output
vb_uid	Module ID using the common video buffer pool	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

You must first call kd_mpi_vb_init to initialize the common video buffer pool.
You must first call kd_mpi_vb_set_mod_pool_config to configure the buffer pool attributes before initializing the buffer pool, otherwise it will fail.
It can be initialized repeatedly without returning failure.

Example:

None

Related Topics:

Description:_mod_common_pool](#2127-kd_mpi_vb_exit_mod_common_pool)

2.1.27 kd_mpi_vb_exit_mod_common_pool#

Description:

Exit the module’s common video buffer pool.

Syntax:

k_s32 kd_mpi_vb_exit_mod_common_pool(k_vb_uid vb_uid);

Parameters:

Parameter Name	Description	Input/Output
vb_uid	Module ID using the common video buffer pool.	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_vb_api.h k_vb_comm.h
Library file: libvb.a

Notes:

You must call this interface before calling kd_mpi_vb_exit, otherwise it will return failure.
Exiting will clear the previous configuration of the module’s common video buffer pool.
It can be exited repeatedly without returning failure.
Ensure that no VB in the VB pool is occupied before exiting the VB pool, otherwise it cannot be exited.

Example:

None

Related Topics:

kd_mpi_vb_init_mod_common_pool

2.2 System Binding#

This functional module provides the following APIs:

kd_mpi_sys_bind
kd_mpi_sys_unbind Description:et_bind_by_dest](#223-kd_mpi_sys_get_bind_by_dest)

2.2.1 kd_mpi_sys_bind#

Description:

Interface for binding data source to data receiver.

Syntax:

k_s32 kd_mpi_sys_bind(k_mpp_chn *src_chn, k_mpp_chn *dest_chn);

Parameters:

Parameter Name	Description	Input/Output
src_chn	Pointer to source channel.	Input
dest_chn	Pointer to destination channel.	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h
Library file: libsys.a

Notes:

For the currently supported binding relationships, please refer to Table 1-1.
A single data receiver can only bind to one data source.
Binding refers to establishing an association between the data source and the data receiver. After binding, the data generated by the data source will be automatically sent to the receiver.

Example:

None

Related Topics:

Description:ind](#222-kd_mpi_sys_unbind)

2.2.2 kd_mpi_sys_unbind#

Description:

Interface for unbinding data source from data receiver.

Syntax:

k_s32 kd_mpi_sys_unbind(k_mpp_chn *src_chn, k_mpp_chn *dest_chn);

Parameters:

Parameter Name	Description	Input/Output
src_chn	Pointer to source channel.	Input
dest_chn	Pointer to destination channel.	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h
Library file: libsys.a

Notes:

If the destination channel cannot find the bound source channel, it will return success directly. If it finds the bound source channel but it does not match the provided source channel, it will return failure.

Example:

None

Related Topics:

Description:d](#221-kd_mpi_sys_bind)

2.2.3 kd_mpi_sys_get_bind_by_dest#

Description:

Get information about the source channel bound to this destination channel.

Syntax:

k_s32 kd_mpi_sys_get_bind_by_dest(k_mpp_chn *dest_chn, k_mpp_chn *src_chn);

Parameters:

Parameter Name	Description	Input/Output
src_chn	Pointer to source channel.	Output
dest_chn	Pointer to destination channel.	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h
Library file: libsys.a

Notes:

None

Example:

None

Related Topics:

kd_mpi_sys_bind
kd_mpi_sys_unbind

2.3 Log Management#

This functional module provides the following APIs:

kd_mpi_log_set_level_conf
kd_mpi_log_get_level_conf
kd_mpi_log_set_wait_flag
kd_mpi_log_read
kd_mpi_log_close
kd_mpi_log_set_console Description:et_console](#237-kd_mpi_log_get_console)

2.3.1 kd_mpi_log_set_level_conf#

Description:

Set the log level.

Syntax:

k_s32 kd_mpi_log_set_level_conf(const k_log_level_conf *conf);

Parameters:

Parameter Name	Description	Input/Output
conf	Log level information structure.	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h k_log_comm.h
Library file: libsys.a

Notes:

When the mod_name member in conf is set to the string “all”, it will set the log level for all modules. Otherwise, it will only set the log level for the module specified by mod_id.

Example:

None

Related Topics:

Description:_level_conf](#232-kd_mpi_log_get_level_conf)

2.3.2 kd_mpi_log_get_level_conf#

Description:

Get the log level.

Syntax:

k_s32 kd_mpi_log_get_level_conf(k_log_level_conf *conf);

Parameters:

Parameter Name	Description	Input/Output
conf->mod_id	Module ID for which to get the log level.	Input
conf->level	Retrieved log level	Output
conf->mod_name	Module name	Output

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h k_log_comm.h
Library file: libsys.a

Notes:

None

Example:

None

Related Topics:

Description:_level_conf](#231-kd_mpi_log_set_level_conf)

2.3.3 kd_mpi_log_set_wait_flag#

Description:

Set the wait flag when reading logs.

Syntax:

k_s32 kd_mpi_log_set_wait_flag(k_bool is_wait);

Parameters:

Parameter Name	Description	Input/Output
is_wait	Wait flag when reading logs.	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h k_log_comm.h
Library file: libsys.a

Notes:

None

Example:

None

Related Topics:

Description:

2.3.4 kd_mpi_log_read#

Description:

Read logs.

Syntax:

k_s32 kd_mpi_log_read(k_char *buf, k_u32 size);

Parameters:

Parameter Name	Description	Input/Output
buf	Memory pointer to store the logs.	Output
size	Size of the logs to read.	Input

Return Values:

Return Value	Description
Greater than or equal to 0	Size of the successfully read logs.

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h k_log_comm.h
Library file: libsys.a

Notes:

None

Example:

None

Related Topics:

Description:

2.3.5 kd_mpi_log_close#

Description:

Close the log file.

Syntax:

void kd_mpi_log_close(void);

Parameters:

None

Return Values:

None

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h k_log_comm.h
Library file: libsys.a

Notes:

None

Example:

None

Related Topics:

Description:

2.3.6 kd_mpi_log_set_console#

Description:

Configure whether the logs are printed directly through the console.

Syntax:

k_s32 kd_mpi_log_set_console(k_bool is_console);

Parameters:

Parameter Name	Description	Input/Output
is_console	Whether to print through the console	Input

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h k_log_comm.h
Library file: libsys.a

Notes:

None

Example:

None

Related Topics:

Description:_console](#237-kd_mpi_log_get_console)

2.3.7 kd_mpi_log_get_console#

Description:

Get whether the logs are printed directly through the console.

Syntax:

k_s32 kd_mpi_log_get_console(k_bool is_console);

Parameters:

Parameter Name	Description	Input/Output
is_console	Whether to print through the console	Output

Return Values:

Return Value	Description
0	Success
Non-0	Failure, see Error Codes for details

Chip Differences:

None

Requirements:

Header file: mpi_sys_api.h k_module.h k_log_comm.h
Library file: libsys.a

Notes:

None

Example:

None

Related Topics:

kd_mpi_log_set_console

3. Data Types#

3.1 Common Data Types#

This module has the following data types:

k_mod_id Description:312-k_mpp_chn)

3.1.1 k_mod_id#

Description:

Defines the module ID enumeration type. Definition:

typedef enum {

K_ID_CMPI = 0, /*< Common module platform interface */

K_ID_LOG = 1, /*< MPI device log */

K_ID_MMZ = 2, /*< Media memory zone */

K_ID_MMZ_USER_DEV = 3, /*< Media memory zone user used */

K_ID_VB = 4, /*< Video buffer device */

K_ID_SYS = 5, /*< System control device */

K_ID_VI = 6, /*< Video input device */

K_ID_VPROC = 7, /*< Video processing device */

K_ID_VREC = 8, /*< Video recognition device */

K_ID_VENC = 9, /*< Video encoding device */

K_ID_VDEC = 10, /*< Video decoding device */

K_ID_VO = 11, /*< Video output device */

K_ID_AI = 12, /*< Audio input device */

K_ID_AREC = 13, /*< Audio recognition device */

K_ID_AENC = 14, /*< Audio encoding device */

K_ID_ADEC = 15, /*< Audio decoding device */

K_ID_AO = 16, /*< Audio output device */

K_ID_DPU = 17, /*< Depth Processing Unit */

K_ID_V_VI, /*< Virtual video input device */

K_ID_V_VO, /*< Virtual video output device */

K_ID_DMA, /*< DMA device */

K_ID_BUTT, /*< Invalid */

} k_mod_id;

Notes:

None

Related Data Types and Interfaces:

Description:

3.1.2 k_mpp_chn#

Description:

Defines the module ID enumeration type.

Definition:

typedef struct {

k_mod_id mod_id; /*< Module ID */

k_s32 dev_id; /*< Device ID */

k_s32 chn_id; /*< Channel ID */

} k_mpp_chn;

Members:

Member Name	Description
mod_id	Module ID
dev_id	Device ID
chn_id	Channel ID

Notes:

None

Related Data Types and Interfaces:

kd_mpi_sys_bind
kd_mpi_sys_unbind
kd_mpi_sys_get_bind_by_dest

3.2 Multimedia Memory Management#

This module has the following data types:

VB_MAX_POOLS
k_vb_uid
k_vb_config
k_vb_pool_config
k_vb_remap_mode Description:ent_config](#326-k_vb_supplement_config)

3.2.1 VB_MAX_POOLS#

Description:

Maximum number of video buffer pools.

Definition:

#define VB_SINGLE_MAX_BLKS 256

Notes:

None

Related Data Types and Interfaces:

Description:

3.2.2 k_vb_uid#

Description:

Defines the module ID enumeration type.

Definition:

typedef enum {

VB_UID_VI = 0,

VB_UID_VPROC = 1,

VB_UID_VREC = 2,

VB_UID_VENC = 3,

VB_UID_VDEC = 4,

VB_UID_VO = 5,

VB_UID_USER = 6,

VB_UID_AI = 7,

VB_UID_AREC = 8,

VB_UID_AENC = 9,

VB_UID_ADEC = 10,

VB_UID_AO = 11,

VB_UID_V_VI = 12,

VB_UID_V_VO = 13,

VB_UID_DMA = 14,

VB_UID_BUTT = 15,

} k_vb_uid;

Notes:

None

Related Data Types and Interfaces:

Description:

3.2.3 k_vb_config#

Description:

Defines the video buffer pool attribute structure.

Definition:

typedef struct {

k_u32 max_pool_cnt;

k_vb_pool_config comm_pool[VB_MAX_COMM_POOLS];

} k_vb_config;

Members:

Member Name	Description
max_pool_cnt	Number of buffer pools that can be accommodated in the system.
comm_pool	Public buffer pool attribute structure.

Notes:

If blk_size is 0 or blk_cnt is 0, the corresponding buffer pool will not be created.
It is recommended to memset the entire structure to 0 before assigning values as needed.

Related Data Types and Interfaces:

Description:_config

3.2.4 k_vb_pool_config#

Description:

Defines the video buffer pool attribute structure.

Definition:

typedef struct

{

k_u64 blk_size; /*< Size of each VB block*/

k_u32 blk_cnt; /*< Number of blocks*/

k_vb_remap_mode mode; /*< Mapping mode of the kernel mode virtual addresses of the VB*/

char mmz_name[MAX_MMZ_NAME_LEN];/*< Name of the MMZ that allocates the memory for the current VB pool*/

} k_vb_pool_config;

Members:

Member Name	Description
blk_size	Size of each buffer block in bytes.
blk_cnt	Number of buffer blocks in each buffer pool.
mode	Kernel mode virtual address mapping mode of the VB
mmz_name	Name of the MMZ from which the current buffer pool allocates memory.

Notes:

The size of each buffer block blk_size should be calculated based on the current image width, pixel format, data bit width, whether it is compressed, etc.
The buffer pool is allocated from the free MMZ memory, and a buffer pool contains several buffer blocks of the same size. If the size of the buffer pool exceeds the free space in the reserved memory, the creation of the buffer pool will fail.
The user must ensure that the input DDR name already exists. If the input DDR name does not exist, memory allocation will fail. If the mmz_name array is memset to 0, it means that the buffer pool is created in unnamed DDR.

Related Data Types and Interfaces:

kd_mpi_vb_set_config Description:eate_pool](#2113-kd_mpi_vb_create_pool)

3.2.5 k_vb_remap_mode#

Description:

Defines the VB kernel mode virtual address mapping mode.

Definition:

typedef enum {

VB_REMAP_MODE_NONE = 0, /*< No remap */

VB_REMAP_MODE_NOCACHE = 1, /*< No cache remap */

VB_REMAP_MODE_CACHED = 2, /*< Cache remap, if you use this mode, you should flush cache by yourself */

VB_REMAP_MODE_BUTT

} k_vb_remap_mode;

Members:

Member Name	Description
VB_REMAP_MODE_NONE	No remap.
VB_REMAP_MODE_NOCACHE	No cache remap.
VB_REMAP_MODE_CACHED	Cache remap.

Notes:

None

Related Data Types and Interfaces:

Description:

3.2.6 k_vb_supplement_config#

Description:

Defines the VB supplementary information structure.

Definition:

typedef struct

{

k_u32 supplement_config; /*< Control of the auxiliary information*/

} k_vb_supplement_config;

Members:

Member Name	Description
supplement_config	Auxiliary information control

Notes:

Currently supports two types of supplementary information. For details, please refer to the description of the interface kd_mpi_vb_set_supplement_config.

Related Data Types and Interfaces:

kd_mpi_vb_set_supplement_config
kd_mpi_vb_get_supplement_config

3.3 Common Video Data Types#

This module has the following data types:

k_video_frame_info
k_video_frame
k_video_supplement
k_isp_frame_info
k_jpeg_dcf
k_isp_dcf_info
k_isp_dcf_update_info
k_isp_dcf_const_info
k_compress_mode
k_color_gamut
k_dynamic_range
k_video_format
k_video_field

Description:at](#3314-k_pixel_format)

3.3.1 k_video_frame_info#

Description:

Defines the video frame information structure.

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;

Members:

Member Name	Description
v_frame	Video picture frame.
pool_id	Video buffer pool ID.
mod_id	Logical unit that generated the current frame data.

Notes:

Currently supports two types of supplementary information. For details, please refer to the description of the interface kd_mpi_vb_set_supplement_config.

Related Data Types and Interfaces:

Description:(#332-k_video_frame)

3.3.2 k_video_frame#

Description:

Defines the video frame information structure.

Definition:

typedef struct {

k_u32 width; /*< Picture width */

k_u32 height; /*< Picture height */

k_video_field field; /*< Video frame field*/

k_pixel_format pixel_format; /*< Pixel format of a picture */

k_video_format video_format;

k_dynamic_range dynamic_range;

k_compress_mode compress_mode;

k_color_gamut color_gamut;

k_u32 header_stride[3];

k_u32 stride[3];

k_u64 header_phys_addr[3];

k_u64 header_virt_addr[3];

k_u64 phys_addr[3];

k_u64 virt_addr[3];

k_s16 offset_top; /* Top offset of show area */

k_s16 offset_bottom; /* Bottom offset of show area */

k_s16 offset_left; /* Left offset of show area */

k_s16 offset_right; /* Right offset of show area */

k_u32 time_ref;

k_u64 pts;

k_u64 priv_data;

k_video_supplement supplement; /*< Supplementary information about images */

} k_video_frame;

Members:

Member Name	Description
width	Picture width
height	Picture height
field	Frame field mode
pixel_format	Pixel format of the video picture
video_format	Video format of the picture
dynamic_range	Dynamic range
compress_mode	Video compression mode
color_gamut	Color gamut range
header_stride	Stride of the compressed header
stride	Stride of the image data
header_phys_addr	Physical address of the compressed header
header_virt_addr	Virtual address of the compressed header (kernel mode virtual address)
phys_addr	Physical address of the image data
virt_addr	Virtual address of the image data (kernel mode virtual address)
offset_top	Top cropping width of the image
offset_bottom	Bottom cropping width of the image
offset_left	Left cropping width of the image
offset_right	Right cropping width of the image
time_ref	Frame sequence number
pts	Image timestamp
priv_data	Private data
supplement	Supplementary information about the image

Notes:

None

Related Data Types and Interfaces:

Description:

3.3.3 k_video_supplement#

Description:

Defines the supplementary information for video frames.

Definition:

typedef struct {

k_u64 jpeg_dcf_phy_addr;

k_u64 isp_info_phy_addr;

void  jpeg_dcf_kvirt_addr; /*< jpeg_dcf, used in JPEG DCF */

void isp_info_kvirt_addr; /*< isp_frame_info, used in ISP debug, when get raw and send raw */

} k_video_supplement;

Members:

Member Name	Description
jpeg_dcf_phy_addr	Physical address of JPEG DCF information.
isp_info_phy_addr	Physical address of ISP auxiliary information.
jpeg_dcf_kvirt_addr	Virtual address of JPEG DCF information (kernel mode virtual address)
isp_info_kvirt_addr	Virtual address of ISP auxiliary information (kernel mode virtual address)

Notes:

None

Related Data Types and Interfaces:

Description:(#332-k_video_frame)

3.3.4 k_isp_frame_info#

Description:

Real-time information of the ISP. Definition:

typedef struct {

k_u32 iso; /*< ISP internal ISO : again\*dgain\*is_pgain */

k_u32 exposure_time; /*< exposure time (reciprocal of shutter speed), unit is us */

k_u32 isp_dgain;

k_u32 again;

k_u32 dgain;

k_u32 ratio[3];

k_u32 isp_nr_strength;

k_u32 f_number; /*< the actual F-number (F-stop) of lens when the image was taken */

k_u32 sensor_id; /*< which sensor is used */

k_u32 sensor_mode;

k_u32 hmax_times; /*< sensor hmax_times, unit is ns */

k_u32 vmax; /*< sensor vmax, unit is line */

k_u32 vc_num; /*< when dumping WDR frame, which is long or short exposure frame. */

} k_isp_frame_info;

Members:

Member Name	Description
iso	Current sensor analog gain * sensor digital gain * ISP digital gain * 100.
exposure_time	Exposure time, unit is microseconds (us).
isp_dgain	ISP digital gain.
again	Sensor analog gain.
dgain	Sensor digital gain.
ratio	Default exposure ratio of adjacent frames in multi-frame WDR synthesis.
isp_nr_strength	ISP NR strength. Currently not supported, default value is 0.
f_number	F-number of the current lens used.
sensor_id	Sensor ID currently in use.
sensor_mode	Sequence mode of the current sensor.
hmax_times	Time to read out one line from the current sensor, unit is nanoseconds (ns).
vmax	Number of lines per frame.
vc_num	Sequence number of the current frame.

Notes:

None

Related Data Types and Interfaces:

Description:

3.3.5 k_jpeg_dcf#

Description:

DCF information used in JPEG images.

Definition:

typedef struct {

k_u8 capture_time[DCF_CAPTURE_TIME_LENGTH]; /*< the date and time when the picture data was generated */

k_u32 flash; /*< whether the picture is captured when a flash lamp is on */

k_u32 digital_zoom_ratio; /*< indicates the digital zoom ratio when the image was shot. If the numerator of the recorded value is 0, this indicates that digital zoom was not used. */

k_isp_dcf_info isp_dcf_info;

} k_jpeg_dcf;

Members:

Member Name	Description
capture_time	Time the JPEG image was captured.
flash	Whether a flash was used when capturing the JPEG image.
digital_zoom_ratio	Digital zoom ratio when capturing the JPEG image.
isp_dcf_info	Other DCF information.

Notes:

None

Related Data Types and Interfaces:

None

3.3.6 k_isp_dcf_info#

Detailed information for this data type is not updated in the current version.

3.3.7 k_isp_dcf_update_info#

Detailed information for this data type is not updated in the current version.

3.3.8 k_isp_dcf_const_info#

Description:ation for this data type is not updated in the current version.

3.3.9 k_compress_mode#

Description:

Defines the structure for video compression data format.

Definition:

typedef enum {

COMPRESS_MODE_NONE = 0, /* no compress */

COMPRESS_MODE_SEG, /* compress unit is 256x1 bytes as a segment. */

COMPRESS_MODE_TILE, /* compress unit is a tile. */

COMPRESS_MODE_LINE, /* compress unit is the whole line. raw for VI */

COMPRESS_MODE_FRAME, /* compress unit is the whole frame. YUV for VI, RGB for VO (read) */

COMPRESS_MODE_BUTT

} k_compress_mode;

Members:

Member Name	Description
COMPRESS_MODE_NONE	Uncompressed video format.
COMPRESS_MODE_SEG	Segment compressed video format.
COMPRESS_MODE_TILE	Tile compressed video format, compressed by tile segments.
COMPRESS_MODE_LINE	Line compressed video format, compressed by lines.
COMPRESS_MODE_FRAME	Frame compressed video format, compressed by frames.

Notes:

None

Related Data Types and Interfaces:

Description:

3.3.10 k_color_gamut#

Description:

Defines the color gamut range enumeration.

Definition:

typedef enum {

COLOR_GAMUT_BT601 = 0,

COLOR_GAMUT_BT709,

COLOR_GAMUT_BT2020,

COLOR_GAMUT_USER,

COLOR_GAMUT_BUTT

} k_color_gamut;

Members:

Member Name	Description
COLOR_GAMUT_BT601	BT601 color gamut range.
COLOR_GAMUT_BT709	BT709 color gamut range.
COLOR_GAMUT_BT2020	BT2020 color gamut range.
COLOR_GAMUT_USER	User-defined color gamut, non-standard.

Notes:

The coordinates of the blue, green, red, and white points for each color gamut range are as follows:

Color Gamut	Primary
	Green	Blue	Red	White
BT601	(0.29, 0.60)	(0.15, 0.06)	(0.64, 0.33)	(0.3127, 0.3290)
BT709	(0.300, 0.600)	(0.150, 0.060)	(0.640, 0.330)	(0.3127, 0.3290)
BT2020	(0.170, 0.797)	(0.131, 0.046)	(0.708, 0.292)	(0.3127, 0.3290)

Related Data Types and Interfaces:

Description:

3.3.11 k_dynamic_range#

Description:

Defines the dynamic range enumeration.

Definition:

typedef enum {

DYNAMIC_RANGE_SDR8 = 0,

DYNAMIC_RANGE_SDR10,

DYNAMIC_RANGE_HDR10,

DYNAMIC_RANGE_HLG,

DYNAMIC_RANGE_SLF,

DYNAMIC_RANGE_XDR,

DYNAMIC_RANGE_BUTT

} k_dynamic_range;

Members:

Member Name	Description
DYNAMIC_RANGE_SDR8	Standard dynamic range for 8-bit data.
DYNAMIC_RANGE_SDR10	Standard dynamic range for 10-bit data.
DYNAMIC_RANGE_HDR10	High dynamic range for 10-bit data.
DYNAMIC_RANGE_HLG	High dynamic range for 10-bit data.
DYNAMIC_RANGE_SLF	Invalid
DYNAMIC_RANGE_XDR	Invalid

Notes:

The transfer characteristics for each dynamic range are as follows:

Dynamic Range	Transfer Characteristic
SDR8/ SDR10	V = α * Lc^0.45 - (α - 1) for 1 >= Lc >= β V = 4.500 * Lc for β > Lc >= 0
HDR10	V = ((c1 + c2 * Lc^n) ÷ (1 + c3 * Lc^n))^m for all values of Lc c1 = c3 - c2 + 1 = 3424 ÷ 4096 = 0.8359375 c2 = 32 * 2413 ÷ 4096 = 18.8515625 c3 = 32 * 2392 ÷ 4096 = 18.6875 m = 128 * 2523 ÷ 4096 = 78.84375 n = 0.25 * 2610 ÷ 4096 = 0.1593017578125 for which Lc equal to 1 for peak white is ordinarily intended to correspond to a reference output luminance level of 10000 candelas per square metre
HLG	V = a * Ln(12 * Lc - b) + c for 1 >= Lc > 1 ÷ 12 V = Sqrt(3) * Lc^0.5 for 1 ÷ 12 >= Lc >= 0 a = 0.17883277, b = 0.28466892, c = 0.55991073

Related Data Types and Interfaces:

Description:

3.3.12 k_video_format#

Description:

Defines the video format structure.

Definition:

typedef enum {

VIDEO_FORMAT_LINEAR = 0, /* natural video line */

VIDEO_FORMAT_TILE_64x16, /* tile cell: 64pixel x 16line */

VIDEO_FORMAT_TILE_16x8, /* tile cell: 16pixel x 8line */

VIDEO_FORMAT_LINEAR_DISCRETE, /* The data bits are aligned in bytes */

VIDEO_FORMAT_BUTT

} k_video_format;

Members:

Member Name	Description
VIDEO_FORMAT_LINEAR	Linear storage video format.
VIDEO_FORMAT_TILE_64x16	Tile format video storage, where the tile block size is 64 pixels wide and 16 lines high.
VIDEO_FORMAT_TILE_16x8	Tile format video storage, where the tile block size is 16 pixels wide and 8 lines high, also known as small tile format.
VIDEO_FORMAT_LINEAR_DISCRETE	Linear discrete natural line storage data format, data bit width aligned in bytes, low bits valid, high bits invalid.

Notes:

None

Related Data Types and Interfaces:

Description:

3.3.13 k_video_field#

Description:

Defines the video image frame field type.

Definition:

typedef enum {

VIDEO_FIELD_TOP = 0x1, /* even field */

VIDEO_FIELD_BOTTOM = 0x2, /* odd field */

VIDEO_FIELD_INTERLACED = 0x3, /* two interlaced fields */

VIDEO_FIELD_FRAME = 0x4, /* frame */

VIDEO_FIELD_BUTT

} k_video_field;

Members:

Member Name	Description
VIDEO_FIELD_TOP	Top field type
VIDEO_FIELD_BOTTOM	Bottom field type
VIDEO_FIELD_INTERLACED	Interlaced field type
VIDEO_FIELD_FRAME	Frame type

Notes:

None

Related Data Types and Interfaces:

Description:(#332-k_video_frame)

3.3.14 k_pixel_format#

Description:

Defines the pixel format types.

Definition:

typedef enum {

PIXEL_FORMAT_RGB_444 = 0,

PIXEL_FORMAT_RGB_555,

PIXEL_FORMAT_RGB_565,

PIXEL_FORMAT_RGB_888,

PIXEL_FORMAT_BGR_444,

PIXEL_FORMAT_BGR_555,

PIXEL_FORMAT_BGR_565,

PIXEL_FORMAT_BGR_888,

PIXEL_FORMAT_ARGB_1555,

PIXEL_FORMAT_ARGB_4444,

PIXEL_FORMAT_ARGB_8565,

PIXEL_FORMAT_ARGB_8888,

PIXEL_FORMAT_ARGB_2BPP,

PIXEL_FORMAT_ABGR_1555,

PIXEL_FORMAT_ABGR_4444,

PIXEL_FORMAT_ABGR_8565,

PIXEL_FORMAT_ABGR_8888,

PIXEL_FORMAT_RGB_MONOCHROME_8BPP,

PIXEL_FORMAT_RGB_BAYER_8BPP,

PIXEL_FORMAT_RGB_BAYER_10BPP,

PIXEL_FORMAT_RGB_BAYER_12BPP,

PIXEL_FORMAT_RGB_BAYER_14BPP,

PIXEL_FORMAT_RGB_BAYER_16BPP,

PIXEL_FORMAT_YVU_PLANAR_422,

PIXEL_FORMAT_YVU_PLANAR_420,

PIXEL_FORMAT_YVU_PLANAR_444,

PIXEL_FORMAT_YVU_SEMIPLANAR_422,

PIXEL_FORMAT_YVU_SEMIPLANAR_420,

PIXEL_FORMAT_YVU_SEMIPLANAR_444,

PIXEL_FORMAT_YUV_SEMIPLANAR_422,

PIXEL_FORMAT_YUV_SEMIPLANAR_420,

PIXEL_FORMAT_YUV_SEMIPLANAR_444,

PIXEL_FORMAT_YUYV_PACKAGE_422,

PIXEL_FORMAT_YVYU_PACKAGE_422,

PIXEL_FORMAT_UYVY_PACKAGE_422,

PIXEL_FORMAT_VYUY_PACKAGE_422,

PIXEL_FORMAT_YYUV_PACKAGE_422,

PIXEL_FORMAT_YYVU_PACKAGE_422,

PIXEL_FORMAT_UVYY_PACKAGE_422,

PIXEL_FORMAT_VUYY_PACKAGE_422,

PIXEL_FORMAT_VY1UY0_PACKAGE_422,

PIXEL_FORMAT_YUV_400,

PIXEL_FORMAT_UV_420,

/* SVP data format */

PIXEL_FORMAT_BGR_888_PLANAR,

PIXEL_FORMAT_HSV_888_PACKAGE,

PIXEL_FORMAT_HSV_888_PLANAR,

PIXEL_FORMAT_LAB_888_PACKAGE,

PIXEL_FORMAT_LAB_888_PLANAR,

PIXEL_FORMAT_S8C1,

PIXEL_FORMAT_S8C2_PACKAGE,

PIXEL_FORMAT_S8C2_PLANAR,

PIXEL_FORMAT_S8C3_PLANAR,

PIXEL_FORMAT_S16C1,

PIXEL_FORMAT_U8C1,

PIXEL_FORMAT_U16C1,

PIXEL_FORMAT_S32C1,

PIXEL_FORMAT_U32C1,

PIXEL_FORMAT_U64C1,

PIXEL_FORMAT_S64C1,

PIXEL_FORMAT_BUTT

} k_pixel_format;

Members:

None

Notes:

None

Related Data Types and Interfaces:

Omitted

3.4 Multimedia Log Management#

This module has the following data structures:

Description:conf](#341-k_log_level_conf)

3.4.1 k_log_level_conf#

Description:

Defines the log level information structure. Definition:

typedef struct {

k_mod_id mod_id;

k_s32 level;

k_char mod_name[16];

} k_log_level_conf;

Members:

Member Name	Description
mod_id	ID of the module
level	Log level
mod_name	Name of the module

Notes:

None

Related Data Types and Interfaces:

kd_mpi_log_set_level_conf
kd_mpi_log_get_level_conf

4. Error Codes#

4.1 Multimedia Memory Management Error Codes#

4.1.1 Video Buffer Pool Error Codes#

Table 41

Error Code	Macro Definition	Description
0xa0048006	K_ERR_VB_NULL_PTR	Null pointer error
0xa004800c	K_ERR_VB_NOMEM	Memory allocation failure
0xa004800d	K_ERR_VB_NOBUF	Buffer allocation failure
0xa0048005	K_ERR_VB_UNEXIST	Video buffer does not exist
0xa0048003	K_ERR_VB_ILLEGAL_PARAM	Invalid parameter setting
0xa0048010	K_ERR_VB_NOTREADY	Buffer pool not ready
0xa0048012	K_ERR_VB_BUSY	System busy
0xa0048009	K_ERR_VB_NOT_PERM	Operation not permitted
0xa0048040	K_ERR_VB_2MPOOLS	Too many buffer pools created

4.1.2 Multimedia Memory Zone Error Codes#

Table 42

Error Code	Macro Definition	Description
0xa0038003	K_ERR_MMZ_USERDEV_ILLEGAL_PARAM	Minor parameter setting
0xa0038006	K_ERR_MMZ_USERDEV_NULL_PTR	Null pointer error
0xa0038008	K_ERR_MMZ_USERDEV_NOT_SUPPORT	Unsupported operation
0xa0038009	K_ERR_MMZ_USERDEV_NOT_PERM	Operation not permitted
0xa003800c	K_ERR_MMZ_USERDEV_NOMEM	Memory allocation failure
0xa0038010	K_ERR_MMZ_USERDEV_NOTREADY	System not ready
0xa0038011	K_ERR_MMZ_USERDEV_BADADDR	Invalid address
0xa0038012	K_ERR_MMZ_USERDEV_BUSY	System busy

4.2 System Binding Error Codes#

Table 43

Error Code	Macro Definition	Description
0xa0058003	K_ERR_SYS_ILLEGAL_PARAM	Invalid parameter
0xa0058006	K_ERR_SYS_NULL_PTR	Null pointer error
0xa0058008	K_ERR_SYS_NOT_SUPPORT	Unsupported feature
0xa0058009	K_ERR_SYS_NOT_PERM	Operation not permitted
0xa0058010	K_ERR_SYS_NOTREADY	System control attributes not configured
0xa0058011	K_ERR_SYS_BADADDR	System bad address
0xa005800c	K_ERR_SYS_NOMEM	Memory allocation failure, e.g., insufficient system memory

4.3 Log Management Error Codes#

Table 44

Error Code	Macro Definition	Description
0xa0018003	K_ERR_LOG_ILLEGAL_PARAM	Invalid parameter
0xa0018006	K_ERR_LOG_NULL_PTR	Null pointer error
0xa0018009	K_ERR_LOG_NOT_PERM	Operation not permitted
0xa0018010	K_ERR_LOG_NOTREADY	Log device not ready
0xa001800c	K_ERR_LOG_NOMEM	Memory allocation failure, e.g., insufficient system memory

5. Debug Information#

5.1 Overview#

The debug information uses the proc file system, reflecting the current system running status in real-time. The recorded information can be used for problem location and analysis.

File Directory:

/proc/

File List:

File Name	Description
umap/sysbind	Records the current system binding status
umap/vb	Records the current buffer usage of the VB module
mem-media	Records the current multimedia memory usage

5.2 Multimedia Memory Management#

5.2.1 Video Buffer Pool Debug Information#

Debug Information:

-----VB PUB CONFIG--------------------------------------------------------------
MaxPoolCnt
        10
-----VB SUPPLEMENT ATTR---------------------------------------------------------
Config  Size    VbCnt
1       204     21
-----COMMON POOL CONFIG---------------------------------------------------------
PoolConfId        BlkSize           Count   RemapMode
0                 8294400           5       CACHED
1                 8192              3       NONE
2                 4096              5       NOCACHE
-----MODULE COMMON MOD POOL CONFIG of [2]---------------------------------------
PoolConfId        BlkSize           Count   RemapMode
0                 4096              5       CACHED
1                 8192              3       NONE

-------------------------------------------------------------------------------------
 PoolId  PhysAddr            VirtAddr            IsComm  Owner  BlkSz     BlkCnt  Free    MinFree
0       0x18001000          0xc00d1000          1       -1     8294400   5       2       2
BLK   VI    VENC  VDEC  VO    USER  AI    AREC  AENC  ADEC  AO    V_VI  V_VO  DMA   DPU
0     0     0     0     0     1     0     0     0     0     0     0     0     0     0
1     0     0     0     0     1     0     0     0     0     0     0     0     0     0
2     0     0     0     0     1     0     0     0     0     0     0     0     0     0
Sum   0     0     0     0     3     0     0     0     0     0     0     0     0     0

-------------------------------------------------------------------------------------
 PoolId  PhysAddr            VirtAddr            IsComm  Owner  BlkSz     BlkCnt  Free    MinFree
1       0x1a78f000          0x0                 1       -1     8192      3       3       3

-------------------------------------------------------------------------------------
 PoolId  PhysAddr            VirtAddr            IsComm  Owner  BlkSz     BlkCnt  Free    MinFree
2       0x1a796000          0xc2860000          1       -1     4096      5       5       5

-------------------------------------------------------------------------------------
 PoolId  PhysAddr            VirtAddr            IsComm  Owner  BlkSz     BlkCnt  Free    MinFree
3       0x1a79c000          0xc2866000          1       2      4096      5       5       5

-------------------------------------------------------------------------------------
 PoolId  PhysAddr            VirtAddr            IsComm  Owner  BlkSz     BlkCnt  Free    MinFree
4       0x1a7a2000          0x0                 1       2      8192      3       3       3

Debug Information Analysis:

Records the current block usage of the VB module.

Parameter Description:

Parameter	Description
VB PUB CONFIG	MaxPoolCnt	Maximum number of buffer pools.
VB SUPPLEMENT ATTR	Config	Configuration of supplementary information for video frames.
	Size	Memory space occupied by supplementary information for video frames.
	VbCnt	Total number of VB blocks in all VB pools (common, private).
COMMON POOL CONFIG	PoolId	Handle of the common buffer pool.
	Size	Size of blocks in the buffer pool.
	Count	Number of blocks in the buffer pool.
MODULE COMMON POOL CONFIG of VB_UID (Common VB allocated by module)	PoolId	Handle of the common buffer pool.
	Size	Size of blocks in the buffer pool.
	Count	Number of blocks in the buffer pool.
NULL (empty table, i.e., anonymous DDR)	PoolId	Handle of the common/private buffer pool.
	PhysAddr	Starting physical address of the common/private buffer pool.
	VirtAddr	Starting virtual address of the common/private buffer pool.
	IsComm	Whether it is a common buffer pool. Values: {0, 1}.
	Owner	Owner of the buffer pool. -2: Private pool. -1: Common pool. ≥0: Module VB.
	BlkSz	Size of blocks in the buffer pool.
	BlkCnt	Number of blocks in the buffer pool.
	Free	Number of free blocks in the buffer pool.
	MinFree	Minimum number of free blocks remaining since the program started. If this count is 0, it may indicate frame drops due to insufficient blocks.
	BLK	Handle of the blocks in the buffer pool.
	VI/VPROC/VREC/VENC/VDEC/VO/USER/AI/AREC/AENC/ADEC/AO/V_VI/V_VO/DMA/DPU	Module name. The number below indicates how many places in the current module occupy the block in the buffer pool. 0: Not occupied. Non-0: Number of times occupied.

5.2.2 Multimedia Memory Zone Debug Information#

Debug Information:

msh /bin>cat /proc/media-mem

+---ZONE: PHYS(0x18000000, 0x1FEFFFFF), GFP=0, nBYTES=130048KB,    NAME="anonymous"
   |-MMB: phys(0x18000000, 0x18000FFF), kvirt=0xC00D0000, flags=0x00000001, length=4KB,    name="sup_nc"
   |-MMB: phys(0x18001000, 0x1A78DFFF), kvirt=0xC00D1000, flags=0x00000003, length=40500KB,    name="vb_pool"
   |-MMB: phys(0x1A78E000, 0x1A78EFFF), kvirt=0xC285E000, flags=0x00000001, length=4KB,    name="sup_nc"
   |-MMB: phys(0x1A78F000, 0x1A794FFF), kvirt=0x00000000, flags=0x00000000, length=24KB,    name="vb_pool"
   |-MMB: phys(0x1A795000, 0x1A795FFF), kvirt=0xC285F000, flags=0x00000001, length=4KB,    name="sup_nc"
   |-MMB: phys(0x1A796000, 0x1A79AFFF), kvirt=0xC2860000, flags=0x00000001, length=20KB,    name="vb_pool"
   |-MMB: phys(0x1A79B000, 0x1A79BFFF), kvirt=0xC2865000, flags=0x00000001, length=4KB,    name="sup_nc"
   |-MMB: phys(0x1A79C000, 0x1A7A0FFF), kvirt=0xC2866000, flags=0x00000003, length=20KB,    name="vb_mod_pool"
   |-MMB: phys(0x1A7A1000, 0x1A7A1FFF), kvirt=0xC286B000, flags=0x00000001, length=4KB,    name="sup_nc"
   |-MMB: phys(0x1A7A2000, 0x1A7A7FFF), kvirt=0x00000000, flags=0x00000000, length=24KB,    name="vb_mod_pool"

---MMZ_USE_INFO:
 total size=130048KB(127MB),used=40608KB(39MB + 672KB),remain=89440KB(87MB + 352KB),zone_number=1,block_number=10

Debug Information Analysis:

Records the current usage of multimedia memory.

Parameter Description:

None

5.3 System Binding#

5.3.1 System Binding Debug Information#

Debug Information:

msh /bin>cat /proc/umap/sysbind

-----BIND RELATION TABLE--------------------------------------------------------

FirMod FirDev FirChn SecMod SecDev SecChn ThrMod ThrDev ThrChn SendCnt rstCnt

vvi 0 0 vvo 0 0 null 0 0 42 0

vvi 0 0 vvo 1 1 null 0 0 42 0

Debug Information Analysis:

Records the current system binding status.

Parameter Description:

Parameter	Description
FirMod	Module number of the data source
FirDev	Device number of the data source
FirChn	Channel number of the data source
SecMod	Module number of the second module (bound to the data source)
SecDev	Device number of the second module (bound to the data source)
SecChn	Channel number of the second module (bound to the data source)
ThrMod	Module number of the third module (bound to the second module)
ThrDev	Device number of the third module (bound to the second module)
ThrChn	Channel number of the third module (bound to the second module)
SendCnt	Number of times data is sent
RstCnt	Number of resets

K230 System Control API Reference

Contents

K230 System Control API Reference#

Preface#

Overview#

Audience#

Abbreviation Definitions#

Revision History#

1. Overview#

1.1 Overview#

1.2 Function Description#

1.2.1 Video Buffer Pool#

1.2.2 System Binding#

2. API Reference#

2.1 Multimedia Memory Management#

2.1.1 kd_mpi_sys_mmz_alloc#

2.1.2 kd_mpi_sys_mmz_alloc_cached#

2.1.3 kd_mpi_sys_mmap#

2.1.4 kd_mpi_sys_mmap_cached#

2.1.5 kd_mpi_sys_munmap#

2.1.6 kd_mpi_sys_mmz_flush_cache#

2.1.7 kd_mpi_sys_mmz_free#

2.1.8 kd_mpi_sys_get_virmem_info#

2.1.9 kd_mpi_vb_set_config#

2.1.10 kd_mpi_vb_get_config#

2.1.11 kd_mpi_vb_init#

2.1.12 kd_mpi_vb_exit#

2.1.13 kd_mpi_vb_create_pool#

2.1.14 kd_mpi_vb_destory_pool#

2.1.15 kd_mpi_vb_get_block#

2.1.16 kd_mpi_vb_release_block#

2.1.17 kd_mpi_vb_phyaddr_to_handle#

2.1.18 kd_mpi_vb_handle_to_phyaddr#

2.1.19 kd_mpi_vb_handle_to_pool_id#

2.1.20 kd_mpi_vb_inquire_user_cnt#

2.1.21 kd_mpi_vb_get_supplement_attr#

2.1.22 kd_mpi_vb_set_supplement_config#

2.1.23 kd_mpi_vb_get_supplement_config#

2.1.24 kd_mpi_vb_set_mod_pool_config#

2.1.25 kd_mpi_vb_get_mod_pool_config#

2.1.26 kd_mpi_vb_init_mod_common_pool#

2.1.27 kd_mpi_vb_exit_mod_common_pool#

2.2 System Binding#

2.2.1 kd_mpi_sys_bind#

2.2.2 kd_mpi_sys_unbind#

2.2.3 kd_mpi_sys_get_bind_by_dest#

2.3 Log Management#

2.3.1 kd_mpi_log_set_level_conf#

2.3.2 kd_mpi_log_get_level_conf#

2.3.3 kd_mpi_log_set_wait_flag#

2.3.4 kd_mpi_log_read#

2.3.5 kd_mpi_log_close#

2.3.6 kd_mpi_log_set_console#

2.3.7 kd_mpi_log_get_console#

3. Data Types#

3.1 Common Data Types#

3.1.1 k_mod_id#

3.1.2 k_mpp_chn#

3.2 Multimedia Memory Management#

3.2.1 VB_MAX_POOLS#

3.2.2 k_vb_uid#

3.2.3 k_vb_config#

3.2.4 k_vb_pool_config#

3.2.5 k_vb_remap_mode#

3.2.6 k_vb_supplement_config#

3.3 Common Video Data Types#

3.3.1 k_video_frame_info#

3.3.2 k_video_frame#

3.3.3 k_video_supplement#

3.3.4 k_isp_frame_info#

3.3.5 k_jpeg_dcf#

3.3.6 k_isp_dcf_info#

3.3.7 k_isp_dcf_update_info#

3.3.8 k_isp_dcf_const_info#

3.3.9 k_compress_mode#

3.3.10 k_color_gamut#

3.3.11 k_dynamic_range#

3.3.12 k_video_format#

3.3.13 k_video_field#

3.3.14 k_pixel_format#