Explain

The explain command takes a C or assembly file and prints an annotated assembly listing with comments explaining how act's language analysis interpreted each line. This is useful for debugging act's language analysis and sanitisation processes.

Synopsis

$ act explain [FLAGS] (-compiler COMPILER_ID | -arch ARCH_NAME) FILE

Details

If the input file is C, act runs the compiler associated with the compiler ID, then processes the resulting assembly as if it were passed to explain directly.

Flags

explain takes the standard flags, as well as the following:

Mandatory

• One of -compiler COMPILER_ID or -arch ARCH_NAME, where COMPILER_ID is any compiler ID in the configuration file, and ARCH_NAME is any of the supported architectures. Note that act can only explain a C file if given a -compiler.

Optional

• -sanitise: if present and true, act does some basic sanitisation on the assembly (for example, removing directives and unused labels).
• -c or -asm: overrides act's default file type behaviour, which is to consider the input as C if its name ends in .c, or assembly otherwise.
• -cvars GLOBALS: asks act to try to find the given C variables (given as a comma-delimited string) in the assembly, and print out their mapping at the end.
• -detailed: asks act to print out a more elaborate representation of the abstract program model it built. This form isn't as close to the assembly as the standard one, but is more useful for in-depth debugging.
• -as-assembly: The opposite of -detailed, enabled by default.

Example command

$ act explain -cvars "x,y,P1" -sanitise -compiler local.clang.x86.normal local/clang/x86/normal/asm/test_5.s

Example output

_P0:  # <-- label (unused label, program boundary)
pushl %EBP # <-- stack (manipulates stack)
movl %ESP, %EBP # <-- move (manipulates stack)
subl $16, %ESP # <-- arith (manipulates stack)
movl $2, -4(%EBP) # <-- move
movl -4(%EBP), %EAX # <-- move
xchgl %EAX, _x # <-- RMW
movl $1, -8(%EBP) # <-- move
movl -8(%EBP), %ECX # <-- move
xchgl %ECX, _y # <-- RMW
movl %EAX, -12(%EBP) # <-- move
movl %ECX, -16(%EBP) # <-- move
addl $16, %ESP # <-- arith (manipulates stack)
popl %EBP # <-- stack (manipulates stack)
retl  # <-- return
_P1:  # <-- label (unused label, program boundary)
pushl %EBP # <-- stack (manipulates stack)
movl %ESP, %EBP # <-- move (manipulates stack)
subl $16, %ESP # <-- arith (manipulates stack)
movl $2, -4(%EBP) # <-- move
movl -4(%EBP), %EAX # <-- move
xchgl %EAX, _y # <-- RMW
movl $1, -8(%EBP) # <-- move
movl -8(%EBP), %ECX # <-- move
xchgl %ECX, _x # <-- RMW
movl %EAX, -12(%EBP) # <-- move
movl %ECX, -16(%EBP) # <-- move
addl $16, %ESP # <-- arith (manipulates stack)
popl %EBP # <-- stack (manipulates stack)
retl  # <-- return

Symbol map:

x -> _x
y -> _y
P1 -> _P1