Test Resource Manager API

Overview

The Test Resource Manager API allows reading and writing files on the Windows machine (i.e. host) from the code running on the target. It is used in unit test applications to access data sets that are too large to fit into the target's memory.

Typical Uses

The most typical use of the Test Resource Manager API would involve opening a file on the host, reading the test data from it, and closing it. See the code below for a quick example:

TRMFileHandle hFile = TRMCreateFile("TestData.dat", sfmOpenReadOnly);
char buffer[512];

if (!hFile)
    FAIL("TestData.dat doesn't exist");

//Read and process data from <Project Dir>\TestResources\TestData.dat
for (;;)
{
    size_t done = TRMReadFile(hFile, buffer, sizeof(buffer));
    //TODO: process the data retrieved from the file
    if (done <= 0)
        break;
}

TRMCloseFile(hFile);

For performance-critical applications, we recommend using the Read Bursts and Write Bursts.

Read Bursts

Read bursts are the fastest way to sequentially read a file on the host. Once a read burst is active, VisualGDB will continuously read data from the file and will keep writing it into the intermediate buffer, as long as it has space. This will continue even while the target is running (e.g. processing the previously read data). Use the TRMBeginReadBurst, TRMEndReadBurst and TRMReadFileCached (or a more advanced combination of TRMBeginReadFileCached and TRMEndReadFileCached) to read the test resources using the burst API.

Below is a quick example of the read burst API:

TRMFileHandle hFile = TRMCreateFile("TestData.dat", sfmOpenReadOnly);
char buffer[512];
char temporaryBuffer[4096];

if (!hFile)
    FAIL("TestData.dat doesn't exist");

TRMReadBurstHandle hBurst = TRMBeginReadBurst(hFile, temporaryBuffer, sizeof(temporaryBuffer));

for (;;)
{
    size_t done = TRMReadFileCached(hBurst, buffer, sizeof(buffer), 0);
    //TODO: process the data retrieved from the file
    if (done <= 0)
        break;
}

TRMEndReadBurst(hBurst);
TRMCloseFile(hFile);    

Note that once a burst is active, calls to the regular TRMReadFile or TRMSeekFile will fail until the burst is ended.

Write Bursts

Write bursts allow quickly writing data to a file on the host, without stopping the target. They use the regular fast semihosting buffer to queue the written data. VisualGDB will process the queued data in the background, without interrupting the target, as long as there is sufficient space in the semihosting buffer.

Below is a quick example of the write burst API:

TRMFileHandle hFile = TRMCreateFile("TestData.dat", sfmCreateOrTruncateWriteOnly);
char buffer[512];
char temporaryBuffer[4096];

TRMWriteBurstHandle hBurst = TRMBeginWriteBurst(hFile);

for (;;)
{
    //TODO: process the data retrieved from the file
    size_t done = TRMWriteFileCached(hBurst, buffer, sizeof(buffer));
    if (done <= 0)
        break;
}

TRMEndWriteBurst(hBurst);
TRMCloseFile(hFile);    

All Functions

See the TestResourceManager.h file to a list of all Test Resource Manager functions.