bap-std 2.2.0 · OCaml Package

Memory region

type t = mem

val sexp_of_t : t -> Ppx_sexp_conv_lib.Sexp.t

val create : 
  ?pos:int ->
  ?len:int ->
  endian ->
  addr ->
  Core_kernel.Bigstring.t ->
  t Core_kernel.Or_error.t

create ?pos ?len endian start data creates a memory region.

Creates a memory view of the provided data using the specified byte order endian and mapping the first (pos) byte to the start address. The pos and len parameters can be used to narrow down the view, and default to 0 and the length of the provided string, correspondingly.

The data may not be copied and the returned memory view may reference the same bigstring object.

val rebase : t -> addr -> t

rebase mem addr returns the same memory but with the new starting address addr.

since 2.2.0

val slot : 
  (Bap_core_theory.Theory.program, mem option) Bap_knowledge.Knowledge.slot

memory representation of a program

val of_file : endian -> addr -> string -> t Core_kernel.Or_error.t

of_file endian start name creates a memory region from file. Takes data stored in a file with the given name and maps it to the memory region with the specified starting address start and using the endian for storing and reading words.

val view : 
  ?word_size:size ->
  ?from:addr ->
  ?words:int ->
  t ->
  t Core_kernel.Or_error.t

view word_size ~from ~words mem returns a new memory that represents the specified region of memory mem. copy function performs deep copy.

parameter addr
defaults min_addr mem

parameter words
defaults to the end of the memory region.

val view_exn : ?word_size:size -> ?from:addr -> ?words:int -> t -> t

view_exn mem is the same as ok_exn @@view_exn mem but is slightly more efficient.

raises Invalid_arg
in case if the arguments are not fitting into the memory.

since 2.2.0

val range : t -> addr -> addr -> t Core_kernel.Or_error.t

range mem a0 a1 returns a view on mem starting from address a0 and ending at a1, bounds inclusive

val merge : t -> t -> t Core_kernel.Or_error.t

merge m1 m2 takes two memory regions, that either intersects or share edges (i.e., difference between min_addr of one of the blocks and max_addr of another is less then or equal to one, and returns memory blocks that spans memory starting from the address

min (min_addr m1) (min_addr m2)

and ending with address

max (max_addr m1) (max_addr m2)

Will return an error, if either the above state precondition doesn't hold, or if this two memory blocks doesn't share the same underlying memory (i.e., bases), or if they have different endianness.

val first_byte : t -> t

first_byte m returns first byte of m as a memory

val last_byte : t -> t

last_byte m returns last byte of m as a memory

val endian : t -> endian

returns the order of bytes in a word

val get : 
  ?disp:int ->
  ?index:int ->
  ?scale:size ->
  ?addr:addr ->
  t ->
  word Core_kernel.Or_error.t

get ?disp ?index ?scale ?addr mem reads a scale sized word from mem.

Parameters mimic the reference syntax in the gas assembler, e.g., dis(base,index,scale) denotes address at base + index * scale + dis.

The size of the returned word is equal to scale, bytes are read in the endian mem order.

parameter disp
is the base offset and defaults to 0

parameter index
defaults to 0

parameter scale
defaults to `r8

val (^) : t -> addr -> word Core_kernel.Or_error.t

m^n dereferences a byte at address n

val (^!) : t -> addr -> word

m^.n dereferences a byte at address n

val max_addr : t -> addr

max_addr m is an address of the last byte of m

val min_addr : t -> addr

min_addr m is an address of the first byte of m

val length : t -> int

length m returns a number of bytes in m

val contains : t -> addr -> bool

contains mem addr returns true if mem contains address addr

val compare_with : 
  t ->
  addr ->
  [ `addr_is_inside | `addr_is_below | `addr_is_above ]

compare_with mem addr compares memory with addr

module Input : sig ... end

A set of low level input operations. Note: it is more effective to use above head iterators, instead of this low level interface, since iterators do not need to check every memory access.

Printing and outputting

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

val to_string : t -> string

val str : unit -> t -> string

val pps : unit -> t -> string

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

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

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

val hexdump : t -> string

hexdump t out outputs hexdump (as per hexdump -C) of the memory to formatter out

a set of iterators, with identity monad.

include Memory_iterators with type t := t and type 'a m = 'a

type 'a m = 'a

val fold : ?word_size:size -> t -> init:'b -> f:(word -> 'b -> 'b m) -> 'b m

fold ~word_size ~init ~f t folds over elements of t, so a result is f (... (f (f a elt_1) elt_2) ...) elt_n

val iter : ?word_size:size -> t -> f:(word -> unit m) -> unit m

iter ~word_size ~f t applies f to elements of t

val foldi : 
  ?word_size:size ->
  t ->
  init:'b ->
  f:(addr -> word -> 'b -> 'b m) ->
  'b m

foldi ~word_size ~init ~f t is like fold, but also passes an address to the f

val iteri : ?word_size:size -> t -> f:(addr -> word -> unit m) -> unit m

iteri ~word_size ~f t is like iter, but also passes an address to the f

val exists : ?word_size:size -> t -> f:(addr -> word -> bool m) -> bool m

exists ~word_size ~f t checks if at least one element of t satisfies the predicate f

val for_all : ?word_size:size -> t -> f:(addr -> word -> bool m) -> bool m

for_all ~word_size ~f t checks if all elements of t satisfies the predicate f

val count : ?word_size:size -> t -> f:(addr -> word -> bool m) -> int m

count ~word_size ~f t is the number of elements in t that satisfies the predicate f.

val find_if : 
  ?word_size:size ->
  t ->
  f:(addr -> word -> bool m) ->
  word option m

find_if ~word_size ~f t returns the first element of t that satisfies the predicate p or None if no elements satisfied

val find_map : 
  ?word_size:size ->
  t ->
  f:(addr -> word -> 'a option m) ->
  'a option m

find_map ~word_size ~f t returns the first evaluation of f that returns Some or None if f always returns None

module With_error : 
  Memory_iterators with type t := t and type 'a m = 'a Core_kernel.Or_error.t

iterators lifter to the Or_error monad

module Make_iterators
  (M : sig ... end) : 
  Memory_iterators with type t := t and type 'a m = 'a M.t

lifts iterators to monad M

Interfacing with C

The following interfaces is supposed to be used only for the purposes of exposing memory to c programs.

val to_buffer : t -> Core_kernel.Bigsubstring.t

to_buffers mem creates a buffer representing the memory mem. It is not specified whether the returned buffer has some sharing with underlying implementation. In other words the returned buffer shouldn't be modified.

Since it is not guaranteed that memory is contiguous, a sequence of buffers is returned, with each buffer representing a contiguous part of memory.

module Trie : sig ... end

Tries over memory

package bap-std

Interfacing with C