Welcome to Hang's Website!
Embedded Systems
Welcome to Hang's Website!

STM32 FreeRTOS: Lists and List Items

STM32 Microcontroller and FreeRTOS Development

List & List Item & Mini List Item

  • List: A FreeRTOS list is a doubly linked list used by the kernel to organize tasks and other objects.
  • List Item: A list item is a node that stores a value, links to neighboring items, and can reference its owning object.
  • Mini List Item: A mini list item is a simplified list item used as the end marker of a FreeRTOS list. 

// List
typedef struct xLIST
{
	listFIRST_LIST_INTEGRITY_CHECK_VALUE				
	volatile UBaseType_t uxNumberOfItems;
	ListItem_t * configLIST_VOLATILE pxIndex;
	MiniListItem_t xListEnd;							
	listSECOND_LIST_INTEGRITY_CHECK_VALUE				
} List_t;

// List Item
struct xLIST_ITEM
{
	listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE			
	configLIST_VOLATILE TickType_t xItemValue;			
	struct xLIST_ITEM * configLIST_VOLATILE pxNext;		
	struct xLIST_ITEM * configLIST_VOLATILE pxPrevious;	
	void * pvOwner;										
	struct xLIST * configLIST_VOLATILE pxContainer;		
	listSECOND_LIST_ITEM_INTEGRITY_CHECK_VALUE			
};
typedef struct xLIST_ITEM ListItem_t;

// Mini List Item
struct xMINI_LIST_ITEM
{
	listFIRST_LIST_ITEM_INTEGRITY_CHECK_VALUE			
	configLIST_VOLATILE TickType_t xItemValue;
	struct xLIST_ITEM * configLIST_VOLATILE pxNext;
	struct xLIST_ITEM * configLIST_VOLATILE pxPrevious;
};
typedef struct xMINI_LIST_ITEM MiniListItem_t;
vListInitialise()

vListInitialise() prepares a List_t structure for use by clearing its item count, setting the list index to the end marker, and linking the mini list item to itself. After initialization, the list is empty and ready to accept list items. 

List_t TestList;
vListInitialise(&TestList);
vListInitialiseItem()

vListInitialiseItem() prepares a ListItem_t structure for use by setting its owner pointer to NULL. After initialization, the list item is ready to be assigned an owner and inserted into a FreeRTOS list. 

ListItem_t ListItem1;
vListInitialiseItem(&ListItem1);
vListInsert()

vListInsert() inserts a list item into a FreeRTOS list in ascending order based on the item’s value. It updates the neighboring links, assigns the list as the item’s container, and increases the number of items in the list. 

List_t TestList;
ListItem_t ListItem1;
ListItem1.xItemValue = 40;
vListInitialise(&TestList);
vListInitialiseItem(&ListItem1);
vListInsert(&TestList, &ListItem1);
vListInsertEnd()

vListInsertEnd() inserts a list item immediately before the list’s current index position. It updates the neighboring links, sets the item’s container pointer, and increases the list’s item count. 

List_t TestList;
ListItem_t ListItem1;
ListItem1.xItemValue = 40;
vListInitialise(&TestList);
vListInitialiseItem(&ListItem1);
vListInsertEnd(&TestList, &ListItem1);
uxListRemove()

uxListRemove() removes a list item from its current FreeRTOS list, reconnects the neighboring items, clears the item’s container pointer, and decreases the list’s item count. It returns the number of items remaining in the list. 

uxListRemove(&ListItem1);
Example: vListTask() 
List_t TestList;
ListItem_t ListItem1;
ListItem_t ListItem2;
ListItem_t ListItem3;

#define LIST_TASK_PRIO		3
#define LIST_STK_SIZE 		256
TaskHandle_t LISTTask_Handler;

xTaskCreate((TaskFunction_t ) vListTask,
            (const char*    ) "List Task",
            (uint16_t       ) LIST_STK_SIZE,
            (void*          ) NULL,
            (UBaseType_t    ) LIST_TASK_PRIO,
            (TaskHandle_t*  ) &LISTTask_Handler);
            
void vListTask(void *pvParameters) {

  	vListInitialise(&TestList);
  	vListInitialiseItem(&ListItem1);
  	vListInitialiseItem(&ListItem2);
  	vListInitialiseItem(&ListItem3);
  
  	ListItem1.xItemValue = 40;
  	ListItem2.xItemValue = 60;
  	ListItem3.xItemValue = 50;

  	printf("/************** List & List Item **************/\r\n");
  	printf("TestList                %#x	  \r\n",(int)&TestList);
  	printf("TestList item number    %d    \r\n",(int)TestList.uxNumberOfItems);
  	printf("TestList->pxIndex       %#x	  \r\n",(int)TestList.pxIndex);
  	printf("TestList->xListEnd      %#x	  \r\n",(int)(&TestList.xListEnd)); 
  	printf("ListItem1               %#x	  \r\n",(int)&ListItem1);
  	printf("ListItem2               %#x	  \r\n",(int)&ListItem2);
  	printf("ListItem3               %#x	  \r\n",(int)&ListItem3);
  	printf("\r\n");
  
  	vListInsert(&TestList, &ListItem1); 
  	printf("/**************** Add ListItem1 ***************/\r\n");
  	printf("TestList item number              %d    \r\n",(int)TestList.uxNumberOfItems);
  	printf("TestList->xListEnd->pxNext        %#x	  \r\n",(int)(TestList.xListEnd.pxNext));     
  	printf("ListItem1->pxNext                 %#x	  \r\n",(int)(ListItem1.pxNext));             
  	printf("TestList->xListEnd->pxPrevious    %#x	  \r\n",(int)(TestList.xListEnd.pxPrevious)); 
  	printf("ListItem1->pxPrevious             %#x   \r\n",(int)(ListItem1.pxPrevious));         
  	printf("\r\n");
  
  	vListInsert(&TestList, &ListItem2); 
  	printf("/**************** Add ListItem2 ***************/\r\n");
  	printf("TestList item number              %d    \r\n",(int)TestList.uxNumberOfItems);
  	printf("TestList->xListEnd->pxNext        %#x	  \r\n",(int)(TestList.xListEnd.pxNext));     
  	printf("ListItem1->pxNext                 %#x	  \r\n",(int)(ListItem1.pxNext));             
  	printf("ListItem2->pxNext                 %#x	  \r\n",(int)(ListItem2.pxNext));             
  	printf("TestList->xListEnd->pxPrevious    %#x	  \r\n",(int)(TestList.xListEnd.pxPrevious)); 
  	printf("ListItem1->pxPrevious             %#x	  \r\n",(int)(ListItem1.pxPrevious));         
  	printf("ListItem2->pxPrevious             %#x   \r\n",(int)(ListItem2.pxPrevious));        
  	printf("\r\n");
  
  	vListInsert(&TestList, &ListItem3); 
  	printf("/**************** Add ListItem3 ***************/\r\n");
  	printf("TestList item number              %d    \r\n",(int)TestList.uxNumberOfItems);
  	printf("TestList->xListEnd->pxNext        %#x	  \r\n",(int)(TestList.xListEnd.pxNext));     
  	printf("ListItem1->pxNext                 %#x	  \r\n",(int)(ListItem1.pxNext));             
  	printf("ListItem3->pxNext                 %#x	  \r\n",(int)(ListItem3.pxNext));             
  	printf("ListItem2->pxNext                 %#x	  \r\n",(int)(ListItem2.pxNext));             
  	printf("TestList->xListEnd->pxPrevious    %#x	  \r\n",(int)(TestList.xListEnd.pxPrevious)); 
  	printf("ListItem1->pxPrevious             %#x	  \r\n",(int)(ListItem1.pxPrevious));        
  	printf("ListItem3->pxPrevious             %#x	  \r\n",(int)(ListItem3.pxPrevious));        
  	printf("ListItem2->pxPrevious             %#x   \r\n",(int)(ListItem2.pxPrevious));         
  	printf("\r\n");
  
  	uxListRemove(&ListItem2); 
  	printf("/************** Delete ListItem2 *************/\r\n");
  	printf("TestList item number              %d    \r\n",(int)TestList.uxNumberOfItems);
  	printf("TestList->xListEnd->pxNext        %#x	  \r\n",(int)(TestList.xListEnd.pxNext));     
  	printf("ListItem1->pxNext                 %#x	  \r\n",(int)(ListItem1.pxNext));             
  	printf("ListItem3->pxNext                 %#x	  \r\n",(int)(ListItem3.pxNext));             
  	printf("TestList->xListEnd->pxPrevious    %#x	  \r\n",(int)(TestList.xListEnd.pxPrevious)); 
  	printf("ListItem1->pxPrevious             %#x	  \r\n",(int)(ListItem1.pxPrevious));        
  	printf("ListItem3->pxPrevious             %#x   \r\n",(int)(ListItem3.pxPrevious));         
  	printf("\r\n");
  
  	TestList.pxIndex = TestList.pxIndex->pxNext; 	
  	vListInsertEnd(&TestList, &ListItem2); 
  	printf("/*********** InsertEnd ListItem2 ************/\r\n");
  	printf("TestList->pxIndex                 %#x	  \r\n",(int)TestList.pxIndex);               
  	printf("TestList item number              %d    \r\n",(int)TestList.uxNumberOfItems);
  	printf("TestList->xListEnd->pxNext        %#x	  \r\n",(int)(TestList.xListEnd.pxNext));     
  	printf("ListItem2->pxNext                 %#x	  \r\n",(int)(ListItem2.pxNext));             
  	printf("ListItem1->pxNext                 %#x   \r\n",(int)(ListItem1.pxNext));             
  	printf("ListItem3->pxNext                 %#x	  \r\n",(int)(ListItem3.pxNext));             
  	printf("TestList->xListEnd->pxPrevious    %#x	  \r\n",(int)(TestList.xListEnd.pxPrevious)); 
  	printf("ListItem2->pxPrevious             %#x	  \r\n",(int)(ListItem2.pxPrevious));       
  	printf("ListItem1->pxPrevious             %#x	  \r\n",(int)(ListItem1.pxPrevious));         
  	printf("ListItem3->pxPrevious             %#x   \r\n",(int)(ListItem3.pxPrevious));         
  	printf("\r\n");

    while(1) {
    	  HAL_GPIO_TogglePin(GPIOD, RED);
        vTaskDelay(_500ms);
    }

}
Results 
/************** List & List Item **************/
TestList                          0x20000254
TestList item number              0
TestList->pxIndex                 0x2000025c
TestList->xListEnd                0x2000025c
ListItem1                         0x20000268
ListItem2                         0x2000027c
ListItem3                         0x20000290

/**************** Add ListItem1 ***************/
TestList item number              1
TestList->xListEnd->pxNext        0x20000268
ListItem1->pxNext                 0x2000025c
TestList->xListEnd->pxPrevious    0x20000268
ListItem1->pxPrevious             0x2000025c
/**************** Add ListItem2 ***************/
TestList item number              2
TestList->xListEnd->pxNext        0x20000268
ListItem1->pxNext                 0x2000027c
ListItem2->pxNext                 0x2000025c
TestList->xListEnd->pxPrevious    0x2000027c
ListItem1->pxPrevious             0x2000025c
ListItem2->pxPrevious             0x20000268
/**************** Add ListItem3 ***************/
TestList item number              3
TestList->xListEnd->pxNext        0x20000268
ListItem1->pxNext                 0x20000290
ListItem3->pxNext                 0x2000027c
ListItem2->pxNext                 0x2000025c
TestList->xListEnd->pxPrevious    0x2000027c
ListItem1->pxPrevious             0x2000025c
ListItem3->pxPrevious             0x20000268
ListItem2->pxPrevious             0x20000290
/************** Delete ListItem2 *************/
TestList item number              2
TestList->xListEnd->pxNext        0x20000268
ListItem1->pxNext                 0x20000290
ListItem3->pxNext                 0x2000025c
TestList->xListEnd->pxPrevious    0x20000290
ListItem1->pxPrevious             0x2000025c
ListItem3->pxPrevious             0x20000268
/*********** InsertEnd ListItem2 ************/
TestList->pxIndex                 0x20000268
TestList item number              3
TestList->xListEnd->pxNext        0x2000027c
ListItem2->pxNext                 0x20000268
ListItem1->pxNext                 0x20000290
ListItem3->pxNext                 0x2000025c
TestList->xListEnd->pxPrevious    0x20000290
ListItem2->pxPrevious             0x2000025c
ListItem1->pxPrevious             0x2000027c
ListItem3->pxPrevious             0x20000268


Back to top of the page