3 Assemble and run the executable:
8 The `example.f` file contains an example that you can run with:
10 $ cat sys.f example.f | ./main
14 We are currently in the process of implementing support for running without
15 Linux, by instead relying on UEFI. Eventually, this will be the only supported
16 method of running the interpreter, but currently the UEFI-related code is
17 isolated in the `uefi/` directory and does not yet contain an implementation of
20 You should have the following dependencies installed (assuming Arch Linux):
24 To run a UEFI shell inside qemu, cd to `uefi/` and run:
28 ### Running on real hardware
30 * [ ] This is not supported yet
32 # Notes on implementation
34 The implementation is based on
35 [JONESFORTH](https://raw.githubusercontent.com/nornagon/jonesforth/master/jonesforth.S).
36 This is my summary of the most important parts.
40 In Forth, words are stored in a dictionary. The dictionary is a linked list
41 whose entries look like this:
43 +------------------------+--------+---------- - - - - +----------- - - - -
44 | LINK POINTER | LENGTH/| NAME | DEFINITION
46 +--- (4 bytes) ----------+- byte -+- n bytes - - - - +----------- - - - -
48 For example, DOUBLE and QUADRUPLE may be stored like this:
50 pointer to previous word
53 +--|------+---+---+---+---+---+---+---+---+------------- - - - -
54 | LINK | 6 | D | O | U | B | L | E | 0 | (definition ...)
55 +---------+---+---+---+---+---+---+---+---+------------- - - - -
58 +--|------+---+---+---+---+---+---+---+---+---+---+---+---+------------- - - - -
59 | LINK | 9 | Q | U | A | D | R | U | P | L | E | 0 | 0 | (definition ...)
60 +---------+---+---+---+---+---+---+---+---+---+---+---+---+------------- - - - -
66 The Forth variable LATEST contains a pointer to the most recently defined word.
70 In a typical Forth interpreter, code is stored in a peculiar way. (This way of
71 storing code is primarily motivated by space contraints on early systems.)
73 The definition of a word is stored as a sequence of memory adresses of each of
74 the words making up that definition. (At the end of a compiled definition, there
75 is also some extra code that causes execution to continue in the correct way.)
77 We use a register (ESI) to store a reference to the next index of the
78 word (inside a definition) that we are executing. Then, in order to execute a
79 word, we just jump to whatever address is pointed to by ESI. The code for
80 updating ESI and continuing execution is stored at the end of each subroutine.
82 Of course, this approach only works if each of the words that we are executing
83 is defined in assembly, but we also want to be able to execute Forth words!
85 We get around this problem by adding a "codeword" to the beginning of any
86 compiled subroutine. This codeword is a pointer to the intrepreter to run the
87 given function. In order to run such functions, we actually need two jumps when
88 executing: In order to execute a word, we jump to the address at the location
89 pointed to by the address in ESI.
93 What does the codeword of a Forth word contain? It needs to save the old value
94 of ESI (so that we can resume execution of whatever outer definition we are
95 executing at the time) and set the new version of ESI to point to the first word
96 in the inner definition.
98 The stack where the values of ESI are stored is called the "return stack". We
99 will use EBP for the return stack.
101 As mentioned, whenever we finish executing a Forth word, we will need to
102 continue execution in the manner described in the previous section. When the
103 word being executed is itself written in Forth, we need to pop the old value of
104 ESI that we saved at the beginning of the definition before doing this.
106 Thus, the actual data for a word in a dictionary will look something like this:
108 pointer to previous word
111 +--|------+---+---+---+---+---+---+---+---+------------+------------+------------+------------+
112 | LINK | 6 | D | O | U | B | L | E | 0 | DOCOL | DUP | + | EXIT |
113 +---------+---+---+---+---+---+---+---+---+------------+--|---------+------------+------------+
116 LINK in next word points to codeword of DUP
118 Here, DOCOL (the codeword) is address of the simple interpreter described above,
119 while EXIT a word (implemented in assembly) that takes care of popping ESI and
120 continuing execution. Note that DOCOL, DUP, + and EXIT are all stored as
121 addresses which point to codewords.
125 Literals are handled in a special way. There is a word in Forth, called LIT,
126 implemented in assembly. When executed, this word looks at the next Forth
127 instruction (i.e. the value of ESI), and places that on the stack as a literal,
128 and then manipulates ESI to skip over the literal value.
130 ## Built-in variables
132 * **STATE** -- Is the interpreter executing code (0) or compiling a word (non-zero)?
133 * **LATEST** -- Points to the latest (most recently defined) word in the dictionary.
134 * **HERE** -- Points to the next free byte of memory. When compiling, compiled words go here.
135 * **S0** -- Stores the address of the top of the parameter stack.
136 * **BASE** -- The current base for printing and reading numbers.
140 `WORD` reads a word from standard input and pushes a string (in the form of an
141 address followed by the length of the string) to the stack. (It uses an internal
142 buffer that is overwritten each time it is called.)
144 `FIND` takes a word as parsed by `WORD` and looks it up in the dictionary. It
145 returns the address of the dictionary header of that word if it is found.
146 Otherwise, it returns 0.
148 `>CFA` turns a dictionary pointer into a codeword pointer. This is used when
153 The Forth word INTERPRET runs in a loop, reading in words (with WORD), looking
154 them up (with FIND), turning them into codeword pointers (with >CFA) and then
155 deciding what to do with them.
157 In immediate mode (when STATE is zero), the word is simply executed immediately.
159 In compilation mode, INTERPRET appends the codeword pointer to user memory
160 (which is at HERE). However, if a word has the immediate flag set, then it is
161 run immediately, even in compile mode.
163 ### Definition of `:` and `;`
165 The word `:` starts by reading in the new word. Then it creates a new entry for
166 that word in the dictoinary, updating the contents of `LATEST`, to which it
167 appends the word `DOCOL`. Then, it switches to compile mode.
169 The word `;` simply appends `EXIT` to the currently compiling definition and
170 then switches back to immediate mode.
172 These words rely on `,` to append words to the currently compiling definition.
173 This word simply appends some literal value to `HERE` and moves the `HERE`
178 `JONASFORTH` is runs without an operating system, instead using the facilities
179 provided by UEFI by running as a UEFI application. (Or rather, in the future it
180 hopefully will. Right now, it uses Linux.) This section contains some notes
181 about how this functionality is implemented.
183 ## Packaging and testing the image
185 UEFI expects a UEFI application to be stored in a FAT32 file system on a
186 GPT-partitioned disk.
188 Luckily, QEMU has a convenient way of making a subdirectory availabe as a
189 FAT-formatted disk (see [the relevant section in the QEMU User
190 Documentation](https://qemu.weilnetz.de/doc/qemu-doc.html#disk_005fimages_005ffat_005fimages)
191 for more information):
193 $ qemu-sytem-x86_64 ... -hda fat:/some/directory
195 We use this to easily test the image in QEMU; see the Makefile for more
196 information, or just run the `qemu` target to run the program inside of QEMU
197 (of course, you must have QEMU installed for this to work):
201 * [ ] How to build the image for real hardware (what should the image look like,
202 which programs, commands, etc.)
204 ## Interfacing with UEFI
206 From [OSDev Wiki](https://wiki.osdev.org/UEFI#How_to_use_UEFI):
208 >Traditional operating systems like Windows and Linux have an existing software
209 >architecture and a large code base to perform system configuration and device
210 >discovery. With their sophisticated layers of abstraction they don't directly
211 >benefit from UEFI. As a result, their UEFI bootloaders do little but prepare
212 >the environment for them to run.
214 >An independent developer may find more value in using UEFI to write
215 >feature-full UEFI applications, rather than viewing UEFI as a temporary
216 >start-up environment to be jettisoned during the boot process. Unlike legacy
217 >bootloaders, which typically interact with BIOS only enough to bring up the OS,
218 >a UEFI application can implement sophisticated behavior with the help of UEFI.
219 >In other words, an independent developer shouldn't be in a rush to leave
222 For `JONASFORTH`, I have decided to run as a UEFI application, taking advantage
223 of UEFI's features, including its text I/O features and general graphical device
224 drivers. Eventually, we would like to add some basic graphical drawing
225 capabilities to `JONASFORTH`, and it's my impression that this would be possible
226 using what is provided to us by UEFI.
228 A UEFI images is basically a windows EXE without symbol tables. There are three
229 types of UEFI images; we use the EFI application, which has subsystem `10`. It
230 is an x68-64 image, which has value `0x8664`.
232 UEFI applications use [Microsoft's 64-bit calling
233 convention](https://en.wikipedia.org/wiki/X86_calling_conventions#Microsoft_x64_calling_convention)
234 for x68-64 functions. See the linked article for a full description. Here is
237 * Integer or pointer arguments are given in RCX, RDX, R8 and R9.
238 * Additional arguments are pushed onto the stack from right to left.
239 * Integer or pointer values are returned in RAX.
240 * An integer-sized struct is passed directly; non-integer-sized structs are passed as pointers.
241 * The caller must allocate 32 bytes of "shadow space" on the stack immediately
242 before calling the function, regardless of the number of parameters used, and
243 the caller is responsible for popping the stack afterwards.
244 * The following registers are volatile (caller-saved): RAX, RCX, RDX, R8, R9, R10, R11
245 * The following registers are nonvolatile (callee-saved): RBX, RBP, RDI, RSI, RSP, R12, R13, R14, R15
247 When the application is loaded, RCX contains a firmware allocated `EFI_HANDLE`
248 for the UEFI image, RDX contains a `EFI_SYSTEM_TABLE*` pointer to the EFI system
249 table and RSP contains the return address. For more infromation about how a UEFI
250 application is entered, see "4 - EFI System Table" in [the latest UEFI
251 specification as of March 2020 (PDF)](https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf).
255 * [UEFI applications in detail - OSDev Wiki](https://wiki.osdev.org/UEFI#UEFI_applications_in_detail)
256 * [Microsoft x64 calling convention](https://en.wikipedia.org/wiki/X86_calling_conventions#Microsoft_x64_calling_convention)
257 * [UEFI Specifications](https://uefi.org/specifications)
261 We might want to consider using something like this: https://wiki.osdev.org/Uefi.inc)
263 FASM can generate UEFI application binaries by default. Use the following
264 template to output a 64-bit UEFI application:
269 section '.text' code executable readable
275 section '.data' data readable writable
279 Use `objdump -x` to inspect the assembled application binary.
281 ### UEFI documentation
283 * [Latest specification as of March 2020 (PDF)](https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf)
288 * 4\. EFI System Table (89)
289 * 7\. Services - Boot Services (140)
290 * 8\. Services - Runtime Services (228)
291 * 12\. Protocols - Console Support (429)
292 * 13\. Protocols - Media Access (493)
293 * Appendix B - Console (2201)
294 * Appendix D - Status Codes (2211)
298 * [UEFI - OSDev Wiki](https://wiki.osdev.org/UEFI)
299 * [Unified Extensible Firmware Interface (Wikipedia)](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface)
300 * [UEFI Specifications](https://uefi.org/specifications)