|
DynamoRIO API
|
|
|
DynamoRIO API
|
|
#include <analysis_tool.h>
Public Member Functions | |
| analysis_tool_t () | |
| virtual std::string | initialize () |
| virtual bool | operator! () |
| virtual std::string | get_error_string () |
| virtual bool | process_memref (const memref_t &memref)=0 |
| virtual bool | print_results ()=0 |
| virtual bool | parallel_shard_supported () |
| virtual void * | parallel_worker_init (int worker_index) |
| virtual std::string | parallel_worker_exit (void *worker_data) |
| virtual void * | parallel_shard_init (int shard_index, void *worker_data) |
| virtual bool | parallel_shard_exit (void *shard_data) |
| virtual bool | parallel_shard_memref (void *shard_data, const memref_t &memref) |
| virtual std::string | parallel_shard_error (void *shard_data) |
| analysis_tool_t () | |
| virtual std::string | initialize () |
| virtual bool | operator! () |
| virtual std::string | get_error_string () |
| virtual bool | process_memref (const memref_t &memref)=0 |
| virtual bool | print_results ()=0 |
| virtual bool | parallel_shard_supported () |
| virtual void * | parallel_worker_init (int worker_index) |
| virtual std::string | parallel_worker_exit (void *worker_data) |
| virtual void * | parallel_shard_init (int shard_index, void *worker_data) |
| virtual bool | parallel_shard_exit (void *shard_data) |
| virtual bool | parallel_shard_memref (void *shard_data, const memref_t &memref) |
| virtual std::string | parallel_shard_error (void *shard_data) |
The base class for a tool that analyzes a trace. A new tool should subclass this class.
Concurrent processing of traces is supported by logically splitting a trace into "shards" which are each processed sequentially. The default shard is a traced application thread, but the tool interface can support other divisions. For tools that support concurrent processing of shards and do not need to see a single thread-interleaved merged trace, the interface functions with the parallel_ prefix should be implemented, and parallel_shard_supported() should return true. parallel_shard_init() will be invoked for each shard prior to invoking parallel_shard_memref() for any entry in that shard; the data structure returned from parallel_shard_init() will be passed to parallel_shard_memref() for each trace entry for that shard. The concurrency model used guarantees that all entries from any one shard are processed by the same single worker thread, so no synchronization is needed inside the parallel_ functions. A single worker thread invokes print_results() as well.
For serial operation, process_memref(), operates on a trace entry in a single, sorted, interleaved stream of trace entries. In the default mode of operation, the analyzer_t class iterates over the trace and calls the process_memref() function of each tool. An alternative mode is supported which exposes the iterator and allows a separate control infrastructure to be built. This alternative mode does not support parallel operation at this time.
Both parallel and serial operation can be supported by a tool, typically by having process_memref() create data on a newly seen traced thread and invoking parallel_shard_memref() to do its work.
For both parallel and serial operation, the function print_results() should be overridden. It is called just once after processing all trace data and it should present the results of the analysis. For parallel operation, any desired aggregation across the whole trace should occur here as well, while shard-specific results can be presented in parallel_shard_exit().
|
inline |
Errors encountered during the constructor will set the success flag, which should be queried via operator!. On an error, get_error_string() provides a descriptive error message.
|
inline |
Errors encountered during the constructor will set the success flag, which should be queried via operator!. On an error, get_error_string() provides a descriptive error message.
|
inlinevirtual |
Returns a description of the last error.
|
inlinevirtual |
Returns a description of the last error.
|
inlinevirtual |
Destructor. Tools are encouraged to perform any initialization that might fail here rather than in the constructor. On an error, this returns an error string. On success, it returns "".
|
inlinevirtual |
Destructor. Tools are encouraged to perform any initialization that might fail here rather than in the constructor. On an error, this returns an error string. On success, it returns "".
|
inlinevirtual |
Returns whether the tool was created successfully.
|
inlinevirtual |
Returns whether the tool was created successfully.
|
inlinevirtual |
Returns a description of the last error for this shard.
|
inlinevirtual |
Returns a description of the last error for this shard.
|
inlinevirtual |
Invoked once when all trace entries for a shard have been processed. shard_data is the value returned by parallel_shard_init() for this shard. This allows a tool to clean up its thread data, or to report thread analysis results. Most tools, however, prefer to aggregate data or at least sort data, and perform nothing here, doing all cleanup in print_results() by storing the thread data into a table. Return whether exiting was successful. On failure, parallel_shard_error() returns a descriptive message.
|
inlinevirtual |
Invoked once when all trace entries for a shard have been processed. shard_data is the value returned by parallel_shard_init() for this shard. This allows a tool to clean up its thread data, or to report thread analysis results. Most tools, however, prefer to aggregate data or at least sort data, and perform nothing here, doing all cleanup in print_results() by storing the thread data into a table. Return whether exiting was successful. On failure, parallel_shard_error() returns a descriptive message.
|
inlinevirtual |
Invoked once for each trace shard prior to calling parallel_shard_memref() for that shard, this allows a tool to create data local to a shard. The shard_index is a unique identifier allowing shard data to be stored into a global table if desired (typically for aggregation use in print_results()). The worker_data is the return value of parallel_worker_init() for the worker thread who will exclusively operate on this shard. The return value here will be passed to each invocation of parallel_shard_memref() for that same shard.
|
inlinevirtual |
Invoked once for each trace shard prior to calling parallel_shard_memref() for that shard, this allows a tool to create data local to a shard. The shard_index is a unique identifier allowing shard data to be stored into a global table if desired (typically for aggregation use in print_results()). The worker_data is the return value of parallel_worker_init() for the worker thread who will exclusively operate on this shard. The return value here will be passed to each invocation of parallel_shard_memref() for that same shard.
|
inlinevirtual |
The heart of an analysis tool, this routine operates on a single trace entry and takes whatever actions the tool needs to perform its analysis. The shard_data parameter is the value returned by parallel_shard_init() for this shard. Since each shard is operated upon in its entirety by the same worker thread, no synchronization is needed. The return value indicates whether this function was successful. On failure, parallel_shard_error() returns a descriptive message.
|
inlinevirtual |
The heart of an analysis tool, this routine operates on a single trace entry and takes whatever actions the tool needs to perform its analysis. The shard_data parameter is the value returned by parallel_shard_init() for this shard. Since each shard is operated upon in its entirety by the same worker thread, no synchronization is needed. The return value indicates whether this function was successful. On failure, parallel_shard_error() returns a descriptive message.
|
inlinevirtual |
Returns whether this tool supports analyzing trace shards concurrently, or whether it needs to see a single thread-interleaved stream of traced events.
|
inlinevirtual |
Returns whether this tool supports analyzing trace shards concurrently, or whether it needs to see a single thread-interleaved stream of traced events.
|
inlinevirtual |
Invoked once when a worker thread is finished processing all shard data. The worker_data is the return value of parallel_worker_init(). A non-empty string indicates an error while an empty string indicates success.
|
inlinevirtual |
Invoked once when a worker thread is finished processing all shard data. The worker_data is the return value of parallel_worker_init(). A non-empty string indicates an error while an empty string indicates success.
|
inlinevirtual |
Invoked once for each worker thread prior to calling any shard routine from that thread. This allows a tool to create data local to a worker, such as a cache of data global to the trace that crosses shards. This data does not need any synchronization as it will only be accessed by this worker thread. The worker_index is a unique identifier for this worker. The return value here will be passed to the invocation of parallel_shard_init() for each shard upon which this worker operates.
|
inlinevirtual |
Invoked once for each worker thread prior to calling any shard routine from that thread. This allows a tool to create data local to a worker, such as a cache of data global to the trace that crosses shards. This data does not need any synchronization as it will only be accessed by this worker thread. The worker_index is a unique identifier for this worker. The return value here will be passed to the invocation of parallel_shard_init() for each shard upon which this worker operates.
|
pure virtual |
This routine reports the results of the trace analysis. The return value indicates whether it was successful. On failure, get_error_string() returns a descriptive message.
|
pure virtual |
This routine reports the results of the trace analysis. The return value indicates whether it was successful. On failure, get_error_string() returns a descriptive message.
|
pure virtual |
The heart of an analysis tool, this routine operates on a single trace entry and takes whatever actions the tool needs to perform its analysis. The return value indicates whether it was successful. On failure, get_error_string() returns a descriptive message.
|
pure virtual |
The heart of an analysis tool, this routine operates on a single trace entry and takes whatever actions the tool needs to perform its analysis. The return value indicates whether it was successful. On failure, get_error_string() returns a descriptive message.
DynamoRIO API version 7.1.0 --- Fri Feb 22 2019 14:52:31