upstream: https://github.com/mirage/ocaml-mbr
mbr: rewrite README — replace stale Cstruct/Mirage API with Wire/bytesrw
+104
-28
+104
-28
README.md
+104
-28
README.md
···
1
-
ocaml-mbr
2
-
=========
1
+
# mbr
2
+
3
+
A library to manipulate Master Boot Records in pure OCaml.
4
+
5
+
## Overview
6
+
7
+
Pure OCaml library for reading and writing Master Boot Records (MBR). Supports
8
+
creating disk images with primary partition tables, CHS geometry translation,
9
+
and streaming I/O via bytesrw.
10
+
11
+
## Features
12
+
13
+
- MBR header and partition table encoding/decoding
14
+
- Up to 4 primary partitions with overlap and bootable flag validation
15
+
- CHS geometry synthesis for pre-LBA compatibility
16
+
- Wire codecs for zero-copy partition entry access
17
+
- Streaming I/O with bytesrw readers/writers
18
+
- Pretty-printer
3
19
4
-
A library for manipulating Master Boot Records. The
5
-
primary purposes of this library are:
6
-
1. to create bootable disk images creating
7
-
[mirage](http://www.openmirage.org/) kernels
8
-
2. for mirage kernels to read the partition tables on
9
-
attached disks
20
+
## Installation
10
21
11
-
Usage
12
-
-----
13
-
Define a single partition as follows:
14
22
```
15
-
let disk_length_bytes = Int32.(mul (mul 16l 1024l) 1024l) in
16
-
let disk_length_sectors = Int32.(div disk_length_bytes 512l) in
23
+
opam install mbr
24
+
```
17
25
18
-
let start_sector = 2048l in
19
-
let length_sectors = Int32.sub disk_length_sectors start_sector in
20
-
let partition = Mbr.Partition.make ~active:true ~ty:6 start_sector length_sectors in
21
-
let mbr = Mbr.make [ partition ] in
26
+
## Usage
27
+
28
+
### Creating an MBR
29
+
30
+
```ocaml
31
+
(* Create a partition: FAT16 (type 6), starting at sector 2048, 32MB *)
32
+
match Mbr.Partition.make ~active:true ~partition_type:6 2048l 65536l with
33
+
| Error e -> failwith e
34
+
| Ok part ->
35
+
match Mbr.v [ part ] with
36
+
| Error e -> failwith e
37
+
| Ok mbr -> Fmt.pr "%a@." Mbr.pp mbr
22
38
```
23
-
You can write the MBR to sector zero of a block device ```B``` as follows:
39
+
40
+
### Serialization
41
+
42
+
```ocaml
43
+
(* Write to string *)
44
+
let bytes = Mbr.to_string mbr
45
+
46
+
(* Read from string *)
47
+
match Mbr.of_string bytes with
48
+
| Ok mbr -> List.iter (fun p ->
49
+
Printf.printf "Partition: start=%Ld, size=%Ld\n"
50
+
(Mbr.Partition.sector_start p)
51
+
(Mbr.Partition.size_sectors p))
52
+
(Mbr.partitions mbr)
53
+
| Error e -> failwith e
24
54
```
25
-
B.connect id >>= fun device ->
26
-
let sector = Cstruct.create 512 in
27
-
Mbr.marshal sector mbr;
28
-
B.write device 0L [ sector ] >>= fun () ->
29
-
...
55
+
56
+
### Streaming I/O with bytesrw
57
+
58
+
```ocaml
59
+
(* Read *)
60
+
match Mbr.read reader with
61
+
| Ok mbr -> Fmt.pr "%a@." Mbr.pp mbr
62
+
| Error e -> failwith e
63
+
64
+
(* Write *)
65
+
Mbr.write writer mbr
66
+
```
67
+
68
+
### CHS Geometry
69
+
70
+
```ocaml
71
+
(* Synthesise geometry for a 4GB disk *)
72
+
match Mbr.Geometry.of_lba_size 8388608L with
73
+
| Ok geom -> Printf.printf "C=%d H=%d S=%d\n"
74
+
geom.cylinders geom.heads geom.sectors
75
+
| Error e -> failwith e
30
76
```
31
77
32
-
To do items
33
-
-----------
78
+
## API
34
79
35
-
* Implement tools to manipulate MBR-formatted disk images
36
-
to construct, inspect or fill partitions that can later
37
-
be used in Mirage unikernels.
80
+
### Partition
81
+
82
+
- `Mbr.Partition.make` -- Create a partition (`~partition_type:int -> int32 -> int32 -> (t, string) result`)
83
+
- `Mbr.Partition.make'` -- Create a partition with int64 args
84
+
- `Mbr.Partition.sector_start` -- LBA start as int64
85
+
- `Mbr.Partition.size_sectors` -- Size in sectors as int64
86
+
- `Mbr.Partition.codec` -- Wire codec for 16-byte partition entry
87
+
88
+
### MBR
89
+
90
+
- `Mbr.v` -- Create an MBR with up to 4 partitions (validates overlaps, active flags)
91
+
- `Mbr.partitions` -- Extract partition list
92
+
- `Mbr.pp` -- Pretty-print
93
+
- `Mbr.sizeof` -- Size in bytes (512)
94
+
- `Mbr.default_partition_start` -- Default first partition offset
95
+
96
+
### Serialization
97
+
98
+
- `Mbr.of_string` / `Mbr.to_string` -- String-based I/O
99
+
- `Mbr.read` / `Mbr.write` -- Bytesrw streaming I/O
100
+
101
+
### Geometry
102
+
103
+
- `Mbr.Geometry.of_lba_size` -- Synthesise CHS from sector count
104
+
- `Mbr.Geometry.to_chs` -- Convert LBA offset to CHS
105
+
106
+
## Requirements
107
+
108
+
- OCaml >= 5.1
109
+
- bytesrw, wire, fmt
110
+
111
+
## Licence
112
+
113
+
ISC