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>
============================================================================
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 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 Bits32 SharedRegion_SRPtr |
SharedRegion pointer type.
typedef struct SharedRegion_Entry SharedRegion_Entry |
Structure defining a region.
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.
regionId | the region id |
Void SharedRegion_entryInit | ( | SharedRegion_Entry * | entry ) |
Initializes the entry fields.
entry | pointer to a SharedRegion entry |
Gets the cache line size for the specified region id.
regionId | the region id |
Int SharedRegion_getEntry | ( | UInt16 | regionId, |
SharedRegion_Entry * | entry | ||
) |
Gets the entry information for the specified region id.
regionId | the region id |
entry | pointer to return region information |
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
regionId | the region id |
Gets the region id for the specified address.
addr | address |
Gets the id of a region, given its name.
name | name of the region |
Ptr SharedRegion_getPtr | ( | SharedRegion_SRPtr | srptr ) |
Calculate the local pointer from the shared region pointer.
srptr | SharedRegion pointer |
SharedRegion_SRPtr SharedRegion_getSRPtr | ( | Ptr | addr, |
UInt16 | regionId | ||
) |
Calculate the shared region pointer given local address and id.
addr | the local address |
regionId | region id |
whether cache enable was specified
regionId | region id |
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.
regionId | region id |
entry | pointer to set region information. |
Whether address translation is enabled.
SharedRegion_SRPtr SharedRegion_invalidSRPtr | ( | Void | ) |
Returns the SharedRegion_SRPtr value that maps to NULL.