From 5fc11865d892857071bed93c9e88036b93abba87 Mon Sep 17 00:00:00 2001 From: Alex Williams Date: Sun, 15 Jan 2023 21:57:15 +0900 Subject: [PATCH] Add memory map and header layour to docs --- docs/REFERENCE.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) diff --git a/docs/REFERENCE.md b/docs/REFERENCE.md index ab58cce..cd342c8 100644 --- a/docs/REFERENCE.md +++ b/docs/REFERENCE.md @@ -12,7 +12,10 @@ This document provides technical details about what's under the hood of _FiveFor 2. [Primitives list](#primitives-list) 3. [Registers list](#registers-list) 4. [Source files list](#source-files-list) -5. [Other Forths](#other-forths) +5. [Memory map](#memory-map) +6. [Word header](#word-header) +7. [Hash format](#hash-format) +8. [Other Forths](#other-forths) ### FiveForths specification @@ -83,6 +86,8 @@ The following _Forth_ registers are assigned to _RISC-V_ registers below. The so ### Source files list +The firmware binary is built using `GNU as`, so all source files have the lowercase `.s` extension. + | Filename | Description | | :---- | :---- | | [fiveforths.s](fiveforths.s) | Loads the actual source files from `src/` | @@ -102,6 +107,69 @@ The following _Forth_ registers are assigned to _RISC-V_ registers below. The so | **`src/mcus//`** | | [mcu.s](src/mcus/gd32vf103/mcu.s) | Variables and constant specific to the `` | +### Memory map + +The stack size is defined in `mcu.s` and defaults to 256 bytes for the `Data, Return, Terminal` stacks. The `Data` and `Return` stacks grow _downward_ from the top of the memory. The `Terminal` buffer grows _upward_ from the start of the `Variables` area. The `User Dictionary` grows _upward_ from the bottom of the memory. Currently `5` Cells are used to store variables. There is also an additional `64` Cells reserved for the `Pad` area, which can grow _upward or downward_. The `Pad` area is not exposed in _Forth_ and should be used exclusively by internal code or new Assembly primitives - as an in-memory scratchpad without affecting the other stacks or user dictionary. + +``` +Top ++-----------------+-------------------------+ +| Memory Map | Size (1 Cell = 4 Bytes) | ++-------------------------------------------+ +| | | | +| Data Stack | 64 Cells (256 Bytes) | | +| | | v ++-------------------------------------------+ +| | | | +| Return Stack | 64 Cells (256 Bytes) | | +| | | v ++-------------------------------------------+ +| | | ^ +| Terminal Buffer | 64 Cells (256 Bytes) | | +| | | | ++-------------------------------------------+ +| | | +| Variables | 5 Cells (20 Bytes) | +| | | ++-------------------------------------------+ +| | | ^ +| Pad Area | 64 Cells (256 Bytes) | | +| | | v ++-------------------------------------------+ +| | | ^ +| | | | +| | | | +| User Dictionary | Variable size | | +| | | | +| | | | +| | | | ++-----------------+-------------------------+ +``` + +### Word header + +A dictionary word header contains 3 Cells (3 x 32 bits = 12 bytes). The `Link` is the value of the last defined word, which is stored in the variable `LATEST`. The `Hash` is generated by the `djb2_hash` function. And the `Codeword` is the address of the `.addr` label which jumps to the `docol` function. + +``` ++----------+----------+-------------+ +| Link | Hash | Codeword | ++----------+----------+-------------+ + 32-bits 32-bits 32-bits +``` + +### Hash format + +The hash is a 32-bit hash with the last 8 bits (from the LSB) used for the Flags (3 bits) and Length (5 bits) of the word. + +``` + 32-bit hash ++-------+--------+------------------+ +| FLAGS | LENGTH | HASH | ++-------+--------+------------------+ + 3-bits 5-bits 24-bits + +``` + ### Other Forths This document would be incomplete without listing other Forths which inspired me and are worth checking out: