The main interface to this module is through the parse_tracex_buffer()
function in the file_parser
module.
from tracex_parser.file_parser import parse_tracex_buffer
TODO: Add more docs here
This module also allows you to specify the format of user events such that they can automatically be parsed from their raw form.
Arguments:
class_name
: A unique name to represent the event (internally it is the name of the returned class)fn_name
: A nice name that will be shown in the trace outputarg_map
: A list of exactly 4 argument names to apply to the event.- Names prefixed with an underscore (
_
) will not be shown by default - See :ref:`events_CommonArg` for special handling of arguments
- Names prefixed with an underscore (
class_name_is_fn_name
: IfTrue
you do not have to specify afn_name
and theclass_name
will be used instead
Some attributes under this class have special meaning to the parsing logic:
events.CommonArg.timeout
: Will replace the raw number with:0
→'NoWait'
0xFFFFFFFF
→'WaitForever'
events.CommonArg.obj_id
: Will look in the object registry for an object with the same memory address and replace the raw number with that object's nameevents.CommonArg.thread_ptr
: Same asevents.CommonArg.obj_id
, but for thread namesevents.CommonArg.next_thread
: Same asevents.CommonArg.thread_ptr
Once the custom event is created with events.tracex_event_factory()
you need to assign it to an event id.
This is done by creating a dictionary with the key corresponding to the event id and the value being the custom event.
Then that dictionary is passed to the custom_events_map
parameter of parse_tracex_buffer()
.
In this example we are going to parse event #5000, which I have compiled into my TraceX application using tx_trace_user_event_insert()
.
I've passed following arguments to event #5000:
- Line number
- Address of a semaphore object
- File descriptor number
- Always 0
In the C code it looks like the following:
tx_trace_user_event_insert(5000, __LINE__, (TX_SEMAPHORE *) semPtr, fd, 0);
Now parsing it with the tracex_parser module:
.. literalinclude:: /../../examples/custom_event.py :caption: examples/custom_event.py :lines: 2-
The parsed event is now shown as:
7821:myThread custEvent(line_num=1234,obj_id=fdSem,fd=5)
Without the custom event it would be shown as:
7821:myThread <TX ID#5000>(arg1=0x4d2,arg2=0x82070000,arg3=0x5,arg4=0x0)