Add memory map and header layour to docs

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>/`** |
 | [mcu.s](src/mcus/gd32vf103/mcu.s) | Variables and constant specific to the `<mcu>` |
 
+### 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: