IPC API  3.40.00.06
Data Structures | Macros | Typedefs | Functions
ListMP.h File Reference

Detailed Description

Multiple processor shared memory list.

Note
ListMP is currently only available for SYS/BIOS.

ListMP is a doubly linked-list based module designed to be used in a multi-processor environment. It provides a way for multiple processors to create, access, and manipulate the same link list in shared memory.

The ListMP module uses a NameServer instance to store information about an instance during create. Each ListMP instance is created by specifying a name and region id. The name supplied must be unique for all ListMP instances in the system.

ListMP_create() is used to create an instance of a ListMP. Shared memory is modified during create. Once created, an instance may be opened by calling ListMP_open(). Open does not modify any shared memory. Open() should be called only when global interrupts are enabled.

To use a ListMP instance, a ListMP_Elem must be embedded as the very first element of a structure. ListMP does not provide cache coherency for the buffer put onto the link list. ListMP only provides cache coherency for the ListMP_Elem fields. The buffer should be written back before being placed on a ListMP, if cache coherency is required.

The ListMP header should be included in an application as follows:

#include <ti/ipc/ListMP.h>
#include <ti/ipc/SharedRegion.h>
#include <ti/ipc/GateMP.h>
Include dependency graph for ListMP.h:

Go to the source code of this file.

Data Structures

struct  ListMP_Elem
 Structure defining a ListMP element. More...
 
struct  ListMP_Params
 Structure defining parameter structure for ListMP_create(). More...
 

Macros

#define ListMP_S_BUSY   2
 The resource is still in use. More...
 
#define ListMP_S_ALREADYSETUP   1
 The module has been already setup. More...
 
#define ListMP_S_SUCCESS   0
 Operation is successful. More...
 
#define ListMP_E_FAIL   -1
 Generic failure. More...
 
#define ListMP_E_INVALIDARG   -2
 Argument passed to function is invalid. More...
 
#define ListMP_E_MEMORY   -3
 Operation resulted in memory failure. More...
 
#define ListMP_E_ALREADYEXISTS   -4
 The specified entity already exists. More...
 
#define ListMP_E_NOTFOUND   -5
 Unable to find the specified entity. More...
 
#define ListMP_E_TIMEOUT   -6
 Operation timed out. More...
 
#define ListMP_E_INVALIDSTATE   -7
 Module is not initialized. More...
 
#define ListMP_E_OSFAILURE   -8
 A failure occurred in an OS-specific call. More...
 
#define ListMP_E_RESOURCE   -9
 Specified resource is not available. More...
 
#define ListMP_E_RESTART   -10
 Operation was interrupted. Please restart the operation. More...
 

Typedefs

typedef struct ListMP_Object * ListMP_Handle
 ListMP_Handle type. More...
 
typedef struct ListMP_Elem ListMP_Elem
 Structure defining a ListMP element. More...
 
typedef struct ListMP_Params ListMP_Params
 Structure defining parameter structure for ListMP_create(). More...
 

Functions

Void ListMP_Params_init (ListMP_Params *params)
 Initializes ListMP parameters. More...
 
ListMP_Handle ListMP_create (const ListMP_Params *params)
 Creates and initializes ListMP module. More...
 
Int ListMP_close (ListMP_Handle *handlePtr)
 Close an opened ListMP instance. More...
 
Int ListMP_delete (ListMP_Handle *handlePtr)
 Deletes a ListMP instance. More...
 
Int ListMP_open (String name, ListMP_Handle *handlePtr)
 Open a created ListMP instance. More...
 
Bool ListMP_empty (ListMP_Handle handle)
 Determines if a ListMP instance is empty. More...
 
GateMP_Handle ListMP_getGate (ListMP_Handle handle)
 Retrieves the GateMP handle associated with the ListMP instance. More...
 
Ptr ListMP_getHead (ListMP_Handle handle)
 Get an element from front of a ListMP instance. More...
 
Ptr ListMP_getTail (ListMP_Handle handle)
 Get an element from back of a ListMP instance. More...
 
Int ListMP_insert (ListMP_Handle handle, ListMP_Elem *newElem, ListMP_Elem *curElem)
 Insert an element into a ListMP instance. More...
 
Ptr ListMP_next (ListMP_Handle handle, ListMP_Elem *elem)
 Return the next element in a ListMP instance (non-atomic) More...
 
Ptr ListMP_prev (ListMP_Handle handle, ListMP_Elem *elem)
 Return the previous element in ListMP instance (non-atomic) More...
 
Int ListMP_putHead (ListMP_Handle handle, ListMP_Elem *elem)
 Put an element at head of a ListMP instance. More...
 
Int ListMP_putTail (ListMP_Handle handle, ListMP_Elem *elem)
 Put an element at back of a ListMP instance. More...
 
Int ListMP_remove (ListMP_Handle handle, ListMP_Elem *elem)
 Remove an element from a ListMP instance. More...
 

Macro Definition Documentation

#define ListMP_S_BUSY   2

The resource is still in use.

#define ListMP_S_ALREADYSETUP   1

The module has been already setup.

#define ListMP_S_SUCCESS   0

Operation is successful.

#define ListMP_E_FAIL   -1

Generic failure.

#define ListMP_E_INVALIDARG   -2

Argument passed to function is invalid.

#define ListMP_E_MEMORY   -3

Operation resulted in memory failure.

#define ListMP_E_ALREADYEXISTS   -4

The specified entity already exists.

#define ListMP_E_NOTFOUND   -5

Unable to find the specified entity.

#define ListMP_E_TIMEOUT   -6

Operation timed out.

#define ListMP_E_INVALIDSTATE   -7

Module is not initialized.

#define ListMP_E_OSFAILURE   -8

A failure occurred in an OS-specific call.

#define ListMP_E_RESOURCE   -9

Specified resource is not available.

#define ListMP_E_RESTART   -10

Operation was interrupted. Please restart the operation.

Typedef Documentation

typedef struct ListMP_Object* ListMP_Handle

ListMP_Handle type.

typedef struct ListMP_Elem ListMP_Elem

Structure defining a ListMP element.

typedef struct ListMP_Params ListMP_Params

Structure defining parameter structure for ListMP_create().

Function Documentation

Void ListMP_Params_init ( ListMP_Params params)

Initializes ListMP parameters.

Parameters
paramsInstance param structure.
ListMP_Handle ListMP_create ( const ListMP_Params params)

Creates and initializes ListMP module.

Parameters
paramsInstance param structure.
Returns
ListMP instance handle. NULL if create failed.
See also
ListMP_delete()
Int ListMP_close ( ListMP_Handle handlePtr)

Close an opened ListMP instance.

Closing an instance will free local memory consumed by the opened instance. Instances that are opened should be closed before the instance is deleted. If using NameServer, the instance name will be removed from the NameServer instance.

Parameters
handlePtrPointer to a ListMP instance
Returns
Status
See also
ListMP_open()
Int ListMP_delete ( ListMP_Handle handlePtr)

Deletes a ListMP instance.

Parameters
handlePtrPointer to ListMP instance
Returns
Status
See also
ListMP_create()
Int ListMP_open ( String  name,
ListMP_Handle handlePtr 
)

Open a created ListMP instance.

An open can be performed on a previously created instance. Open is used to gain access to the same ListMP instance. Generally an instance is created on one processor and opened on other processors but it can be opened on the same processor too. Open returns a ListMP instance handle like create, but it does not initialize any shared memory.

The open call searches the local ListMP NameServer table first for a matching name. If no local match is found, it will search all remote ListMP NameServer tables for a matching name.

A status value of ListMP_S_SUCCESS is returned if a matching ListMP instance is found. A ListMP_E_FAIL is returned if no matching instance is found. Generally this means the ListMP instance has not yet been created. A more specific status error is returned if an error was raised.

Call close() when the opened instance is no longer needed.

Parameters
nameName of created ListMP instance
handlePtrpointer to the handle if a handle was found.
Returns
Status
See also
ListMP_close()
ListMP_create()
Bool ListMP_empty ( ListMP_Handle  handle)

Determines if a ListMP instance is empty.

Parameters
handlea ListMP handle.
Returns
TRUE if 'next' element points to head, otherwise FALSE
GateMP_Handle ListMP_getGate ( ListMP_Handle  handle)

Retrieves the GateMP handle associated with the ListMP instance.

Parameters
handlea ListMP handle.
Returns
GateMP handle for ListMP instance.
Ptr ListMP_getHead ( ListMP_Handle  handle)

Get an element from front of a ListMP instance.

Atomically removes the element from the front of a ListMP instance and returns a pointer to it. Uses ListMP_Params.gate for critical region management.

Parameters
handlea ListMP handle.
Returns
pointer to former first element. NULL if the ListMP is empty.
Ptr ListMP_getTail ( ListMP_Handle  handle)

Get an element from back of a ListMP instance.

Atomically removes the element from the back of a ListMP instance and returns a pointer to it. Uses ListMP_Params.gate for critical region management.

Parameters
handlea ListMP handle.
Returns
pointer to former last element. NULL if the ListMP is empty.
Int ListMP_insert ( ListMP_Handle  handle,
ListMP_Elem newElem,
ListMP_Elem curElem 
)

Insert an element into a ListMP instance.

Atomically inserts newElem in the instance in front of curElem. To place an element at the back of a ListMP instance, use ListMP_putTail(). To place an element at the front of a ListMP instance, use ListMP_putHead().

The following code shows an example.

1 ListMP_Elem elem, curElem;
2 
3 ListMP_insert(listHandle, &elem, &curElem); // insert before curElem
Parameters
handlea ListMP handle.
newElemnew element to insert into the ListMP.
curElemcurrent element in the ListMP.
Returns
Status
Ptr ListMP_next ( ListMP_Handle  handle,
ListMP_Elem elem 
)

Return the next element in a ListMP instance (non-atomic)

Is useful in searching a ListMP instance. It does not remove any items from the ListMP instance. The caller should protect the ListMP instance from being changed while using this call since it is non-atomic.

To look at the first elem on the ListMP, use NULL as the elem argument.

The following code shows an example. The scanning of a ListMP instance should be protected against other threads that modify the ListMP.

1 ListMP_Elem *elem = NULL;
2 GateMP_Handle gate;
3 IArg key;
4 
5 // get the gate for the ListMP instance
6 gate = ListMP_getGate(listHandle);
7 
8 // Begin protection against modification of the ListMP.
9 key = GateMP_enter(gate);
10 
11 while ((elem = ListMP_next(ListMPHandle, elem)) != NULL) {
12  //act on elem as needed. For example call ListMP_remove().
13 }
14 
15 // End protection against modification of the ListMP.
16 GateMP_leave(gate, key);
Parameters
handlea ListMP handle.
elemelement in ListMP or NULL to start at the head
Returns
next element in ListMP instance or NULL to denote end.
Ptr ListMP_prev ( ListMP_Handle  handle,
ListMP_Elem elem 
)

Return the previous element in ListMP instance (non-atomic)

Useful in searching a ListMP instance in reverse order. It does not remove any items from the ListMP instance. The caller should protect the ListMP instance from being changed while using this call since it is non-atomic.

To look at the last elem on the ListMP instance, use NULL as the elem argument.

The following code shows an example. The scanning of a ListMP instance should be protected against other threads that modify the instance.

1 ListMP_Elem *elem = NULL;
2 GateMP_Handle gate;
3 IArg key;
4 
5 // get the gate for the ListMP instance
6 gate = ListMP_getGate(listHandle);
7 
8 // Begin protection against modification of the ListMP.
9 key = GateMP_enter(gate);
10 
11 while ((elem = ListMP_prev(listHandle, elem)) != NULL) {
12  //act on elem as needed. For example call ListMP_remove().
13 }
14 
15 // End protection against modification of the ListMP.
16 GateMP_leave(gate, key);
Parameters
handlea ListMP handle.
elemelement in ListMP or NULL to start at the end
Returns
previous element in ListMP or NULL if empty.
Int ListMP_putHead ( ListMP_Handle  handle,
ListMP_Elem elem 
)

Put an element at head of a ListMP instance.

Atomically places the element at the front of a ListMP instance. Uses ListMP_Params.gate for critical region management.

Parameters
handlea ListMP handle
elempointer to new ListMP element
Returns
Status
Int ListMP_putTail ( ListMP_Handle  handle,
ListMP_Elem elem 
)

Put an element at back of a ListMP instance.

Atomically places the element at the back of a ListMP instance. Uses ListMP_Params.gate for critical region management.

Parameters
handlea ListMP handle
elempointer to new ListMP element
Returns
Status
Int ListMP_remove ( ListMP_Handle  handle,
ListMP_Elem elem 
)

Remove an element from a ListMP instance.

Atomically removes an element from a ListMP.

The elem parameter is a pointer to an existing element to be removed from a ListMP instance.

Parameters
handlea ListMP handle
elemelement in ListMP
Returns
Status
Copyright 2015, Texas Instruments Incorporated