module ti.sdo.ipc.SharedRegion

Shared memory manager and address translator

C synopsis
Individual elements
XDCscript usage
Individual elements

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

C synopsis target-domain sourced in ti/sdo/ipc/SharedRegion.xdc

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

Functions common to all target modules
	SharedRegion_Module_getMask// Returns the diagnostics mask for this module, SharedRegion_Module_hasMask// Test whether this module has a diagnostics mask, SharedRegion_Module_heap// The heap from which this module allocates memory, SharedRegion_Module_id// Get this module's unique id, SharedRegion_Module_setMask// Set the diagnostics mask for this module, SharedRegion_Module_startupDone// Test if this module has completed startup
Defines
#define	SharedRegion_DEFAULTOWNERID// Specifies the default owner proc id (UInt16)~0
#define	SharedRegion_INVALIDREGIONID// Specifies the invalid id (UInt16)0xFFFF
Typedefs
typedef struct	SharedRegion_Entry// Structure for specifying a region ...
typedef Bits32	SharedRegion_SRPtr// Definition of shared region pointer type;
Constants
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;

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.

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.

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