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 of Queue wording. It is an entity that contains a node or set of nodes linked between each others. Each node contains a set of data a link to the next node.

This module is an utility HAL driver that can be used only with specific HAL modules that supports linked-list feature. This module is activated automatically when activation USE_HAL_PPP_LINKEDLIST compilation flag through stm32ynxx_hal_conf.h module. This module allows to build a linked-list Q executable from masters that supports linked-list feature. In order to build Q(s) compatible with different linked-list masters, this module supports two addressing modes :

  • Direct addressing mode : where node links addresses presents the physical node address.

  • Base offset addressing mode : where node links addresses presents the offset of the node versus Q head node address. This module supports singly linked-list Q nodes. The behavior of this module is not granted when a Q is modified outside this module.

This module provides 6 different set of APIs that allows to :

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

    • Initialize the logical Q object thanks to a set of information provided by any HAL peripheral module that supports the linked list feature. When initialized, the Q must be ready to apply any operation provided by this module.

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

  2. Insert new node in a Q :

    • Insert a new node to a Q into any position thanks to the following set of functions models :

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

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

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

          • When the p_node is not null, the new node is placed directly after the p_node. If the 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 to add a new node as a new head node Q.

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

    • It is forbidden to add a new node when the selected Q is circular.

    • When possible, it is recommended to use tail node insertion model function to reduce footprint.

  3. Remove an existing node from a Q :

    • Remove any existing node from a Q thanks to the following set of functions models :

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

        • This functionality is ensured by HAL_Q_RemoveNode() function.

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

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

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

    • It is forbidden to remove an existent node when the selected Q is circular.

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

  4. Replace an existing node in a Q :

    • Replace any existing node by a new node in a Q thanks to the following set of functions models :

      • Generic node replacing function that allows to replace any existing node by a new node in a Q.

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

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

      • Head node replacing function that allows to replace the existing head node by a new head node in a Q.

      • Tail node replacing function that allows to replace the existing tail node by a new tail node in a Q.

    • It is forbidden to replace an existent node when the selected Q is circular.

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

  5. Insert source Q in a destination Q :

    • Insert a source Q to a destination Q into any position thanks to the following set of functions models :

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

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

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

          • When the p_node is not null, the source Q node(s) is placed directly after the p_node. If the 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 to insert a source Q node(s) before all the destination Q node(s).

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

    • It is forbidden to add a source Q node(s) to a destination Q node(s) when any Q is circular.

    • When possible, it is recommended to use tail Q insertion model function to reduce footprint.

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

  6. Set and clear a circular link to not empty Q :

    • Set a circular link to any Q node thanks to the following set of functions models :

      • Generic circular link Q setting function that allows to set a circular link to a any not empty Q position.

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

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

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

    • Clear a circular link from a Q.