Francisco Paez
/
freertos
Important changes to repositories hosted on mbed.com
Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.
To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.
It is also possible to export all your personal repositories from the account settings page.
Dependents: frdm_k64f_freertos_lib
src/include/list.h@0:62cd296ba2a7, 2017-05-31 (annotated)
- Committer:
- fep
- Date:
- Wed May 31 02:27:10 2017 +0000
- Revision:
- 0:62cd296ba2a7
FreeRTOS v9.0.0 for Cortex-M4F (FRDM-K64F and others...)
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| fep | 0:62cd296ba2a7 | 1 | /* |
| fep | 0:62cd296ba2a7 | 2 | FreeRTOS V9.0.0 - Copyright (C) 2016 Real Time Engineers Ltd. |
| fep | 0:62cd296ba2a7 | 3 | All rights reserved |
| fep | 0:62cd296ba2a7 | 4 | |
| fep | 0:62cd296ba2a7 | 5 | VISIT http://www.FreeRTOS.org TO ENSURE YOU ARE USING THE LATEST VERSION. |
| fep | 0:62cd296ba2a7 | 6 | |
| fep | 0:62cd296ba2a7 | 7 | This file is part of the FreeRTOS distribution. |
| fep | 0:62cd296ba2a7 | 8 | |
| fep | 0:62cd296ba2a7 | 9 | FreeRTOS is free software; you can redistribute it and/or modify it under |
| fep | 0:62cd296ba2a7 | 10 | the terms of the GNU General Public License (version 2) as published by the |
| fep | 0:62cd296ba2a7 | 11 | Free Software Foundation >>>> AND MODIFIED BY <<<< the FreeRTOS exception. |
| fep | 0:62cd296ba2a7 | 12 | |
| fep | 0:62cd296ba2a7 | 13 | *************************************************************************** |
| fep | 0:62cd296ba2a7 | 14 | >>! NOTE: The modification to the GPL is included to allow you to !<< |
| fep | 0:62cd296ba2a7 | 15 | >>! distribute a combined work that includes FreeRTOS without being !<< |
| fep | 0:62cd296ba2a7 | 16 | >>! obliged to provide the source code for proprietary components !<< |
| fep | 0:62cd296ba2a7 | 17 | >>! outside of the FreeRTOS kernel. !<< |
| fep | 0:62cd296ba2a7 | 18 | *************************************************************************** |
| fep | 0:62cd296ba2a7 | 19 | |
| fep | 0:62cd296ba2a7 | 20 | FreeRTOS is distributed in the hope that it will be useful, but WITHOUT ANY |
| fep | 0:62cd296ba2a7 | 21 | WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS |
| fep | 0:62cd296ba2a7 | 22 | FOR A PARTICULAR PURPOSE. Full license text is available on the following |
| fep | 0:62cd296ba2a7 | 23 | link: http://www.freertos.org/a00114.html |
| fep | 0:62cd296ba2a7 | 24 | |
| fep | 0:62cd296ba2a7 | 25 | *************************************************************************** |
| fep | 0:62cd296ba2a7 | 26 | * * |
| fep | 0:62cd296ba2a7 | 27 | * FreeRTOS provides completely free yet professionally developed, * |
| fep | 0:62cd296ba2a7 | 28 | * robust, strictly quality controlled, supported, and cross * |
| fep | 0:62cd296ba2a7 | 29 | * platform software that is more than just the market leader, it * |
| fep | 0:62cd296ba2a7 | 30 | * is the industry's de facto standard. * |
| fep | 0:62cd296ba2a7 | 31 | * * |
| fep | 0:62cd296ba2a7 | 32 | * Help yourself get started quickly while simultaneously helping * |
| fep | 0:62cd296ba2a7 | 33 | * to support the FreeRTOS project by purchasing a FreeRTOS * |
| fep | 0:62cd296ba2a7 | 34 | * tutorial book, reference manual, or both: * |
| fep | 0:62cd296ba2a7 | 35 | * http://www.FreeRTOS.org/Documentation * |
| fep | 0:62cd296ba2a7 | 36 | * * |
| fep | 0:62cd296ba2a7 | 37 | *************************************************************************** |
| fep | 0:62cd296ba2a7 | 38 | |
| fep | 0:62cd296ba2a7 | 39 | http://www.FreeRTOS.org/FAQHelp.html - Having a problem? Start by reading |
| fep | 0:62cd296ba2a7 | 40 | the FAQ page "My application does not run, what could be wrong?". Have you |
| fep | 0:62cd296ba2a7 | 41 | defined configASSERT()? |
| fep | 0:62cd296ba2a7 | 42 | |
| fep | 0:62cd296ba2a7 | 43 | http://www.FreeRTOS.org/support - In return for receiving this top quality |
| fep | 0:62cd296ba2a7 | 44 | embedded software for free we request you assist our global community by |
| fep | 0:62cd296ba2a7 | 45 | participating in the support forum. |
| fep | 0:62cd296ba2a7 | 46 | |
| fep | 0:62cd296ba2a7 | 47 | http://www.FreeRTOS.org/training - Investing in training allows your team to |
| fep | 0:62cd296ba2a7 | 48 | be as productive as possible as early as possible. Now you can receive |
| fep | 0:62cd296ba2a7 | 49 | FreeRTOS training directly from Richard Barry, CEO of Real Time Engineers |
| fep | 0:62cd296ba2a7 | 50 | Ltd, and the world's leading authority on the world's leading RTOS. |
| fep | 0:62cd296ba2a7 | 51 | |
| fep | 0:62cd296ba2a7 | 52 | http://www.FreeRTOS.org/plus - A selection of FreeRTOS ecosystem products, |
| fep | 0:62cd296ba2a7 | 53 | including FreeRTOS+Trace - an indispensable productivity tool, a DOS |
| fep | 0:62cd296ba2a7 | 54 | compatible FAT file system, and our tiny thread aware UDP/IP stack. |
| fep | 0:62cd296ba2a7 | 55 | |
| fep | 0:62cd296ba2a7 | 56 | http://www.FreeRTOS.org/labs - Where new FreeRTOS products go to incubate. |
| fep | 0:62cd296ba2a7 | 57 | Come and try FreeRTOS+TCP, our new open source TCP/IP stack for FreeRTOS. |
| fep | 0:62cd296ba2a7 | 58 | |
| fep | 0:62cd296ba2a7 | 59 | http://www.OpenRTOS.com - Real Time Engineers ltd. license FreeRTOS to High |
| fep | 0:62cd296ba2a7 | 60 | Integrity Systems ltd. to sell under the OpenRTOS brand. Low cost OpenRTOS |
| fep | 0:62cd296ba2a7 | 61 | licenses offer ticketed support, indemnification and commercial middleware. |
| fep | 0:62cd296ba2a7 | 62 | |
| fep | 0:62cd296ba2a7 | 63 | http://www.SafeRTOS.com - High Integrity Systems also provide a safety |
| fep | 0:62cd296ba2a7 | 64 | engineered and independently SIL3 certified version for use in safety and |
| fep | 0:62cd296ba2a7 | 65 | mission critical applications that require provable dependability. |
| fep | 0:62cd296ba2a7 | 66 | |
| fep | 0:62cd296ba2a7 | 67 | 1 tab == 4 spaces! |
| fep | 0:62cd296ba2a7 | 68 | */ |
| fep | 0:62cd296ba2a7 | 69 | |
| fep | 0:62cd296ba2a7 | 70 | /* |
| fep | 0:62cd296ba2a7 | 71 | * This is the list implementation used by the scheduler. While it is tailored |
| fep | 0:62cd296ba2a7 | 72 | * heavily for the schedulers needs, it is also available for use by |
| fep | 0:62cd296ba2a7 | 73 | * application code. |
| fep | 0:62cd296ba2a7 | 74 | * |
| fep | 0:62cd296ba2a7 | 75 | * list_ts can only store pointers to list_item_ts. Each ListItem_t contains a |
| fep | 0:62cd296ba2a7 | 76 | * numeric value (xItemValue). Most of the time the lists are sorted in |
| fep | 0:62cd296ba2a7 | 77 | * descending item value order. |
| fep | 0:62cd296ba2a7 | 78 | * |
| fep | 0:62cd296ba2a7 | 79 | * Lists are created already containing one list item. The value of this |
| fep | 0:62cd296ba2a7 | 80 | * item is the maximum possible that can be stored, it is therefore always at |
| fep | 0:62cd296ba2a7 | 81 | * the end of the list and acts as a marker. The list member pxHead always |
| fep | 0:62cd296ba2a7 | 82 | * points to this marker - even though it is at the tail of the list. This |
| fep | 0:62cd296ba2a7 | 83 | * is because the tail contains a wrap back pointer to the true head of |
| fep | 0:62cd296ba2a7 | 84 | * the list. |
| fep | 0:62cd296ba2a7 | 85 | * |
| fep | 0:62cd296ba2a7 | 86 | * In addition to it's value, each list item contains a pointer to the next |
| fep | 0:62cd296ba2a7 | 87 | * item in the list (pxNext), a pointer to the list it is in (pxContainer) |
| fep | 0:62cd296ba2a7 | 88 | * and a pointer to back to the object that contains it. These later two |
| fep | 0:62cd296ba2a7 | 89 | * pointers are included for efficiency of list manipulation. There is |
| fep | 0:62cd296ba2a7 | 90 | * effectively a two way link between the object containing the list item and |
| fep | 0:62cd296ba2a7 | 91 | * the list item itself. |
| fep | 0:62cd296ba2a7 | 92 | * |
| fep | 0:62cd296ba2a7 | 93 | * |
| fep | 0:62cd296ba2a7 | 94 | * \page ListIntroduction List Implementation |
| fep | 0:62cd296ba2a7 | 95 | * \ingroup FreeRTOSIntro |
| fep | 0:62cd296ba2a7 | 96 | */ |
| fep | 0:62cd296ba2a7 | 97 | |
| fep | 0:62cd296ba2a7 | 98 | #ifndef INC_FREERTOS_H |
| fep | 0:62cd296ba2a7 | 99 | #error FreeRTOS.h must be included before list.h |
| fep | 0:62cd296ba2a7 | 100 | #endif |
| fep | 0:62cd296ba2a7 | 101 | |
| fep | 0:62cd296ba2a7 | 102 | #ifndef LIST_H |
| fep | 0:62cd296ba2a7 | 103 | #define LIST_H |
| fep | 0:62cd296ba2a7 | 104 | |
| fep | 0:62cd296ba2a7 | 105 | /* |
| fep | 0:62cd296ba2a7 | 106 | * The list structure members are modified from within interrupts, and therefore |
| fep | 0:62cd296ba2a7 | 107 | * by rights should be declared volatile. However, they are only modified in a |
| fep | 0:62cd296ba2a7 | 108 | * functionally atomic way (within critical sections of with the scheduler |
| fep | 0:62cd296ba2a7 | 109 | * suspended) and are either passed by reference into a function or indexed via |
| fep | 0:62cd296ba2a7 | 110 | * a volatile variable. Therefore, in all use cases tested so far, the volatile |
| fep | 0:62cd296ba2a7 | 111 | * qualifier can be omitted in order to provide a moderate performance |
| fep | 0:62cd296ba2a7 | 112 | * improvement without adversely affecting functional behaviour. The assembly |
| fep | 0:62cd296ba2a7 | 113 | * instructions generated by the IAR, ARM and GCC compilers when the respective |
| fep | 0:62cd296ba2a7 | 114 | * compiler's options were set for maximum optimisation has been inspected and |
| fep | 0:62cd296ba2a7 | 115 | * deemed to be as intended. That said, as compiler technology advances, and |
| fep | 0:62cd296ba2a7 | 116 | * especially if aggressive cross module optimisation is used (a use case that |
| fep | 0:62cd296ba2a7 | 117 | * has not been exercised to any great extend) then it is feasible that the |
| fep | 0:62cd296ba2a7 | 118 | * volatile qualifier will be needed for correct optimisation. It is expected |
| fep | 0:62cd296ba2a7 | 119 | * that a compiler removing essential code because, without the volatile |
| fep | 0:62cd296ba2a7 | 120 | * qualifier on the list structure members and with aggressive cross module |
| fep | 0:62cd296ba2a7 | 121 | * optimisation, the compiler deemed the code unnecessary will result in |
| fep | 0:62cd296ba2a7 | 122 | * complete and obvious failure of the scheduler. If this is ever experienced |
| fep | 0:62cd296ba2a7 | 123 | * then the volatile qualifier can be inserted in the relevant places within the |
| fep | 0:62cd296ba2a7 | 124 | * list structures by simply defining configLIST_VOLATILE to volatile in |
| fep | 0:62cd296ba2a7 | 125 | * FreeRTOSConfig.h (as per the example at the bottom of this comment block). |
| fep | 0:62cd296ba2a7 | 126 | * If configLIST_VOLATILE is not defined then the preprocessor directives below |
| fep | 0:62cd296ba2a7 | 127 | * will simply #define configLIST_VOLATILE away completely. |
| fep | 0:62cd296ba2a7 | 128 | * |
| fep | 0:62cd296ba2a7 | 129 | * To use volatile list structure members then add the following line to |
| fep | 0:62cd296ba2a7 | 130 | * FreeRTOSConfig.h (without the quotes): |
| fep | 0:62cd296ba2a7 | 131 | * "#define configLIST_VOLATILE volatile" |
| fep | 0:62cd296ba2a7 | 132 | */ |
| fep | 0:62cd296ba2a7 | 133 | #ifndef configLIST_VOLATILE |
| fep | 0:62cd296ba2a7 | 134 | #define configLIST_VOLATILE |
| fep | 0:62cd296ba2a7 | 135 | #endif /* configSUPPORT_CROSS_MODULE_OPTIMISATION */ |
| fep | 0:62cd296ba2a7 | 136 | |
| fep | 0:62cd296ba2a7 | 137 | #ifdef __cplusplus |
| fep | 0:62cd296ba2a7 | 138 | extern "C" { |
| fep | 0:62cd296ba2a7 | 139 | #endif |
| fep | 0:62cd296ba2a7 | 140 | |
| fep | 0:62cd296ba2a7 | 141 | /* Macros that can be used to place known values within the list structures, |
| fep | 0:62cd296ba2a7 | 142 | then check that the known values do not get corrupted during the execution of |
| fep | 0:62cd296ba2a7 | 143 | the application. These may catch the list data structures being overwritten in |
| fep | 0:62cd296ba2a7 | 144 | memory. They will not catch data errors caused by incorrect configuration or |
| fep | 0:62cd296ba2a7 | 145 | use of FreeRTOS.*/ |
| fep | 0:62cd296ba2a7 | 146 | #if( configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES == 0 ) |
| fep | 0:62cd296ba2a7 | 147 | /* Define the macros to do nothing. */ |
| fep | 0:62cd296ba2a7 | 148 | #define listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE |
| fep | 0:62cd296ba2a7 | 149 | #define listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE |
| fep | 0:62cd296ba2a7 | 150 | #define listFIRST_LIST_INTEGRITY_CHECK_VALUE |
| fep | 0:62cd296ba2a7 | 151 | #define listSECOND_LIST_INTEGRITY_CHECK_VALUE |
| fep | 0:62cd296ba2a7 | 152 | #define listSET_FIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem ) |
| fep | 0:62cd296ba2a7 | 153 | #define listSET_SECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem ) |
| fep | 0:62cd296ba2a7 | 154 | #define listSET_LIST_INTEGRITY_CHECK_1_VALUE( pxList ) |
| fep | 0:62cd296ba2a7 | 155 | #define listSET_LIST_INTEGRITY_CHECK_2_VALUE( pxList ) |
| fep | 0:62cd296ba2a7 | 156 | #define listTEST_LIST_ITEM_INTEGRITY( pxItem ) |
| fep | 0:62cd296ba2a7 | 157 | #define listTEST_LIST_INTEGRITY( pxList ) |
| fep | 0:62cd296ba2a7 | 158 | #else |
| fep | 0:62cd296ba2a7 | 159 | /* Define macros that add new members into the list structures. */ |
| fep | 0:62cd296ba2a7 | 160 | #define listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE TickType_t xListItemIntegrityValue1; |
| fep | 0:62cd296ba2a7 | 161 | #define listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE TickType_t xListItemIntegrityValue2; |
| fep | 0:62cd296ba2a7 | 162 | #define listFIRST_LIST_INTEGRITY_CHECK_VALUE TickType_t xListIntegrityValue1; |
| fep | 0:62cd296ba2a7 | 163 | #define listSECOND_LIST_INTEGRITY_CHECK_VALUE TickType_t xListIntegrityValue2; |
| fep | 0:62cd296ba2a7 | 164 | |
| fep | 0:62cd296ba2a7 | 165 | /* Define macros that set the new structure members to known values. */ |
| fep | 0:62cd296ba2a7 | 166 | #define listSET_FIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem ) ( pxItem )->xListItemIntegrityValue1 = pdINTEGRITY_CHECK_VALUE |
| fep | 0:62cd296ba2a7 | 167 | #define listSET_SECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE( pxItem ) ( pxItem )->xListItemIntegrityValue2 = pdINTEGRITY_CHECK_VALUE |
| fep | 0:62cd296ba2a7 | 168 | #define listSET_LIST_INTEGRITY_CHECK_1_VALUE( pxList ) ( pxList )->xListIntegrityValue1 = pdINTEGRITY_CHECK_VALUE |
| fep | 0:62cd296ba2a7 | 169 | #define listSET_LIST_INTEGRITY_CHECK_2_VALUE( pxList ) ( pxList )->xListIntegrityValue2 = pdINTEGRITY_CHECK_VALUE |
| fep | 0:62cd296ba2a7 | 170 | |
| fep | 0:62cd296ba2a7 | 171 | /* Define macros that will assert if one of the structure members does not |
| fep | 0:62cd296ba2a7 | 172 | contain its expected value. */ |
| fep | 0:62cd296ba2a7 | 173 | #define listTEST_LIST_ITEM_INTEGRITY( pxItem ) configASSERT( ( ( pxItem )->xListItemIntegrityValue1 == pdINTEGRITY_CHECK_VALUE ) && ( ( pxItem )->xListItemIntegrityValue2 == pdINTEGRITY_CHECK_VALUE ) ) |
| fep | 0:62cd296ba2a7 | 174 | #define listTEST_LIST_INTEGRITY( pxList ) configASSERT( ( ( pxList )->xListIntegrityValue1 == pdINTEGRITY_CHECK_VALUE ) && ( ( pxList )->xListIntegrityValue2 == pdINTEGRITY_CHECK_VALUE ) ) |
| fep | 0:62cd296ba2a7 | 175 | #endif /* configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES */ |
| fep | 0:62cd296ba2a7 | 176 | |
| fep | 0:62cd296ba2a7 | 177 | |
| fep | 0:62cd296ba2a7 | 178 | /* |
| fep | 0:62cd296ba2a7 | 179 | * Definition of the only type of object that a list can contain. |
| fep | 0:62cd296ba2a7 | 180 | */ |
| fep | 0:62cd296ba2a7 | 181 | struct xLIST_ITEM |
| fep | 0:62cd296ba2a7 | 182 | { |
| fep | 0:62cd296ba2a7 | 183 | listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ |
| fep | 0:62cd296ba2a7 | 184 | configLIST_VOLATILE TickType_t xItemValue; /*< The value being listed. In most cases this is used to sort the list in descending order. */ |
| fep | 0:62cd296ba2a7 | 185 | struct xLIST_ITEM * configLIST_VOLATILE pxNext; /*< Pointer to the next ListItem_t in the list. */ |
| fep | 0:62cd296ba2a7 | 186 | struct xLIST_ITEM * configLIST_VOLATILE pxPrevious; /*< Pointer to the previous ListItem_t in the list. */ |
| fep | 0:62cd296ba2a7 | 187 | void * pvOwner; /*< Pointer to the object (normally a TCB) that contains the list item. There is therefore a two way link between the object containing the list item and the list item itself. */ |
| fep | 0:62cd296ba2a7 | 188 | void * configLIST_VOLATILE pvContainer; /*< Pointer to the list in which this list item is placed (if any). */ |
| fep | 0:62cd296ba2a7 | 189 | listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ |
| fep | 0:62cd296ba2a7 | 190 | }; |
| fep | 0:62cd296ba2a7 | 191 | typedef struct xLIST_ITEM ListItem_t; /* For some reason lint wants this as two separate definitions. */ |
| fep | 0:62cd296ba2a7 | 192 | |
| fep | 0:62cd296ba2a7 | 193 | struct xMINI_LIST_ITEM |
| fep | 0:62cd296ba2a7 | 194 | { |
| fep | 0:62cd296ba2a7 | 195 | listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ |
| fep | 0:62cd296ba2a7 | 196 | configLIST_VOLATILE TickType_t xItemValue; |
| fep | 0:62cd296ba2a7 | 197 | struct xLIST_ITEM * configLIST_VOLATILE pxNext; |
| fep | 0:62cd296ba2a7 | 198 | struct xLIST_ITEM * configLIST_VOLATILE pxPrevious; |
| fep | 0:62cd296ba2a7 | 199 | }; |
| fep | 0:62cd296ba2a7 | 200 | typedef struct xMINI_LIST_ITEM MiniListItem_t; |
| fep | 0:62cd296ba2a7 | 201 | |
| fep | 0:62cd296ba2a7 | 202 | /* |
| fep | 0:62cd296ba2a7 | 203 | * Definition of the type of queue used by the scheduler. |
| fep | 0:62cd296ba2a7 | 204 | */ |
| fep | 0:62cd296ba2a7 | 205 | typedef struct xLIST |
| fep | 0:62cd296ba2a7 | 206 | { |
| fep | 0:62cd296ba2a7 | 207 | listFIRST_LIST_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ |
| fep | 0:62cd296ba2a7 | 208 | configLIST_VOLATILE UBaseType_t uxNumberOfItems; |
| fep | 0:62cd296ba2a7 | 209 | ListItem_t * configLIST_VOLATILE pxIndex; /*< Used to walk through the list. Points to the last item returned by a call to listGET_OWNER_OF_NEXT_ENTRY (). */ |
| fep | 0:62cd296ba2a7 | 210 | MiniListItem_t xListEnd; /*< List item that contains the maximum possible item value meaning it is always at the end of the list and is therefore used as a marker. */ |
| fep | 0:62cd296ba2a7 | 211 | listSECOND_LIST_INTEGRITY_CHECK_VALUE /*< Set to a known value if configUSE_LIST_DATA_INTEGRITY_CHECK_BYTES is set to 1. */ |
| fep | 0:62cd296ba2a7 | 212 | } List_t; |
| fep | 0:62cd296ba2a7 | 213 | |
| fep | 0:62cd296ba2a7 | 214 | /* |
| fep | 0:62cd296ba2a7 | 215 | * Access macro to set the owner of a list item. The owner of a list item |
| fep | 0:62cd296ba2a7 | 216 | * is the object (usually a TCB) that contains the list item. |
| fep | 0:62cd296ba2a7 | 217 | * |
| fep | 0:62cd296ba2a7 | 218 | * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER |
| fep | 0:62cd296ba2a7 | 219 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 220 | */ |
| fep | 0:62cd296ba2a7 | 221 | #define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner ) ( ( pxListItem )->pvOwner = ( void * ) ( pxOwner ) ) |
| fep | 0:62cd296ba2a7 | 222 | |
| fep | 0:62cd296ba2a7 | 223 | /* |
| fep | 0:62cd296ba2a7 | 224 | * Access macro to get the owner of a list item. The owner of a list item |
| fep | 0:62cd296ba2a7 | 225 | * is the object (usually a TCB) that contains the list item. |
| fep | 0:62cd296ba2a7 | 226 | * |
| fep | 0:62cd296ba2a7 | 227 | * \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER |
| fep | 0:62cd296ba2a7 | 228 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 229 | */ |
| fep | 0:62cd296ba2a7 | 230 | #define listGET_LIST_ITEM_OWNER( pxListItem ) ( ( pxListItem )->pvOwner ) |
| fep | 0:62cd296ba2a7 | 231 | |
| fep | 0:62cd296ba2a7 | 232 | /* |
| fep | 0:62cd296ba2a7 | 233 | * Access macro to set the value of the list item. In most cases the value is |
| fep | 0:62cd296ba2a7 | 234 | * used to sort the list in descending order. |
| fep | 0:62cd296ba2a7 | 235 | * |
| fep | 0:62cd296ba2a7 | 236 | * \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE |
| fep | 0:62cd296ba2a7 | 237 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 238 | */ |
| fep | 0:62cd296ba2a7 | 239 | #define listSET_LIST_ITEM_VALUE( pxListItem, xValue ) ( ( pxListItem )->xItemValue = ( xValue ) ) |
| fep | 0:62cd296ba2a7 | 240 | |
| fep | 0:62cd296ba2a7 | 241 | /* |
| fep | 0:62cd296ba2a7 | 242 | * Access macro to retrieve the value of the list item. The value can |
| fep | 0:62cd296ba2a7 | 243 | * represent anything - for example the priority of a task, or the time at |
| fep | 0:62cd296ba2a7 | 244 | * which a task should be unblocked. |
| fep | 0:62cd296ba2a7 | 245 | * |
| fep | 0:62cd296ba2a7 | 246 | * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE |
| fep | 0:62cd296ba2a7 | 247 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 248 | */ |
| fep | 0:62cd296ba2a7 | 249 | #define listGET_LIST_ITEM_VALUE( pxListItem ) ( ( pxListItem )->xItemValue ) |
| fep | 0:62cd296ba2a7 | 250 | |
| fep | 0:62cd296ba2a7 | 251 | /* |
| fep | 0:62cd296ba2a7 | 252 | * Access macro to retrieve the value of the list item at the head of a given |
| fep | 0:62cd296ba2a7 | 253 | * list. |
| fep | 0:62cd296ba2a7 | 254 | * |
| fep | 0:62cd296ba2a7 | 255 | * \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE |
| fep | 0:62cd296ba2a7 | 256 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 257 | */ |
| fep | 0:62cd296ba2a7 | 258 | #define listGET_ITEM_VALUE_OF_HEAD_ENTRY( pxList ) ( ( ( pxList )->xListEnd ).pxNext->xItemValue ) |
| fep | 0:62cd296ba2a7 | 259 | |
| fep | 0:62cd296ba2a7 | 260 | /* |
| fep | 0:62cd296ba2a7 | 261 | * Return the list item at the head of the list. |
| fep | 0:62cd296ba2a7 | 262 | * |
| fep | 0:62cd296ba2a7 | 263 | * \page listGET_HEAD_ENTRY listGET_HEAD_ENTRY |
| fep | 0:62cd296ba2a7 | 264 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 265 | */ |
| fep | 0:62cd296ba2a7 | 266 | #define listGET_HEAD_ENTRY( pxList ) ( ( ( pxList )->xListEnd ).pxNext ) |
| fep | 0:62cd296ba2a7 | 267 | |
| fep | 0:62cd296ba2a7 | 268 | /* |
| fep | 0:62cd296ba2a7 | 269 | * Return the list item at the head of the list. |
| fep | 0:62cd296ba2a7 | 270 | * |
| fep | 0:62cd296ba2a7 | 271 | * \page listGET_NEXT listGET_NEXT |
| fep | 0:62cd296ba2a7 | 272 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 273 | */ |
| fep | 0:62cd296ba2a7 | 274 | #define listGET_NEXT( pxListItem ) ( ( pxListItem )->pxNext ) |
| fep | 0:62cd296ba2a7 | 275 | |
| fep | 0:62cd296ba2a7 | 276 | /* |
| fep | 0:62cd296ba2a7 | 277 | * Return the list item that marks the end of the list |
| fep | 0:62cd296ba2a7 | 278 | * |
| fep | 0:62cd296ba2a7 | 279 | * \page listGET_END_MARKER listGET_END_MARKER |
| fep | 0:62cd296ba2a7 | 280 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 281 | */ |
| fep | 0:62cd296ba2a7 | 282 | #define listGET_END_MARKER( pxList ) ( ( ListItem_t const * ) ( &( ( pxList )->xListEnd ) ) ) |
| fep | 0:62cd296ba2a7 | 283 | |
| fep | 0:62cd296ba2a7 | 284 | /* |
| fep | 0:62cd296ba2a7 | 285 | * Access macro to determine if a list contains any items. The macro will |
| fep | 0:62cd296ba2a7 | 286 | * only have the value true if the list is empty. |
| fep | 0:62cd296ba2a7 | 287 | * |
| fep | 0:62cd296ba2a7 | 288 | * \page listLIST_IS_EMPTY listLIST_IS_EMPTY |
| fep | 0:62cd296ba2a7 | 289 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 290 | */ |
| fep | 0:62cd296ba2a7 | 291 | #define listLIST_IS_EMPTY( pxList ) ( ( BaseType_t ) ( ( pxList )->uxNumberOfItems == ( UBaseType_t ) 0 ) ) |
| fep | 0:62cd296ba2a7 | 292 | |
| fep | 0:62cd296ba2a7 | 293 | /* |
| fep | 0:62cd296ba2a7 | 294 | * Access macro to return the number of items in the list. |
| fep | 0:62cd296ba2a7 | 295 | */ |
| fep | 0:62cd296ba2a7 | 296 | #define listCURRENT_LIST_LENGTH( pxList ) ( ( pxList )->uxNumberOfItems ) |
| fep | 0:62cd296ba2a7 | 297 | |
| fep | 0:62cd296ba2a7 | 298 | /* |
| fep | 0:62cd296ba2a7 | 299 | * Access function to obtain the owner of the next entry in a list. |
| fep | 0:62cd296ba2a7 | 300 | * |
| fep | 0:62cd296ba2a7 | 301 | * The list member pxIndex is used to walk through a list. Calling |
| fep | 0:62cd296ba2a7 | 302 | * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list |
| fep | 0:62cd296ba2a7 | 303 | * and returns that entry's pxOwner parameter. Using multiple calls to this |
| fep | 0:62cd296ba2a7 | 304 | * function it is therefore possible to move through every item contained in |
| fep | 0:62cd296ba2a7 | 305 | * a list. |
| fep | 0:62cd296ba2a7 | 306 | * |
| fep | 0:62cd296ba2a7 | 307 | * The pxOwner parameter of a list item is a pointer to the object that owns |
| fep | 0:62cd296ba2a7 | 308 | * the list item. In the scheduler this is normally a task control block. |
| fep | 0:62cd296ba2a7 | 309 | * The pxOwner parameter effectively creates a two way link between the list |
| fep | 0:62cd296ba2a7 | 310 | * item and its owner. |
| fep | 0:62cd296ba2a7 | 311 | * |
| fep | 0:62cd296ba2a7 | 312 | * @param pxTCB pxTCB is set to the address of the owner of the next list item. |
| fep | 0:62cd296ba2a7 | 313 | * @param pxList The list from which the next item owner is to be returned. |
| fep | 0:62cd296ba2a7 | 314 | * |
| fep | 0:62cd296ba2a7 | 315 | * \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY |
| fep | 0:62cd296ba2a7 | 316 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 317 | */ |
| fep | 0:62cd296ba2a7 | 318 | #define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList ) \ |
| fep | 0:62cd296ba2a7 | 319 | { \ |
| fep | 0:62cd296ba2a7 | 320 | List_t * const pxConstList = ( pxList ); \ |
| fep | 0:62cd296ba2a7 | 321 | /* Increment the index to the next item and return the item, ensuring */ \ |
| fep | 0:62cd296ba2a7 | 322 | /* we don't return the marker used at the end of the list. */ \ |
| fep | 0:62cd296ba2a7 | 323 | ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \ |
| fep | 0:62cd296ba2a7 | 324 | if( ( void * ) ( pxConstList )->pxIndex == ( void * ) &( ( pxConstList )->xListEnd ) ) \ |
| fep | 0:62cd296ba2a7 | 325 | { \ |
| fep | 0:62cd296ba2a7 | 326 | ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext; \ |
| fep | 0:62cd296ba2a7 | 327 | } \ |
| fep | 0:62cd296ba2a7 | 328 | ( pxTCB ) = ( pxConstList )->pxIndex->pvOwner; \ |
| fep | 0:62cd296ba2a7 | 329 | } |
| fep | 0:62cd296ba2a7 | 330 | |
| fep | 0:62cd296ba2a7 | 331 | |
| fep | 0:62cd296ba2a7 | 332 | /* |
| fep | 0:62cd296ba2a7 | 333 | * Access function to obtain the owner of the first entry in a list. Lists |
| fep | 0:62cd296ba2a7 | 334 | * are normally sorted in ascending item value order. |
| fep | 0:62cd296ba2a7 | 335 | * |
| fep | 0:62cd296ba2a7 | 336 | * This function returns the pxOwner member of the first item in the list. |
| fep | 0:62cd296ba2a7 | 337 | * The pxOwner parameter of a list item is a pointer to the object that owns |
| fep | 0:62cd296ba2a7 | 338 | * the list item. In the scheduler this is normally a task control block. |
| fep | 0:62cd296ba2a7 | 339 | * The pxOwner parameter effectively creates a two way link between the list |
| fep | 0:62cd296ba2a7 | 340 | * item and its owner. |
| fep | 0:62cd296ba2a7 | 341 | * |
| fep | 0:62cd296ba2a7 | 342 | * @param pxList The list from which the owner of the head item is to be |
| fep | 0:62cd296ba2a7 | 343 | * returned. |
| fep | 0:62cd296ba2a7 | 344 | * |
| fep | 0:62cd296ba2a7 | 345 | * \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY |
| fep | 0:62cd296ba2a7 | 346 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 347 | */ |
| fep | 0:62cd296ba2a7 | 348 | #define listGET_OWNER_OF_HEAD_ENTRY( pxList ) ( (&( ( pxList )->xListEnd ))->pxNext->pvOwner ) |
| fep | 0:62cd296ba2a7 | 349 | |
| fep | 0:62cd296ba2a7 | 350 | /* |
| fep | 0:62cd296ba2a7 | 351 | * Check to see if a list item is within a list. The list item maintains a |
| fep | 0:62cd296ba2a7 | 352 | * "container" pointer that points to the list it is in. All this macro does |
| fep | 0:62cd296ba2a7 | 353 | * is check to see if the container and the list match. |
| fep | 0:62cd296ba2a7 | 354 | * |
| fep | 0:62cd296ba2a7 | 355 | * @param pxList The list we want to know if the list item is within. |
| fep | 0:62cd296ba2a7 | 356 | * @param pxListItem The list item we want to know if is in the list. |
| fep | 0:62cd296ba2a7 | 357 | * @return pdTRUE if the list item is in the list, otherwise pdFALSE. |
| fep | 0:62cd296ba2a7 | 358 | */ |
| fep | 0:62cd296ba2a7 | 359 | #define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( BaseType_t ) ( ( pxListItem )->pvContainer == ( void * ) ( pxList ) ) ) |
| fep | 0:62cd296ba2a7 | 360 | |
| fep | 0:62cd296ba2a7 | 361 | /* |
| fep | 0:62cd296ba2a7 | 362 | * Return the list a list item is contained within (referenced from). |
| fep | 0:62cd296ba2a7 | 363 | * |
| fep | 0:62cd296ba2a7 | 364 | * @param pxListItem The list item being queried. |
| fep | 0:62cd296ba2a7 | 365 | * @return A pointer to the List_t object that references the pxListItem |
| fep | 0:62cd296ba2a7 | 366 | */ |
| fep | 0:62cd296ba2a7 | 367 | #define listLIST_ITEM_CONTAINER( pxListItem ) ( ( pxListItem )->pvContainer ) |
| fep | 0:62cd296ba2a7 | 368 | |
| fep | 0:62cd296ba2a7 | 369 | /* |
| fep | 0:62cd296ba2a7 | 370 | * This provides a crude means of knowing if a list has been initialised, as |
| fep | 0:62cd296ba2a7 | 371 | * pxList->xListEnd.xItemValue is set to portMAX_DELAY by the vListInitialise() |
| fep | 0:62cd296ba2a7 | 372 | * function. |
| fep | 0:62cd296ba2a7 | 373 | */ |
| fep | 0:62cd296ba2a7 | 374 | #define listLIST_IS_INITIALISED( pxList ) ( ( pxList )->xListEnd.xItemValue == portMAX_DELAY ) |
| fep | 0:62cd296ba2a7 | 375 | |
| fep | 0:62cd296ba2a7 | 376 | /* |
| fep | 0:62cd296ba2a7 | 377 | * Must be called before a list is used! This initialises all the members |
| fep | 0:62cd296ba2a7 | 378 | * of the list structure and inserts the xListEnd item into the list as a |
| fep | 0:62cd296ba2a7 | 379 | * marker to the back of the list. |
| fep | 0:62cd296ba2a7 | 380 | * |
| fep | 0:62cd296ba2a7 | 381 | * @param pxList Pointer to the list being initialised. |
| fep | 0:62cd296ba2a7 | 382 | * |
| fep | 0:62cd296ba2a7 | 383 | * \page vListInitialise vListInitialise |
| fep | 0:62cd296ba2a7 | 384 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 385 | */ |
| fep | 0:62cd296ba2a7 | 386 | void vListInitialise( List_t * const pxList ) PRIVILEGED_FUNCTION; |
| fep | 0:62cd296ba2a7 | 387 | |
| fep | 0:62cd296ba2a7 | 388 | /* |
| fep | 0:62cd296ba2a7 | 389 | * Must be called before a list item is used. This sets the list container to |
| fep | 0:62cd296ba2a7 | 390 | * null so the item does not think that it is already contained in a list. |
| fep | 0:62cd296ba2a7 | 391 | * |
| fep | 0:62cd296ba2a7 | 392 | * @param pxItem Pointer to the list item being initialised. |
| fep | 0:62cd296ba2a7 | 393 | * |
| fep | 0:62cd296ba2a7 | 394 | * \page vListInitialiseItem vListInitialiseItem |
| fep | 0:62cd296ba2a7 | 395 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 396 | */ |
| fep | 0:62cd296ba2a7 | 397 | void vListInitialiseItem( ListItem_t * const pxItem ) PRIVILEGED_FUNCTION; |
| fep | 0:62cd296ba2a7 | 398 | |
| fep | 0:62cd296ba2a7 | 399 | /* |
| fep | 0:62cd296ba2a7 | 400 | * Insert a list item into a list. The item will be inserted into the list in |
| fep | 0:62cd296ba2a7 | 401 | * a position determined by its item value (descending item value order). |
| fep | 0:62cd296ba2a7 | 402 | * |
| fep | 0:62cd296ba2a7 | 403 | * @param pxList The list into which the item is to be inserted. |
| fep | 0:62cd296ba2a7 | 404 | * |
| fep | 0:62cd296ba2a7 | 405 | * @param pxNewListItem The item that is to be placed in the list. |
| fep | 0:62cd296ba2a7 | 406 | * |
| fep | 0:62cd296ba2a7 | 407 | * \page vListInsert vListInsert |
| fep | 0:62cd296ba2a7 | 408 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 409 | */ |
| fep | 0:62cd296ba2a7 | 410 | void vListInsert( List_t * const pxList, ListItem_t * const pxNewListItem ) PRIVILEGED_FUNCTION; |
| fep | 0:62cd296ba2a7 | 411 | |
| fep | 0:62cd296ba2a7 | 412 | /* |
| fep | 0:62cd296ba2a7 | 413 | * Insert a list item into a list. The item will be inserted in a position |
| fep | 0:62cd296ba2a7 | 414 | * such that it will be the last item within the list returned by multiple |
| fep | 0:62cd296ba2a7 | 415 | * calls to listGET_OWNER_OF_NEXT_ENTRY. |
| fep | 0:62cd296ba2a7 | 416 | * |
| fep | 0:62cd296ba2a7 | 417 | * The list member pxIndex is used to walk through a list. Calling |
| fep | 0:62cd296ba2a7 | 418 | * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list. |
| fep | 0:62cd296ba2a7 | 419 | * Placing an item in a list using vListInsertEnd effectively places the item |
| fep | 0:62cd296ba2a7 | 420 | * in the list position pointed to by pxIndex. This means that every other |
| fep | 0:62cd296ba2a7 | 421 | * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before |
| fep | 0:62cd296ba2a7 | 422 | * the pxIndex parameter again points to the item being inserted. |
| fep | 0:62cd296ba2a7 | 423 | * |
| fep | 0:62cd296ba2a7 | 424 | * @param pxList The list into which the item is to be inserted. |
| fep | 0:62cd296ba2a7 | 425 | * |
| fep | 0:62cd296ba2a7 | 426 | * @param pxNewListItem The list item to be inserted into the list. |
| fep | 0:62cd296ba2a7 | 427 | * |
| fep | 0:62cd296ba2a7 | 428 | * \page vListInsertEnd vListInsertEnd |
| fep | 0:62cd296ba2a7 | 429 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 430 | */ |
| fep | 0:62cd296ba2a7 | 431 | void vListInsertEnd( List_t * const pxList, ListItem_t * const pxNewListItem ) PRIVILEGED_FUNCTION; |
| fep | 0:62cd296ba2a7 | 432 | |
| fep | 0:62cd296ba2a7 | 433 | /* |
| fep | 0:62cd296ba2a7 | 434 | * Remove an item from a list. The list item has a pointer to the list that |
| fep | 0:62cd296ba2a7 | 435 | * it is in, so only the list item need be passed into the function. |
| fep | 0:62cd296ba2a7 | 436 | * |
| fep | 0:62cd296ba2a7 | 437 | * @param uxListRemove The item to be removed. The item will remove itself from |
| fep | 0:62cd296ba2a7 | 438 | * the list pointed to by it's pxContainer parameter. |
| fep | 0:62cd296ba2a7 | 439 | * |
| fep | 0:62cd296ba2a7 | 440 | * @return The number of items that remain in the list after the list item has |
| fep | 0:62cd296ba2a7 | 441 | * been removed. |
| fep | 0:62cd296ba2a7 | 442 | * |
| fep | 0:62cd296ba2a7 | 443 | * \page uxListRemove uxListRemove |
| fep | 0:62cd296ba2a7 | 444 | * \ingroup LinkedList |
| fep | 0:62cd296ba2a7 | 445 | */ |
| fep | 0:62cd296ba2a7 | 446 | UBaseType_t uxListRemove( ListItem_t * const pxItemToRemove ) PRIVILEGED_FUNCTION; |
| fep | 0:62cd296ba2a7 | 447 | |
| fep | 0:62cd296ba2a7 | 448 | #ifdef __cplusplus |
| fep | 0:62cd296ba2a7 | 449 | } |
| fep | 0:62cd296ba2a7 | 450 | #endif |
| fep | 0:62cd296ba2a7 | 451 | |
| fep | 0:62cd296ba2a7 | 452 | #endif |
| fep | 0:62cd296ba2a7 | 453 | |
| fep | 0:62cd296ba2a7 | 454 |