GateMP.h File Reference


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

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.a

Version:
0.00.01

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

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...

Defines

#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.

Typedefs

typedef struct GateMP_Object * GateMP_Handle
 GateMP_Handle type.

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.
GateMP_Handle GateMP_create (const GateMP_Params *params)
 Create a GateMP instance.
Int GateMP_delete (GateMP_Handle *handlePtr)
 Delete a created GateMP instance.
GateMP_Handle GateMP_getDefaultRemote (Void)
 Get the default remote gate.
GateMP_LocalProtect GateMP_getLocalProtect (GateMP_Handle handle)
 Get the local protection level configured in a GateMP instance.
GateMP_RemoteProtect GateMP_getRemoteProtect (GateMP_Handle handle)
 Get the remote protection level configured in a GateMP instance.
Int GateMP_open (String name, GateMP_Handle *handlePtr)
 Open a created GateMP by name.
Void GateMP_Params_init (GateMP_Params *params)
 Initialize a GateMP parameters struct.
IArg GateMP_enter (GateMP_Handle handle)
 Enter the GateMP.
Void GateMP_leave (GateMP_Handle handle, IArg key)
 Leave the GateMP.

Define 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 struct GateMP_Object* GateMP_Handle

GateMP_Handle type.


Enumeration Type Documentation

A set of local context protection levels.

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

In linux user mode, the following are the mapping for the constants

  • INTERRUPT -> [N/A]
  • TASKLET -> [N/A]
  • THREAD -> GateMutex
  • PROCESS -> GateMutex

In linux kernel mode, the following are the mapping for the constants

  • INTERRUPT -> [Interrupts disabled]
  • TASKLET -> GateMutex
  • THREAD -> GateMutex
  • PROCESS -> GateMutex

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

  • INTERRUPT -> GateHwi: disables interrupts
  • TASKLET -> GateSwi: disables Swi's (software interrupts)
  • 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

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:
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

Copyright 2010, Texas Instruments Incorporated