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