Detailed Description

Multiple processor gate that provides local and remote context protection.

A GateMP instance can be used to enforce both local and remote context context protection. That is, entering a GateMP can prevent preemption by another thread running on the same processor and simultaneously prevent a remote processor from entering the same gate. GateMP's are typically used to protect reads/writes to a shared resource, such as shared memory.

Creating a GateMP requires supplying the following configuration

Instance name (see GateMP_Params.name)
Region id (see GateMP_Params.regionId)

In addition, the following parameters should be configured as necessary:

The level of local protection (interrupt, thread, tasklet, process or none) can be configured using the GateMP_Params.localProtect config parameter.
The type of remote system gate that can be used. Most devices will typically have a single type of system gate so this configuration should typically be left alone. See GateMP_Params.remoteProtect for more information.

Once created, GateMP allows the gate to be opened on another processor using GateMP_open() and the name that was used in GateMP_create().

A GateMP can be entered and left using GateMP_enter() and GateMP_leave() like any other gate that implements the IGateProvider interface.

GateMP has the following proxies - RemoteSystemProxy, RemoteCustom1Proxy and RemoteCustom2Proxy which are automatically plugged with device-specific delegates that implement multiple processor mutexes using a variety of hardware mechanisms.

GateMP creates a default system gate whose handle may be obtained using GateMP_getDefaultRemote(). Most IPC modules typically use this gate by default if they require gates and no instance gate is configured by the user.

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

#include <ti/ipc/GateMP.h>

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	GateMP_Params
	Structure defining parameters for the GateMP module. More...

Macros
#define	GateMP_S_BUSY (2)
	The resource is still in use. More...

#define	GateMP_S_ALREADYSETUP (1)
	The module has been already setup. More...

#define	GateMP_S_SUCCESS (0)
	Operation is successful. More...

#define	GateMP_E_FAIL (-1)
	Generic failure. More...

#define	GateMP_E_INVALIDARG (-2)
	Argument passed to function is invalid. More...

#define	GateMP_E_MEMORY (-3)
	Operation resulted in memory failure. More...

#define	GateMP_E_ALREADYEXISTS (-4)
	The specified entity already exists. More...

#define	GateMP_E_NOTFOUND (-5)
	Unable to find the specified entity. More...

#define	GateMP_E_TIMEOUT (-6)
	Operation timed out. More...

#define	GateMP_E_INVALIDSTATE (-7)
	Module is not initialized. More...

#define	GateMP_E_OSFAILURE (-8)
	A failure occurred in an OS-specific call. More...

#define	GateMP_E_RESOURCE (-9)
	Specified resource is not available. More...

#define	GateMP_E_RESTART (-10)
	Operation was interrupted. Please restart the operation. More...

Typedefs
typedef enum GateMP_LocalProtect	GateMP_LocalProtect
	A set of local context protection levels. More...

typedef enum GateMP_RemoteProtect	GateMP_RemoteProtect
	Type of remote Gate. More...

typedef struct GateMP_Object *	GateMP_Handle
	GateMP_Handle type. More...

typedef struct GateMP_Params	GateMP_Params
	Structure defining parameters for the GateMP module. More...

Enumerations
enum	GateMP_LocalProtect { GateMP_LocalProtect_NONE = 0, GateMP_LocalProtect_INTERRUPT = 1, GateMP_LocalProtect_TASKLET = 2, GateMP_LocalProtect_THREAD = 3, GateMP_LocalProtect_PROCESS = 4 }
	A set of local context protection levels. More...

enum	GateMP_RemoteProtect { GateMP_RemoteProtect_NONE = 0, GateMP_RemoteProtect_SYSTEM = 1, GateMP_RemoteProtect_CUSTOM1 = 2, GateMP_RemoteProtect_CUSTOM2 = 3 }
	Type of remote Gate. More...

Functions
Int	GateMP_close (GateMP_Handle *handlePtr)
	Close an opened gate. More...

GateMP_Handle	GateMP_create (const GateMP_Params *params)
	Create a GateMP instance. More...

Int	GateMP_delete (GateMP_Handle *handlePtr)
	Delete a created GateMP instance. More...

GateMP_Handle	GateMP_getDefaultRemote (Void)
	Get the default remote gate. More...

GateMP_LocalProtect	GateMP_getLocalProtect (GateMP_Handle handle)
	Get the local protection level configured in a GateMP instance. More...

GateMP_RemoteProtect	GateMP_getRemoteProtect (GateMP_Handle handle)
	Get the remote protection level configured in a GateMP instance. More...

Int	GateMP_open (String name, GateMP_Handle *handlePtr)
	Open a created GateMP by name. More...

Void	GateMP_Params_init (GateMP_Params *params)
	Initialize a GateMP parameters struct. More...

IArg	GateMP_enter (GateMP_Handle handle)
	Enter the GateMP. More...

Void	GateMP_leave (GateMP_Handle handle, IArg key)
	Leave the GateMP. More...

Macro Definition Documentation

#define GateMP_S_BUSY (2)

The resource is still in use.

#define GateMP_S_ALREADYSETUP (1)

The module has been already setup.

#define GateMP_S_SUCCESS (0)

Operation is successful.

#define GateMP_E_FAIL (-1)

Generic failure.

#define GateMP_E_INVALIDARG (-2)

Argument passed to function is invalid.

#define GateMP_E_MEMORY (-3)

Operation resulted in memory failure.

#define GateMP_E_ALREADYEXISTS (-4)

The specified entity already exists.

#define GateMP_E_NOTFOUND (-5)

Unable to find the specified entity.

#define GateMP_E_TIMEOUT (-6)

Operation timed out.

#define GateMP_E_INVALIDSTATE (-7)

Module is not initialized.

#define GateMP_E_OSFAILURE (-8)

A failure occurred in an OS-specific call.

#define GateMP_E_RESOURCE (-9)

Specified resource is not available.

#define GateMP_E_RESTART (-10)

Operation was interrupted. Please restart the operation.

Typedef Documentation

typedef enum GateMP_LocalProtect GateMP_LocalProtect

A set of local context protection levels.

Each member corresponds to a specific local processor gates used for local protection.

For SYS/BIOS users, the following are the mappings for the constants

INTERRUPT -> GateAll: disables interrupts, Swis and Tasks
TASKLET -> GateSwi: disables Swis and Tasks
THREAD -> GateMutexPri: based on Semaphores
PROCESS -> GateMutexPri: based on Semaphores

typedef enum GateMP_RemoteProtect GateMP_RemoteProtect

Type of remote Gate.

Each member corresponds to a specific type of remote gate. Each enum value corresponds to the following remote protection levels:

NONE -> No remote protection (the GateMP instance will exclusively offer local protection configured in GateMP_Params.localProtect
SYSTEM -> Use the SYSTEM remote protection level (default for remote protection
CUSTOM1 -> Use the CUSTOM1 remote protection level
CUSTOM2 -> Use the CUSTOM2 remote protection level

typedef struct GateMP_Object* GateMP_Handle

GateMP_Handle type.

typedef struct GateMP_Params GateMP_Params

Structure defining parameters for the GateMP module.

Enumeration Type Documentation

enum GateMP_LocalProtect

A set of local context protection levels.

Each member corresponds to a specific local processor gates used for local protection.

For SYS/BIOS users, the following are the mappings for the constants

INTERRUPT -> GateAll: disables interrupts, Swis and Tasks
TASKLET -> GateSwi: disables Swis and Tasks
THREAD -> GateMutexPri: based on Semaphores
PROCESS -> GateMutexPri: based on Semaphores

Enumerator
GateMP_LocalProtect_NONE	Use no local protection
GateMP_LocalProtect_INTERRUPT	Use the INTERRUPT local protection level
GateMP_LocalProtect_TASKLET	Use the TASKLET local protection level
GateMP_LocalProtect_THREAD	Use the THREAD local protection level
GateMP_LocalProtect_PROCESS	Use the PROCESS local protection level

enum GateMP_RemoteProtect

Type of remote Gate.

Each member corresponds to a specific type of remote gate. Each enum value corresponds to the following remote protection levels:

NONE -> No remote protection (the GateMP instance will exclusively offer local protection configured in GateMP_Params.localProtect
SYSTEM -> Use the SYSTEM remote protection level (default for remote protection
CUSTOM1 -> Use the CUSTOM1 remote protection level
CUSTOM2 -> Use the CUSTOM2 remote protection level

Enumerator
GateMP_RemoteProtect_NONE	No remote protection (the GateMP instance will exclusively offer local protection configured in GateMP_Params.localProtect)
GateMP_RemoteProtect_SYSTEM	Use the SYSTEM remote protection level (default remote protection)
GateMP_RemoteProtect_CUSTOM1	Use the CUSTOM1 remote protection level
GateMP_RemoteProtect_CUSTOM2	Use the CUSTOM2 remote protection level

Function Documentation

Int GateMP_close ( GateMP_Handle * handlePtr )

Close an opened gate.

Parameters

[in,out] handlePtr Pointer to handle to opened GateMP instance

Returns: GateMP status

GateMP_Handle GateMP_create ( const GateMP_Params * params )

Create a GateMP instance.

The params structure should be initialized using GateMP_Params_init().

Parameters

[in] params GateMP parameters

Returns: GateMP Handle

Int GateMP_delete ( GateMP_Handle * handlePtr )

Delete a created GateMP instance.

Parameters

[in,out] handlePtr Pointer to GateMP handle

Returns: GateMP Status

GateMP_Handle GateMP_getDefaultRemote ( Void )

Get the default remote gate.

Returns: GateMP handle

GateMP_LocalProtect GateMP_getLocalProtect ( GateMP_Handle handle )

Get the local protection level configured in a GateMP instance.

Returns: GateMP_LocalProtect corresponding to local protection level

GateMP_RemoteProtect GateMP_getRemoteProtect ( GateMP_Handle handle )

Get the remote protection level configured in a GateMP instance.

Returns: GateMP_RemoteProtect corresponding to remote protection level

Int GateMP_open	(	String	name,
		GateMP_Handle *	handlePtr
	)

Open a created GateMP by name.

Parameters

[in]	name	Name of the GateMP instance
[out]	handlePtr	Pointer to GateMP handle to be opened

Returns

GateMP status:

GateMP_E_NOTFOUND: open failed (name not found on any processor)
GateMP_E_FAIL: open failed (general failure occurred)
GateMP_S_SUCCESS: open successful

Void GateMP_Params_init ( GateMP_Params * params )

Initialize a GateMP parameters struct.

Parameters

[out] params Pointer to GateMP parameters

IArg GateMP_enter ( GateMP_Handle handle )

Enter the GateMP.

Parameters

[in] handle GateMP handle

Returns: key that must be used to leave the gate

Void GateMP_leave	(	GateMP_Handle	handle,
		IArg	key
	)

Leave the GateMP.

Parameters

[in]	handle	GateMP handle
[in]	key	key returned from GateMP_enter

Detailed Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation