SGL Memory Format Interfaces

(The SGL interfaces are pending temporarily and will be reviewed after the implementation is determined.)

/* SGL buffers, inner details are not cared about by users */
struct wd_sgl;

/* SGL Memory pool creating parameters */
struct wd_sglpool_setup {
__u32 slice_num;/* Total number of SGEs with buffer slices */
__u16 sgl_num;/* Total number of sgl with entries and buffers */
__u16 align_size;/* SGE data buffer startging address align size */
__u32 buf_size;/* memory size of entry buffer */
struct wd_mm_br br;/* memory from user if don't use WD memory */
};

Prototype	void wd_sglpool_create(struct wd_queue q, struct wd_sglpool_setup *setup);
Function	Create an SGL pool based on the specifications and memory provided by the user.
Input Description	q: WD algorithm queue setup: specifications and memory information provided by users
Output Description	setup->slice_num: number of actually created slices, which is output only when the default WD memory is used. When the number is less than 90% of the number required by the user, the SGL pool fails to be created.
Return Value Description	A non-NULL value: success NULL: failure
Usage Instruction	When the WD default memory is used to create the SGL pool, if there are strict requirements on the value of slice_num, set slice_num of setup to 15% higher than the actual requirement. When the external memory is used, you must provide struct wd_mm_ops. ops must meet the memory size requirement for creating the pool, and the dma map and unmap operations must be applicable to the memory. If the direct physical address DMA is used, the physical addresses in the memory must be consecutive.
Precautions	If no memory is specified, the WD reserved memory is used by default to create the pool. When the WD default memory is used to create the pool, slice_num in struct wd_sglpool_setup is an input and output parameter.

Prototype	void wd_sglpool_destroy(void *pool);
Function	Destroy an SGL pool.
Input Description	pool: SGL pool to be destroyed
Output Description	None
Return Value Description	None
Usage Instruction
Precautions

Prototype	struct wd_sgl wd_alloc_sgl(void pool, __u32 size);
Function	Allocate SGL buffers from Warpdrive SGL memory pool.
Input Description	pool: SGL pool size: size of the SGL buffers
Output Description	None
Return Value Description	A non-NULL value: first SGL address of an SGL chain buffer NULL: failure
Usage Instruction	Multiple threads are supported.
Precautions

Prototype	void wd_free_sgl(void pool, struct wd_sgl sgl);
Function	Free an SGL buffers to Warpdrive SGL memory pool.
Input Description	pool: SGL pool sgl: first SGL address of an SGL chain buffer
Output Description	None
Return Value Description	None
Usage Instruction	Multiple threads are supported.
Precautions

Prototype	void wd_sgl_last_entry(struct wd_sgl sgl);
Function	Get the start address of the last entry of SGL.
Input Description	sgl: an SGL chain
Output Description	None
Return Value Description	A non-NULL value: start address of last entry in the SGL NULL: no entry in the SGL
Usage Instruction	Multiple threads are supported.
Precautions

Prototype	void wd_sgl_entry(struct wd_sgl sgl, int num);
Function	Get the start address of the num-th entry of SGL.
Input Description	sgl: an SGL chain Num: entry number. 0 indicates the first one.
Output Description	None
Return Value Description	A non-NULL value: indicates the start address of entry Num in the SGL. NULL: The value of Num exceeds the SGL range.
Usage Instruction	Multiple threads are supported.
Precautions

Prototype	void wd_sgl_iova_map(struct wd_sgl sgl);
Function	Get the IOVA of an SGL buffer.
Input Description	sgl: address of an SGL
Output Description	None
Return Value Description	A non-NULL value: IOVA address of the SGL NULL: mapping failure
Usage Instruction	Multiple threads are supported.
Precautions	This interface is used to support the no-IOMMU and IOMMU-passthrough scenarios.

Prototype	int wd_sgl_entry_bsize(struct wd_sgl sgl, size_t size);
Function	Get the buffer size of an SGL.
Input Description	sgl: address of an SGL
Output Description	size: entry buffer size
Return Value Description	0: success Others: failure
Usage Instruction	Multiple threads are supported.
Precautions	Maintenance and debugging interface

Prototype	int wd_sgl_bsize(struct wd_sgl sgl, size_t size);
Function	Get the total buffer size of an SGL.
Input Description	sgl: address of an SGL
Output Description	size: total buffer size of the SGL
Return Value Description	0: success Others: failure
Usage Instruction	Multiple threads are supported.
Precautions

Prototype	void wd_sgl_iova_unmap(void pool, void sgl_iova, struct wd_sgl *sgl);
Function	Unmap the IOVA of an SGL with the physical address of the SGL.
Input Description	pool: SGL pool sgl_iova: IOVA address of an SGL sgl: address of an SGL
Output Description	None
Return Value Description	None
Usage Instruction	Multiple threads are supported.
Precautions	This interface is used to support the no-IOMMU and IOMMU-passthrough scenarios. No operation is performed in the no-IOMMU mode.

Prototype	int wd_get_free_sgl_num(void *pool);
Function	Get the number of free SGL buffers of the pool.
Input Description	pool: SGL pool
Output Description	None
Return Value Description	Number of free SGL buffers
Usage Instruction	Multiple threads are supported.
Precautions	Maintenance and debugging interface

Prototype	int wd_alloc_sgl_failures(void *pool);
Function	Get the allocation failure times of the pool.
Input Description	pool: SGL pool
Output Description	None
Return Value Description	Number of allocation failure times
Usage Instruction	Multiple threads are supported.
Precautions	Maintenance and debugging interface

Parent topic: WD Data Storage Formats and Memory Interfaces