SharedRegion.h File Reference


Detailed Description

Shared memory manager and address translator.

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

The SharedRegion module is designed to be used in a multi-processor environment in which memory regions are shared and accessed across different processors. The module itself does not use any shared memory, because all module state is stored locally. SharedRegion APIs use the system gate for thread protection.

This module creates and stores a local shared memory region table. The table contains the processor's view for every shared region in the system. The table must not contain any overlapping regions. Each processor's view of a particular shared memory region is determined by the region id. In cases where a processor cannot access a certain shared memory region, that shared memory region should be left invalid for that processor. Note: The number of entries must be the same on all processors.

Each shared region contains the following:

A region is added using the SharedRegion_setEntry API. The length of a region must be the same across all processors. The owner of the region can be specified. If specified, the owner manages the shared region. It creates a HeapMemMP instance which spans the full size of the region. The other processors open the same HeapMemMP instance.

After a shared region is valid, SharedRegion APIs can be used to convert pointers between the local processor's address space and the SharedRegion- pointer (SRPtr) address space. These APIs include SharedRegion_getId, SharedRegion_getSRPtr and SharedRegion_getPtr. An example is shown below:

  SharedRegion_SRPtr srptr;
  Ptr     addr;
  UInt16  id;

  // to get the id of the local address if id is not already known.
  id = SharedRegion_getId(addr);

  // to get the shared region pointer for the local address
  srptr = SharedRegion_getSRPtr(addr, id);

  // to get the local address from the shared region pointer
  addr = SharedRegion_getPtr(srptr);

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

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

Go to the source code of this file.

Data Structures

struct  SharedRegion_Entry
 Structure defining a region. More...

Defines

#define SharedRegion_S_BUSY   2
 The resource is still in use.
#define SharedRegion_S_ALREADYSETUP   1
 The module has been already setup.
#define SharedRegion_S_SUCCESS   0
 Operation is successful.
#define SharedRegion_E_FAIL   -1
 Generic failure.
#define SharedRegion_E_INVALIDARG   -2
 Argument passed to function is invalid.
#define SharedRegion_E_MEMORY   -3
 Operation resulted in memory failure.
#define SharedRegion_E_ALREADYEXISTS   -4
 The specified entity already exists.
#define SharedRegion_E_NOTFOUND   -5
 Unable to find the specified entity.
#define SharedRegion_E_TIMEOUT   -6
 Operation timed out.
#define SharedRegion_E_INVALIDSTATE   -7
 Module is not initialized.
#define SharedRegion_E_OSFAILURE   -8
 A failure occurred in an OS-specific call.
#define SharedRegion_E_RESOURCE   -9
 Specified resource is not available.
#define SharedRegion_E_RESTART   -10
 Operation was interrupted. Please restart the operation.
#define SharedRegion_INVALIDREGIONID   (0xFFFF)
 Invalid region id.
#define SharedRegion_DEFAULTOWNERID   (UInt16)(~0)
 Default owner processor id.

Typedefs

typedef Bits32 SharedRegion_SRPtr
 SharedRegion pointer type.

Functions

Int SharedRegion_clearEntry (UInt16 regionId)
 Clears the entry at the specified region id.
Void SharedRegion_entryInit (SharedRegion_Entry *entry)
 Initializes the entry fields.
SizeT SharedRegion_getCacheLineSize (UInt16 regionId)
 Gets the cache line size for the specified region id.
Int SharedRegion_getEntry (UInt16 regionId, SharedRegion_Entry *entry)
 Gets the entry information for the specified region id.
Ptr SharedRegion_getHeap (UInt16 regionId)
 Gets the heap associated with the specified region id.
UInt16 SharedRegion_getId (Ptr addr)
 Gets the region id for the specified address.
UInt16 SharedRegion_getIdByName (String name)
 Gets the id of a region, given its name.
UInt16 SharedRegion_getNumRegions (Void)
 Gets the number of regions.
Ptr SharedRegion_getPtr (SharedRegion_SRPtr srptr)
 Calculate the local pointer from the shared region pointer.
SharedRegion_SRPtr SharedRegion_getSRPtr (Ptr addr, UInt16 regionId)
 Calculate the shared region pointer given local address and id.
Bool SharedRegion_isCacheEnabled (UInt16 regionId)
 whether cache enable was specified
Int SharedRegion_setEntry (UInt16 regionId, SharedRegion_Entry *entry)
 Sets the entry at the specified region id.
Bool SharedRegion_translateEnabled (Void)
 Whether address translation is enabled.
SharedRegion_SRPtr SharedRegion_invalidSRPtr (Void)
 Returns the SharedRegion_SRPtr value that maps to NULL.

Define Documentation

#define SharedRegion_S_BUSY   2

The resource is still in use.

#define SharedRegion_S_ALREADYSETUP   1

The module has been already setup.

#define SharedRegion_S_SUCCESS   0

Operation is successful.

#define SharedRegion_E_FAIL   -1

Generic failure.

#define SharedRegion_E_INVALIDARG   -2

Argument passed to function is invalid.

#define SharedRegion_E_MEMORY   -3

Operation resulted in memory failure.

#define SharedRegion_E_ALREADYEXISTS   -4

The specified entity already exists.

#define SharedRegion_E_NOTFOUND   -5

Unable to find the specified entity.

#define SharedRegion_E_TIMEOUT   -6

Operation timed out.

#define SharedRegion_E_INVALIDSTATE   -7

Module is not initialized.

#define SharedRegion_E_OSFAILURE   -8

A failure occurred in an OS-specific call.

#define SharedRegion_E_RESOURCE   -9

Specified resource is not available.

#define SharedRegion_E_RESTART   -10

Operation was interrupted. Please restart the operation.

#define SharedRegion_INVALIDREGIONID   (0xFFFF)

Invalid region id.

#define SharedRegion_DEFAULTOWNERID   (UInt16)(~0)

Default owner processor id.


Typedef Documentation

typedef Bits32 SharedRegion_SRPtr

SharedRegion pointer type.


Function Documentation

Int SharedRegion_clearEntry ( UInt16  regionId  ) 

Clears the entry at the specified region id.

Parameters:
regionId the region id
Returns:
Status
See also:
SharedRegion_setEntry
Void SharedRegion_entryInit ( SharedRegion_Entry entry  ) 

Initializes the entry fields.

Parameters:
entry pointer to a SharedRegion entry
See also:
SharedRegion_setEntry
SizeT SharedRegion_getCacheLineSize ( UInt16  regionId  ) 

Gets the cache line size for the specified region id.

Parameters:
regionId the region id
Returns:
Cache line size
See also:
SharedRegion_isCacheEnabled
Int SharedRegion_getEntry ( UInt16  regionId,
SharedRegion_Entry entry 
)

Gets the entry information for the specified region id.

Parameters:
regionId the region id
entry pointer to return region information
Returns:
Status
See also:
SharedRegion_setEntry
Ptr SharedRegion_getHeap ( UInt16  regionId  ) 

Gets the heap associated with the specified region id.

Parameters:
regionId the region id
Returns:
Handle of the heap, NULL if the region has no heap
UInt16 SharedRegion_getId ( Ptr  addr  ) 

Gets the region id for the specified address.

Parameters:
addr address
Returns:
region id
UInt16 SharedRegion_getIdByName ( String  name  ) 

Gets the id of a region, given its name.

Parameters:
name name of the region
Returns:
region id
UInt16 SharedRegion_getNumRegions ( Void   ) 

Gets the number of regions.

Returns:
number of regions
Ptr SharedRegion_getPtr ( SharedRegion_SRPtr  srptr  ) 

Calculate the local pointer from the shared region pointer.

Parameters:
srptr SharedRegion pointer
Returns:
local pointer
See also:
SharedRegion_getPtr
SharedRegion_SRPtr SharedRegion_getSRPtr ( Ptr  addr,
UInt16  regionId 
)

Calculate the shared region pointer given local address and id.

Parameters:
addr the local address
regionId region id
Returns:
SharedRegion pointer
See also:
SharedRegion_getPtr
Bool SharedRegion_isCacheEnabled ( UInt16  regionId  ) 

whether cache enable was specified

Parameters:
regionId region id
Returns:
'TRUE' if cache enable specified, otherwise 'FALSE'
Int SharedRegion_setEntry ( UInt16  regionId,
SharedRegion_Entry entry 
)

Sets the entry at the specified region id.

Parameters:
regionId region id
entry pointer to set region information.
Returns:
Status
Bool SharedRegion_translateEnabled ( Void   ) 

Whether address translation is enabled.

Returns:
'TRUE' if translate is enabled otherwise 'FALSE'
SharedRegion_SRPtr SharedRegion_invalidSRPtr ( Void   ) 

Returns the SharedRegion_SRPtr value that maps to NULL.

Returns:
Value in SRPtr-space that maps to NULL in Ptr-space

Copyright 2010, Texas Instruments Incorporated