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 config 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.
• -track SYMBOLS: asks act to try to locate the given symbols (a single comma-delimited string) in the assembly. If any tracked symbols were located, act will print out the mapping.

Example command

$ act explain -track "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