package bap-std

  1. Overview
  2. Docs
The Binary Analysis Platform Standard Library

Install 

dune-project
 Dependency

github.com Edit opam file Versions (5)

Authors

  1. B
    BAP Team

Maintainers

  1. I
    Ivan Gotovchits <ivg@ieee.org>

Sources

v2.4.0.tar.gz
sha256=63ada71fa4f602bd679174dc6bf780d54aeded40ad4ec20d256df15886e3d2d5
md5=b8b1aff8c6846f2213eafc54de07b304

doc/bap/Bap/Std/Toplevel/index.html

Module Std.Toplevel

The interface to the BAP toplevel state.

To create a project from the binary code BAP relies on the knowledge base, which is a state monad underneath the hood, or, put it simply, each knowledge computation is a function of type state -> state * 'a. To enable backward compatibility, we compute each such stateful computation in the toplevel, which also stores the hidden state.

Using this interface it is possible to evaluate knowledge base computations and extract their results to concrete values. Since the knowledge base computations are not expression but objective language, i.e., they evaluate to knowledge base objects, not to values, we commonly need to create objects that will carry the result of the computation as their properties. To ease the process this module provides the notion of toplevel variables, that denote such properties. Here is an example, how to run a knowledge base computation and extract its result, assuming that analysis is a function of type unit -> my knowledge

  let result : my var = Toplevel.var "my-property"
  let run analysis : my =
    Toplevel.put result (analysis ());
    Toplevel.get result

There are also eval and exec functions that could be used to extract values from the existing properties, e.g.,

  let get_unit tid =
    eval Theory.Label.unit (KB.return tid)

Finally, the interface provides functions to control the inner state of the toplevel, which is the knowledge base that is used by BAP throught the lifetime of the BAP process and could be also persistet between runs. E.g., the disassemble plugin is persisting the knowledge base in the BAP cache facility and loads it when it identifies that the input digest is the same.

Warning: this interface should be used with care, in particular, it shall not be used in the context of another knowledge computation that is also run in the toplevel.

  • since 2.2.0 made public and documented, the state interface

was available since 2.0.0 but wasn't documented and considered official.

exception Conflict of Bap_knowledge.Knowledge.conflict

this exception is raised when the knowledge computation enters the inconsistent state.

  • since 2.2.0

Toplevel variables

type 'p var

the type of variables holding property 'p

val var : string -> 'p var

var name creates a fresh variable.

Creates and declares a fresh new property of the bap:toplevel class. The name is mangled to prevent clashing with existing properties, and each evaluation of this function creates a new property that is distinct from any previously created properties.

Warning: this function changes the static representation of the knowledge base (the scheme) and should be only used to create static (global) variables, that have the lifetime of the BAP process. It is not recommended to call this function inside any other function.

val put : 'p var -> 'p Bap_knowledge.knowledge -> unit

put var exp evaluates exp and sets var to its result.

  • raises Conflict

    if exp ends up in the conflicting state.

val get : 'p var -> 'p

get var reads the value of the variable.

  • raises Not_found

    if var was not set with put.

The slot interface

eval property obj_exp gets property of obj_exp.

Evaluates the computation obj_exp that shall return an object of class 'a and returns the value 'p of the specified property.

  • raises Conflict

    when the knowledge base enters the conflicting state.

try_eval property object is like eval property object but returns Error conflict instead of raising an exception.

val exec : unit Bap_knowledge.knowledge -> unit

exec stmt executes the side-effectful knowledge computation.

Executes the statement and updates the internal knowledge base.

  • raises Conflict

    when the knowledge base enters the conflicting state.

try_exec stmt is like exec stmt but returns Error conflict instead of raising an exception.

The state interface

set s sets the knowledge base state to s.

Any existing state is discarded.

val current : unit -> Bap_knowledge.Knowledge.state

current () is the current state of the knowledge base.

val reset : unit -> unit

reset () resets the knowledge state to the empty state.

It is the same as set @@ KB.empty