Contains Test Resource Manager API. More...

#include <stddef.h>
#include <stdint.h>
#include <stdio.h>
#include <memory.h>

Typedefs
typedef struct tagTRMFileHandle *	TRMFileHandle

typedef struct tagTRMReadBurstHandle *	TRMReadBurstHandle

typedef struct tagTRMWriteBurstHandle *	TRMWriteBurstHandle

Enumerations
enum	SemihostingFileMode { sfmCreateOrTruncateWriteOnly, sfmCreateOrAppendWriteOnly, sfmOpenReadOnly, sfmCreateOrOpenReadWrite, sfmCreateOrTruncateReadWrite }
	Lists the supported file open modes. More...

enum	TRMErrorCode { trmSuccess = 0, trmUnknownError = -1, trmInvalidArgument = -2 }
	Specifies the error code returned by common Test Resource Manager functions. More...

Functions
uint64_t	TRMGetHostSystemTime ()
	Returns system time on host in Windows FILETIME format. More...

TRMFileHandle	TRMCreateFile (const char *pFileName, SemihostingFileMode mode)
	Creates or opens a file on the host. More...

void	TRMCloseFile (TRMFileHandle hFile)
	Closes a handle returned by TRMCreateFile. More...

ssize_t	TRMReadFile (TRMFileHandle hFile, void *pBuffer, size_t size)
	Reads the data from a file on the host machine. More...

ssize_t	TRMWriteFile (TRMFileHandle hFile, const void *pBuffer, size_t size)
	Write the data to a file on the host machine. More...

uint64_t	TRMGetFileSize (TRMFileHandle hFile)
	Returns the size of the file. More...

uint64_t	TRMSeekFile (TRMFileHandle hFile, int mode, int64_t distance)
	Moves the file pointer. More...

void	TRMTruncateFile (TRMFileHandle hFile)
	Truncates the file. More...

TRMErrorCode	TRMDeleteFile (const char *pFileName)
	Deletes a file. More...

TRMErrorCode	TRMCreateDirectory (const char *pDirName)
	Creates a subdirectory. More...

TRMErrorCode	TRMDeleteDirectory (const char *pDirName, int recursively)
	Deletes a file. More...

TRMReadBurstHandle	TRMBeginReadBurst (TRMFileHandle hFile, void *pWorkArea, size_t workAreaSize)
	Starts a read burst. More...

TRMErrorCode	TRMEndReadBurst (TRMReadBurstHandle hBurst)
	Ends a read burst. More...

void *	TRMBeginReadFileCached (TRMReadBurstHandle hBurst, size_t *pSize, int waitForData)
	Returns the pointer to a block of data that has been prefetched into the read burst buffer. More...

TRMErrorCode	TRMEndReadFileCached (TRMReadBurstHandle hBurst, void *pBuffer, size_t size)
	Releases the buffer returned by TRMBeginReadFileCached. More...

ssize_t	TRMReadFileCached (TRMReadBurstHandle hBurst, void *pBuffer, size_t size, int allowPartialReads)
	Reads data within a read burst. More...

TRMWriteBurstHandle	TRMBeginWriteBurst (TRMFileHandle hFile)
	Starts a read burst. More...

TRMErrorCode	TRMEndWriteBurst (TRMWriteBurstHandle hBurst)
	Ends a write burst. More...

ssize_t	TRMWriteFileCached (TRMWriteBurstHandle hBurst, const void *pData, size_t size)
	Writes data within a write burst. More...

Detailed Description

Contains Test Resource Manager API.

Typedef Documentation

typedef struct tagTRMFileHandle* TRMFileHandle

typedef struct tagTRMReadBurstHandle* TRMReadBurstHandle

typedef struct tagTRMWriteBurstHandle* TRMWriteBurstHandle

Enumeration Type Documentation

enum SemihostingFileMode

Lists the supported file open modes.

Enumerator
sfmCreateOrTruncateWriteOnly	Create an empty file if it doesn't exist. Otherwise, truncate an existing file. Allow writing to the file, but not reading from it.
sfmCreateOrAppendWriteOnly	Create an empty file if it doesn't exist. Otherwise, open the existing file and immediately seek to the end of it. Allow writing to the file, but not reading from it.
sfmOpenReadOnly	Open an existing file in read-only mode. If the file doesn't exist, TRMCreateFile will return 0.
sfmCreateOrOpenReadWrite	Open an existing file and allow reading/writing it. If the file doesn't exist, create it.
sfmCreateOrTruncateReadWrite	Create an empty file if it doesn't exist. Otherwise, truncate an existing file. Allow reading to the file and reading from it.

enum TRMErrorCode

Specifies the error code returned by common Test Resource Manager functions.

Remarks: Use View->Other Windows->VisualGDB Diagnostics Console to see details on why a specific Test Resource Manager call failed.

Enumerator
trmSuccess
trmUnknownError
trmInvalidArgument

Function Documentation

TRMReadBurstHandle TRMBeginReadBurst	(	TRMFileHandle	hFile,
		void *	pWorkArea,
		size_t	workAreaSize
	)

Starts a read burst.

This function starts a read burst (i.e. background prefetch) using the supplied temporary buffer. See Read Bursts for more details. Once a burst has been started, use TRMReadFileCached to read the data from the file.

Parameters

hFile	File handle returned by TRMCreateFile.
pWorkArea	Temporary buffer that will be used to prefetch the data from the host. The buffer must be at least 16 bytes long (although 4096KB or more is recommended for optimal performance).
workAreaSize	Specifies the temporary buffer size, in bytes.

Returns: The function returns a read burst handle. If an error occurs, the function returns 0.

Remarks: Once the burst has been started, VisualGDB will automatically prefetch the file contents and store it in the buffer without interrupting the target. Use the TRMBeginReadFileCached (or TRMBeginReadFileCached + TRMEndReadFileCached) to access the data. Use TRMEndReadBurst to end an active burst.

void* TRMBeginReadFileCached	(	TRMReadBurstHandle	hBurst,
		size_t *	pSize,
		int	waitForData
	)

Returns the pointer to a block of data that has been prefetched into the read burst buffer.

This function allows directly accessing the data that has been prefetched by VisualGDB into the burst buffer. Use TRMEndReadFileCached to release the returned data and let VisualGDB rewrite it with new data. Call TRMEndReadFileCached to release the returned buffer.

Parameters

hBurst	Burst handle returned by TRMBeginReadBurst
pSize	Receives the amount of bytes available for processing
waitForData	Specifies whether to wait for more data, if it hasn't been fetched yet

Returns: The function returns the pointer to the first byte of the data fetched from the file. If the end-of-file has been reached, or if waitForData is 0 and no new data has been fetched by the host yet, the function returns NULL.

The typical use of the TRMBeginReadFileCached/TRMEndReadFileCached functions is shown below:

 for (;;)
 {
     size_t size = 0;
     void *pData = TRMBeginReadFileCached(hBurst, &size, 1);
     if (!pData)
         break;  //End-of-file
     ProcessData(pData, size);
     TRMEndReadFileCached(hBurst, pData, size);
 }

Remarks: Is is critical to call TRMEndReadFileCached after each succesful call to TRMBeginReadFileCached. If you prefer a simpler API, use the TRMReadFileCached function instead.

TRMWriteBurstHandle TRMBeginWriteBurst ( TRMFileHandle hFile )

Starts a read burst.

This function starts a write burst (i.e. series of cached non-blocking writes) using the fast semihosting buffer. See Write Bursts for more details. Once a burst has been started, use TRMWriteFileCached to write the data to the file.

Parameters

hFile File handle returned by TRMCreateFile.

Remarks: Once the burst has been started, regular file API will not work for the file. Use TRMEndWriteBurst to end the burst. Each file can only have one burst operation active at once, however multiple files can have active bursts at the same time.

void TRMCloseFile ( TRMFileHandle hFile )

Closes a handle returned by TRMCreateFile.

TRMErrorCode TRMCreateDirectory ( const char * pDirName )

Creates a subdirectory.

This function creates a subdirectory inside the TestResources folder of the current project. See TRMCreateFile for the limitations on file paths.

TRMFileHandle TRMCreateFile	(	const char *	pFileName,
		SemihostingFileMode	mode
	)

Creates or opens a file on the host.

This function creates or opens a file in the TestResources directory of the project on the Windows machine.

Parameters

pFileName	Specifies the relative path to the file (including possible subdirectories). Absolute paths, or paths starting with ".." will be rejected by the host.
mode	Specifies the file open mode. See SemihostingFileMode for a list of supported modes.

Returns: The function returns a file handle that can be used in calls to TRMReadFile, TRMWriteFile and other functions. If the function fails, the returned value will be 0. Use TRMCloseFile to close the returned handle.

TRMErrorCode TRMDeleteDirectory	(	const char *	pDirName,
		int	recursively
	)

Deletes a file.

This function deletes a directory inside the TestResources folder of the current project. See TRMCreateFile for the limitations on file paths.

Parameters

pDirName	Relative path to the deleted subdirectory.
recursively	Specify a non-zero value to delete the directory recursively.

Remarks: VisualGDB will automatically restrict all file API (including TRMDeleteDirectory) to the TestResources folder of the debugged project.

TRMErrorCode TRMDeleteFile ( const char * pFileName )

Deletes a file.

This function deletes a file inside the TestResources folder of the current project. See TRMCreateFile for the limitations on file paths.

TRMErrorCode TRMEndReadBurst ( TRMReadBurstHandle hBurst )

Ends a read burst.

Parameters

hBurst Burst handle returned by TRMBeginReadBurst

TRMErrorCode TRMEndReadFileCached	(	TRMReadBurstHandle	hBurst,
		void *	pBuffer,
		size_t	size
	)

Releases the buffer returned by TRMBeginReadFileCached.

Parameters

hBurst	Burst handle returned by TRMBeginReadBurst
pBuffer	Buffer returned by TRMBeginReadFileCached
size	Specifies the amount of bytes to be released. It must be equal or less to the amount of bytes returned by TRMBeginReadBurst via the pSize

parameter.

Remarks: After a buffer has been released by a call to TRMEndReadFileCached, you can immediately call TRMBeginReadFileCached to read the next portion of data from the file.

TRMErrorCode TRMEndWriteBurst ( TRMWriteBurstHandle hBurst )

Ends a write burst.

Parameters

hBurst Burst handle returned by TRMBeginWriteBurst

uint64_t TRMGetFileSize ( TRMFileHandle hFile )

Returns the size of the file.

Parameters

hFile File handle returned by TRMCreateFile.

uint64_t TRMGetHostSystemTime ( )

Returns system time on host in Windows FILETIME format.

Returns: The function returns the number of 100-nanosecond intervals elapsed since January 1, 1601 (UTC).

ssize_t TRMReadFile	(	TRMFileHandle	hFile,
		void *	pBuffer,
		size_t	size
	)

Reads the data from a file on the host machine.

Parameters

hFile	File handle returned by TRMCreateFile.
pBuffer	Buffer that will receive the data.
size	The maximum number of bytes that should be read from the file.

Returns: Normally, the function returns the amount of bytes that was read from the file. Unless an end of file is reached, or an error occurs, it will be equivalent to the size parameter. If an end of file is reached, will return 0. If an error occurs, the function will return a negative value.

Remarks: TRMReadFile will not prefetch any data from the host and may take some time to process due to the latency between the host and the target. For a faster prefetching alternative to TRMReadFile, see Read Bursts.

ssize_t TRMReadFileCached	(	TRMReadBurstHandle	hBurst,
		void *	pBuffer,
		size_t	size,
		int	allowPartialReads
	)

Reads data within a read burst.

This function reads a portion of data within a read burst into the supplied buffer. Because the read bursts involve prefetching the data into a temporary buffer (see TRMBeginReadBurst), calling this function involves an unnecessary copying of data between the temporary buffer and the final buffer. If you would like to avoid it, use the TRMBeginReadFileCached/TRMEndReadFileCached instead.

Parameters

hBurst	Burst handle returned by TRMBeginReadBurst
pBuffer	Buffer that will receive the data
size	Maximum amount of bytes to read
allowPartialReads	Specifies whether the function can return if some, but not all of the data has been read (similar to the socket API).

Returns: If the function succeeds, it returns the number of bytes read from the file. Unless allowPartialReads was set to 1, an end-of-file or an error has been encountered, it will be equal to the size parameter. If the function fails, the return value is zero or negative.

uint64_t TRMSeekFile	(	TRMFileHandle	hFile,
		int	mode,
		int64_t	distance
	)

Moves the file pointer.

Parameters

hFile	File handle returned by TRMCreateFile.
mode	Specifies one of the following values SEEK_SET. The distance is an absolute value from the beginning of the file. SEEK_CUR. The distance is a relative value (positive of negative), relative to the current position of the file pointer. SEEK_END. The distance is a negative value, relative to the end of the file.
distance	Specifies the distance to move the file pointer. See the mode parameter for more details.

void TRMTruncateFile ( TRMFileHandle hFile )

Truncates the file.

This function will set the end-of-file to the current position of the file pointer.

Parameters

hFile File handle returned by TRMCreateFile.

ssize_t TRMWriteFile	(	TRMFileHandle	hFile,
		const void *	pBuffer,
		size_t	size
	)

Write the data to a file on the host machine.

Parameters

hFile	File handle returned by TRMCreateFile.
pBuffer	Buffer that contains the data.
size	The maximum number of bytes that should be written to the file.

Returns: Normally, the function returns the amount of bytes that was written to the file. Unless an error occurs, it will be equivalent to the size parameter. If an error occurs, the function will return a negative value or a zero.

Remarks: TRMWriteFile will not return until the host receives the written data. This may take some time due to the latency between the host and the target. For a faster non-blocking alternative to TRMWriteFile, see Write Bursts.

ssize_t TRMWriteFileCached	(	TRMWriteBurstHandle	hBurst,
		const void *	pData,
		size_t	size
	)

Writes data within a write burst.

This function writes data to a file on the host within a write burst. As long as the fast semihosting buffer has sufficient space, the function will return immediately, letting the target run more code, while VisualGDB is processing the data in the background.

Parameters

hBurst	Burst handle returned by TRMBeginWriteBurst.
pBuffer	Buffer that contains the data.
size	The maximum number of bytes that should be written to the file.

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

Enumeration Type Documentation

Function Documentation