NAME

     ESIL - Evaluable Strings Intermediate Language

SYNOPSIS

     ESIL provides an abstract, stack-based format for representing CPU instruction semantics
     across various architectures, facilitating instruction emulation for analysis and debugging
     within the radare2 framework.

DESCRIPTION

     Evaluable Strings Intermediate Language (ESIL) adopts a Forth-like syntax, offering a method
     to describe and emulate the behavior of machine instructions in a platform-agnostic manner.
     It is particularly useful in reverse engineering, allowing for cross-architecture binary
     analysis and exploitation through radare2.

SYNTAX

     ESIL expressions use a series of operands and operations, manipulating values on an internal
     stack. These expressions are executed within an ESIL virtual machine (VM), enabling the
     simulation of CPU instructions' effects on registers and memory.

     Uppercase words are special keywords that operate on the esil VM.

     Lowercase words are register names that can be used for reading or writing through
     operations.

     Words starting with $ represent internal variables of the VM that are readonly

     Numbers can be in base 10 or hexadecimal.

     The rest of keywords can be added or removed via esil or arch plugins, but this document
     describes all the common and standard ESIL commands. Note that the list of instructions is
     subject to change (will be reduced over time) for simplicity reasons.

USING ESIL IN RADARE2

     Radare2's visual mode and various configuration options, such as `emu.str` and `asm.esil`,
     facilitate the inspection of ESIL evaluations alongside traditional disassembly. This dual
     view can greatly enhance understanding of binary behavior without requiring physical
     execution.

ESIL COMMANDS

     Radare2 leverages ESIL for detailed emulation of instruction execution, enabling users to
     step through instructions, inspect changes to registers and memory, and evaluate conditional
     logic in a controlled environment.

     In the visual mode of radare2 you can emulate code doing single stepping, but it is also
     possible to debug the expressions using the `aev` command

     ae: Evaluate an ESIL expression. Note that some expressions contain special characters that
     can be evaluated by the radare2 shell, so it's better to prefix the command with a single
     quote ' to skip that parsing.

     "aev": Enter the interactive visual debugger to debug and emulate an esil expression.

     "aes": ESIL Step: execute a single step in ESIL emulation.

     "aeso": ESIL Step Over: perform a step over call instructions in ESIL emulation.

     "aesu": ESIL Step Until: continue ESIL execution until a specified address is reached.

     "ar": Show or modify ESIL registers.

WORDS

     The comma separated words in an ESIL expression can be grouped into different scopes:

     internal flags
                 Prefixed with '$' they represent internal states of the esil vm and are used to
                 perform conditional

                 comparison flags: $z, $c, $b, $p, $s, $o, $ds, $jt, $js

                 current address: $$

     assignment  Pop the value and the destination from the stack

                 "=": strong assignment (update flags)

                 ":=": weak assignment without updating flags

     arithmetic and binary operations
                 Basic math operations like add, sub, mul, mod, div, shift, rotate, and, or

                 + - / * %

                 "~" sign extend

                 "<<" shift left (see ">>" for shift right)

                 "<<<" rotate left (">>>" for rotate right

                 "<<<<" arithmetic shift left (">>>>" for asr)

                 "&" binary AND

                 "|" binary OR

                 "!" negate value ins tack

                 "L*": long multiplication

                 "*": multiplication

                 "^": xor

                 "~/": signed division

                 "%": mod

     comparison

                 Comparison words update the internal flags and can be used to make conditional
                 operations.

                 "<": smaller than

                 "<=": smaller or equal

                 "<=": bigger or equal

                 ">": bigger than

                 "==": compare equality

     control flow
                 Conditional expressions, loops

                 GOTO BREAK "?{" "}" "}{"

     memory access
                 The memory access expressions contain the [] braces to read and =[] to write,
                 address and value are popped from the stack, and size is defined between the
                 brackets.

                 In order to simplify the VM and reduce the amount of keywords those combined
                 operations may change in the future.

                 reading: [1] [2] [4] [8] [16]

                 writing: =[1] =[2] =[4] =[8] =[16]

                 combined: |=[2] +=[4] &=[4] --=[2]

                 special [*] =[*]

     special     Represented as uppercase words, they are used to manipulate the internal esil
                 stack, swaping, perform a cast, set flags and so on

                 STACK POP TODO CLEAR DUP NUM SWAP TRAP BITS SETJT SETJTS SETD

     other (may use uppercase words)

                 "()": syscall "$": interrupt "#!": r2 command

     floating point

                 NAN I2D U2D D2I D2F F2D F== F!= F< F<= F+ F- F* F/ -F CEIL FLOOR ROUND SQRT

BASIC OPERATIONS

     Core operations in ESIL are designed to replicate basic CPU instructions' behavior,
     including arithmetic, logical, and control flow.

     "=" Assignment: Transfers the value from the right operand to the left operand.

     "+" Addition: Adds the two topmost values on the stack, pushing the result.

     "-" Subtraction: Subtracts the top value from the second top value on the stack, pushing the
     result.

     "*" Multiplication: Multiplies the two topmost values on the stack, pushing the result.

     "/" Division: Divides the second top value by the top value on the stack, pushing the
     result.

     "[]" Memory Access: Represents reading or writing to memory, with operation size being
     context-dependent.

     "?{" Conditional Execution: If the top value of the stack is not zero, execute the following
     block of instructions.

     "$" Special Flags and Operations: Accesses internal VM flags for conditions like carry,
     zero, and overflow or performs special operations like system calls.

     "<<", ">>" Bit Shifts: Performs bitwise shift left or right operations.

     "&", "|", "^" Bitwise Operations: Executes AND, OR, XOR on the two topmost stack values.

     "!"  Logical NOT: Inverts the top value on the stack.

INTERNAL FLAGS AND COMPARISONS

     ESIL uses internal flags to represent the outcome of operations, similar to how CPU flags
     work. These flags enable conditional execution and comparisons within the ESIL VM.

     "$z" Zero Flag: Set if the result of an operation is zero. Used to perform equality checks.

     "$c" Carry Flag: Set if an operation results in a carry out of the most significant bit.
     Useful for unsigned arithmetic operations.

     "$s" Sign Flag: Set if the result of an operation is negative, indicating the sign in signed
     arithmetic.

     "$o" Overflow Flag: Set if an arithmetic operation produces a result too large for the
     destination register, indicating overflow in signed arithmetic.

     "$p" Parity Flag: Set if the number of set bits in the operation result is even. Rarely used
     in high-level analysis.

     Flags are often used following comparison or arithmetic operations to guide conditional
     jumps and other control flow decisions, mimicking the behavior of physical CPUs.

EXPRESSION EXAMPLES

     Compares EAX and EBX, setting the zero flag (zf) in ESIL if they are equal.
       cmp eax, ebx -> ebx,eax,==,$z,zf,:="

     Adds 1 to EAX, demonstrating basic arithmetic.
       add eax, 1 -> 1,eax,+=

     Jumps to the label if the zero flag (zf) is set, illustrating conditional execution based on
     comparison results.
       jz .label -> zf,?{,.label,eip,=,}

R2WARS

     Code-wars like game implemented on top of ESIL, this is the implementation used in the r2con
     conference.

     https://github.com/radareorg/r2wars

SEE ALSO

     radare2(1),

WWW

     https://www.radare.org/

AUTHORS

     pancake <pancake@nopcode.org>

                                           Mar 16, 2024