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.
was available since 2.0.0 but wasn't documented and considered official.
this exception is raised when the knowledge computation enters the inconsistent state.
Toplevel variables
the type of variables holding property 'p
val var : string -> 'p varvar 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.
put var exp evaluates exp and sets var to its result.
get var reads the value of the variable.
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.
try_eval property object is like eval property object but returns Error conflict instead of raising an exception.
exec stmt executes the side-effectful knowledge computation.
Executes the statement and updates the internal knowledge base.
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.
current () is the current state of the knowledge base.
reset () resets the knowledge state to the empty state.
It is the same as set @@ KB.empty