/*
|
/*
|
FreeRTOS.org V4.2.0 - Copyright (C) 2003-2007 Richard Barry.
|
FreeRTOS.org V4.2.0 - Copyright (C) 2003-2007 Richard Barry.
|
|
|
This file is part of the FreeRTOS.org distribution.
|
This file is part of the FreeRTOS.org distribution.
|
|
|
FreeRTOS.org is free software; you can redistribute it and/or modify
|
FreeRTOS.org is free software; you can redistribute it and/or modify
|
it under the terms of the GNU General Public License as published by
|
it under the terms of the GNU General Public License as published by
|
the Free Software Foundation; either version 2 of the License, or
|
the Free Software Foundation; either version 2 of the License, or
|
(at your option) any later version.
|
(at your option) any later version.
|
|
|
FreeRTOS.org is distributed in the hope that it will be useful,
|
FreeRTOS.org is distributed in the hope that it will be useful,
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
GNU General Public License for more details.
|
GNU General Public License for more details.
|
|
|
You should have received a copy of the GNU General Public License
|
You should have received a copy of the GNU General Public License
|
along with FreeRTOS.org; if not, write to the Free Software
|
along with FreeRTOS.org; if not, write to the Free Software
|
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
|
A special exception to the GPL can be applied should you wish to distribute
|
A special exception to the GPL can be applied should you wish to distribute
|
a combined work that includes FreeRTOS.org, without being obliged to provide
|
a combined work that includes FreeRTOS.org, without being obliged to provide
|
the source code for any proprietary components. See the licensing section
|
the source code for any proprietary components. See the licensing section
|
of http://www.FreeRTOS.org for full details of how and when the exception
|
of http://www.FreeRTOS.org for full details of how and when the exception
|
can be applied.
|
can be applied.
|
|
|
***************************************************************************
|
***************************************************************************
|
See http://www.FreeRTOS.org for documentation, latest information, license
|
See http://www.FreeRTOS.org for documentation, latest information, license
|
and contact details. Please ensure to read the configuration and relevant
|
and contact details. Please ensure to read the configuration and relevant
|
port sections of the online documentation.
|
port sections of the online documentation.
|
***************************************************************************
|
***************************************************************************
|
*/
|
*/
|
|
|
/*
|
/*
|
* This is the list implementation used by the scheduler. While it is tailored
|
* This is the list implementation used by the scheduler. While it is tailored
|
* heavily for the schedulers needs, it is also available for use by
|
* heavily for the schedulers needs, it is also available for use by
|
* application code.
|
* application code.
|
*
|
*
|
* xLists can only store pointers to xListItems. Each xListItem contains a
|
* xLists can only store pointers to xListItems. Each xListItem contains a
|
* numeric value (xItemValue). Most of the time the lists are sorted in
|
* numeric value (xItemValue). Most of the time the lists are sorted in
|
* descending item value order.
|
* descending item value order.
|
*
|
*
|
* Lists are created already containing one list item. The value of this
|
* Lists are created already containing one list item. The value of this
|
* item is the maximum possible that can be stored, it is therefore always at
|
* item is the maximum possible that can be stored, it is therefore always at
|
* the end of the list and acts as a marker. The list member pxHead always
|
* the end of the list and acts as a marker. The list member pxHead always
|
* points to this marker - even though it is at the tail of the list. This
|
* points to this marker - even though it is at the tail of the list. This
|
* is because the tail contains a wrap back pointer to the true head of
|
* is because the tail contains a wrap back pointer to the true head of
|
* the list.
|
* the list.
|
*
|
*
|
* In addition to it's value, each list item contains a pointer to the next
|
* In addition to it's value, each list item contains a pointer to the next
|
* item in the list (pxNext), a pointer to the list it is in (pxContainer)
|
* item in the list (pxNext), a pointer to the list it is in (pxContainer)
|
* and a pointer to back to the object that contains it. These later two
|
* and a pointer to back to the object that contains it. These later two
|
* pointers are included for efficiency of list manipulation. There is
|
* pointers are included for efficiency of list manipulation. There is
|
* effectively a two way link between the object containing the list item and
|
* effectively a two way link between the object containing the list item and
|
* the list item itself.
|
* the list item itself.
|
*
|
*
|
*
|
*
|
* \page ListIntroduction List Implementation
|
* \page ListIntroduction List Implementation
|
* \ingroup FreeRTOSIntro
|
* \ingroup FreeRTOSIntro
|
*/
|
*/
|
|
|
|
|
#ifndef LIST_H
|
#ifndef LIST_H
|
#define LIST_H
|
#define LIST_H
|
|
|
/*
|
/*
|
* Definition of the only type of object that a list can contain.
|
* Definition of the only type of object that a list can contain.
|
*/
|
*/
|
struct xLIST_ITEM
|
struct xLIST_ITEM
|
{
|
{
|
portTickType xItemValue; /*< The value being listed. In most cases this is used to sort the list in descending order. */
|
portTickType xItemValue; /*< The value being listed. In most cases this is used to sort the list in descending order. */
|
volatile struct xLIST_ITEM * pxNext; /*< Pointer to the next xListItem in the list. */
|
volatile struct xLIST_ITEM * pxNext; /*< Pointer to the next xListItem in the list. */
|
volatile struct xLIST_ITEM * pxPrevious;/*< Pointer to the previous xListItem in the list. */
|
volatile struct xLIST_ITEM * pxPrevious;/*< Pointer to the previous xListItem in the list. */
|
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. */
|
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. */
|
void * pvContainer; /*< Pointer to the list in which this list item is placed (if any). */
|
void * pvContainer; /*< Pointer to the list in which this list item is placed (if any). */
|
};
|
};
|
typedef struct xLIST_ITEM xListItem; /* For some reason lint wants this as two separate definitions. */
|
typedef struct xLIST_ITEM xListItem; /* For some reason lint wants this as two separate definitions. */
|
|
|
struct xMINI_LIST_ITEM
|
struct xMINI_LIST_ITEM
|
{
|
{
|
portTickType xItemValue;
|
portTickType xItemValue;
|
volatile struct xLIST_ITEM *pxNext;
|
volatile struct xLIST_ITEM *pxNext;
|
volatile struct xLIST_ITEM *pxPrevious;
|
volatile struct xLIST_ITEM *pxPrevious;
|
};
|
};
|
typedef struct xMINI_LIST_ITEM xMiniListItem;
|
typedef struct xMINI_LIST_ITEM xMiniListItem;
|
|
|
/*
|
/*
|
* Definition of the type of queue used by the scheduler.
|
* Definition of the type of queue used by the scheduler.
|
*/
|
*/
|
typedef struct xLIST
|
typedef struct xLIST
|
{
|
{
|
volatile unsigned portBASE_TYPE uxNumberOfItems;
|
volatile unsigned portBASE_TYPE uxNumberOfItems;
|
volatile xListItem * pxIndex; /*< Used to walk through the list. Points to the last item returned by a call to pvListGetOwnerOfNextEntry (). */
|
volatile xListItem * pxIndex; /*< Used to walk through the list. Points to the last item returned by a call to pvListGetOwnerOfNextEntry (). */
|
volatile xMiniListItem 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. */
|
volatile xMiniListItem 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. */
|
} xList;
|
} xList;
|
|
|
/*
|
/*
|
* Access macro to set the owner of a list item. The owner of a list item
|
* Access macro to set the owner of a list item. The owner of a list item
|
* is the object (usually a TCB) that contains the list item.
|
* is the object (usually a TCB) that contains the list item.
|
*
|
*
|
* \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER
|
* \page listSET_LIST_ITEM_OWNER listSET_LIST_ITEM_OWNER
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
#define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner ) ( pxListItem )->pvOwner = ( void * ) pxOwner
|
#define listSET_LIST_ITEM_OWNER( pxListItem, pxOwner ) ( pxListItem )->pvOwner = ( void * ) pxOwner
|
|
|
/*
|
/*
|
* Access macro to set the value of the list item. In most cases the value is
|
* Access macro to set the value of the list item. In most cases the value is
|
* used to sort the list in descending order.
|
* used to sort the list in descending order.
|
*
|
*
|
* \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE
|
* \page listSET_LIST_ITEM_VALUE listSET_LIST_ITEM_VALUE
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
#define listSET_LIST_ITEM_VALUE( pxListItem, xValue ) ( pxListItem )->xItemValue = xValue
|
#define listSET_LIST_ITEM_VALUE( pxListItem, xValue ) ( pxListItem )->xItemValue = xValue
|
|
|
/*
|
/*
|
* Access macro the retrieve the value of the list item. The value can
|
* Access macro the retrieve the value of the list item. The value can
|
* represent anything - for example a the priority of a task, or the time at
|
* represent anything - for example a the priority of a task, or the time at
|
* which a task should be unblocked.
|
* which a task should be unblocked.
|
*
|
*
|
* \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE
|
* \page listGET_LIST_ITEM_VALUE listGET_LIST_ITEM_VALUE
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
#define listGET_LIST_ITEM_VALUE( pxListItem ) ( ( pxListItem )->xItemValue )
|
#define listGET_LIST_ITEM_VALUE( pxListItem ) ( ( pxListItem )->xItemValue )
|
|
|
/*
|
/*
|
* Access macro to determine if a list contains any items. The macro will
|
* Access macro to determine if a list contains any items. The macro will
|
* only have the value true if the list is empty.
|
* only have the value true if the list is empty.
|
*
|
*
|
* \page listLIST_IS_EMPTY listLIST_IS_EMPTY
|
* \page listLIST_IS_EMPTY listLIST_IS_EMPTY
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
#define listLIST_IS_EMPTY( pxList ) ( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 )
|
#define listLIST_IS_EMPTY( pxList ) ( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 )
|
|
|
/*
|
/*
|
* Access macro to return the number of items in the list.
|
* Access macro to return the number of items in the list.
|
*/
|
*/
|
#define listCURRENT_LIST_LENGTH( pxList ) ( ( pxList )->uxNumberOfItems )
|
#define listCURRENT_LIST_LENGTH( pxList ) ( ( pxList )->uxNumberOfItems )
|
|
|
/*
|
/*
|
* Access function to obtain the owner of the next entry in a list.
|
* Access function to obtain the owner of the next entry in a list.
|
*
|
*
|
* The list member pxIndex is used to walk through a list. Calling
|
* The list member pxIndex is used to walk through a list. Calling
|
* listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list
|
* listGET_OWNER_OF_NEXT_ENTRY increments pxIndex to the next item in the list
|
* and returns that entries pxOwner parameter. Using multiple calls to this
|
* and returns that entries pxOwner parameter. Using multiple calls to this
|
* function it is therefore possible to move through every item contained in
|
* function it is therefore possible to move through every item contained in
|
* a list.
|
* a list.
|
*
|
*
|
* The pxOwner parameter of a list item is a pointer to the object that owns
|
* The pxOwner parameter of a list item is a pointer to the object that owns
|
* the list item. In the scheduler this is normally a task control block.
|
* the list item. In the scheduler this is normally a task control block.
|
* The pxOwner parameter effectively creates a two way link between the list
|
* The pxOwner parameter effectively creates a two way link between the list
|
* item and its owner.
|
* item and its owner.
|
*
|
*
|
* @param pxList The list from which the next item owner is to be returned.
|
* @param pxList The list from which the next item owner is to be returned.
|
*
|
*
|
* \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY
|
* \page listGET_OWNER_OF_NEXT_ENTRY listGET_OWNER_OF_NEXT_ENTRY
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
#define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList ) \
|
#define listGET_OWNER_OF_NEXT_ENTRY( pxTCB, pxList ) \
|
/* Increment the index to the next item and return the item, ensuring */ \
|
/* Increment the index to the next item and return the item, ensuring */ \
|
/* we don't return the marker used at the end of the list. */ \
|
/* we don't return the marker used at the end of the list. */ \
|
( pxList )->pxIndex = ( pxList )->pxIndex->pxNext; \
|
( pxList )->pxIndex = ( pxList )->pxIndex->pxNext; \
|
if( ( pxList )->pxIndex == ( xListItem * ) &( ( pxList )->xListEnd ) ) \
|
if( ( pxList )->pxIndex == ( xListItem * ) &( ( pxList )->xListEnd ) ) \
|
{ \
|
{ \
|
( pxList )->pxIndex = ( pxList )->pxIndex->pxNext; \
|
( pxList )->pxIndex = ( pxList )->pxIndex->pxNext; \
|
} \
|
} \
|
pxTCB = ( pxList )->pxIndex->pvOwner
|
pxTCB = ( pxList )->pxIndex->pvOwner
|
|
|
|
|
/*
|
/*
|
* Access function to obtain the owner of the first entry in a list. Lists
|
* Access function to obtain the owner of the first entry in a list. Lists
|
* are normally sorted in ascending item value order.
|
* are normally sorted in ascending item value order.
|
*
|
*
|
* This function returns the pxOwner member of the first item in the list.
|
* This function returns the pxOwner member of the first item in the list.
|
* The pxOwner parameter of a list item is a pointer to the object that owns
|
* The pxOwner parameter of a list item is a pointer to the object that owns
|
* the list item. In the scheduler this is normally a task control block.
|
* the list item. In the scheduler this is normally a task control block.
|
* The pxOwner parameter effectively creates a two way link between the list
|
* The pxOwner parameter effectively creates a two way link between the list
|
* item and its owner.
|
* item and its owner.
|
*
|
*
|
* @param pxList The list from which the owner of the head item is to be
|
* @param pxList The list from which the owner of the head item is to be
|
* returned.
|
* returned.
|
*
|
*
|
* \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY
|
* \page listGET_OWNER_OF_HEAD_ENTRY listGET_OWNER_OF_HEAD_ENTRY
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
#define listGET_OWNER_OF_HEAD_ENTRY( pxList ) ( ( pxList->uxNumberOfItems != ( unsigned portBASE_TYPE ) 0 ) ? ( (&( pxList->xListEnd ))->pxNext->pvOwner ) : ( NULL ) )
|
#define listGET_OWNER_OF_HEAD_ENTRY( pxList ) ( ( pxList->uxNumberOfItems != ( unsigned portBASE_TYPE ) 0 ) ? ( (&( pxList->xListEnd ))->pxNext->pvOwner ) : ( NULL ) )
|
|
|
/*
|
/*
|
* Check to see if a list item is within a list. The list item maintains a
|
* Check to see if a list item is within a list. The list item maintains a
|
* "container" pointer that points to the list it is in. All this macro does
|
* "container" pointer that points to the list it is in. All this macro does
|
* is check to see if the container and the list match.
|
* is check to see if the container and the list match.
|
*
|
*
|
* @param pxList The list we want to know if the list item is within.
|
* @param pxList The list we want to know if the list item is within.
|
* @param pxListItem The list item we want to know if is in the list.
|
* @param pxListItem The list item we want to know if is in the list.
|
* @return pdTRUE is the list item is in the list, otherwise pdFALSE.
|
* @return pdTRUE is the list item is in the list, otherwise pdFALSE.
|
* pointer against
|
* pointer against
|
*/
|
*/
|
#define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( pxListItem )->pvContainer == ( void * ) pxList )
|
#define listIS_CONTAINED_WITHIN( pxList, pxListItem ) ( ( pxListItem )->pvContainer == ( void * ) pxList )
|
|
|
/*
|
/*
|
* Must be called before a list is used! This initialises all the members
|
* Must be called before a list is used! This initialises all the members
|
* of the list structure and inserts the xListEnd item into the list as a
|
* of the list structure and inserts the xListEnd item into the list as a
|
* marker to the back of the list.
|
* marker to the back of the list.
|
*
|
*
|
* @param pxList Pointer to the list being initialised.
|
* @param pxList Pointer to the list being initialised.
|
*
|
*
|
* \page vListInitialise vListInitialise
|
* \page vListInitialise vListInitialise
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
void vListInitialise( xList *pxList );
|
void vListInitialise( xList *pxList );
|
|
|
/*
|
/*
|
* Must be called before a list item is used. This sets the list container to
|
* Must be called before a list item is used. This sets the list container to
|
* null so the item does not think that it is already contained in a list.
|
* null so the item does not think that it is already contained in a list.
|
*
|
*
|
* @param pxItem Pointer to the list item being initialised.
|
* @param pxItem Pointer to the list item being initialised.
|
*
|
*
|
* \page vListInitialiseItem vListInitialiseItem
|
* \page vListInitialiseItem vListInitialiseItem
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
void vListInitialiseItem( xListItem *pxItem );
|
void vListInitialiseItem( xListItem *pxItem );
|
|
|
/*
|
/*
|
* Insert a list item into a list. The item will be inserted into the list in
|
* Insert a list item into a list. The item will be inserted into the list in
|
* a position determined by its item value (descending item value order).
|
* a position determined by its item value (descending item value order).
|
*
|
*
|
* @param pxList The list into which the item is to be inserted.
|
* @param pxList The list into which the item is to be inserted.
|
*
|
*
|
* @param pxNewListItem The item to that is to be placed in the list.
|
* @param pxNewListItem The item to that is to be placed in the list.
|
*
|
*
|
* \page vListInsert vListInsert
|
* \page vListInsert vListInsert
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
void vListInsert( xList *pxList, xListItem *pxNewListItem );
|
void vListInsert( xList *pxList, xListItem *pxNewListItem );
|
|
|
/*
|
/*
|
* Insert a list item into a list. The item will be inserted in a position
|
* Insert a list item into a list. The item will be inserted in a position
|
* such that it will be the last item within the list returned by multiple
|
* such that it will be the last item within the list returned by multiple
|
* calls to listGET_OWNER_OF_NEXT_ENTRY.
|
* calls to listGET_OWNER_OF_NEXT_ENTRY.
|
*
|
*
|
* The list member pvIndex is used to walk through a list. Calling
|
* The list member pvIndex is used to walk through a list. Calling
|
* listGET_OWNER_OF_NEXT_ENTRY increments pvIndex to the next item in the list.
|
* listGET_OWNER_OF_NEXT_ENTRY increments pvIndex to the next item in the list.
|
* Placing an item in a list using vListInsertEnd effectively places the item
|
* Placing an item in a list using vListInsertEnd effectively places the item
|
* in the list position pointed to by pvIndex. This means that every other
|
* in the list position pointed to by pvIndex. This means that every other
|
* item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before
|
* item within the list will be returned by listGET_OWNER_OF_NEXT_ENTRY before
|
* the pvIndex parameter again points to the item being inserted.
|
* the pvIndex parameter again points to the item being inserted.
|
*
|
*
|
* @param pxList The list into which the item is to be inserted.
|
* @param pxList The list into which the item is to be inserted.
|
*
|
*
|
* @param pxNewListItem The list item to be inserted into the list.
|
* @param pxNewListItem The list item to be inserted into the list.
|
*
|
*
|
* \page vListInsertEnd vListInsertEnd
|
* \page vListInsertEnd vListInsertEnd
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
void vListInsertEnd( xList *pxList, xListItem *pxNewListItem );
|
void vListInsertEnd( xList *pxList, xListItem *pxNewListItem );
|
|
|
/*
|
/*
|
* Remove an item from a list. The list item has a pointer to the list that
|
* Remove an item from a list. The list item has a pointer to the list that
|
* it is in, so only the list item need be passed into the function.
|
* it is in, so only the list item need be passed into the function.
|
*
|
*
|
* @param vListRemove The item to be removed. The item will remove itself from
|
* @param vListRemove The item to be removed. The item will remove itself from
|
* the list pointed to by it's pxContainer parameter.
|
* the list pointed to by it's pxContainer parameter.
|
*
|
*
|
* \page vListRemove vListRemove
|
* \page vListRemove vListRemove
|
* \ingroup LinkedList
|
* \ingroup LinkedList
|
*/
|
*/
|
void vListRemove( xListItem *pxItemToRemove );
|
void vListRemove( xListItem *pxItemToRemove );
|
|
|
|
|
|
|
#endif
|
#endif
|
|
|
|
|
