lldb/source/Plugins/TraceExporter/docs/htr.rst - llvm-project - Git at Google

 Hierarchical Trace Representation (HTR)
 ======================================
 The humongous amount of data processor traces like the ones obtained with Intel PT contain is not digestible to humans in its raw form. Given this, it is useful to summarize these massive traces by extracting useful information. Hierarchical Trace Representation (HTR) is the way lldb represents a summarized trace internally. HTR efficiently stores trace data and allows the trace data to be transformed in a way akin to compiler passes.

 Concepts
 --------
 **Block:** One or more contiguous units of the trace. At minimum, the unit of a trace is the load address of an instruction.

 **Block Metadata:** Metadata associated with each *block*. For processor traces, some metadata examples are the number of instructions in the block or information on what functions are called in the block.

 **Layer:** The representation of trace data between passes. For Intel PT there are two types of layers:

  **Instruction Layer:** Composed of the load addresses of the instructions in the trace. In an effort to save space,
  metadata is only stored for instructions that are of interest, not every instruction in the trace. HTR contains a
  single instruction layer.

  **Block Layer:** Composed of blocks - a block in *layer n* refers to a sequence of blocks in *layer n - 1*. A block in
  *layer 1* refers to a sequence of instructions in *layer 0* (the instruction layer). Metadata is stored for each block in
  a block layer. HTR contains one or more block layers.

 **Pass:** A transformation applied to a *layer* that generates a new *layer* that is a more summarized, consolidated representation of the trace data.
 A pass merges instructions/blocks based on its specific purpose - for example, a pass designed to summarize a processor trace by function calls would merge all the blocks of a function into a single block representing the entire function.

 The image below illusrates the transformation of a trace's representation (HTR)

 .. image:: media/htr-example.png


 Passes
 ------
 A *pass* is applied to a *layer* to extract useful information (summarization) and compress the trace representation into a new *layer*. The idea is to have a series of passes where each pass specializes in extracting certain information about the trace. Some examples of potential passes include: identifying functions, identifying loops, or a more general purpose such as identifying long sequences of instructions that are repeated (i.e. Basic Super Block). Below you will find a description of each pass currently implemented in lldb.

 **Basic Super Block Reduction**

 A “basic super block” is the longest sequence of blocks that always occur in the same order. (The concept is akin to “Basic Block'' in compiler theory, but refers to dynamic occurrences rather than CFG nodes).

 The image below shows the "basic super blocks" of the sequence. Each unique "basic super block" is marked with a different color

 .. image:: media/basic_super_block_pass.png

 *Procedure to find all super blocks:*

 - For each block, compute the number of distinct predecessor and successor blocks.

  - **Predecessor** - the block that occurs directly before (to the left of) the current block
  - **Successor** - the block that occurs directly after (to the right of) the current block

 - A block with more than one distinct successor is always the start of a super block, the super block will continue until the next block with more than one distinct predecessor or successor.
	Hierarchical Trace Representation (HTR)
	======================================
	The humongous amount of data processor traces like the ones obtained with Intel PT contain is not digestible to humans in its raw form. Given this, it is useful to summarize these massive traces by extracting useful information. Hierarchical Trace Representation (HTR) is the way lldb represents a summarized trace internally. HTR efficiently stores trace data and allows the trace data to be transformed in a way akin to compiler passes.

	Concepts
	--------
	Block: One or more contiguous units of the trace. At minimum, the unit of a trace is the load address of an instruction.

	Block Metadata: Metadata associated with each block. For processor traces, some metadata examples are the number of instructions in the block or information on what functions are called in the block.

	Layer: The representation of trace data between passes. For Intel PT there are two types of layers:

	Instruction Layer: Composed of the load addresses of the instructions in the trace. In an effort to save space,
	metadata is only stored for instructions that are of interest, not every instruction in the trace. HTR contains a
	single instruction layer.

	Block Layer: Composed of blocks - a block in layer n refers to a sequence of blocks in layer n - 1. A block in
	layer 1 refers to a sequence of instructions in layer 0 (the instruction layer). Metadata is stored for each block in
	a block layer. HTR contains one or more block layers.

	Pass: A transformation applied to a layer that generates a new layer that is a more summarized, consolidated representation of the trace data.
	A pass merges instructions/blocks based on its specific purpose - for example, a pass designed to summarize a processor trace by function calls would merge all the blocks of a function into a single block representing the entire function.

	The image below illusrates the transformation of a trace's representation (HTR)

	.. image:: media/htr-example.png


	Passes
	------
	A pass is applied to a layer to extract useful information (summarization) and compress the trace representation into a new layer. The idea is to have a series of passes where each pass specializes in extracting certain information about the trace. Some examples of potential passes include: identifying functions, identifying loops, or a more general purpose such as identifying long sequences of instructions that are repeated (i.e. Basic Super Block). Below you will find a description of each pass currently implemented in lldb.

	Basic Super Block Reduction

	A “basic super block” is the longest sequence of blocks that always occur in the same order. (The concept is akin to “Basic Block'' in compiler theory, but refers to dynamic occurrences rather than CFG nodes).

	The image below shows the "basic super blocks" of the sequence. Each unique "basic super block" is marked with a different color

	.. image:: media/basic_super_block_pass.png

	Procedure to find all super blocks:

	- For each block, compute the number of distinct predecessor and successor blocks.

	- Predecessor - the block that occurs directly before (to the left of) the current block
	- Successor - the block that occurs directly after (to the right of) the current block

	- A block with more than one distinct successor is always the start of a super block, the super block will continue until the next block with more than one distinct predecessor or successor.