package bap-std

predicate to drive the disassembler

insn basic instruction.

See Insn module for a more detailed description.

@typevar 'a = asm | empty, denotes whether assembly representation is available for the given instruction.

@typevar 'k = kind | empty, denotes whether semantics kinds are available for the given instruction.

insns is a list of pairs, where each pair consists of a memory region occupied by an instruction, and the instruction itself.

witnesses the absence of the information

witnesses a presence of the assembly string

witnesses a presence of the semantic kinds

abbreviate an instruction with full information.

Disassembler.

'a and 'k type variables specify disassembler modes of operation. In a process of disassembly it can store extra information that might be useful. Although, since storing it takes extra time and space, it is disabled by default.

The first type variable specifies whether storing assembly strings is enabled. It can be switched using store_asm, drop_asm functions. When it is enabled, then this type variable will be set to asm, and it will give an access to functions that returns this information. Otherwise, this type variable will be set to empty, thus stopping you from accessing assembler information.

The second type variable stands for kinds, i.e. to store or not to store extra information about instruction kind.

Note: at some points you can have an access to this information even if you don't enable it explicitly.

Disassembler state.

Words of precautions: this state is valid only inside handlers functions of the run function. It shouldn't be stored anywhere. First two type variables are bound correspondingly to two variables of the disassmbler ('a,'k) t type. The last pair of type variables are bounded to input and output types of user functions. They are made different, so that a function can be run in an arbitrary monad. For simple cases, the can be made the same.

with_disasm ?debug_level ?cpu ~backend ~f target creates a disassembler passing all options to create function and applies function f to it. Once f is evaluated the disassembler is closed with close function.

create ?debug_level ?cpu ~backend target creates a disassembler for the specified target. All parameters are backend specific, consult the concrete backend for more information. In general, the greater debug_level is, the more debug information will be outputed by a backend. To silent backend set it 0. This is a default value. Example:

create ~debug_level:3 ~backend:"llvm" "x86_64" ~f:process

close d closes a disassembler d.

enables storing assembler information

enables storing instruction kinds information

run ?stop_on ?invalid ?stopped dis mem ~init ~return ~hit performs recursive disassembly of specified memory mem. The process of disassembly can be driven using stop, step, back and jump functions, described later.

• parameter backlog

  defines a size of history of states, that can be used for backtracking. Defaults to some positive natural number.

• parameter stop_on

  defines a set of predicates that will be checked on each step to decide whether it should stop here and call a user-provided hit function, or it should continue. The descision is made acording to the rule: if exists stop_on then stop, i.e., it there exists such predicate in a set of predicates, that evaluates to true, then stop the disassembly and pass the control to the user function hit. A few notes: only valid instructions can match predicates, and if the set is empty, then it always evaluates to false.

• parameter init

  initial value of user data, that can be passed through handlers (cf., fold)

• parameter return

  a function that lifts user data type 's to type 'r. It is useful when you need to perform disassembly in some monad, like Or_error, or Lwt. Otherwise, just use ident function and assume that 's == 'r.

  In a process of disassembly user provided callbacks are invoked by the engine. To each callback at least two parameters are passed: state and user_data. user_data is arbitrary data of type 's with which the folding over the memory is actually performed. state incapsulates the current state of the disassembler, and provides continuation functions, namely stop, next and back, that drives the process of disassembly. This functions are used to pass control back to the disassembler.

  stopped state user_data is called when there is no more data to disassemble. This handler is optional and defaults to stop.

  invalid state user_data is an optional handler that is called on each invalid instruction (i.e., a portion of data that is not a valid instruction), it defaults to step, i.e., to skipping.

  hit state mem insn data is called when one of the predicates specifed by a user was hit. insn is actually the instruction that satisfies the predicate. mem is a memory region spanned by the instruction. data is a user data. insn can be queried for assembly string and kinds even if the corresponding modes are disabled.

insn_of_mem dis mem performes a disassembly of one instruction from the a given memory region mem. Returns a tuple imem,insn,`left over where imem stands for a piece of memory consumed in a process of disassembly, insn can be Some ins if disassembly was successful, and None otherwise. `left over complements imem to original mem.

current position of the disassembler

current set of predicates

updates the set of predicates, that rules the stop condition.

a queue of instructions disassembled in this step

last s n returns last n instructions disassembled in this step. If there are less then n instructions, then returns a smaller list

the memory region we're currently working on

stop the disassembly and return the provided value.

continue disassembling from the current point. You can change a a set of predicates, before stepping next. If you want to continue from a different address, use jump

jump to the specified memory and continue disassembly in it.

For example, if you want to jump to a specified address, and you're working in a Or_error monad, then you can:

view ~from:addr (mem state) >>= fun mem -> jump mem data

restarts last step.

Basic instruction. This instruction is an opaque pointer into C-backend, thus it is protected with phantom types.

Trie maps over instructions

enumerates names of available disassembler backends.