mirage-types 1.2.0 · OCaml Package

Operations on sector-addressible block devices, usually used for persistent storage

type page_aligned_buffer

Abstract type for a page-aligned memory buffer

type error = [

| `Unknown of string
(*
an undiagnosed error
*)
| `Unimplemented
(*
operation not yet implemented in the code
*)
| `Is_read_only
(*
you cannot write to a read/only instance
*)
| `Disconnected
(*
the device has been previously disconnected
*)

]

IO operation errors

include DEVICE with type error := error

type +'a io

A potentially blocking I/O operation

type t

The type representing the internal state of the device

type id

Type defining an identifier for this device that uniquely identifies it among a device tree.

val id : t -> id

Return the identifier that was used to construct this device

val connect : id -> [ `Error of error | `Ok of t ] io

Connect to the device identified by id

val disconnect : t -> unit io

Disconnect from the device. While this might take some time to complete, it can never result in an error.

type info = {

read_write : bool;
(*
True if we can write, false if read/only
*)
sector_size : int;
(*
Octets per sector
*)
size_sectors : int64;
(*
Total sectors per device
*)

}

Characteristics of the block device. Note some devices may be able to make themselves bigger over time.

val get_info : t -> info io

Query the characteristics of a specific block device

val read : 
  t ->
  int64 ->
  page_aligned_buffer list ->
  [ `Error of error | `Ok of unit ] io

read device sector_start buffers returns a blocking IO operation which attempts to fill buffers with data starting at sector_start. Each of buffers must be a whole number of sectors in length. The list of buffers can be of any length.

val write : 
  t ->
  int64 ->
  page_aligned_buffer list ->
  [ `Error of error | `Ok of unit ] io

write device sector_start buffers returns a blocking IO operation which attempts to write the data contained within buffers to t starting at sector_start. When the IO operation completes then all writes have been persisted.

Once submitted, it is not possible to cancel a request and there is no timeout.

The operation may fail with * `Unimplemented: the operation has not been implemented, no data has been written * `Is_read_only: the device is read-only, no data has been written * `Disconnected: the device has been disconnected at application request, an unknown amount of data has been written * `Unknown: some other permanent, fatal error (e.g. disk is on fire), where an unknown amount of data has been written

Each of buffers must be a whole number of sectors in length. The list of buffers can be of any length.

The data will not be copied, so the supplied buffers must not be re-used until the IO operation completes.

package mirage-types