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

Detailed Description

Shared memory manager and address translator.

Note
SharedRegion is currently only available for SYS/BIOS.

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:

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:

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

Macros

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

Typedefs

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

Functions

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

Macro Definition 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 regionid entry.

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()
SharedRegion_Entry* SharedRegion_getEntryPtr ( UInt16  regionId)

Return the address of the shared region entry structure.

This function is to be used only for module startup configuration. The returned address gives you direct access to the in-memory entry structure. Use it to configure the entry just before the module startup phase begins. It is intended to support single-image loading.

Do not use this function during normal run-time operations; use SharedRegion_getEntry() instead.

Ptr SharedRegion_getHeap ( UInt16  regionId)

Gets the heap associated with the specified region id.

The heap handle returned is of type xdc.runtime.IHeap. This handle type can be used with xdc.runtime.Memory.

The following code shows an example.

1 #include <xdc/runtime/IHeap.h>
2 #include <xdc/runtime/Memory.h>
3 #include <ti/ipc/SharedRegion.h>
4 
5 IHeap_Handle heap;
6 UInt16 regionId;
7 SizeT size;
8 SizeT align;
9 
10 heap = (IHeap_Handle)SharedRegion_getHeap(regionId); // get the heap
11 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 or NULL if shared region pointer is invalid
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
Copyright 2015, Texas Instruments Incorporated