list.h File Reference

Go to the source code of this file.

Data Structures
struct	xLIST
struct	xLIST_ITEM
struct	xMINI_LIST_ITEM
Defines
#define	listCURRENT_LIST_LENGTH(pxList)   ( ( pxList )->uxNumberOfItems )
#define	listGET_LIST_ITEM_VALUE(pxListItem)   ( ( pxListItem )->xItemValue )
#define	listGET_OWNER_OF_HEAD_ENTRY(pxList)   ( ( pxList->uxNumberOfItems != ( unsigned portBASE_TYPE ) 0 ) ? ( (&( pxList->xListEnd ))->pxNext->pvOwner ) : ( NULL ) )
#define	listGET_OWNER_OF_NEXT_ENTRY(pxTCB, pxList)
#define	listIS_CONTAINED_WITHIN(pxList, pxListItem)   ( ( pxListItem )->pvContainer == ( void * ) pxList )
#define	listLIST_IS_EMPTY(pxList)   ( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 )
#define	listSET_LIST_ITEM_OWNER(pxListItem, pxOwner)   ( pxListItem )->pvOwner = ( void * ) pxOwner
#define	listSET_LIST_ITEM_VALUE(pxListItem, xValue)   ( pxListItem )->xItemValue = xValue
Typedefs
typedef struct xLIST	xList
typedef struct xLIST_ITEM	xListItem
typedef struct xMINI_LIST_ITEM	xMiniListItem
Functions
void	vListInitialise (xList *pxList)
void	vListInitialiseItem (xListItem *pxItem)
void	vListInsert (xList *pxList, xListItem *pxNewListItem)
void	vListInsertEnd (xList *pxList, xListItem *pxNewListItem)
void	vListRemove (xListItem *pxItemToRemove)

---

Define Documentation

#define listCURRENT_LIST_LENGTH

(

pxList

)

( ( pxList )->uxNumberOfItems )

Definition at line 166 of file list.h.

Referenced by portTASK_FUNCTION().

#define listGET_LIST_ITEM_VALUE

(

pxListItem

)

( ( pxListItem )->xItemValue )

Definition at line 152 of file list.h.

Referenced by prvCheckDelayedList().

#define listGET_OWNER_OF_HEAD_ENTRY

(

pxList

)

( ( pxList->uxNumberOfItems != ( unsigned portBASE_TYPE ) 0 ) ? ( (&( pxList->xListEnd ))->pxNext->pvOwner ) : ( NULL ) )

Definition at line 217 of file list.h.

Referenced by prvCheckDelayedList(), prvCheckPendingReadyList(), prvCheckTasksWaitingTermination(), xCoRoutineRemoveFromEventList(), xTaskRemoveFromEventList(), and xTaskResumeAll().

#define listGET_OWNER_OF_NEXT_ENTRY	(	pxTCB,
		pxList		)

Value:

{                                                                                       \
xList * const pxConstList = pxList;                                                     \
    /* 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.  */                      \
    ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext;                        \
    if( ( pxConstList )->pxIndex == ( xListItem * ) &( ( pxConstList )->xListEnd ) )    \
    {                                                                                   \
        ( pxConstList )->pxIndex = ( pxConstList )->pxIndex->pxNext;                    \
    }                                                                                   \
    pxTCB = ( pxConstList )->pxIndex->pvOwner;                                          \
}

Definition at line 187 of file list.h.

Referenced by vCoRoutineSchedule(), and vTaskSwitchContext().

#define listIS_CONTAINED_WITHIN	(	pxList,
		pxListItem		)	( ( pxListItem )->pvContainer == ( void * ) pxList )

Definition at line 229 of file list.h.

#define listLIST_IS_EMPTY

(

pxList

)

( ( pxList )->uxNumberOfItems == ( unsigned portBASE_TYPE ) 0 )

Definition at line 161 of file list.h.

Referenced by prvCheckPendingReadyList(), prvCheckTasksWaitingTermination(), prvUnlockQueue(), vCoRoutineSchedule(), vTaskSwitchContext(), xQueueGenericReceive(), xQueueGenericSend(), xQueueGenericSendFromISR(), and xQueueReceiveFromISR().

#define listSET_LIST_ITEM_OWNER	(	pxListItem,
		pxOwner		)	( pxListItem )->pvOwner = ( void * ) pxOwner

Definition at line 133 of file list.h.

Referenced by prvInitialiseTCBVariables(), and xCoRoutineCreate().

#define listSET_LIST_ITEM_VALUE	(	pxListItem,
		xValue		)	( pxListItem )->xItemValue = xValue

Definition at line 142 of file list.h.

Referenced by prvInitialiseTCBVariables(), vCoRoutineAddToDelayedList(), vTaskPlaceOnEventList(), and xCoRoutineCreate().

---

Typedef Documentation

typedef struct xLIST xList

typedef struct xLIST_ITEM xListItem

Definition at line 106 of file list.h.

typedef struct xMINI_LIST_ITEM xMiniListItem

Definition at line 114 of file list.h.

---

Function Documentation

void vListInitialise

(

xList *

pxList

)

Definition at line 63 of file list.c.

References portMAX_DELAY, xLIST::pxIndex, xMINI_LIST_ITEM::pxNext, xMINI_LIST_ITEM::pxPrevious, xLIST::uxNumberOfItems, xMINI_LIST_ITEM::xItemValue, and xLIST::xListEnd.

Referenced by prvInitialiseCoRoutineLists(), and prvInitialiseTaskLists().

{
    /* The list structure contains a list item which is used to mark the
    end of the list.  To initialise the list the list end is inserted
    as the only list entry. */
    pxList->pxIndex = ( xListItem * ) &( pxList->xListEnd );

    /* The list end value is the highest possible value in the list to
    ensure it remains at the end of the list. */
    pxList->xListEnd.xItemValue = portMAX_DELAY;

    /* The list end next and previous pointers point to itself so we know
    when the list is empty. */
    pxList->xListEnd.pxNext = ( xListItem * ) &( pxList->xListEnd );
    pxList->xListEnd.pxPrevious = ( xListItem * ) &( pxList->xListEnd );

    pxList->uxNumberOfItems = 0;
}

void vListInitialiseItem

(

xListItem *

pxItem

)

Definition at line 83 of file list.c.

References xLIST_ITEM::pvContainer.

Referenced by prvInitialiseTCBVariables(), and xCoRoutineCreate().

{
    /* Make sure the list item is not recorded as being on a list. */
    pxItem->pvContainer = NULL;
}

void vListInsert	(	xList *	pxList,
		xListItem *	pxNewListItem
	)

Definition at line 113 of file list.c.

References portMAX_DELAY, xLIST_ITEM::pvContainer, xLIST_ITEM::pxNext, xLIST_ITEM::pxPrevious, xMINI_LIST_ITEM::pxPrevious, xLIST::uxNumberOfItems, xLIST_ITEM::xItemValue, and xLIST::xListEnd.

Referenced by vCoRoutineAddToDelayedList(), and vTaskPlaceOnEventList().

{
volatile xListItem *pxIterator;
portTickType xValueOfInsertion;

    /* Insert the new list item into the list, sorted in ulListItem order. */
    xValueOfInsertion = pxNewListItem->xItemValue;

    /* If the list already contains a list item with the same item value then
    the new list item should be placed after it.  This ensures that TCB's which
    are stored in ready lists (all of which have the same ulListItem value)
    get an equal share of the CPU.  However, if the xItemValue is the same as 
    the back marker the iteration loop below will not end.  This means we need
    to guard against this by checking the value first and modifying the 
    algorithm slightly if necessary. */
    if( xValueOfInsertion == portMAX_DELAY )
    {
        pxIterator = pxList->xListEnd.pxPrevious;
    }
    else
    {
        /* *** NOTE ***********************************************************
        If you find your application is crashing here then likely causes are:
            1) Stack overflow - 
               see http://www.freertos.org/Stacks-and-stack-overflow-checking.html
            2) Incorrect interrupt priority assignment, especially on Cortex M3 
               parts where numerically high priority values denote low actual 
               interrupt priories, which can seem counter intuitive.  See 
               configMAX_SYSCALL_INTERRUPT_PRIORITY on http://www.freertos.org/a00110.html
            3) Calling an API function from within a critical section or when
               the scheduler is suspended.
            4) Using a queue or semaphore before it has been initialised or
               before the scheduler has been started (are interrupts firing
               before vTaskStartScheduler() has been called?).
        See http://www.freertos.org/FAQHelp.html for more tips. 
        **********************************************************************/
        
        for( pxIterator = ( xListItem * ) &( pxList->xListEnd ); pxIterator->pxNext->xItemValue <= xValueOfInsertion; pxIterator = pxIterator->pxNext )
        {
            /* There is nothing to do here, we are just iterating to the
            wanted insertion position. */
        }
    }

    pxNewListItem->pxNext = pxIterator->pxNext;
    pxNewListItem->pxNext->pxPrevious = ( volatile xListItem * ) pxNewListItem;
    pxNewListItem->pxPrevious = pxIterator;
    pxIterator->pxNext = ( volatile xListItem * ) pxNewListItem;

    /* Remember which list the item is in.  This allows fast removal of the
    item later. */
    pxNewListItem->pvContainer = ( void * ) pxList;

    ( pxList->uxNumberOfItems )++;
}

void vListInsertEnd	(	xList *	pxList,
		xListItem *	pxNewListItem
	)

Definition at line 90 of file list.c.

References xLIST_ITEM::pvContainer, xLIST::pxIndex, xLIST_ITEM::pxNext, xLIST_ITEM::pxPrevious, and xLIST::uxNumberOfItems.

Referenced by vTaskPlaceOnEventList(), xCoRoutineRemoveFromEventList(), and xTaskRemoveFromEventList().

{
volatile xListItem * pxIndex;

    /* Insert a new list item into pxList, but rather than sort the list,
    makes the new list item the last item to be removed by a call to
    pvListGetOwnerOfNextEntry.  This means it has to be the item pointed to by
    the pxIndex member. */
    pxIndex = pxList->pxIndex;

    pxNewListItem->pxNext = pxIndex->pxNext;
    pxNewListItem->pxPrevious = pxList->pxIndex;
    pxIndex->pxNext->pxPrevious = ( volatile xListItem * ) pxNewListItem;
    pxIndex->pxNext = ( volatile xListItem * ) pxNewListItem;
    pxList->pxIndex = ( volatile xListItem * ) pxNewListItem;

    /* Remember which list the item is in. */
    pxNewListItem->pvContainer = ( void * ) pxList;

    ( pxList->uxNumberOfItems )++;
}

void vListRemove

(

xListItem *

pxItemToRemove

)

Definition at line 170 of file list.c.

References xLIST_ITEM::pvContainer, xLIST::pxIndex, xLIST_ITEM::pxNext, xLIST_ITEM::pxPrevious, and xLIST::uxNumberOfItems.

Referenced by prvCheckDelayedList(), prvCheckPendingReadyList(), prvCheckTasksWaitingTermination(), vCoRoutineAddToDelayedList(), vTaskPlaceOnEventList(), xCoRoutineRemoveFromEventList(), xTaskRemoveFromEventList(), and xTaskResumeAll().

{
xList * pxList;

    pxItemToRemove->pxNext->pxPrevious = pxItemToRemove->pxPrevious;
    pxItemToRemove->pxPrevious->pxNext = pxItemToRemove->pxNext;
    
    /* The list item knows which list it is in.  Obtain the list from the list
    item. */
    pxList = ( xList * ) pxItemToRemove->pvContainer;

    /* Make sure the index is left pointing to a valid item. */
    if( pxList->pxIndex == pxItemToRemove )
    {
        pxList->pxIndex = pxItemToRemove->pxPrevious;
    }

    pxItemToRemove->pvContainer = NULL;
    ( pxList->uxNumberOfItems )--;
}