mirage 2.9.1 · OCaml Package

Mirage combinators.

Mirage devices a set of devices and combinator to to define portable applications across all platforms that MirageOS supports.

module Key : module type of struct include Mirage_key end

Configuration keys.

include Functoria_app.DSL

Combinators

type _ typ = _ Functoria.typ =

| Type : 'a -> 'a typ
| Function : 'b typ * 'c typ -> ('b -> 'c) typ

The type for values representing module types.

val typ : 'a -> 'a typ

type t is a value representing the module type t.

val (@->) : 'a typ -> 'b typ -> ('a -> 'b) typ

Construct a functor type from a type and an existing functor type. This corresponds to prepending a parameter to the list of functor parameters. For example:

kv_ro @-> ip @-> kv_ro

This describes a functor type that accepts two arguments -- a kv_ro and an ip device -- and returns a kv_ro.

type job = Functoria.job

Type for job values.

val job : job typ

job is the signature for user's application main module.

type 'a impl = 'a Functoria.impl

The type for values representing module implementations.

val ($) : ('a -> 'b) impl -> 'a impl -> 'b impl

m $ a applies the functor m to the module a.

type abstract_impl = Functoria.abstract_impl =

| Abstract : _ impl -> abstract_impl

The type for abstract implementations.

val abstract : _ impl -> abstract_impl

abstract t is t but with its type variable abstracted. Useful for dependencies.

Keys

type key = Functoria_key.t

The type for command-line keys. See Functoria_key.t.

type context = Functoria_key.context

The type for keys' parsing context. See Functoria_key.context.

type 'a value = 'a Functoria_key.value

The type for values parsed from the command-line. See Functoria_key.value.

val if_impl : bool value -> 'a impl -> 'a impl -> 'a impl

if_impl v impl1 impl2 is impl1 if v is resolved to true and impl2 otherwise.

val match_impl : 'b value -> default:'a impl -> ('b * 'a impl) list -> 'a impl

match_impl v cases ~default chooses the implementation amongst cases by matching the v's value. default is chosen if no value matches.

module type KEY = Functoria.KEY

The signature for run-time and configure-time command-line keys.

Application Builder

Values of type impl are tied to concrete module implementation with the foreign construct. Module implementations of type job can then be registered into an application builder. The builder is in charge if parsing the command-line arguments and of generating code for the final application. See Functoria_app for details.

val foreign : 
  ?packages:string list ->
  ?libraries:string list ->
  ?keys:key list ->
  ?deps:abstract_impl list ->
  string ->
  'a typ ->
  'a impl

foreign name typ is the module name, having the module type typ.

If packages is set, then the given OPAM packages are installed before compiling the current application.
If libraries is set, the given OCamlfind libraries are included and linked with the module name.
If keys is set, use the given keys to parse at configure and runtime the command-line arguments before calling name.connect.
If deps is set, the given list of abstract implementations is added as data-dependencies: they will be initialized before calling name.connect.

For a more flexible definition of libraries and packages, or for a custom configuration step, see the configurable class type and the foreign class.

module Info = Functoria.Info

Information about the final application.

class type 'ty configurable = object ... end

Signature for configurable module implementations. A configurable is a module implementation which contains a runtime state which can be set either at configuration time (by the application builder) or at runtime, using command-line arguments.

val impl : 'a configurable -> 'a impl

impl c is the implementation of the configurable c.

class base_configurable : object ... end

base_configurable pre-defining many methods from the configurable class. To be used as follow:

class 'a foreign : ?packages:string list -> ?libraries:string list -> ?keys:key list -> ?deps:
  abstract_impl
    list -> string -> 'a typ -> 'a configurable

This class can be inherited to define a configurable with an API similar to foreign.

val hash : 'a impl -> int

hash is the hash function on implementations. FIXME(samoht) expand on how it works.

val equal : 'a impl -> 'a impl -> bool

equal is the equality over implementations.

module ImplTbl = Functoria.ImplTbl

Hashtbl of implementations.

General mirage devices

type tracing

The type for tracing.

val tracing : tracing typ

Implementation of the tracing type.

val mprof_trace : size:int -> unit -> tracing impl

Use mirage-profile to trace the unikernel. On Unix, this creates and mmaps a file called "trace.ctf". On Xen, it shares the trace buffer with dom0.

parameter size:
size of the ring buffer to use.

Time

type time

Abstract type for timers.

val time : time typ

Implementations of the V1.TIME signature.

val default_time : time impl

The default timer implementation.

Clocks

type clock

Abstract type for clocks.

val clock : clock typ

Implementations of the V1.CLOCK signature.

val default_clock : clock impl

The default mirage-clock implementation.

Log reporters

type reporter

The type for log reporters.

val reporter : reporter typ

Implementation of the log reporter type.

val default_reporter : 
  ?clock:clock impl ->
  ?ring_size:int ->
  ?level:Logs.level ->
  unit ->
  reporter impl

default_reporter ?clock ?level () is the log reporter that prints log messages to the console, timestampted with clock. If not provided, the default clock is default_clock. level is the default log threshold. It is Logs.Info if not specified.

val no_reporter : reporter impl

no_reporter disable log reporting.

Random

type random

Abstract type for random sources.

val random : random typ

Implementations of the V1.RANDOM signature.

val default_random : random impl

Passthrough to the OCaml Random generator.

Consoles

type console

Abstract type for consoles.

val console : console typ

Implementations of the V1.CONSOLE signature.

val default_console : console impl

Default console implementation.

val custom_console : string -> console impl

Custom console implementation.

Memory allocation interface

type io_page

Abstract type for page-aligned buffers.

val io_page : io_page typ

Implementations of the V1.IO_PAGE signature.

val default_io_page : io_page impl

The default Io_page implementation.

Block devices

type block

Abstract type for raw block device configurations.

val block : block typ

Implementations of the V1.BLOCK signature.

val block_of_file : string -> block impl

Use the given filen as a raw block device.

Static key/value stores

type kv_ro

Abstract type for read-only key/value store.

val kv_ro : kv_ro typ

Implementations of the V1.KV_RO signature.

val crunch : string -> kv_ro impl

Crunch a directory.

val archive : block impl -> kv_ro impl

val archive_of_files : ?dir:string -> unit -> kv_ro impl

val direct_kv_ro : string -> kv_ro impl

Direct access to the underlying filesystem as a key/value store. For Xen backends, this is equivalent to crunch.

Filesystem

type fs

Abstract type for filesystems.

val fs : fs typ

Implementations of the V1.FS signature.

val fat : ?io_page:io_page impl -> block impl -> fs impl

Consider a raw block device as a FAT filesystem.

val fat_of_files : ?dir:string -> ?regexp:string -> unit -> fs impl

fat_files dir ?dir ?regexp () collects all the files matching the shell pattern regexp in the directory dir into a FAT image. By default, dir is the current working directory and regexp is *

val kv_ro_of_fs : fs impl -> kv_ro impl

Consider a filesystem implementation as a read-only key/value store.

Generic key/value stores

val generic_kv_ro : 
  ?key:[ `Archive | `Crunch | `Fat ] value ->
  string ->
  kv_ro impl

Generic key/value that will choose dynamically between fat, archive and crunch.

If no key is provided, it uses Key.kv_ro to create a new one.

Network interfaces

type network

Abstract type for network configurations.

val network : network typ

Implementations of the V1.NETWORK signature.

val tap0 : network impl

The '/dev/tap0' interface.

val netif : ?group:string -> string -> network impl

A custom network interface. Exposes a Key.network key.

Ethernet configuration

type ethernet

val ethernet : ethernet typ

Implementations of the V1.ETHIF signature.

val etif : network impl -> ethernet impl

ARP configuration

type arpv4

val arpv4 : arpv4 typ

Implementation of the V1.ARPV4 signature.

val arp : ?clock:clock impl -> ?time:time impl -> ethernet impl -> arpv4 impl

IP configuration

Implementations of the V1.IP signature.

type v4

type v6

type 'a ip

Abstract type for IP configurations.

type ipv4 = v4 ip

type ipv6 = v6 ip

val ipv4 : ipv4 typ

The V1.IPV4 module signature.

val ipv6 : ipv6 typ

The V1.IPV6 module signature.

type ('ipaddr, 'prefix) ip_config = {

address : 'ipaddr;
netmask : 'prefix;
gateways : 'ipaddr list;

}

Types for IP manual configuration.

type ipv4_config = (Ipaddr.V4.t, Ipaddr.V4.t) ip_config

Types for IPv4 manual configuration.

val create_ipv4 : 
  ?clock:clock impl ->
  ?time:time impl ->
  ?group:string ->
  network impl ->
  ipv4_config ->
  ipv4 impl

Use an IPv4 address. Exposes the keys Key.V4.ip, Key.V4.netmask and Key.V4.gateways.

val default_ipv4 : ?group:string -> network impl -> ipv4 impl

Default local IP listening on the given network interfaces:

address: 10.0.0.2
netmask: 255.255.255.0
gateways: 10.0.0.1

type ipv6_config = (Ipaddr.V6.t, Ipaddr.V6.Prefix.t list) ip_config

Types for IPv6 manual configuration.

val create_ipv6 : 
  ?time:time impl ->
  ?clock:clock impl ->
  ?group:string ->
  network impl ->
  ipv6_config ->
  ipv6 impl

Use an IPv6 address. Exposes the keys Key.V6.ip, Key.V6.netmask and Key.V6.gateways.

UDP configuration

type 'a udp

type udpv4 = v4 udp

type udpv6 = v6 udp

val udp : 'a udp typ

Implementation of the V1.UDP signature.

val udpv4 : udpv4 typ

val udpv6 : udpv6 typ

val direct_udp : 'a ip impl -> 'a udp impl

val socket_udpv4 : ?group:string -> Ipaddr.V4.t option -> udpv4 impl

TCP configuration

type 'a tcp

type tcpv4 = v4 tcp

type tcpv6 = v6 tcp

val tcp : 'a tcp typ

Implementation of the V1.TCP signature.

val tcpv4 : tcpv4 typ

val tcpv6 : tcpv6 typ

val direct_tcp : 
  ?clock:clock impl ->
  ?random:random impl ->
  ?time:time impl ->
  'a ip impl ->
  'a tcp impl

val socket_tcpv4 : ?group:string -> Ipaddr.V4.t option -> tcpv4 impl

Network stack configuration

type stackv4

val stackv4 : stackv4 typ

Implementation of the V1.STACKV4 signature.

val direct_stackv4_with_default_ipv4 : 
  ?clock:clock impl ->
  ?random:random impl ->
  ?time:time impl ->
  ?group:string ->
  console impl ->
  network impl ->
  stackv4 impl

Same as direct_stackv4_with_static_ipv4 with the default given by default_ipv4.

val direct_stackv4_with_static_ipv4 : 
  ?clock:clock impl ->
  ?random:random impl ->
  ?time:time impl ->
  ?group:string ->
  console impl ->
  network impl ->
  ipv4_config ->
  stackv4 impl

Direct network stack with ip. Exposes the keys Key.V4.ip, Key.V4.netmask and Key.V4.gateways.

val direct_stackv4_with_dhcp : 
  ?clock:clock impl ->
  ?random:random impl ->
  ?time:time impl ->
  ?group:string ->
  console impl ->
  network impl ->
  stackv4 impl

Direct network stack using dhcp.

val socket_stackv4 : 
  ?group:string ->
  console impl ->
  Ipaddr.V4.t list ->
  stackv4 impl

Network stack with sockets. Exposes the key Key.interfaces.

val generic_stackv4 : 
  ?group:string ->
  ?dhcp_key:bool value ->
  ?net_key:[ `Direct | `Socket ] value ->
  console impl ->
  network impl ->
  stackv4 impl

Generic stack using a dhcp and a net keys: Key.net and Key.dhcp.

If net = socket then socket_stackv4 is used.
Else, if dhcp then direct_stackv4_with_dhcp is used
Else, direct_stackv4_with_default_ipv4 is used.

If a key is not provided, it uses Key.net or Key.dhcp (with the group argument) to create it.

Resolver configuration

type resolver

val resolver : resolver typ

val resolver_dns : 
  ?ns:Ipaddr.V4.t ->
  ?ns_port:int ->
  ?time:time impl ->
  stackv4 impl ->
  resolver impl

val resolver_unix_system : resolver impl

Entropy

val nocrypto : job impl

Device that initializes the entropy.

Conduit configuration

type conduit

val conduit : conduit typ

val conduit_direct : ?tls:bool -> stackv4 impl -> conduit impl

HTTP configuration

type http

val http : http typ

val http_server : conduit impl -> http impl

Argv configuration

val default_argv : Functoria_app.argv impl

default_argv is a dynamic argv implementation that resolves either to the xen or the unix implementation.

val no_argv : Functoria_app.argv impl

no_argv Disable command line parsing and set argv to |""|.

Other devices

val noop : job impl

noop is a job that does nothing, has no dependency and returns ()

type info

info is the type for module implementing Mirage_runtime.Info.

val info : info typ

info is the combinator to generate info values to use at runtime.

val app_info : info impl

app_info exports all the information available at configure time into a runtime Mirage.Info.t value.

Deprecated functions

val get_mode : unit -> [ `Unix | `Xen | `MacOSX ]

Current configuration mode.

deprecated
Use Key.target and Key.is_xen.

val add_to_opam_packages : string list -> unit

deprecated
Use the ~package argument from register.

val add_to_ocamlfind_libraries : string list -> unit

deprecated
Use the ~libraries argument from register.

Application registering

val register : 
  ?argv:Functoria_app.argv impl ->
  ?tracing:tracing impl ->
  ?reporter:reporter impl ->
  ?keys:Key.t list ->
  ?libraries:string list ->
  ?packages:string list ->
  string ->
  job impl list ->
  unit

register name jobs registers the application named by name which will executes the given jobs.

parameter libraries
The ocamlfind libraries needed by this module.

parameter packages
The opam packages needed by this module.

parameter keys
The keys related to this module.

parameter tracing
Enable tracing.

parameter reporter
Configure logging. The default log reporter is default_reporter. To disable logging, use no_reporter.

parameter argv
Configure command-line argument parsing. The default parser is default_argv. To disable command-line parsing, use no_argv.

package mirage