module ti.sdo.ipc.SharedRegion

Shared memory manager and address translator

C synopsis
XDCscript usage
XDCspec declarations
Individual elements
Additional documentation

This module has a common header that can be found in the ti.ipc package. Application code should include the common header file (not the RTSC-generated one):

#include <ti/ipc/SharedRegion.h>

The RTSC module must be used in the application's RTSC configuration file (.cfg) if runtime APIs will be used in the application:

SharedRegion = xdc.useModule('ti.sdo.ipc.SharedRegion');

Documentation for all runtime APIs, instance configuration parameters, error codes macros and type definitions available to the application integrator can be found in the Doxygen documenation for the IPC product. However, the documentation presented on this page should be referred to for information specific to the RTSC module, such as module configuration, Errors, and Asserts. [ more ... ]

XDCspec summary sourced in ti/sdo/ipc/SharedRegion.xdc

module SharedRegion { ...

// inherits xdc.runtime.IModule

C synopsis target-domain

#include <ti/sdo/ipc/SharedRegion.h>

module-wide constants & types

#define SharedRegion_DEFAULTOWNERID// Specifies the default owner proc id (UInt16)~0

#define SharedRegion_INVALIDREGIONID// Specifies the invalid id (UInt16)0xFFFF

typedef Bits32 SharedRegion_SRPtr// Definition of shared region pointer type;

typedef struct SharedRegion_Entry// Structure for specifying a region {

Ptr base;

SizeT len;

UInt16 ownerProcId;

Bool isValid;

Bool cacheEnable;

SizeT cacheLineSize;

Bool createHeap;

String name;

} SharedRegion_Entry;

module-wide config parameters

extern const Assert_Id SharedRegion_A_addrOutOfRange// Assert raised when an address is out of the range of the region id;

extern const Assert_Id SharedRegion_A_alreadyExists// Assert raised when a valid table entry already exists;

extern const Assert_Id SharedRegion_A_cacheLineSizeIsZero// Assert raised when cache enabled but cache line size = 0;

extern const Assert_Id SharedRegion_A_idTooLarge// Assert raised when the id is larger than numEntries;

extern const Assert_Id SharedRegion_A_noHeap// Assert raised when trying to use a heap for a region that has no heap;

extern const Assert_Id SharedRegion_A_overlap// Assert raised when a new entry overlaps an existing one;

extern const Assert_Id SharedRegion_A_region0Clear// Assert raised when attempting to clear region 0;

extern const Assert_Id SharedRegion_A_region0Invalid// Assert raised when region zero is invalid;

extern const Assert_Id SharedRegion_A_regionInvalid// Assert raised when region is invalid;

extern const Assert_Id SharedRegion_A_reserveTooMuch// Assert raised when the trying to reserve too much memory;

extern const SizeT SharedRegion_cacheLineSize// Worst-case cache line size;

extern const UInt16 SharedRegion_numEntries// The number of shared region table entries;

extern const Bool SharedRegion_translate// Determines whether address translation is required;

module-wide built-ins

Types_ModuleId SharedRegion_Module_id// Get this module's unique id( );

Bool SharedRegion_Module_startupDone// Test if this module has completed startup( );

IHeap_Handle SharedRegion_Module_heap// The heap from which this module allocates memory( );

Bool SharedRegion_Module_hasMask// Test whether this module has a diagnostics mask( );

Bits16 SharedRegion_Module_getMask// Returns the diagnostics mask for this module( );

Void SharedRegion_Module_setMask// Set the diagnostics mask for this module( Bits16 mask );

XDCscript usage meta-domain

var SharedRegion = xdc.useModule('ti.sdo.ipc.SharedRegion');

module-wide constants & types

const SharedRegion.DEFAULTOWNERID// Specifies the default owner proc id = ~0;

const SharedRegion.INVALIDREGIONID// Specifies the invalid id = 0xFFFF;

var obj = new SharedRegion.Entry// Structure for specifying a region;

obj.base = Ptr ...

obj.len = SizeT ...

obj.ownerProcId = UInt16 ...

obj.isValid = Bool ...

obj.cacheEnable = Bool ...

obj.cacheLineSize = SizeT ...

obj.createHeap = Bool ...

obj.name = String ...

module-wide config parameters

SharedRegion.A_addrOutOfRange// Assert raised when an address is out of the range of the region id = Assert.Desc {

msg: "A_addrOutOfRange: Address is out of region id's range"

};

SharedRegion.A_alreadyExists// Assert raised when a valid table entry already exists = Assert.Desc {

msg: "A_alreadyExists: Trying to overwrite an existing valid entry"

};

SharedRegion.A_cacheLineSizeIsZero// Assert raised when cache enabled but cache line size = 0 = Assert.Desc {

msg: "A_cacheLineSizeIsZero: cache line size cannot be zero"

};

SharedRegion.A_idTooLarge// Assert raised when the id is larger than numEntries = Assert.Desc {

msg: "A_idTooLarge: id cannot be larger than numEntries"

};

SharedRegion.A_noHeap// Assert raised when trying to use a heap for a region that has no heap = Assert.Desc {

msg: "A_noHeap: Region has no heap"

};

SharedRegion.A_overlap// Assert raised when a new entry overlaps an existing one = Assert.Desc {

msg: "A_overlap: Shared region overlaps"

};

SharedRegion.A_region0Clear// Assert raised when attempting to clear region 0 = Assert.Desc {

msg: "A_region0Clear: Region 0 cannot be cleared"

};

SharedRegion.A_region0Invalid// Assert raised when region zero is invalid = Assert.Desc {

msg: "A_region0Invalid: Region zero is invalid"

};

SharedRegion.A_regionInvalid// Assert raised when region is invalid = Assert.Desc {

msg: "A_regionInvalid: Region is invalid"

};

SharedRegion.A_reserveTooMuch// Assert raised when the trying to reserve too much memory = Assert.Desc {

msg: "A_reserveTooMuch: Trying to reserve too much memory"

};

SharedRegion.cacheLineSize// Worst-case cache line size = SizeT 128;

SharedRegion.numEntries// The number of shared region table entries = UInt16 4;

SharedRegion.translate// Determines whether address translation is required = Bool true;

SharedRegion.common$// Common module configuration parameters = Types.Common$ undefined;

module-wide functions

SharedRegion.getCacheLineSizeMeta// Meta version of Ipc_getCacheLineSize( UInt16 id ) returns SizeT

SharedRegion.setEntryMeta// Sets the entry at the specified region id in the shared region table( UInt16 id, SharedRegion.Entry entry ) returns Void

XDCspec declarations sourced in ti/sdo/ipc/SharedRegion.xdc

package ti.sdo.ipc;

module SharedRegion {

module-wide constants & types

const UInt16 DEFAULTOWNERID// Specifies the default owner proc id = ~0;

const UInt16 INVALIDREGIONID// Specifies the invalid id = 0xFFFF;

typedef Bits32 SRPtr// Definition of shared region pointer type;

struct Entry// Structure for specifying a region {

Ptr base;

SizeT len;

UInt16 ownerProcId;

Bool isValid;

Bool cacheEnable;

SizeT cacheLineSize;

Bool createHeap;

String name;

};

module-wide config parameters

config Assert.Id A_addrOutOfRange// Assert raised when an address is out of the range of the region id = {

msg: "A_addrOutOfRange: Address is out of region id's range"

};

config Assert.Id A_alreadyExists// Assert raised when a valid table entry already exists = {

msg: "A_alreadyExists: Trying to overwrite an existing valid entry"

};

config Assert.Id A_cacheLineSizeIsZero// Assert raised when cache enabled but cache line size = 0 = {

msg: "A_cacheLineSizeIsZero: cache line size cannot be zero"

};

config Assert.Id A_idTooLarge// Assert raised when the id is larger than numEntries = {

msg: "A_idTooLarge: id cannot be larger than numEntries"

};

config Assert.Id A_noHeap// Assert raised when trying to use a heap for a region that has no heap = {

msg: "A_noHeap: Region has no heap"

};

config Assert.Id A_overlap// Assert raised when a new entry overlaps an existing one = {

msg: "A_overlap: Shared region overlaps"

};

config Assert.Id A_region0Clear// Assert raised when attempting to clear region 0 = {

msg: "A_region0Clear: Region 0 cannot be cleared"

};

config Assert.Id A_region0Invalid// Assert raised when region zero is invalid = {

msg: "A_region0Invalid: Region zero is invalid"

};

config Assert.Id A_regionInvalid// Assert raised when region is invalid = {

msg: "A_regionInvalid: Region is invalid"

};

config Assert.Id A_reserveTooMuch// Assert raised when the trying to reserve too much memory = {

msg: "A_reserveTooMuch: Trying to reserve too much memory"

};

config SizeT cacheLineSize// Worst-case cache line size = 128;

config UInt16 numEntries// The number of shared region table entries = 4;

config Bool translate// Determines whether address translation is required = true;

metaonly config Types.Common$ common$// Common module configuration parameters;

module-wide functions

metaonly SizeT getCacheLineSizeMeta// Meta version of Ipc_getCacheLineSize( UInt16 id );

metaonly Void setEntryMeta// Sets the entry at the specified region id in the shared region table( UInt16 id, SharedRegion.Entry entry );

}

DETAILS

This module has a common header that can be found in the ti.ipc package. Application code should include the common header file (not the RTSC-generated one):

#include <ti/ipc/SharedRegion.h>

The RTSC module must be used in the application's RTSC configuration file (.cfg) if runtime APIs will be used in the application:

SharedRegion = xdc.useModule('ti.sdo.ipc.SharedRegion');

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 numEntries must be the same on all processors.

Each shared region contains the following:

base: The base address
len: The length
name: The name of the region
isValid: Whether the region is valid
ownerProcId: The id of the processor which owns the region
cacheEnable: Whether the region is cacheable
cacheLineSize: The cache line size
createHeap: Whether a heap is created for the region.

A region is added statically using the setEntryMeta 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.

An example of a SharedRegion configuration is as follows:

 var SharedRegion = xdc.useModule('ti.sdo.ipc.SharedRegion');
 SharedRegion.setEntryMeta(0,
     { base: 0x80000000,
       len: 0x20000,
       ownerProcId: 0,
       isValid: true,
       cacheLineSize: 64,
       name: "DDR2",
     });

The shared region table along with a shared region pointer (SRPtr) is used to do address translation at runtime. The shared region pointer is a 32-bit portable pointer composed of an id and offset. The most significant bits of a SRPtr are used for the id. The id corresponds to the index of the entry in the table. The offset is the offset from the base of the shared memory region. The number of entries in the table determines the number of bits to use for the id. Increasing the number of entries increases the range of ids but decreases the range of the offset.

Note: Region 0 must be visible by all processors. Region 0 is used for synchonizing the processors, creating the default GateMP, and creating Notify and MessageQ transport instances. The HeapMemMP created in Region 0 is the length of the region minus memory reserved for creating these internal instances.

Refer to the doxygen documentation for run-time API documenation.

const SharedRegion.DEFAULTOWNERID