1. Structure

This section contains a detailed breakdown of the directory structure found in the project repository which is important for the purpose of development.

• tsan - TSan top directory (drop into the LLVM Compiler RT directory before building)
  • rtl - TSan runtime library
    • ufo - UFO online program tracing library
• ufo-predict - java project which implements the offline trace analysis

The directory tsan is mostly the same as the directory that would be found in the LLVM Compiler RT module [1]. We highlight the differences here:

• The subdirectory tsan/rtl/ufo/ has been added, which contains the library for trace generation.
• Functions from the UFO tracing library have been added into the TSan rtl in order to instrument code and produce execution traces at runtime. For details, see the wiki page, "UFO Tracing In Depth."

UFO RTL Structure

This section contains information over each file in the UFO runtime tracing library (tsan/rtl/ufo/). For an overview of the implementation, see Section 5. UFO IMPLEMENTATION in our ICSE '18 paper [2].

• defs.h: contains the definitions of environment variables which one can use to configure UFO. For details on usage, see the project README at https://github.com/parasol-aser/UFO/#ufo-usage

• ufo.h/cc: defines UFOContext, which is the main class definition for the UFO tracing library. Defined here are function pointers to the tracing functions, configuration based on environment variables, and data structures for tracing.

• ufo_interface.h/cc: this is the external interface to the UFO tracing library. Defined here are the functions that are called in the TSan RTL. (for a complete list of their insertion points in the TSan RTL, see "UFO Tracing In Depth")

• ufo_stat.h/cc: contains the data structure and functions responsible for printing a summary of the current process' runtime statistics when a trace is finished (upon call to aser::ufo::finish_ufo()).

• tlbuffer.h/cc: defines the thread-local buffer, which is allocated to each live thread. To prevent application threads from blocking when flushing events to disk, we instead use a thread-local buffer to store events. When a thread-local buffer is full, it is flushed to the global buffer queue [2].

• io_queue.h/cc: defines the global buffer queue. When a thread-local buffer is flushed to the global buffer queue, a worker thread is invoked to flush the data in the queue to disk asynchronously [2].

• dummy_rtl.h: contains empty tracing functions. The function pointers in UFOContext are set to these when tracing is turned off.

• rtl_impl.h: contains the implementations of the tracing functions (except memory accesses which are defined in impl_mem_acc.h). The function pointers in UFOContext are set to these when tracing is turned on.

• impl_mem_acc.h: as mentioned above, contains the implementations of the memory access functions. There are a total of 6 functions, 3 for memory range accesses, and 3 for memory accesses. For both memory and memory range accesses, there are 3 types based on the UFO configuration: normal, no stack, and no value. No stack (env var NO_STACK) will not trace reads/writes to the stack or thread-local storage. No value (env var NO_VALUE) will not record read/write values. The function pointers relating to memory accesses in UFOContext are set to these when tracing is turned on.

• report.h/cc: currently not in use.

References

[1] https://compiler-rt.llvm.org/

[2] https://parasol.tamu.edu/people/jeff/academic/ufo.pdf