Tornado API Reference : Target Server Internal Routines
tgtmem - target memory manager
tgtMemMalloc( ) - allocate a block of memory from the system memory partition
tgtMemFree( ) - free a block of memory
tgtMemCalloc( ) - allocate a block of memory for an array
tgtMemRealloc( ) - reallocate a block of memory
tgtMemValloc( ) - allocate memory on a page boundary
tgtMemRead( ) - read a block of target memory
tgtMemWidthRead( ) - read a block of target memory
tgtMemSet( ) - set a memory area to a particular value
tgtMemWriteByte( ) - write a byte to the target
tgtMemWriteShort( ) - write a short to the target
tgtMemWriteInt( ) - write an int to the target
tgtMemWrite( ) - write a block to the target
tgtMemWidthWrite( ) - write a block to the target
tgtMemMove( ) - move a block on the target
tgtMemCacheSet( ) - give a block of target memory an attribute
tgtMemCacheGet( ) - get a block descriptor for target memory
tgtMemAlignGet( ) - return the alignment value for the target memory
This library provides core facilities for managing the allocation of blocks of memory from the target agent's pool of memory. This library consists of two sets of routines: the first comprises a general facility for the target memory cache and for the allocation and deallocation of blocks from the target; the second comprises a general facility for read/write operations.
The allocation of memory, typically using tgtMemMalloc( ), is done with a first-fit algorithm. Adjacent blocks of memory are coalesced when they are freed.
Architectures have various alignment constraints. To provide optimal performance, tgtMemMalloc( ) returns a pointer to a buffer having the appropriate alignment for the target architecture in use.
tgtmem.h
tgtMemMalloc( ) - allocate a block of memory from the system memory partition
REMPTR tgtMemMalloc ( size_t nBytes /* number of bytes to allocate */ )
This routine allocates a block of memory from the free list. The size of the block is equal to or greater than nBytes and it matches the target's alignment requirements.
A pointer to the allocated block of memory or a NULL pointer if an error occurs.
tgtmem, API Programmer's Guide: Object Module Loader
tgtMemFree( ) - free a block of memory
void tgtMemFree ( REMPTR ptr /* pointer to block of memory to free */ )
This routine returns a block of memory, previously allocated with tgtMemMalloc( ), tgtMemCalloc( ), or tgtMemValloc( ), to the free memory pool.
N/A
tgtmem, API Programmer's Guide: Object Module Loader
tgtMemCalloc( ) - allocate a block of memory for an array
REMPTR tgtMemCalloc ( size_t elemNum, /* number of elements */ size_t elemSize /* size of elements */ )
This routine allocates a block of memory for an array that contains elemNum elements of size elemSize. This space matches the target alignment requirements and is initially filled with zeros.
A pointer to the block or NULL if the call fails.
tgtmem, API Programmer's Guide: Object Module Loader
tgtMemRealloc( ) - reallocate a block of memory
REMPTR tgtMemRealloc ( REMPTR pBlock, /* block to reallocate */ size_t newSize /* new block size */ )
This routine changes the size of a specified block of memory and returns a pointer to the new block of memory. The contents of the old memory block that fit inside the new size (or the old size if the new block is smaller) remain unchanged. The memory alignment of the new block is not guaranteed to be the same as the original block.
A pointer to the new block of memory or NULL if the call fails.
tgtmem, API Programmer's Guide: Object Module Loader
tgtMemValloc( ) - allocate memory on a page boundary
REMPTR tgtMemValloc ( unsigned size /* number of bytes to allocate */ )
This routine allocates a buffer of size bytes from the system memory partition. Additionally, it insures that the allocated buffer begins on a page boundary. Page sizes depend on the target architecture.
A pointer to the newly allocated block or NULL if the buffer cannot be allocated or the memory management unit (MMU) support library has not been initialized.
tgtmem, API Programmer's Guide: Object Module Loader
tgtMemRead( ) - read a block of target memory
STATUS tgtMemRead ( REMPTR source, void * destination, int nBytes )
This routine reads a block of memory from the target. Actual operation depends on the cache memory attribute of the destination block.
OK or ERROR if the block of memory does not exist or cannot be read.
tgtmem, tgtMemCacheSet( ), API Programmer's Guide: Object Module Loader
tgtMemWidthRead( ) - read a block of target memory
STATUS tgtMemWidthRead ( REMPTR source, void * destination, int nBytes, int width )
This routine reads a block of memory from the target. Actual operation depends on the cache memory attribute of the destination block. The memory is read width bytes by width bytes.
OK or ERROR if the block of memory does not exist or cannot be read.
tgtmem, tgtMemCacheSet( ), API Programmer's Guide: Object Module Loader
tgtMemSet( ) - set a memory area to a particular value
STATUS tgtMemSet ( REMPTR destination, /* buffer to be set */ int nBytes, /* number of bytes in buffer */ int value /* set value */ )
This routine fills a block of target memory with the specified value. Actual operation depends on the cache memory attribute of the destination block.
OK or ERROR if the operation fails.
tgtmem, tgtMemCacheSet( ), API Programmer's Guide: Object Module Loader
tgtMemWriteByte( ) - write a byte to the target
STATUS tgtMemWriteByte ( REMPTR destination, char value )
This routine writes a byte to the target. Actual operation depends on the cache memory attribute of the destination block.
OK or ERROR if the operation fails.
tgtmem, tgtMemCacheSet( ), tgtMemWrite( ), API Programmer's Guide: Object Module Loader
tgtMemWriteShort( ) - write a short to the target
STATUS tgtMemWriteShort ( REMPTR destination, UINT16 value )
This routine writes a short to the target. Actual operation depends on the cache memory attribute of the destination block.
OK or ERROR if the operation fails.
tgtmem, tgtMemCacheSet( ), tgtMemWrite( ), API Programmer's Guide: Object Module Loader
tgtMemWriteInt( ) - write an int to the target
STATUS tgtMemWriteInt ( REMPTR destination, int value )
This routine writes a integer to the target. Actual operation depends on the cache memory attribute of the destination block.
OK or ERROR if the operation fails.
tgtmem, tgtMemCacheSet( ), tgtMemWrite( ), API Programmer's Guide: Object Module Loader
tgtMemWrite( ) - write a block to the target
STATUS tgtMemWrite ( void * source, REMPTR destination, int nBytes )
This routine writes a block of memory to the target. Actual operation depends on the cache memory attribute of the destination block.
OK or ERROR if the operation fails.
tgtmem, tgtMemCacheSet( ), API Programmer's Guide: Object Module Loader
tgtMemWidthWrite( ) - write a block to the target
STATUS tgtMemWidthWrite ( void * source, REMPTR destination, int nBytes, int width )
This routine writes a block of memory to the target. Actual operation depends on the cache memory attribute of the destination block. The memory is written width bytes by width bytes.
OK or ERROR if the operation fails.
tgtmem, tgtMemCacheSet( ), API Programmer's Guide: Object Module Loader
tgtMemMove( ) - move a block on the target
STATUS tgtMemMove ( REMPTR source, REMPTR destination, int nBytes )
This routine copies a block of memory from one target location to another target location and updates the host memory cache.
OK or ERROR if the operations fails.
tgtmem, tgtMemCacheSet( ), API Programmer's Guide: Object Module Loader
tgtMemCacheSet( ) - give a block of target memory an attribute
STATUS tgtMemCacheSet ( REMPTR pRem, /* pointer to block of memory to map */ int nBytes, /* block size */ MEM_ATTRIB attribute, /* attribute of memory */ BOOL pushBlock /* push the block to target memory */ )
This routine specifies the attribute of a block of host-mapped target memory. Blocks with attributes may not overlap, but block attributes mapped previously with this routine may be changed with this routine. All allocation routines return memory with the attribute MEM_NONE.
The possible values for MEM_ATTRIBUTE are:
- MEM_NO_WRITE
- Flag write operations as errors. Perform read operations from the target. This is typically used to protect read-only data structures. Note that this does not protect the memory from a target-originated write, only from writes originating from the host.
- MEM_HOST
- Allocate a block of memory to store all reads and writes locally. Do not update the target memory when the block is modified. This mode is utilized to prefill an entire block of memory before the block is transferred to the target. When relocating a new object module into target memory, for instance, the object module can be staged in this way to avoid all target intrusion during the link.
- MEM_TEXT
- Allocate a block of memory to cache all reads from this region. Handle writes as write-through requests, updating both the cache and the target memory.
Setting the attribute of a block the first time does not synchronize the target and host memory. However, when changing an attribute to turn off MEM_HOST, a tgtMemWrite( ) of the block is performed to update target memory.
OK or ERROR if passed an invalid block pointer, if the block is not mapped or if the target server cache for agent memory is full.
tgtmem, API Programmer's Guide: Object Module Loader
tgtMemCacheGet( ) - get a block descriptor for target memory
STATUS tgtMemCacheGet ( REMPTR pRem, /* pointer to block of memory to map */ BLOCK_DESC * pBlockDesc /* memory descriptor to fill in */ )
This routine fills in a block descriptor for the block of memory in which the specified remote pointer resides.
typedef struct /* BLOCK_DESC */ { MEM_DESC memDesc; /* block descriptor */ REMPTR base; /* block pointer */ void * pLocal; /* local cached copy */ int nBytes; /* block size */ MEM_ATTRIB attrib; /* memory attribute */ } BLOCK_DESC;The size of the block is returned in the field nBytes. If the block has no attribute set, the attribute MEM_NONE is returned, and the nBytes field contains the number of bytes to the beginning of the next highest block with an attribute set or NONE if there is no higher block.
OK or ERROR if the operation fails.
tgtmem, tgtMemCacheSet( ), API Programmer's Guide: Object Module Loader
tgtMemAlignGet( ) - return the alignment value for the target memory
UINT tgtMemAlignGet (void)
This function returns the alignment value for the target memory.
An integer or ERROR if the operation fails.