readme: Update HWI documentation, referencing the wiki for technical detailsHEADmain

1 files changed, 15 insertions, 66 deletions

diff --git a/README.md b/README.md
index 3930240..993c9a3 100644
--- a/README.md
+++ b/README.md
@@ -38,7 +38,7 @@ QEMU can be adapted to use this boot flow as well (the default is different).
 
 Required dependencies:
 
-* zig ^0.12.0
+* zig (most recent release version at the time of the latest commit)
 * init executable (see below)
 
 To make a debug build of this kernel, run:
@@ -261,15 +261,15 @@ 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.
+The HWI format was developed as a more robust and efficient alternative to
+standard device trees. The `hwi` tool reads a text 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.
 
 ## Build hwi
 
-The `hwi(1)` tool can be built easily:
+The `hwi` tool can be built easily:
 
 ```
 zig build-exe src/hwi.zig
@@ -277,10 +277,10 @@ zig build-exe src/hwi.zig
 
 This produces a `hwi` binary in the current working directory.
 
-## The hwi tool
+## Use hwi tool
 
-You can use the `hwi(1)` command to convert from the textual representation
-to the binary representation:
+You can use the `hwi` command to convert from the text representation to the
+binary representation:
 
 ```
 hwi < src/cfg/platform/<PLATFORM>.txt > src/cfg/platform/<PLATFORM>.hwi
@@ -296,60 +296,9 @@ hwi > src/cfg/platform/<PLATFORM>.hwi
 Press Control+D after finishing the last line (and pressing Enter)
 to close stdin, quitting the tool.
 
-## Textual format
+## Text and binary formats
 
-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
-```
+The [text](https://himbeerserver.de/md/srvre/kernel/wiki/hwi.md#text-format)
+and
+[binary](https://himbeerserver.de/md/srvre/kernel/wiki/hwi.md#binary-format)
+formats are documented in the wiki.