list.c source file defined the list data structure, which is highly used by the FreeRTOS itself. The scheduler uses it to maintain threads. TCB uses it to maintain events and states.

The list (List_t) is a doubly linked list, each of its node elements (ListItem_t) contains a pre and a next pointer, a pvContainer points back to the List_t

By convention, the list is sorted according to the value in a descending order.

When initializing a list, a default item node (xMINI_LIST_ITEM) is also created, this value of this node is the maximum value can be stored in this list, so this list is always the first element in this list.

Data structure

                        /////////////// ListItem_t ////////////////
                
                        /*A doubly linked list (pxNext, pxPrevious), it also has a pvContainer, which points the list self.*/
                        /*TickType_t is a uint32_t variable used to store useful data*/
                        /*The pvOwner is usually the TCB*/
                        struct xLIST_ITEM
                        {
                            configLIST_VOLATILE TickType_t xItemValue;			/* The value being listed.  In most cases this is used to sort the list in descending order. */
                            struct xLIST_ITEM * configLIST_VOLATILE pxNext;		
                            struct xLIST_ITEM * configLIST_VOLATILE pxPrevious;	
                            void * pvOwner;										
                            void * configLIST_VOLATILE pvContainer;				
                            listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE			
                        };
                        typedef struct xLIST_ITEM ListItem_t;
                
                        struct xMINI_LIST_ITEM
                        {
                            configLIST_VOLATILE TickType_t xItemValue;
                            struct xLIST_ITEM * configLIST_VOLATILE pxNext;
                            struct xLIST_ITEM * configLIST_VOLATILE pxPrevious;
                        };
                        typedef struct xMINI_LIST_ITEM MiniListItem_t;
                
                        typedef struct xLIST
                        {
                            configLIST_VOLATILE UBaseType_t uxNumberOfItems;
                            ListItem_t * configLIST_VOLATILE pxIndex;			/*used to walk throught the list*/
                            MiniListItem_t xListEnd;							
                        } List_t;
                        // function vListInitialiseItem really does nothing
                    

Functions

                    // this function is invoked by the scheduler to initialized thread lists.
                    void vListInitialise( List_t * const pxList )
                    {
                        pxList->pxIndex = ( ListItem_t * ) &( pxList->xListEnd );
                        pxList->xListEnd.xItemValue = portMAX_DELAY;
                        pxList->xListEnd.pxNext = ( ListItem_t * ) &( pxList->xListEnd );	
                        pxList->xListEnd.pxPrevious = ( ListItem_t * ) &( pxList->xListEnd );
                        pxList->uxNumberOfItems = ( UBaseType_t ) 0U;
                    }
                

                    // vListInsertEnd (forget the order)
                    // void vListInsert( List_t * const pxList, ListItem_t * const pxNewListItem ) (sorted order)