Queue buffer pool

This GOAL core module provides functions to manage a pool of buffers organized in queues. Single buffers can be taken from top of the queue. The buffers can be read, written or cleared by the application. After processing the buffers are returned at the end of the queue. The buffer handling of a queue is organized as FIFO. Accesses to the queue and the buffers is protected by the GOAL locking mechanism.

Figure: queue buffer handling

It is possible to store buffers to other queues. This method shall only be used in exceptional cases and shall be used very careful.
The function using the queue mechanism is responsible to manage the buffers and for the buffer content. Each buffer has a header for management purposes, described in Chapter: Buffer header.
This module provides the following functions to manage the queue:

Function in goal_queue	Description

Function in goal_queue	Description
goal_queueInit()	create a queue with buffers This function allocates the memory of a specified number of buffers with the same size and assigns the buffers to the queue. It is also possible to create an empty queue without buffers and to add buffers in the state `GOAL_FSA_OPERATION`. In this case the memory for the buffers must be allocated in the state `GOAL_FSA_INIT` by another process. The second argument (max number of elements) has become legacy since GOAL version 2.23.0 and will not be used anymore. It’s just available to keep the API compatible. A queue can now never be full and goal_queueIsFull() returns 0 (queue not full) always.
goal_queuePoolBufsReq()	Initially create free buffers for application specific usage This function has to be called by each user of a pool. It tells the queue buffer pool how many buffers the user requires. There are two paremeters regarding the number of buffers. First parameter defines the number of buffers that are required at any given time. Seconds parameter defines the number of buffers, that may be required temporarily additionally. Those temporarily buffers can be shared between multiple applications. This function is required if the system pools are used (`goal_queueGetNewBuf`).
goal_queueSetReleaseCallback()	specify a callback function buffer-related, which is called by one of the functions `goal_queueRelease*()`
goal_queueGetNewBuf()	take a buffer from the queue and initialize buffer The following buffer properties are initialized, see Chapter: Buffer header: flags: GOAL_QUEUE_FLG_USED dataLen: 0 netPort: GOAL_ETH_PORT_HOST relCb: NULL pEthBufHdlr: NULL
goal_queueGetElem()	take a buffer from the queue The buffer can be uninitialized or can contain valid data.
goal_queueAddElem()	return a buffer into the queue The content of the buffer remains unchanged.
goal_queueReleaseBuf() goal_queueReleaseBufToOrigQueue() goal_queueReleaseBufToNewQueue()	It is only allowed to release a buffer if: the release was allowed for this buffer: see Chapter: Buffer flags/ GOAL_QUEUE_FLG_NO_RELEASE content of the buffer is not in transmission: see Chapter: Buffer flags/ GOAL_QUEUE_FLG_TX If no release callback is specified by function `goal_queueSetReleaseCallback()`, the buffer is returned in the desired queue according to the called function: goal_queueReleaseBuf(): return buffer into the queue specified in the buffer property pQueue goal_ queueReleaseBufToOrigQueue(): return buffer into the queue, which has created the buffer during goal_queueInit() goal_queueReleaseBufToNewQueue(): append buffer to the specified queue in the function call The flag `GOAL_QUEUE_FLG_USED` is cleared. If a release callback is specified by function `goal_queueSetReleaseCallback()`, the callback function is called and is responsible to return the buffer into a queue. The content of the buffer remains unchanged.

GOAL files:
- goal_queue.[h,c]
example:
- not available

Callback functions

GOAL allows to install a callback function to release a buffer to a queue application-specific. The name of the callback function is application-specific.

Table: cbQueueRelFunc

Prototype	GOAL_STATUS_T cbQueueRelFunc(struct GOAL_BUFFER_T pBuf, void pArg)
Description	This callback function allows to do actions by the application before the buffer is return to the specified queue. If the actions are finished, the callback function has to call one of the functions `goal_queueReleaseBuf()` or `goal_queueReleaseBufToNewQueue()` or `goal_queueReleaseBufToOrigQueue()` to release the buffer.
Parameters	pBuf	buffer, which shall be returned
	pArg	specific arguments used by the callback function
Return values	GOAL return status, see Chapter: GOAL status
Category	optional If a callback function is not available, GOAL returns the buffer to the specified queue.
Registration	during runtime about function `goal_queueSetReleaseCallback()`

Buffer header

The usage of each buffer can be controlled separately from the queue management by the user of the queue buffer pool. There are properties available for the buffer management represented by the structure GOAL_BUFFER_T in code. The structure GOAL_BUFFER_T contains public and private properties. The user of the queue buffer pool shall only change the public properties listed in Table 6.
Some properties are also changed by the queue management during initialization and re-initialization of buffers, see Table 6.

Table: public elements of queue buffers

Public property of GOAL_BUFFER_T	Description

Public property of GOAL_BUFFER_T	Description
dataLen	length of the data in bytes, i.e. used bytes of the buffer This value is cleared by function goal_queueGetNewBuf().
flags	bit-coded flags to control special buffer tasks, see Chapter: Buffer flags
netPort	port number to the Ethernet network, usable if the GOAL queue mechanism is used for sending and receiving Ethernet frames
etherType	type field of the received Ethernet frame according to IEEE-802.3
relCb	callback function called by goal_queueRelease*() The application can specify a callback function by function goal_queueSetReleaseCallback(). The callback function is deleted by the function goal_queueGetNewBuf().
tsSec	timestamp in s of the received Ethernet frame The availability of a timestamp depends on the platform.
tsNsec	timestamp in ns oft he received Ethernet frame The availability of a timestamp depends on the platform.

Buffer flags

Each buffer of a queue buffer pool can be controlled by the following flags:

Table: control flags of queue buffers

Flag of GOAL_BUFFER_T/flags	Description

Flag of GOAL_BUFFER_T/flags	Description
GOAL_QUEUE_FLG_USED	0: buffer is free 1: buffer is used goal_queueGetNewBuf() set this bit. goal_queueRelease*() reset this bit.
GOAL_QUEUE_FLG_NO_RELEASE	0: buffer can be released 1: buffer must not be released
GOAL_QUEUE_FLG_TX	0: no transmission is active, buffer can be released 1: buffer content is still transmitted, buffer cannot be released
GOAL_QUEUE_FLG_VLAN	This bit indicates if the received Ethernet frame uses the VLAN protocol: 0: Ethernet frame uses another protocol 1: VLAN is used This setting corresponds with the property etherType of GOAL_BUFFER_T.
GOAL_QUEUE_FLG_TIMESTAMP	This bit allows to activate the sending an Ethernet frame with time stamp: 0: no timestamp is transmitted 1: timestamp is transmitted This property must be supported by the platform.

Internal queue usage

GOAL uses 3 queues for internal purposes with different memory sizes: small, medium and big. The number and size of the data buffers can be configured and adapted to the user system.
The number and the size of each internal queue can be configured by a CM-variable in the CM-module with the module-ID GOAL_ID_QUEUE. If no values for these CM-variables are stored in the nonvolatile memory, GOAL uses default values. The memory configuration shall only be changed in a GOAL project if memory optimizations are required.

Table: SMALLBUFSIZE

CM-variable-ID	0
CM-variable name	SMALLBUFSIZE
Description	size of a small memory buffer
CM data type	GOAL_CM_INT16
Size	2 bytes
Default value	from NVS or GOAL_QUEUE_SMALL_SIZE: 0 byte

Table: SMALLBUFNUM

CM-variable-ID	1
CM-variable name	SMALLBUFNUM
Description	amount of small memory buffers
CM data type	GOAL_CM_INT16
Size	2 bytes
Default value	from NVS or GOAL_QUEUE_SMALL_NUM: 0 byte

Table: MEDBUFSIZE

CM-variable-ID	2
CM-variable name	MEDBUFSIZE
Description	size of a medium memory buffer
CM data type	GOAL_CM_INT16
Size	2 bytes
Default value	from NVS or GOAL_QUEUE_MED_SIZE: 0 byte

Table: MEDBUFNUM

CM-variable-ID	3
CM-variable name	MEDBUFNUM
Description	amount of medium memory buffers
CM data type	GOAL_CM_INT16
Size	2 bytes
Default value	from NVS or GOAL_QUEUE_MED_NUM: 0 byte

Table: BIGBUFSIZE

CM-variable-ID	4
CM-variable name	BIGBUFSIZE
Description	size of a medium memory buffer
CM data type	GOAL_CM_INT16
Size	2 bytes
Default value	from NVS or GOAL_QUEUE_BIG_SIZE: GOAL_NETBUF_SIZE for Ethernet or TCP/IP usage, else 0

Table: BIGBUFNUM

CM-variable-ID	5
CM-variable name	BIGBUFNUM
Description	amount of medium memory buffers
CM data type	GOAL_CM_INT16
Size	2 bytes
Default value	from NVS or GOAL_QUEUE_BIG_NUM: GOAL_CONFIG_BUF_NUM for Ethernet or TCP/IP usage, else 0

Implementation guidelines

Get an uninitialized buffer from the queue and add the buffer to the queue

Create a handle for the queue:

GOAL_QUEUE_T *pQueueHdl;
Create a queue and allocate the memory for all buffers. The size of each buffer is 20 bytes. The queue has to be created by function goal_queueInit() in the state GOAL_FSA_INIT.

goal_queueInit(&pQueueHdl, 10, 10, 20);
Create a handle for a buffer:

GOAL_BUFFER_T *pBuf;
Take an uninitialized buffer from the queue:
Initialize the buffer and mark the buffer as used:
Use the buffer application-specific.
Return the buffer to the same queue:

Get an initialized buffer from the queue and release the buffer without a callback function

Create a handle for the queue:
Create a queue with max. 10 buffers and allocate the memory for all buffers. The size of each buffer is 20 bytes. The queue has to be created by function goal_queueInit() in the state GOAL_FSA_INIT.
Create a handle for a buffer:
Take an initialized buffer from the queue. The same queue is specified as return queue. No callback function is specified.
Use the buffer application-specific.
Release the buffer to the same queue:

Get an initialized buffer from the queue and release the buffer with a callback function

Create an application-specific callback function to release the buffer:
Create a handle for the queue:
Create a queue with max. 10 buffers and allocate the memory for all buffers. The size of each buffer is 20 bytes. The queue has to be created by function goal_queueInit() in the state GOAL_FSA_INIT.
Create a handle for a buffer:
Take an initialized buffer from the queue. The same queue is specified as return queue. No callback function is specified.
Register the callback function without arguments for the buffer:
Use the buffer application-specific.
Return the buffer into the queue by function goal_queueReleaseBuf(). The function goal_queueReleaseBuf() calls the callback function and the buffer is returned to the queue.

1 Callback functions
2 Buffer header
3 Buffer flags
4 Internal queue usage
5 Implementation guidelines