gazagnaire.org
Block device abstraction for OCaml 5 with Eio direct-style I/O and Bytesrw integration
1# block
2
3Block device abstraction for OCaml 5 with Eio direct-style I/O and Bytesrw integration.
4
5## Overview
6
7This library provides a minimal block device interface inspired by MirageOS
8[mirage-block](https://github.com/mirage/mirage-block) but using Eio's
9effects-based concurrency instead of Lwt.
10
11## Features
12
13- Eio direct-style I/O (no monads)
14- Bytesrw integration for streaming access
15- Memory, file, and flow backends
16- CRC32C integrity checking wrapper
17- Sub-device views for partitioning
18- Read-only wrapper
19
20## Installation
21
22```
23opam install block
24```
25
26## Usage
27
28```ocaml
29Eio_main.run @@ fun env ->
30Eio.Switch.run @@ fun sw ->
31
32(* Create a file-backed block device *)
33let blk = Block.of_file ~sw env#fs "disk.img" ~sector_size:512 ~create:1000L () in
34let info = Block.info blk in
35Printf.printf "Sectors: %Ld\n" info.sectors;
36
37(* Write a sector *)
38let data = String.make 512 'A' in
39Block.write blk 0L data |> Result.get_ok;
40
41(* Read it back *)
42let read = Block.read blk 0L |> Result.get_ok in
43assert (data = read);
44
45(* Add CRC32C integrity checking *)
46let safe_blk = Block.with_crc32c blk in
47(* Now reads verify checksums, writes compute them *)
48```
49
50## API
51
52### Core Operations
53
54- `Block.info` - Get device info (sector size, count, read/write)
55- `Block.read` - Read a single sector
56- `Block.write` - Write a single sector
57- `Block.read_many` - Read multiple consecutive sectors
58- `Block.write_many` - Write multiple consecutive sectors
59- `Block.sync` - Flush pending writes
60- `Block.close` - Release resources
61
62### Backends
63
64- `Block.of_memory` - In-memory device (for testing)
65- `Block.of_string` - Read-only device from string
66- `Block.of_file` - File-backed device
67- `Block.of_flow` - Eio flow-backed device
68- `Block.of_bigarray` - Bigarray-backed device
69
70### Wrappers
71
72- `Block.read_only` - Read-only view
73- `Block.sub` - Sub-device view (for partitions)
74- `Block.with_crc32c` - CRC32C integrity checking
75
76### Bytesrw Integration
77
78- `Block.to_reader` - Create sequential reader from offset
79- `Block.to_writer` - Create sequential writer from offset
80
81## Related Work
82
83- [mirage-block](https://github.com/mirage/mirage-block) - MirageOS block
84 interface (Lwt-based)
85- [mirage-block-unix](https://github.com/mirage/mirage-block-unix) - Unix
86 backend for mirage-block
87
88## Licence
89
90ISC License. See [LICENSE.md](LICENSE.md) for details.