Detailed Description

Linked List interface for use in drivers.

============================================================================

This module provides simple doubly-link list implementation. There are two main structures:

List_List: The structure that holds the start of a linked list. There is no API to create one. It is up to the driver to provide the structure itself.
List_Elem: The structure that must be in the structure that is placed onto a linked list. Generally it is the first field in the structure. For example:
typedef struct MyStruct {
List_Elem elem;
void *buffer;
} MyStruct;

The following shows how to create a linked list with three elements.

+ denotes null-terminated
        _______        _______        _______      _______
       |_______|----->|_______|----->|_______|--->|_______|--//---,
  ,----|_______|    ,-|_______|<-----|_______|<---|_______|<-//-, +
  |      List       +   elem           elem          elem       |
  |_____________________________________________________________|

The APIs List_get, List_put, and List_putHead are atomic. The other APIs are not necessarily atomic. In other words, when traversing a linked list, it is up to the application to provide thread-safety (e.g. HwiP_disable/restore or MutexP_pend/post).

Initializing and adding an element to the tail and removing it

typedef struct MyStruct {
    List_Elem elem;
    void *buffer;
} MyStruct;
List_List list;
MyStruct foo;
MyStruct *bar;
List_clearList(&list);
List_put(&list, (List_Elem *)&foo);
bar = (MyStruct *)List_get(&list);

The List_put and List_get APIs are used to maintain a first-in first-out (FIFO) linked list.

The List_putHead and List_get APIs are used to maintain a last-in first-out (LIFO) linked list.

Traversing a list from head to tail. Note: thread-safety calls are not shown here.

List_List list;
List_Elem *temp;
for (temp = List_head(&list); temp != NULL; temp = List_next(temp)) {
     printf("address = 0x%x\n", temp);
}

Traversing a list from tail to head. Note: thread-safety calls are not shown here.

List_List list;
List_Elem *temp;
for (temp = List_tail(&list); temp != NULL; temp = List_prev(temp)) {
     printf("address = 0x%x\n", temp);
}

#include <stdint.h>
#include <stdbool.h>
#include <stddef.h>

Go to the source code of this file.

Data Structures
struct	List_Elem

struct	List_List

Typedefs
typedef struct List_Elem	List_Elem

typedef struct List_List	List_List

Functions
void	List_clearList (List_List *list)
	Function to initialize the contents of a List_List. More...

bool	List_empty (List_List *list)
	Function to test whether a linked list is empty. More...

List_Elem *	List_get (List_List *list)
	Function to atomically get the first elem in a linked list. More...

List_Elem *	List_head (List_List *list)
	Function to return the head of a linked list. More...

void	List_insert (List_List list, List_Elem newElem, List_Elem *curElem)
	Function to insert an elem into a linked list. More...

List_Elem *	List_next (List_Elem *elem)
	Function to return the next elem in a linked list. More...

List_Elem *	List_prev (List_Elem *elem)
	Function to return the prev elem in a linked list. More...

void	List_put (List_List list, List_Elem elem)
	Function to atomically put an elem onto the end of a linked list. More...

void	List_putHead (List_List list, List_Elem elem)
	Function to atomically put an elem onto the head of a linked list. More...

void	List_remove (List_List list, List_Elem elem)
	Function to remove an elem from a linked list. More...

List_Elem *	List_tail (List_List *list)
	Function to return the tail of a linked list. More...

Typedef Documentation

§ List_Elem

typedef struct List_Elem List_Elem

§ List_List

typedef struct List_List List_List

Function Documentation

§ List_clearList()

void List_clearList ( List_List * list )

Function to initialize the contents of a List_List.

Parameters

list	Pointer to a List_List structure that will be used to maintain a linked list

§ List_empty()

bool List_empty ( List_List * list )

Function to test whether a linked list is empty.

Parameters

list	A pointer to a linked list

Returns: true if empty, false if not empty

§ List_get()

List_Elem* List_get ( List_List * list )

Function to atomically get the first elem in a linked list.

Parameters

list	A pointer to a linked list

Returns: Pointer the first elem in the linked list or NULL if empty

§ List_head()

List_Elem* List_head ( List_List * list )

Function to return the head of a linked list.

This function does not remove the head, it simply returns a pointer to it. This function is typically used when traversing a linked list.

Parameters

list	A pointer to the linked list

Returns: Pointer to the first elem in the linked list or NULL if empty

§ List_insert()

void List_insert	(	List_List *	list,
		List_Elem *	newElem,
		List_Elem *	curElem
	)

Function to insert an elem into a linked list.

Parameters

list	A pointer to the linked list
newElem	New elem to insert
curElem	Elem to insert the newElem in front of. This value cannot be NULL.

§ List_next()

List_Elem* List_next ( List_Elem * elem )

Function to return the next elem in a linked list.

This function does not remove the elem, it simply returns a pointer to next one. This function is typically used when traversing a linked list.

Parameters

elem	Elem in the list

Returns: Pointer to the next elem in linked list or NULL if at the end

§ List_prev()

List_Elem* List_prev ( List_Elem * elem )

Function to return the prev elem in a linked list.

This function does not remove the elem, it simply returns a pointer to prev one. This function is typically used when traversing a linked list.

Parameters

elem	Elem in the list

Returns: Pointer to the prev elem in linked list or NULL if at the beginning

§ List_put()

void List_put	(	List_List *	list,
		List_Elem *	elem
	)

Function to atomically put an elem onto the end of a linked list.

Parameters

list	A pointer to the linked list
elem	Element to place onto the end of the linked list

§ List_putHead()

void List_putHead	(	List_List *	list,
		List_Elem *	elem
	)

Function to atomically put an elem onto the head of a linked list.

Parameters

list	A pointer to the linked list
elem	Element to place onto the beginning of the linked list

§ List_remove()

void List_remove	(	List_List *	list,
		List_Elem *	elem
	)

Function to remove an elem from a linked list.

Parameters

list	A pointer to the linked list
elem	Element to be removed from a linked list

§ List_tail()

List_Elem* List_tail ( List_List * list )

Function to return the tail of a linked list.

This function does not remove the tail, it simply returns a pointer to it. This function is typically used when traversing a linked list.

Parameters

list	A pointer to the linked list

Returns: Pointer to the last elem in the linked list or NULL if empty

Detailed Description

Data Structures

Typedefs

Functions

Typedef Documentation

§ List_Elem

§ List_List

Function Documentation

§ List_clearList()

§ List_empty()

§ List_get()

§ List_head()

§ List_insert()

§ List_next()

§ List_prev()

§ List_put()

§ List_putHead()

§ List_remove()

§ List_tail()