![]() |
Simutrace
3.0
Simulation Tracing Framework
|
Functions | |
SIMUTRACE_API int | StGetLastError (ExceptionInformation *informationOut) |
Returns the last exception. More... | |
SIMUTRACE_API SessionId | StSessionCreate (const char *server) |
Creates a new session. More... | |
SIMUTRACE_API BOOL | StSessionOpen (SessionId session) |
Opens an existing local session. More... | |
SIMUTRACE_API BOOL | StSessionClose (SessionId session) |
Closes an open session. More... | |
SIMUTRACE_API BOOL | StSessionCreateStore (SessionId session, const char *specifier, BOOL alwaysCreate) |
Creates or opens a store. More... | |
SIMUTRACE_API BOOL | StSessionCloseStore (SessionId session) |
Closes a session's store. More... | |
SIMUTRACE_API BOOL | StSessionSetConfiguration (SessionId session, const char *configuration) |
Sets session configurations. More... | |
SIMUTRACE_API BOOL | StMakeStreamDescriptor (const char *name, size_t entrySize, BOOL temporalOrder, StreamDescriptor *descOut) |
Creates a new stream descriptor. More... | |
SIMUTRACE_API BOOL | StMakeStreamDescriptorFromType (const char *name, const StreamTypeDescriptor *type, StreamDescriptor *descOut) |
Creates a new stream descriptor from existing type information. More... | |
SIMUTRACE_API StreamId | StStreamRegister (SessionId session, StreamDescriptor *desc) |
Registers a new stream. More... | |
SIMUTRACE_API int | StStreamEnumerate (SessionId session, size_t bufferSize, StreamId *streamIdsOut) |
Returns a list of all registered streams. More... | |
SIMUTRACE_API BOOL | StStreamQuery (SessionId session, StreamId stream, StreamQueryInformation *informationOut) |
Returns detailed information on a stream. More... | |
SIMUTRACE_API StreamHandle | StStreamAppend (SessionId session, StreamId stream, StreamHandle handle) |
Opens a stream for appending write access. More... | |
SIMUTRACE_API StreamHandle | StStreamOpen (SessionId session, StreamId stream, QueryIndexType type, uint64_t value, StreamAccessFlags flags, StreamHandle handle) |
Opens a stream for read access. More... | |
SIMUTRACE_API BOOL | StStreamClose (StreamHandle handle) |
Closes a handle to a stream. More... | |
static void * | StGetNextEntryFast (StreamHandle *handlePtr) |
Returns a pointer to the next entry in a stream. More... | |
static void | StSubmitEntryFast (StreamHandle handle) |
Completes an entry. More... | |
SIMUTRACE_API size_t | StWriteVariableData (StreamHandle *handlePtr, byte *sourceBuffer, size_t sourceLength, uint64_t *referenceOut) |
Writes variable-sized data to a stream. More... | |
SIMUTRACE_API size_t | StReadVariableData (StreamHandle *handlePtr, uint64_t reference, byte *destinationBuffer) |
Reads variable-sized data. More... | |
Variables | |
SIMUTRACE_API const uint32_t | StClientVersion |
Version of the Simutrace client. More... | |
SIMUTRACE_API int StGetLastError | ( | ExceptionInformation * | informationOut | ) |
Returns extended exception information on the last error during a Simutrace API call.
informationOut | A pointer to an ExceptionInformation structure that will receive the error information. The parameter is optional and may be NULL . Freeing the message member in the structure is not necessary, however the string will only be valid until the next API call. |
SIMUTRACE_API SessionId StSessionCreate | ( | const char * | server | ) |
Connections of a client to a Simutrace storage server are represented as a session. This method connects to the specified server and creates a new local session as well as a new session on the server side. Calling this function is the first step, when working with Simutrace. To successfully establish a connection, the server process must already be running and accept connections on the address specified by server
.
server | Specifies the connection string used to contact the server. The specifier must be supplied in the form channel:address . Supported specifiers are:
|
INVALID_SESSION_ID
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API BOOL StSessionOpen | ( | SessionId | session | ) |
Each thread that wants to participate in a tracing session (e.g., read or write data via the tracing API), must be connected to a session. This method connects a thread to an existing local session.
session | The id of the session to be opened as originally returned by StSessionCreate(). |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API BOOL StSessionClose | ( | SessionId | session | ) |
This method closes a thread's reference to an open session. If this is the last reference, the session is run down. After closing the session, the executing thread may connect to a different session again.
session | The id of the session to be closed as originally returned by StSessionCreate(). |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API BOOL StSessionCreateStore | ( | SessionId | session, |
const char * | specifier, | ||
BOOL | alwaysCreate | ||
) |
A store is the data back-end for a Simutrace tracing session. All trace data recorded or read in a session is stored in the currently open store. Opening a store is thus typically the next operation after creating a new session. This method either creates a new stores or overwrites or opens an existing one.
session | The id of the session to open a store in as originally returned by StSessionCreate(). |
specifier | Simutrace comes with a modular storage back-end that can employ custom trace formats to save trace data. The specifier must be supplied in the form format:path . Supported specifiers are:
|
alwaysCreate | Indicates if the store should be overwritten, if it already exists. Supply FALSE to open an existing store. This will fail if the store cannot be found. Supply TRUE to always create a new store, potentially overwriting an existing one. |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().alwaysCreate
set to TRUE
will fail if the store is still open in another session.alwaysCreate
parameter as intended to avoid data loss. Simutrace won't present a confirmation before deleting an existing store!SIMUTRACE_API BOOL StSessionCloseStore | ( | SessionId | session | ) |
Each session may have only one store open at a time. Use this function to close a store without creating a new session.
session | The id of the session whose store should be closed as originally returned by StSessionCreate(). |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API BOOL StSessionSetConfiguration | ( | SessionId | session, |
const char * | configuration | ||
) |
This method allows configuring various parameters for the specified session. For a reference of all configurable parameters see the sample server configuration file, which comes with Simutrace.
session | The id of the session to be configured as originally returned by StSessionCreate(). |
configuration | A string describing the configuration to set. For information on the format see the documentation of libconfig. |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API BOOL StMakeStreamDescriptor | ( | const char * | name, |
size_t | entrySize, | ||
BOOL | temporalOrder, | ||
StreamDescriptor * | descOut | ||
) |
This method is a helper function to quickly create a new stream description needed to register a new stream. The description contains information about the stream's name and layout of trace entries, that is records written to or read from a stream.
name | A friendly name of the new stream (e.g., "CPU Memory Accesses"). |
entrySize | The size of a single trace entry in bytes. To specify a variable-sized entry type, use makeVariableEntrySize(). |
temporalOrder | Indicates if the entries in the stream will contain a time stamp. The time stamp must be the first field in each entry and be of type CycleCount , at least TEMPORAL_ORDER_CYCLE_COUNT_BITS (default 48) bits wide. The time stamp must further be monotonic increasing. |
descOut | Pointer to a StreamDescriptor structure that will receive the new stream information. |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API BOOL StMakeStreamDescriptorFromType | ( | const char * | name, |
const StreamTypeDescriptor * | type, | ||
StreamDescriptor * | descOut | ||
) |
This method is a helper function to quickly create a new stream description needed to register a new stream. The description contains information about the stream's name and layout of trace entries, that is records written to or read from a stream. This method uses the supplied type information.
name | A friendly name of the new stream (e.g., "CPU Memory Accesses"). |
type | Pointer to a valid StreamTypeDescriptor structure, defining the desired type of the new stream. |
descOut | Pointer to a StreamDescriptor structure that will receive the new stream information. |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API StreamId StStreamRegister | ( | SessionId | session, |
StreamDescriptor * | desc | ||
) |
Streams are the basic interface to write or read data with Simutrace. Streams always belong to a store. This method registers a new stream in the session's active store. Before doing so, the caller must initially create a new store with StSessionCreateStore().
session | The id of the session, whose store should register the stream. |
desc | Pointer to a stream descriptor defining the properties of the new stream (e.g., the desired type of data entries). To create a descriptor see StMakeStreamDescriptor() or StMakeStreamDescriptorFromType(). |
INVALID_STREAM_ID
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API int StStreamEnumerate | ( | SessionId | session, |
size_t | bufferSize, | ||
StreamId * | streamIdsOut | ||
) |
After registering streams or opening an existing store, all streams are available through their corresponding ids. This method enumerates all registered streams by returning a list of valid stream ids. To get information on a certain stream call StStreamQuery().
session | The id of the session to enumerate all streams from. |
bufferSize | Total size in bytes of the buffer supplied to receive the stream ids. The function fails when the buffer is too small. |
streamIdsOut | Supplies the destination buffer, which receives the list of stream ids. Each element in the buffer will be of type StreamId. The buffer must be at least bufferSize bytes in size. |
-1
on error. For a more detailed error description call StGetLastError().bufferSize
and streamIdsOut
set to 0
and NULL
respectively. The return value indicates the number of stream ids (StreamId) the buffer must be able to accommodate.SIMUTRACE_API BOOL StStreamQuery | ( | SessionId | session, |
StreamId | stream, | ||
StreamQueryInformation * | informationOut | ||
) |
This method returns detailed information on the properties of a stream. The information includes the StreamDescriptor originally supplied to create the stream as well as a set of statistics such as the compressed size of the stream. See StreamQueryInformation for furthers details.
session | The id of the session that holds the stream of interest. |
stream | The id of the stream to query. |
informationOut | A pointer to a StreamQueryInformation structure which will receive the stream information. |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API StreamHandle StStreamAppend | ( | SessionId | session, |
StreamId | stream, | ||
StreamHandle | handle | ||
) |
This method opens a write handle to the specified stream. The handle can be used with StGetNextEntryFast() to append new entries to a stream.
session | The id of the session that holds the stream of interest. Must be INVALID_SESSION_ID , when supplying handle . |
stream | The id of the stream to open a handle for. Must be INVALID_STREAM_ID , when supplying handle . |
handle | Existing write handle or NULL . |
NULL
otherwise. For a more detailed error description call StGetLastError().handle
.session
and stream
parameters and set handle to NULL
. StGetNextEntryFast() will take care of proceeding the handle along the stream.SIMUTRACE_API StreamHandle StStreamOpen | ( | SessionId | session, |
StreamId | stream, | ||
QueryIndexType | type, | ||
uint64_t | value, | ||
StreamAccessFlags | flags, | ||
StreamHandle | handle | ||
) |
This method opens a new read handle to the specified stream. The handle can be used with StGetNextEntryFast() to read entries.
session | The id of the session that holds the stream of interest. Must be INVALID_SESSION_ID , when supplying handle . |
stream | The id of the stream to open a handle for. Must be INVALID_STREAM_ID , when supplying handle . |
type | Type of property value that indicates which position in the stream should be opened. For further information on the possible query types see QueryIndexType. |
value | A value used in the query specified by type . See QueryIndexType for more details. |
flags | Supplies information on how the caller intends to access the stream with the requested handle. For more information see StreamAccessFlags. If handle is supplied and flags is set to StreamAccessFlags::SafNone , the flags are taken from the handle. |
handle | An existing handle to the same stream, which will be closed or reused for the request. The handle may be a write handle or a read handle. Leave this parameter NULL . |
NULL
otherwise (if handle
has been specified, an invalidated version of the handle will be returned). For a more detailed error description call StGetLastError(). If successful, the handle will NOT point to the exact entry requested by the <type
, value>-pair
. The method only guarantees that the requested entry is in the data delivered by the server for this request. To find the desired entry, use StGetNextEntryFast() on the returned handle and scan over the entries manually. This may change in the future.session
and stream
parameters and set handle to NULL
. StGetNextEntryFast() will take care of proceeding the handle along the stream.SIMUTRACE_API BOOL StStreamClose | ( | StreamHandle | handle | ) |
This method closes the supplied stream handle.
handle | The handle to be closed. |
TRUE
if successful, FALSE
otherwise. For a more detailed error description call StGetLastError().
|
inlinestatic |
This method moves the read/write pointer of the supplied handle to the next entry in the stream. The pointer returned by this method can be used to write or read (depending on the handle) a single trace entry.
handlePtr | A pointer to the stream handle. The method may allocate a new handle and update the supplied pointer. |
NULL
otherwise. For a more detailed error description call StGetLastError(). On error, the supplied handle will be invalidated. It may be used to retry the operation. If successful, the caller must cast the pointer to the data type (e.g., DataWrite64) for the type supplied at stream registration.
|
inlinestatic |
This method builds the closing operation when writing a new entry to a stream, signaling Simutrace that the entry has been fully written and is valid.
handle | The write handle of the stream, which has been used in matching call to StGetNextEntryFast(). |
SIMUTRACE_API size_t StWriteVariableData | ( | StreamHandle * | handlePtr, |
byte * | sourceBuffer, | ||
size_t | sourceLength, | ||
uint64_t * | referenceOut | ||
) |
In Simutrace, entries are required to be of fixed size. This method enables tracing of variable-sized data such as strings. To trace entries that contain variable-sized fields, the data fields should be replaced with fixed-size reference fields. The data itself can then be traced with this method.
handlePtr | Pointer to a write handle for the stream that will receive the variable-sized data. |
sourceBuffer | Pointer to a buffer containing the variable-sized data. |
sourceLength | Length of the variable-sized data. |
referenceOut | Pointer to a reference field receiving the reference to the variable-sized data in the given stream. |
sourceLength
if successful. For a more detailed error description call StGetLastError().SIMUTRACE_API size_t StReadVariableData | ( | StreamHandle * | handlePtr, |
uint64_t | reference, | ||
byte * | destinationBuffer | ||
) |
This method reads variable-sized data from the supplied stream given a reference, originally returned by StWriteVariableData().
handlePtr | Pointer to a read handle for the stream that stores the variable-sized data. |
reference | Reference to the variable-sized data in the given stream. |
destinationBuffer | Pointer to a buffer receiving the variable-sized data. The buffer needs provide enough space. Supply NULL to determine the length of the data. |
-1
otherwise. For a more detailed error description call StGetLastError().SIMUTRACE_API const uint32_t StClientVersion |
Version number of the Simutrace client. This should ideally match the version of the server. The version number has the form: <Revision (16 bits), Major Version (8 bits), Minor Version (8 bits)> with the revision being stored in the high word.