openairinterface5g/common/utils/T/DOC/T/howto_new_trace.md

T tracer - a simple tutorial

There is a diff file with all modifications: howto_new_trace.patch. We use tag 2023.w28 To use the patch, clone the repository, then in the top directory of openairinterface:

git checkout 2023.w28
patch -p1 < common/utils/T/DOC/T/howto_new_trace.patch

Then compile nr-softmodem as usual.

1 - create a new trace

As an example, let's add a new trace to dump LDPC decoding success.

In the file common/utils/T/T_messages.txt we add those two lines:

ID = LDPC_OK
    FORMAT = int,segment : int,nb_segments : int,offset : buffer,data

• You create an ID for the new trace.
• You give the format as a list of variables with there types.

Then, in the file openair1/SCHED_NR/phy_procedures_nr_gNB.c, in function nr_postDecode(), we add, at the place where we want to trace:

    T(T_LDPC_OK,
      T_INT(rdata->segment_r),
      T_INT(rdata->nbSegments),
      T_INT(rdata->offset),
      T_BUFFER(ulsch_harq->c[r], rdata->Kr_bytes - (ulsch_harq->F>>3) -((ulsch_harq->C>1)?3:0)));

And that's all, the code is instrumented, a trace is created, we now need a tracer to process the trace.

2. create a tracer

See trace_ldpc.c in the attached diff. Read it, there is documentation. To compile, just do make trace_ldpc in common/utils/T/tracer To use: cd common/utils/T/tracer; ./trace_ldpc -d ../T_messages.txt

Your tracer can do whatever it wants with the data.

The Makefile has been modified to compile it. See the diff.

Use it as a basis for your own tracer. You can also look at the other tracers, especially textlog.c and macpdu2wireshark.c which are the most useful for me to trace/debug the nr-softmodem.

3. available types in a trace

You trace the code with:

    T(T_trace_name, T_xxx(variable1), T_xxx(variables2), ...);

T_xxx can be:

• T_INT(variable)
• T_FLOAT(variable) (not tested much, may fail)
• T_BUFFER(variable, length)
• T_STRING(variable)
• T_PRINTF(format, arg1, ... argn)

What is traced is obvious from the name. T_INT traces an int for example.

corresponding type to put in T_messages.txt

• T_INT: int
• T_FLOAT: float
• T_BUFFER: buffer
• T_STRING: string
• T_PRINTF: string

And that's all. You can add as many traces as you want, just add them in T_messages.txt, put the T() macro in the code where you want to trace, and modify your tracer to deal with it.

An alternative to writing your own tracer could be to use textlog with -full command line and process the text with some external tools.

It is also possible to record the events in a file using the tracer record and then use replay to process the recorded file later.