Queue buffer pool
- Michael Bachmeier
- Marcus Züche
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 |
|---|---|
goal_queueInit() | create a queue with buffers 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 is required if the system pools are used ( |
goal_queueSetReleaseCallback() | specify a callback function buffer-related, which is called by one of the functions |
goal_queueGetNewBuf() | take a buffer from the queue and initialize buffer |
goal_queueGetElem() | take a buffer from the queue |
goal_queueAddElem() | return a buffer into the queue |
goal_queueReleaseBuf() | It is only allowed to release a buffer if:
|
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 | |
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 | |
Registration | during runtime about function | |
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 |
|---|---|
dataLen | length of the data in bytes, i.e. used bytes of the buffer |
flags | bit-coded flags to control special buffer tasks, see Chapter: Buffer flags |
netPort | port number to the Ethernet network, |
etherType | type field of the received Ethernet frame according to IEEE-802.3 |
relCb | callback function called by goal_queueRelease*() |
tsSec | timestamp in s of the received Ethernet frame |
tsNsec | timestamp in ns oft he received Ethernet frame |
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 |
|---|---|
GOAL_QUEUE_FLG_USED | 0: buffer is free |
GOAL_QUEUE_FLG_NO_RELEASE | 0: buffer can be released |
GOAL_QUEUE_FLG_TX | 0: no transmission is active, buffer can be released |
GOAL_QUEUE_FLG_VLAN | This bit indicates if the received Ethernet frame uses the VLAN protocol: |
GOAL_QUEUE_FLG_TIMESTAMP | This bit allows to activate the sending an Ethernet frame with time stamp: |
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.