HAL Q How to Use

group Q_How_To_Use

How to use the Q HAL module driver

The Q HAL module can be used as follows:

Q is the abbreviation for Queue. It is an entity that contains a node or a set of nodes linked to each other. Each node contains a data set and a link to the next node.

Use this utility HAL driver only with HAL modules that support the linked-list feature. This module is activated automatically when the USE_HAL_PPP_LINKEDLIST compilation flag is enabled in stm32ynxx_hal_conf.h. Use this module to build a linked-list Q executable for masters that support the linked-list feature. To build Q(s) compatible with different linked-list masters, this module supports two addressing modes:

• Direct addressing mode: node link addresses represent the physical node address.

• Base offset addressing mode: node link addresses represent the offset of the node from the Q head node address. This module supports singly linked-list Q nodes. Behavior is not guaranteed if a Q is modified outside this module.

This module provides six API sets that allow you to:

1. Initialize and de-initialize the logical Q object:

   • Initialize the logical Q object using information provided by any HAL peripheral module that supports the linked list feature. When initialized, the Q is ready to apply any operation provided by this module.

   • De-initialize the logical Q object and unlink all Q node(s). When de-initialized, reuse the Q object for the same or another master executor.

2. Insert a new node in a Q:

   • Insert a new node into a Q at any position using the following function models:

     • Generic new node insertion function that allows you to add a new node at any selected Q position.

       • This functionality is ensured by HAL_Q_InsertNode() function. The p_node parameter allows you to specify where the new node is inserted.

         • When p_node is null, the new node is placed at the head of Q.

         • When p_node is not null, the new node is placed directly after p_node. If p_node is not found within the Q, the function returns an error and the Q is not modified.

     • New head node insertion function that allows you to add a new node as the head node of a Q.

       • This functionality is ensured by HAL_Q_InsertNode_Head() function.

     • New tail node insertion function that allows you to add a new node as the tail node of a Q.

       • This functionality is ensured by HAL_Q_InsertNode_Tail() function.

   • Do not add a new node when the selected Q is circular.

   • Prefer the tail node insertion model function to reduce footprint.

3. Remove an existing node from a Q:

   • Remove any existing node from a Q using the following function models:

     • Generic node removal function that allows you to remove any existing node from a Q.

       • This functionality is ensured by HAL_Q_RemoveNode() function.

         • The p_node parameter allows you to select the node to be removed. This function returns an error when p_node is not found within the Q or p_node is null.

     • Head node removal function that allows you to remove the head node from a Q.

       • This functionality is ensured by HAL_Q_RemoveNode_Head() function.

     • Tail node removal function that allows you to remove the tail node from a Q.

       • This functionality is ensured by HAL_Q_RemoveNode_Tail() function.

   • Do not remove an existing node when the selected Q is circular.

   • When successfully removed, the removed node can be reused later.

4. Replace an existing node in a Q:

   • Replace any existing node with a new node in a Q using the following function models:

     • Generic node replacement function that allows you to replace any existing node with a new node in a Q.

       • This functionality is ensured by HAL_Q_ReplaceNode() function. The p_old_node parameter allows you to specify the node to be replaced.

         • When p_old_node is not null, p_new_node replaces p_old_node. If p_old_node is not found within the Q, the function returns an error and the Q is not modified.

     • Head node replacement function that allows you to replace the existing head node with a new head node in a Q.

       • This functionality is ensured by HAL_Q_ReplaceNode_Head() function.

     • Tail node replacement function that allows you to replace the existing tail node with a new tail node in a Q.

       • This functionality is ensured by HAL_Q_ReplaceNode_Tail() function.

   • Do not replace an existing node when the selected Q is circular.

   • When successfully replaced, the replaced node can be reused later.

5. Insert a source Q into a destination Q:

   • Insert a source Q into a destination Q at any position using the following function models:

     • Generic source Q insertion function that allows you to insert source Q node(s) at any selected destination Q position.

       • This functionality is ensured by HAL_Q_InsertNode() function. The p_node parameter allows you to specify where the source Q node(s) are inserted.

         • When p_node is null, the source Q node(s) are placed at the head of the destination Q.

         • When p_node is not null, the source Q node(s) are placed directly after p_node. If p_node is not found within the destination Q, the function returns an error and the source and destination Qs are not modified.

     • Head source Q insertion function that allows you to insert source Q node(s) before all the destination Q node(s).

       • This functionality is ensured by HAL_Q_InsertNode_Head() function.

     • Tail source Q insertion function that allows you to insert source Q node(s) after all the destination Q node(s).

       • This functionality is ensured by HAL_Q_InsertNode_Tail() function.

   • Do not add source Q node(s) to destination Q node(s) when any Q is circular.

   • Prefer the tail Q insertion model function to reduce footprint.

   • When successfully inserted, the destination Q contains the source Q nodes and destination Q nodes, and the source Q is cleared and can be reused later without needing to reinitialize it.

6. Set and clear a circular link on a non-empty Q:

   • Set a circular link to any Q node using the following function models:

     • Generic circular link Q setting function that allows you to set a circular link at any non-empty Q position.

       • This functionality is ensured by HAL_Q_SetCircularLinkQ() function. The p_node parameter allows you to specify the first circular node (node linked to Q tail node). This function returns an error when p_node is not found within the Q or p_node is null.

     • Head circular link Q setting function that allows you to set a circular link to the head node of Q.

       • This functionality is ensured by HAL_Q_SetCircularLinkQ_Head() function.

     • Tail circular link Q setting function that allows you to set a circular link to the tail node of Q.

       • This functionality is ensured by HAL_Q_SetCircularLinkQ_Tail() function.

   • Clear a circular link from a Q.

     • This functionality is ensured by HAL_Q_ClearCircularLinkQ() function.