git.sur5r.net Git - freertos/blob - FreeRTOS/Demo/CORTEX_MPU_M33F_NXP_LPC55S69_MCUXpresso/NXP_Code/component/lists/generic_list.h

   1 /*\r
   2  * Copyright 2018 NXP\r
   3  * All rights reserved.\r
   4  *\r
   5  *\r
   6  * SPDX-License-Identifier: BSD-3-Clause\r
   7  */\r
   8 \r
   9 #ifndef _GENERIC_LIST_H_\r
  10 #define _GENERIC_LIST_H_\r
  11 \r
  12 /*!*********************************************************************************\r
  13 *************************************************************************************\r
  14 * Include\r
  15 *************************************************************************************\r
  16 ********************************************************************************** */\r
  17 \r
  18 /*! *********************************************************************************\r
  19 *************************************************************************************\r
  20 * Public macro definitions\r
  21 *************************************************************************************\r
  22 ********************************************************************************** */\r
  23 \r
  24 /*! *********************************************************************************\r
  25 *************************************************************************************\r
  26 * Public type definitions\r
  27 *************************************************************************************\r
  28 ********************************************************************************** */\r
  29 /*! @brief The list status */\r
  30 typedef enum _list_status\r
  31 {\r
  32     kLIST_Ok = kStatus_Success,                                  /*!< Success */\r
  33     kLIST_Full = MAKE_STATUS(kStatusGroup_LIST, 1),              /*!< FULL */\r
  34     kLIST_Empty = MAKE_STATUS(kStatusGroup_LIST, 2),             /*!< Empty */\r
  35     kLIST_OrphanElement = MAKE_STATUS(kStatusGroup_LIST, 3),     /*!< Orphan Element */\r
  36 }list_status_t;\r
  37 \r
  38 /*! @brief The list structure*/\r
  39 typedef struct list_tag\r
  40 {\r
  41     struct list_element_tag *head;     /*!< list head */\r
  42     struct list_element_tag *tail;     /*!< list tail */\r
  43     uint16_t size;                     /*!< list size */\r
  44     uint16_t max;                      /*!< list max number of elements */\r
  45 }list_t, *list_handle_t;\r
  46 \r
  47 /*! @brief The list element*/\r
  48 typedef struct list_element_tag\r
  49 {\r
  50     struct list_element_tag *next;     /*!< next list element   */\r
  51     struct list_element_tag *prev;     /*!< previous list element */\r
  52     struct list_tag *list;             /*!< pointer to the list */\r
  53 }list_element_t, *list_element_handle_t;\r
  54 \r
  55 /*! *********************************************************************************\r
  56 *************************************************************************************\r
  57 * Public prototypes\r
  58 *************************************************************************************\r
  59 ********************************************************************************** */\r
  60 /*******************************************************************************\r
  61  * API\r
  62  ******************************************************************************/\r
  63 \r
  64 #if defined(__cplusplus)\r
  65 extern "C" {\r
  66 #endif /* _cplusplus */\r
  67 /*!\r
  68  * @brief Initialize the list.\r
  69  *\r
  70  * This function initialize the list.\r
  71  *\r
  72  * @param list - List handle to initialize.\r
  73  * @param max - Maximum number of elements in list. 0 for unlimited.\r
  74  */\r
  75 void LIST_Init(list_handle_t list, uint32_t max);\r
  76 \r
  77 /*!\r
  78  * @brief Gets the list that contains the given element.\r
  79  *\r
  80  *\r
  81  * @param element - Handle of the element.\r
  82  * @retval NULL if element is orphan, Handle of the list the element is inserted into.\r
  83  */\r
  84 list_handle_t LIST_GetList(list_element_handle_t element);\r
  85 \r
  86 /*!\r
  87  * @brief Links element to the head of the list.\r
  88  *\r
  89  * @param list - Handle of the list.\r
  90  * @param element - Handle of the element.\r
  91  * @retval kLIST_Full if list is full, kLIST_Ok if insertion was successful.\r
  92  */\r
  93 list_status_t LIST_AddHead(list_handle_t list, list_element_handle_t element);\r
  94 \r
  95 /*!\r
  96  * @brief Links element to the tail of the list.\r
  97  *\r
  98  * @param list - Handle of the list.\r
  99  * @param element - Handle of the element.\r
 100  * @retval kLIST_Full if list is full, kLIST_Ok if insertion was successful.\r
 101  */\r
 102 list_status_t LIST_AddTail(list_handle_t list, list_element_handle_t element);\r
 103 \r
 104 /*!\r
 105  * @brief Unlinks element from the head of the list.\r
 106  *\r
 107  * @param list - Handle of the list.\r
 108  *\r
 109  * @retval NULL if list is empty, handle of removed element(pointer) if removal was successful.\r
 110  */\r
 111 list_element_handle_t LIST_RemoveHead(list_handle_t list);\r
 112 \r
 113 /*!\r
 114  * @brief Gets head element handle.\r
 115  *\r
 116  * @param list - Handle of the list.\r
 117  *\r
 118  * @retval NULL if list is empty, handle of removed element(pointer) if removal was successful.\r
 119  */\r
 120 list_element_handle_t LIST_GetHead(list_handle_t list);\r
 121 \r
 122 /*!\r
 123  * @brief Gets next element handle for given element handle.\r
 124  *\r
 125  * @param element - Handle of the element.\r
 126  *\r
 127  * @retval NULL if list is empty, handle of removed element(pointer) if removal was successful.\r
 128  */\r
 129 list_element_handle_t LIST_GetNext(list_element_handle_t element);\r
 130 \r
 131 /*!\r
 132  * @brief Gets previous element handle for given element handle.\r
 133  *\r
 134  * @param element - Handle of the element.\r
 135  *\r
 136  * @retval NULL if list is empty, handle of removed element(pointer) if removal was successful.\r
 137  */\r
 138 list_element_handle_t LIST_GetPrev(list_element_handle_t element);\r
 139 \r
 140 /*!\r
 141  * @brief Unlinks an element from its list.\r
 142  *\r
 143  * @param element - Handle of the element.\r
 144  *\r
 145  * @retval kLIST_OrphanElement if element is not part of any list.\r
 146  * @retval kLIST_Ok if removal was successful.\r
 147  */\r
 148 list_status_t LIST_RemoveElement(list_element_handle_t element);\r
 149 \r
 150 /*!\r
 151  * @brief Links an element in the previous position relative to a given member of a list.\r
 152  *\r
 153  * @param element - Handle of the element.\r
 154  * @param newElement - New element to insert before the given member.\r
 155  *\r
 156  * @retval kLIST_OrphanElement if element is not part of any list.\r
 157  * @retval kLIST_Ok if removal was successful.\r
 158  */\r
 159 list_status_t LIST_AddPrevElement(list_element_handle_t element, list_element_handle_t newElement);\r
 160 \r
 161 /*!\r
 162  * @brief Gets the current size of a list.\r
 163  *\r
 164  * @param list - Handle of the list.\r
 165  *\r
 166  * @retval Current size of the list.\r
 167  */\r
 168 uint32_t LIST_GetSize(list_handle_t list);\r
 169 \r
 170 /*!\r
 171  * @brief Gets the number of free places in the list.\r
 172  *\r
 173  * @param list - Handle of the list.\r
 174  *\r
 175  * @retval Available size of the list.\r
 176  */\r
 177 uint32_t LIST_GetAvailableSize(list_handle_t list);\r
 178 \r
 179 /* @} */\r
 180 \r
 181 #if defined(__cplusplus)\r
 182 }\r
 183 #endif\r
 184 \r
 185 #endif /*_GENERIC_LIST_H_*/\r