Module `Std.Blk`

Basic block.

Logically block consists of a set of phi nodes, a sequence of definitions and a sequence of out-coming edges, aka jumps. A colloquial term for this three entities is a block element.

The order of Phi-nodes can be specified in any order, as they execute simultaneously . Definitions are stored in the order of execution. Jumps are specified in the order in which they should be taken, i.e., jmp_n is taken only after jmp_n-1 and if and only if the latter was not taken. For example, if block ends with N jumps, where each n-th jump have destination named t_n and condition c_n then it would have the semantics as per the following OCaml program:

      if c_1 then jump t_1 else
      if c_2 then jump t_2 else
      if c_N then jump t_N else
      stop

type t = blk term

type elt = [

| `Def of def term
| `Phi of phi term
| `Jmp of jmp term

]

Union type for all element types

val create : ?tid:tid -> unit -> t

create () creates a new empty block.

val lift : cfg -> block -> blk term list

lift block takes a basic block of assembly instructions and lifts it to a list of blk terms. The first term in the list is the entry.

val from_insn : insn -> blk term list

from_insn insn creates an IR representation of a single machine instruction insn.

val split_while : t -> f:(def term -> bool) -> t * t

split_while blk ~f splits blk into two block: the first block holds all definitions for which f p is true and has the same tid as blk. The second block is freshly created and holds the rest definitions (if any). All successors of the blk become successors of the second block, which becomes the successor of the first block.

Note: if f def is true for all blocks, then the second block will not contain any definitions, i.e., the result would be the same as of split_bot function.

val split_after : t -> def term -> t * t

split_after blk def creates two new blocks, where the first block contains all defintions up to def inclusive, the second contains the rest.

Note: if def is not in a blk then the first block will contain all the defintions, and the second block will be empty.

val split_before : t -> def term -> t * t

split_before blk def is like split_after but def will fall into the second blk

val split_top : t -> t * t

split_top blk returns two blocks, where first block shares the same tid as blk and has all $\Phi$-nodes of blk, but has only one destination, namely the second block. Second block has new tidentity, but inherits all definitions and jumps from the blk.

val split_bot : t -> t * t

split_top blk returns two blocks, where first block shares the same tid as blk, has all $\Phi$-nodes and definitions from blk, but has only one destination, namely the second block. Second block has new tidentity, all jumps from the blk.

val elts : ?rev:bool -> t -> elt seq

elts ~rev blk return all elements of the blk. if rev is false or left unspecified, then elements are returned in the following order: $\Phi$-nodes, defs (in normal order), jmps in the order in which they will be taken. If rev is true, the order will be the following: all jumps in the opposite order, then definitions in the opposite order, and finally $\Phi$-nodes.

val map_exp : ?skip:[ `phi | `def | `jmp ] list -> t -> f:(exp -> exp) -> t

map_exp b ~f applies function f for each expression in block b. By default function f will be applied to all values of type exp, including right hand sides of phi-nodes, definitions, jump conditions and targets. If skip parameter is specified, then terms of corresponding kind will be skipped, i.e., function f will not be applied to them.

val map_elts : 
  ?phi:(phi term -> phi term) ->
  ?def:(def term -> def term) ->
  ?jmp:(jmp term -> jmp term) ->
  blk term ->
  blk term

map_elt ?phi ?def ?jmp blk applies provided functions to the terms of corresponding classes. All functions default to the identity function.

val substitute : ?skip:[ `phi | `def | `jmp ] list -> t -> exp -> exp -> t

substitute ?skip blk x y substitutes each occurrence of expression x with expression y in block blk. The substitution is performed deeply. If skip parameter is specified, then terms of corresponding kind will be left untouched.

val map_lhs : ?skip:[ `phi | `def ] list -> t -> f:(var -> var) -> t

map_lhs blk ~f applies f to every left hand side variable in def and phi subterms of blk. If skip parameter is specified, then terms of corresponding kind will be left untouched. E.g., map_lhs ~skip:[`phi] ~f:(substitute vars) will perform a substitution only on definitions (and will ignore phi-nodes)

val find_var : t -> var -> [ `Phi of phi term | `Def of def term ] option

find_var blk var finds a last definition of a variable var in a block blk.

val defines_var : t -> var -> bool

defines_var blk x true if there exists such phi term or def term with left hand side equal to x

val free_vars : t -> Var.Set.t

free_vars blk returns a set of variables that occurs free in block blk. A variable is free, if it occurs unbound in the expression and there is no preceding definition of this variable in a block blk.

val uses_var : t -> var -> bool

uses_var blk x true if variable x is in free_vars blk. If you need to call this function on several variables it is better to compute free_vars explicitly and use Set.mem function.

val occurs : t -> after:tid -> tid -> bool

occurs blk after:x def if def is occurs after definition def in blk.

module Builder : sig ... end

Builder interface.

val pp_slots : string list -> Format.formatter -> t -> unit

pp_slots names prints slots that are in names.

include Regular.Std.Regular.S with type t := t

include Core_kernel.Bin_prot.Binable.S with type t := t

val bin_size_t : t Bin_prot.Size.sizer

val bin_write_t : t Bin_prot.Write.writer

val bin_read_t : t Bin_prot.Read.reader

val __bin_read_t__ : (int -> t) Bin_prot.Read.reader

val bin_shape_t : Bin_prot.Shape.t

val bin_writer_t : t Bin_prot.Type_class.writer

val bin_reader_t : t Bin_prot.Type_class.reader

val bin_t : t Bin_prot.Type_class.t

include Ppx_sexp_conv_lib.Sexpable.S with type t := t

val t_of_sexp : Sexplib0__.Sexp.t -> t

val sexp_of_t : t -> Sexplib0__.Sexp.t

include Regular.Std.Printable.S with type t := t

val to_string : t -> string

to_string x returns a human-readable representation of x

val str : unit -> t -> string

str () t is formatted output function that matches "%a" conversion format specifier in functions, that prints to string, e.g., sprintf, failwithf, errorf and, surprisingly all Lwt printing function, including Lwt_io.printf and logging (or any other function with type ('a,unit,string,...) formatN`. Example:

Or_error.errorf "type %a is not valid for %a"
    Type.str ty Exp.str exp

val pps : unit -> t -> string

synonym for str

val ppo : Core_kernel.Out_channel.t -> t -> unit

will print to a standard output_channel, useful for using in printf, fprintf, etc.

val pp_seq : Format.formatter -> t Core_kernel.Sequence.t -> unit

prints a sequence of values of type t

this will include pp function from Core that has type t printer, and can be used in Format.printf family of functions

include Core_kernel.Pretty_printer.S with type t := t

val pp : Base__.Formatter.t -> t -> unit

include Core_kernel.Comparable.S_binable with type t := t

include Base.Comparable.S with type t := t

val (>=) : t -> t -> bool

val (<=) : t -> t -> bool

val (=) : t -> t -> bool

val (>) : t -> t -> bool

val (<) : t -> t -> bool

val (<>) : t -> t -> bool

val equal : t -> t -> bool

val compare : t -> t -> int

compare t1 t2 returns 0 if t1 is equal to t2, a negative integer if t1 is less than t2, and a positive integer if t1 is greater than t2.

val min : t -> t -> t

val max : t -> t -> t

val ascending : t -> t -> int

ascending is identical to compare. descending x y = ascending y x. These are intended to be mnemonic when used like List.sort ~compare:ascending and List.sort ~cmp:descending, since they cause the list to be sorted in ascending or descending order, respectively.

val descending : t -> t -> int

val between : t -> low:t -> high:t -> bool

between t ~low ~high means low <= t <= high

val clamp_exn : t -> min:t -> max:t -> t

clamp_exn t ~min ~max returns t', the closest value to t such that between t' ~low:min ~high:max is true.

Raises if not (min <= max).

val clamp : t -> min:t -> max:t -> t Base__.Or_error.t

type comparator_witness

val validate_lbound : min:t Base__.Maybe_bound.t -> t Base__.Validate.check

val validate_ubound : max:t Base__.Maybe_bound.t -> t Base__.Validate.check

val validate_bound : 
  min:t Base__.Maybe_bound.t ->
  max:t Base__.Maybe_bound.t ->
  t Base__.Validate.check

module Replace_polymorphic_compare : 
  Base.Comparable.Polymorphic_compare with type t := t

val comparator : (t, comparator_witness) Base__.Comparator.comparator

module Map : 
  Core_kernel.Map.S_binable
    with type Key.t = t
    with type Key.comparator_witness = comparator_witness

module Set : 
  Core_kernel.Set.S_binable
    with type Elt.t = t
    with type Elt.comparator_witness = comparator_witness

include Core_kernel.Hashable.S_binable with type t := t

val hash_fold_t : 
  Ppx_hash_lib.Std.Hash.state ->
  t ->
  Ppx_hash_lib.Std.Hash.state

val hash : t -> Ppx_hash_lib.Std.Hash.hash_value

val hashable : t Core_kernel.Hashtbl.Hashable.t

module Table : Core_kernel.Hashtbl.S_binable with type key = t

module Hash_set : Core_kernel.Hash_set.S_binable with type elt = t

module Hash_queue : Core_kernel.Hash_queue.S with type key = t

include Regular.Std.Data.S with type t := t

type info = string * [ `Ver of string ] * string option

name,Ver v,desc information attached to a particular reader or writer.

val version : string

Data representation version. After any change in data representation the version should be increased.

Serializers that are derived from a data representation must have the same version as a version of the data structure, from which it is derived. This kind of serializers can only read and write data of the same version.

Other serializers can actually read and write data independent on its representation version. A serializer, that can't store data of current version simply shouldn't be added to a set of serializers.

It is assumed, that if a reader and a writer has the same name and version, then whatever was written by the writer should be readable by the reader. The round-trip equality is not required, thus it is acceptable if some information is lost.

It is also possible, that a reader and a writer that has the same name are compatible. In that case it is recommended to use semantic versioning.

val size_in_bytes : ?ver:string -> ?fmt:string -> t -> int

size_in_bytes ?ver ?fmt datum returns the amount of bytes that is needed to represent datum in the given format and version

val of_bytes : ?ver:string -> ?fmt:string -> Regular.Std.bytes -> t

of_bytes ?ver ?fmt bytes deserializes a value from bytes.

val to_bytes : ?ver:string -> ?fmt:string -> t -> Regular.Std.bytes

to_bytes ?ver ?fmt datum serializes a datum to a sequence of bytes.

val blit_to_bytes : 
  ?ver:string ->
  ?fmt:string ->
  Regular.Std.bytes ->
  t ->
  int ->
  unit

blit_to_bytes ?ver ?fmt buffer datum offset copies a serialized representation of datum into a buffer, starting from the offset.

val of_bigstring : ?ver:string -> ?fmt:string -> Core_kernel.bigstring -> t

of_bigstring ?ver ?fmt buf deserializes a datum from bigstring

val to_bigstring : ?ver:string -> ?fmt:string -> t -> Core_kernel.bigstring

of_bigstring ?ver ?fmt datum serializes a datum to a sequence of bytes represented as bigstring

val blit_to_bigstring : 
  ?ver:string ->
  ?fmt:string ->
  Core_kernel.bigstring ->
  t ->
  int ->
  unit

blit_to_bigstring ?ver ?fmt buffer datum offset copies a serialized representation of datum into a buffer, starting from offset.

module Io : sig ... end

Input/Output functions for the given datum.

module Cache : sig ... end

Data cache.

val add_reader : 
  ?desc:string ->
  ver:string ->
  string ->
  t Regular.Std.reader ->
  unit

add_reader ?desc ~ver name reader registers a new reader with a provided name, version ver and optional description desc

val add_writer : 
  ?desc:string ->
  ver:string ->
  string ->
  t Regular.Std.writer ->
  unit

add_writer ?desc ~ver name writer registers a new writer with a provided name, version ver and optional description desc

val available_readers : unit -> info list

available_reader () lists available readers for the data type

val default_reader : unit -> info

default_reader returns information about default reader

val set_default_reader : ?ver:string -> string -> unit

set_default_reader ?ver name sets new default reader. If version is not specified then the latest available version is used. Raises an exception if a reader with a given name doesn't exist.

val with_reader : ?ver:string -> string -> (unit -> 'a) -> 'a

with_reader ?ver name operation temporary sets a default reader to a reader with a specified name and version. The default reader is restored after operation is finished.

val available_writers : unit -> info list

available_writer () lists available writers for the data type

val default_writer : unit -> info

default_writer returns information about the default writer

val set_default_writer : ?ver:string -> string -> unit

set_default_writer ?ver name sets new default writer. If version is not specified then the latest available version is used. Raises an exception if a writer with a given name doesn't exist.

val with_writer : ?ver:string -> string -> (unit -> 'a) -> 'a

with_writer ?ver name operation temporary sets a default writer to a writer with a specified name and version. The default writer is restored after operation is finished.

val default_printer : unit -> info option

default_writer optionally returns an information about default printer

val set_default_printer : ?ver:string -> string -> unit

set_default_printer ?ver name sets new default printer. If version is not specified then the latest available version is used. Raises an exception if a printer with a given name doesn't exist.

val with_printer : ?ver:string -> string -> (unit -> 'a) -> 'a

with_printer ?ver name operation temporary sets a default printer to a printer with a specified name and version. The default printer is restored after operation is finished.

Low level access to serializers

val find_reader : ?ver:string -> string -> t Regular.Std.reader option

find_reader ?ver name lookups a reader with a given name. If version is not specified, then a reader with maximum version is returned.

val find_writer : ?ver:string -> string -> t Regular.Std.writer option

find_writer ?ver name lookups a writer with a given name. If version is not specified, then a writer with maximum version is returned.

Install

Dune Dependency

Authors

Maintainers

Sources

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

Module `Std.Blk`

Low level access to serializers

package bap-std

Install

Dune Dependency

Authors

Maintainers

Sources

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

Module Std.Blk

Low level access to serializers

Module `Std.Blk`