Lines Matching full:the
8 * this software and associated documentation files (the "Software"), to deal in
9 * the Software without restriction, including without limitation the rights to
11 * the Software, and to permit persons to whom the Software is furnished to do so,
12 * subject to the following conditions:
14 * The above copyright notice and this permission notice shall be included in all
15 * copies or substantial portions of the Software.
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
19 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
22 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
30 * This is the list implementation used by the scheduler. While it is tailored
31 * heavily for the schedulers needs, it is also available for use by
35 * numeric value (xItemValue). Most of the time the lists are sorted in
38 * Lists are created already containing one list item. The value of this
39 * item is the maximum possible that can be stored, it is therefore always at
40 * the end of the list and acts as a marker. The list member pxHead always
41 * points to this marker - even though it is at the tail of the list. This
42 * is because the tail contains a wrap back pointer to the true head of
43 * the list.
45 * In addition to it's value, each list item contains a pointer to the next
46 * item in the list (pxNext), a pointer to the list it is in (pxContainer)
47 * and a pointer to back to the object that contains it. These later two
49 * effectively a two way link between the object containing the list item and
50 * the list item itself.
66 * The list structure members are modified from within interrupts, and therefore
68 * functionally atomic way (within critical sections of with the scheduler
70 * a volatile variable. Therefore, in all use cases tested so far, the volatile
72 * improvement without adversely affecting functional behaviour. The assembly
73 * instructions generated by the IAR, ARM and GCC compilers when the respective
77 * has not been exercised to any great extend) then it is feasible that the
79 * that a compiler removing essential code because, without the volatile
80 * qualifier on the list structure members and with aggressive cross module
81 * optimisation, the compiler deemed the code unnecessary will result in
82 * complete and obvious failure of the scheduler. If this is ever experienced
83 * then the volatile qualifier can be inserted in the relevant places within the
85 * FreeRTOSConfig.h (as per the example at the bottom of this comment block).
86 * If configLIST_VOLATILE is not defined then the preprocessor directives below
89 * To use volatile list structure members then add the following line to
90 * FreeRTOSConfig.h (without the quotes):
103 /* Macros that can be used to place known values within the list structures,
104 * then check that the known values do not get corrupted during the execution of
105 * the application. These may catch the list data structures being overwritten in
109 /* Define the macros to do nothing. */
121 /* Define macros that add new members into the list structures. */
127 /* Define macros that set the new structure members to known values. */
133 /* Define macros that will assert if one of the structure members does not
141 * Definition of the only type of object that a list can contain.
147 …OLATILE TickType_t xItemValue; /**< The value being listed. In most cases this is used t…
148 …struct xLIST_ITEM * configLIST_VOLATILE pxNext; /**< Pointer to the next ListItem_t in the lis…
149 …xLIST_ITEM * configLIST_VOLATILE pxPrevious; /**< Pointer to the previous ListItem_t in the list. …
150 …r to the object (normally a TCB) that contains the list item. There is therefore a two way link b…
151 …struct xLIST * configLIST_VOLATILE pxContainer; /**< Pointer to the list in which this list it…
170 * Definition of the type of queue used by the scheduler.
176 …ListItem_t * configLIST_VOLATILE pxIndex; /**< Used to walk through the list. Points to the last …
177 … /**< List item that contains the maximum possible item value meaning it is always at t…
182 * Access macro to set the owner of a list item. The owner of a list item
183 * is the object (usually a TCB) that contains the list item.
191 * Access macro to get the owner of a list item. The owner of a list item
192 * is the object (usually a TCB) that contains the list item.
200 * Access macro to set the value of the list item. In most cases the value is
201 * used to sort the list in ascending order.
209 * Access macro to retrieve the value of the list item. The value can
210 * represent anything - for example the priority of a task, or the time at
219 * Access macro to retrieve the value of the list item at the head of a given
228 * Return the list item at the head of the list.
236 * Return the next list item.
244 * Return the list item that marks the end of the list
252 * Access macro to determine if a list contains any items. The macro will
253 * only have the value true if the list is empty.
261 * Access macro to return the number of items in the list.
266 * Access function to obtain the owner of the next entry in a list.
268 * The list member pxIndex is used to walk through a list. Calling
269 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list
274 * The pxOwner parameter of a list item is a pointer to the object that owns
275 * the list item. In the scheduler this is normally a task control block.
276 * The pxOwner parameter effectively creates a two way link between the list
279 * @param pxTCB pxTCB is set to the address of the owner of the next list item.
280 * @param pxList The list from which the next item owner is to be returned.
288 /* Increment the index to the next item and return the item, ensuring */ \
289 /* we don't return the marker used at the end of the list. */ \
302 * Remove an item from a list. The list item has a pointer to the list that
303 * it is in, so only the list item need be passed into the function.
305 * @param uxListRemove The item to be removed. The item will remove itself from
306 * the list pointed to by it's pxContainer parameter.
308 * @return The number of items that remain in the list after the list item has
316 /* The list item knows which list it is in. Obtain the list from the list \
322 /* Make sure the index is left pointing to a valid item. */ \
336 * Insert a list item into a list. The item will be inserted in a position
337 * such that it will be the last item within the list returned by multiple
340 * The list member pxIndex is used to walk through a list. Calling
341 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list.
342 * Placing an item in a list using vListInsertEnd effectively places the item
343 * in the list position pointed to by pxIndex. This means that every other
344 * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before
345 * the pxIndex parameter again points to the item being inserted.
347 * @param pxList The list into which the item is to be inserted.
349 * @param pxNewListItem The list item to be inserted into the list.
359 * the list data structures being overwritten in memory. They will not catch \
364 /* Insert a new list item into ( pxList ), but rather than sort the list, \
365 * makes the new list item the last item to be removed by a call to \
373 /* Remember which list the item is in. */ \
380 * Access function to obtain the owner of the first entry in a list. Lists
383 * This function returns the pxOwner member of the first item in the list.
384 * The pxOwner parameter of a list item is a pointer to the object that owns
385 * the list item. In the scheduler this is normally a task control block.
386 * The pxOwner parameter effectively creates a two way link between the list
389 * @param pxList The list from which the owner of the head item is to be
398 * Check to see if a list item is within a list. The list item maintains a
399 * "container" pointer that points to the list it is in. All this macro does
400 * is check to see if the container and the list match.
402 * @param pxList The list we want to know if the list item is within.
403 * @param pxListItem The list item we want to know if is in the list.
404 * @return pdTRUE if the list item is in the list, otherwise pdFALSE.
409 * Return the list a list item is contained within (referenced from).
411 * @param pxListItem The list item being queried.
412 * @return A pointer to the List_t object that references the pxListItem
418 * pxList->xListEnd.xItemValue is set to portMAX_DELAY by the vListInitialise()
424 * Must be called before a list is used! This initialises all the members
425 * of the list structure and inserts the xListEnd item into the list as a
426 * marker to the back of the list.
428 * @param pxList Pointer to the list being initialised.
436 * Must be called before a list item is used. This sets the list container to
437 * null so the item does not think that it is already contained in a list.
439 * @param pxItem Pointer to the list item being initialised.
447 * Insert a list item into a list. The item will be inserted into the list in
450 * @param pxList The list into which the item is to be inserted.
452 * @param pxNewListItem The item that is to be placed in the list.
461 * Insert a list item into a list. The item will be inserted in a position
462 * such that it will be the last item within the list returned by multiple
465 * The list member pxIndex is used to walk through a list. Calling
466 * listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list.
467 * Placing an item in a list using vListInsertEnd effectively places the item
468 * in the list position pointed to by pxIndex. This means that every other
469 * item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before
470 * the pxIndex parameter again points to the item being inserted.
472 * @param pxList The list into which the item is to be inserted.
474 * @param pxNewListItem The list item to be inserted into the list.
483 * Remove an item from a list. The list item has a pointer to the list that
484 * it is in, so only the list item need be passed into the function.
486 * @param uxListRemove The item to be removed. The item will remove itself from
487 * the list pointed to by it's pxContainer parameter.
489 * @return The number of items that remain in the list after the list item has