Data Structures | Defines | Typedefs | Functions

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.

Note: Prior to calling Ipc_start(), If a SharedRegion's 'isValid' is true and 'createHeap' is true then the owner of the SharedRegion must be the same as the owner of SharedRegion 0.

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);

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

  #include <ti/ipc/SharedRegion.h>

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

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.

Typedefs

typedef Bits32 SharedRegion_SRPtr
 SharedRegion pointer type.
typedef struct SharedRegion_Entry SharedRegion_Entry
 Structure defining a region.

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.


Typedef Documentation

typedef Bits32 SharedRegion_SRPtr

SharedRegion pointer type.

Structure defining a region.


Function Documentation

Int SharedRegion_clearEntry ( UInt16  regionId )

Clears the entry at the specified region id.

SharedRegion_clearEntry is used to render invalid a shared region that is currently valid. If the region has a heap, it will either be closed or deleted as necessary. All attributes of region are reset to defaults.

Calling SharedRegion_clearEntry upon a region that is already invalid simply resets the region attributes to their defaults.

NOTE: Region #0 is special and can neither be cleared nor set.

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

Initializes the entry fields.

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

Gets the cache line size for the specified region id.

Parameters:
regionIdthe 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:
regionIdthe region id
entrypointer to return region information
Returns:
Status
See also:
SharedRegion_setEntry
Ptr SharedRegion_getHeap ( UInt16  regionId )

Gets the heap associated with the specified region id.

If running on BIOS, the heap handle returned is of type xdc.runtime.IHeap. This handle type can be used with xdc.runtime.Memory. However, if running on Linux, the heap handle is of type ti.syslink.utils.IHeap. This handle type cannot be used with xdc.runtime.Memory, but can be used with ti.syslink.utils.Memory. The handle type is determined at compile time and cannot be deferred until runtime. The correct header file must be included to get the right type.

The following code shows an example.

  #if defined(ti_sdo_ipc)
  #include <xdc/runtime/IHeap.h>
  #include <xdc/runtime/Memory.h>
  #elif defined(ti_syslink)
  #include <ti/syslink/utils/IHeap.h>
  #include <ti/syslink/utils/Memory.h>
  #endif
  #include <ti/ipc/SharedRegion.h>

  IHeap_Handle heap;
  UInt16       regionId;
  SizeT        size;
  SizeT        align;

  heap = (IHeap_Handle)SharedRegion_getHeap(regionId);  // get the heap 
  Memory_alloc(heap, size, align, NULL);  // alloc memory from heap
Parameters:
regionIdthe 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:
addraddress
Returns:
region id
UInt16 SharedRegion_getIdByName ( String  name )

Gets the id of a region, given its name.

Parameters:
namename 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:
srptrSharedRegion pointer
Returns:
local pointer
See also:
SharedRegion_getSRPtr
SharedRegion_SRPtr SharedRegion_getSRPtr ( Ptr  addr,
UInt16  regionId 
)

Calculate the shared region pointer given local address and id.

Parameters:
addrthe local address
regionIdregion id
Returns:
SharedRegion pointer
See also:
SharedRegion_getPtr
Bool SharedRegion_isCacheEnabled ( UInt16  regionId )

whether cache enable was specified

Parameters:
regionIdregion 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.

SharedRegion_setEntry is used to set up a shared region that is currently invalid. Configuration is performed using the values supplied in the 'entry' parameter. If the 'createHeap' flag is TRUE, then a region heap will be created (if the processor is the region owner) or opened.

If 'createHeap' is TRUE, SharedRegion_setEntry must always be called by a 'client' of the shared region only after the region owner has called SharedRegion_setEntry. It is unsafe to poll using SharedRegion_setEntry to wait for the corresponding heap to be created by the owner. An external synchronization mechanism (i.e. Notify, shared memory, etc) must be used to ensure the proper sequence of operations.

NOTE: This function should never be called upon a region that is currently valid.

Parameters:
regionIdregion id
entrypointer 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
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines

Copyright 2012, Texas Instruments Incorporated