doc: Update instructions to platform-specific builds and HWI usage

1 files changed, 104 insertions, 13 deletions

diff --git a/README.md b/README.md
index 9cf29db..e9ef819 100644
--- a/README.md
+++ b/README.md
@@ -40,13 +40,17 @@ Required dependencies:
 
 * zig ^0.12.0
 
-Making a debug build of this kernel is straightforward:
+To make a debug build of this kernel, run:
 
 ```
-zig build
+zig build -Dplatform=<PLATFORM>
 ```
 
-You can also use any other Zig build mode, e.g. `-Doptimize=ReleaseFast`.
+Replace `<PLATFORM>` with the platform you want to build for.
+Support options include `qemu` and `lpi4a`.
+See the `src/lib/cfg/platform` directory for the full list.
+
+You can also use any other Zig build mode, e.g. `--release=fast`.
 
 This results in a `zig-out/bin/srvre_kernel.elf` file.
 You may `strip(1)` this file if you want to.
@@ -77,13 +81,6 @@ This issue has not been observed on QEMU, possibly due to it using a
 more recent version of OpenSBI or the device tree being unable to trigger
 the bug.
 
-**Important:** The default fw_dynamic payload corrupts the device tree.
-You can fix this by padding it with zeroes at the end:
-
-```
-for i in {1..8192}; do echo -e '\x00' >> build/platform/generic/firmware/fw_dynamic.bin; done
-```
-
 ## Building U-Boot
 
 Required dependencies:
@@ -178,12 +175,11 @@ using the commands above.
 The kernel expects to be loaded in S-mode with the following register values:
 
 * a0: Current Hart ID
-* a1: Memory address of FDT (Flattened Device Tree)
 
 Typically you'll want to load it directly from OpenSBI.
 Depending on your platform you may use a slightly patched version of U-Boot
-that runs in M-mode boot a combined kernel / OpenSBI image.
-This process is yet to be documented.
+that runs in M-mode to boot a combined kernel / OpenSBI image.
+This process is documented above.
 
 Completely skipping U-Boot and using OpenSBI directly should work
 if your platform supports it. However it is currently untested.
@@ -204,3 +200,98 @@ target remote localhost:1234
 
 Be sure to confirm the prompt from the `add-symbol-file` command.
 You can also use `riscv64-elf-gdb /path/to/srvre_kernel.elf` directly.
+
+# Translating device trees to the HWI (Hardware Info) format
+
+The HWI format was developed as a more robust and efficient alternative
+to standard device trees. The `hwi(1)` tool reads a textual representation
+from stdin and writes the corresponding binary representation to stdout.
+The values can be obtained from the device tree, but automated conversion
+is not implemented due to the complexity of the device tree format.
+
+## Building hwi
+
+The `hwi(1)` tool can be built easily:
+
+```
+zig build-exe src/hwi.zig
+```
+
+This produces a `hwi` binary in the current working directory.
+
+## Using hwi
+
+You can use the `hwi(1)` command to convert from the textual representation
+to the binary representation:
+
+```
+hwi < src/lib/cfg/platform/<PLATFORM>.txt > src/lib/cfg/platform/<PLATFORM>.hwi
+```
+
+Omitting the stdin pipe allows you to type out the textual representation
+manually:
+
+```
+hwi > src/lib/cfg/platform/<PLATFORM>.hwi
+```
+
+Press Control+D after finishing the last line (and pressing Enter)
+to close stdin, quitting the tool.
+
+## Textual format
+
+The textual HWI format is a list of entries where each entry
+is represented by a line of text. Separation is done using a single `\n`
+character.
+
+The entry format is as follows:
+
+```
+<KIND> <ADDRESS> <SIZE> [VALUE]
+```
+
+* `<KIND>`: The kind of the entry. Can be `cpus`, `plic`, `pcie` or `pci`.
+* `<ADDRESS>`: The base address for memory-mapped I/O. Ignored (and preferably set to zero) if not applicable.
+* `<SIZE>`: The size of the memory-mapped I/O region. Ignored (and preferably set to zero) if not applicable.
+* `[VALUE]`: Optional additional (numeric) data. Defaults to zero if unspecified.
+
+Numeric values are represented as unsigned 64-bit integers and may be parsed
+from non-decimal notations.
+See [the documentation of std.fmt.parseUnsigned](https://ziglang.org/documentation/0.12.0/std/#std.fmt.parseUnsigned)
+for details on supported notations.
+
+### cpus
+
+Gives information about the processors. MMIO is not applicable.
+The `VALUE` parameter holds the timebase frequency (used for interrupt timers).
+
+### plic
+
+Gives information about the Platform-Level Interrupt Controller.
+MMIO is applicable. The `VALUE` parameter is ignored.
+
+### pcie
+
+Gives information about an ECAM PCI(e) controller. MMIO is applicable.
+The `VALUE` parameter is ignored.
+
+### pci
+
+Gives information about a legacy CAM PCI controller. MMIO is applicable.
+The `VALUE` parameter is ignored.
+
+## Binary format
+
+The binary HWI format is a sequence of entry structures that isn't aware
+of endianness. The number of entries is `n/32` where `n` is the size
+of a valid HWI sequence in bytes.
+
+The entry format is as follows:
+
+```
+kind: enum(u32) { cpus, plic, pcie, pci }
+ALIGNMENT (u32)
+reg.addr: u64
+reg.len: u64
+value: u64
+```