# Building and running
-Assemble and run the executable:
+You can run JONASFORTH inside QEMU or on real hardware. If you want to run
+inside QEMU, you should have the following dependencies installed (assuming
+Arch Linux):
- $ make main
- $ ./main
+ $ pacman -S qemu ovmf
+
+Then, to run a UEFI shell inside QEMU, run:
-The `example.f` file contains an example that you can run with:
+ $ make qemu
- $ cat sys.f example.f | ./main
+JONASFORTH will be available as `main` on `FS0:`. Thus, to run it, you can run
+the following command inside the UEFI shell:
-## Running with UEFI
+ Shell> fs0:main
+ Ready.
+ S" Hello, World!" TELL
+ Hello World!
-We are currently in the process of implementing support for running without
-Linux, by instead relying on UEFI. Eventually, this will be the only supported
-method of running the interpreter, but currently the UEFI-related code is
-isolated in the `uefi/` directory and does not yet contain an implementation of
-the main program.
+(Try typing in the code in `example.f` for something a little more
+interesting.)
-You should have the following dependencies installed (assuming Arch Linux):
+## Running on real hardware
- $ pacman -S qemu ovmf
+Making the program run on physical hardware is pretty easy. Just create a
+FAT32-formatted USB drive, and copy `out/main` to it. Then, you can execute the
+program in the same way that you did from inside QEMU, assuming your system
+comes with a UEFI shell built-in.
-To run a UEFI shell inside qemu, cd to `uefi/` and run:
+If your system doesn't have a UEFI shell, then you can copy the executable to
+`\EFI\BOOT\BOOTx64.EFI` on the USB drive. Then, the system should be able to
+boot from the USB drive and directly into JONASFORTH. The way to do this is a
+little bit different depending on the exact firmware, but most firmwares will
+have some way to enter a boot menu where you can select the USB drive. You may
+need to disable Secure Boot first.
- $ make run
+To format a USB drive as FAT32, you can run
-### Running on real hardware
+ # mkfs.vfat -F32 /dev/sdx
-* [ ] This is not supported yet
+with `/dev/sdx` replaced by the path of your USB drive. Then mount the drive,
+and copy `out/main` to `\EFI\BOOT\BOOTx64.EFI`:
+
+ $ mkdir mnt
+ # mount /dev/sdx mnt
+ $ mkdir -p mnt/EFI/BOOT
+ $ make out/main
+ $ cp out/main mnt/EFI/BOOT/BOOTx64.EFI
+
+Now you should be able to boot directly from the USB drive.
# Notes on implementation
## Built-in variables
-* **STATE** -- Is the interpreter executing code (0) or compiling a word (non-zero)?
-* **LATEST** -- Points to the latest (most recently defined) word in the dictionary.
-* **HERE** -- Points to the next free byte of memory. When compiling, compiled words go here.
-* **S0** -- Stores the address of the top of the parameter stack.
-* **BASE** -- The current base for printing and reading numbers.
+- **STATE** -- Is the interpreter executing code (0) or compiling a word (non-zero)?
+- **LATEST** -- Points to the latest (most recently defined) word in the dictionary.
+- **HERE** -- Points to the next free byte of memory. When compiling, compiled words go here.
+- **S0** -- Stores the address of the top of the parameter stack.
+- **BASE** -- The current base for printing and reading numbers.
## Input and lookup
hopefully will. Right now, it uses Linux.) This section contains some notes
about how this functionality is implemented.
+I also wrote an entire tutorial that descirbes how to write and compile a
+"Hello, World!" UEFI application, including how to run it on real hardware,
+which you can find here: [Getting started with bare-metal
+assembly](https://johv.dk/blog/bare-metal-assembly-tutorial.html).
+
## Packaging and testing the image
UEFI expects a UEFI application to be stored in a FAT32 file system on a
$ make qemu
-* [ ] How to build the image for real hardware (what should the image look like,
- which programs, commands, etc.)
-
## Interfacing with UEFI
From [OSDev Wiki](https://wiki.osdev.org/UEFI#How_to_use_UEFI):
->Traditional operating systems like Windows and Linux have an existing software
->architecture and a large code base to perform system configuration and device
->discovery. With their sophisticated layers of abstraction they don't directly
->benefit from UEFI. As a result, their UEFI bootloaders do little but prepare
->the environment for them to run.
+> Traditional operating systems like Windows and Linux have an existing software
+> architecture and a large code base to perform system configuration and device
+> discovery. With their sophisticated layers of abstraction they don't directly
+> benefit from UEFI. As a result, their UEFI bootloaders do little but prepare
+> the environment for them to run.
>
->An independent developer may find more value in using UEFI to write
->feature-full UEFI applications, rather than viewing UEFI as a temporary
->start-up environment to be jettisoned during the boot process. Unlike legacy
->bootloaders, which typically interact with BIOS only enough to bring up the OS,
->a UEFI application can implement sophisticated behavior with the help of UEFI.
->In other words, an independent developer shouldn't be in a rush to leave
->"UEFI-land".
+> An independent developer may find more value in using UEFI to write
+> feature-full UEFI applications, rather than viewing UEFI as a temporary
+> start-up environment to be jettisoned during the boot process. Unlike legacy
+> bootloaders, which typically interact with BIOS only enough to bring up the OS,
+> a UEFI application can implement sophisticated behavior with the help of UEFI.
+> In other words, an independent developer shouldn't be in a rush to leave
+> "UEFI-land".
For `JONASFORTH`, I have decided to run as a UEFI application, taking advantage
of UEFI's features, including its text I/O features and general graphical device
for x68-64 functions. See the linked article for a full description. Here is
the short version:
-* Integer or pointer arguments are given in RCX, RDX, R8 and R9.
-* Additional arguments are pushed onto the stack from right to left.
-* Integer or pointer values are returned in RAX.
-* An integer-sized struct is passed directly; non-integer-sized structs are passed as pointers.
-* The caller must allocate 32 bytes of "shadow space" on the stack immediately
+- Integer or pointer arguments are given in RCX, RDX, R8 and R9.
+- Additional arguments are pushed onto the stack from right to left.
+- Integer or pointer values are returned in RAX.
+- An integer-sized struct is passed directly; non-integer-sized structs are passed as pointers.
+- The caller must allocate 32 bytes of "shadow space" on the stack immediately
before calling the function, regardless of the number of parameters used, and
the caller is responsible for popping the stack afterwards.
-* The following registers are volatile (caller-saved): RAX, RCX, RDX, R8, R9, R10, R11
-* The following registers are nonvolatile (callee-saved): RBX, RBP, RDI, RSI, RSP, R12, R13, R14, R15
+- The following registers are volatile (caller-saved): RAX, RCX, RDX, R8, R9, R10, R11
+- The following registers are nonvolatile (callee-saved): RBX, RBP, RDI, RSI, RSP, R12, R13, R14, R15
When the application is loaded, RCX contains a firmware allocated `EFI_HANDLE`
for the UEFI image, RDX contains a `EFI_SYSTEM_TABLE*` pointer to the EFI system
**Sources:**
-* [UEFI applications in detail - OSDev Wiki](https://wiki.osdev.org/UEFI#UEFI_applications_in_detail)
-* [Microsoft x64 calling convention](https://en.wikipedia.org/wiki/X86_calling_conventions#Microsoft_x64_calling_convention)
-* [UEFI Specifications](https://uefi.org/specifications)
+- [UEFI applications in detail - OSDev Wiki](https://wiki.osdev.org/UEFI#UEFI_applications_in_detail)
+- [Microsoft x64 calling convention](https://en.wikipedia.org/wiki/X86_calling_conventions#Microsoft_x64_calling_convention)
+- [UEFI Specifications](https://uefi.org/specifications)
### UEFI with FASM
### UEFI documentation
-* [Latest specification as of March 2020 (PDF)](https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf)
+- [Latest specification as of March 2020 (PDF)](https://uefi.org/sites/default/files/resources/UEFI_Spec_2_8_A_Feb14.pdf)
Notable sections:
-* 2\. Overview (14)
-* 4\. EFI System Table (89)
-* 7\. Services - Boot Services (140)
-* 8\. Services - Runtime Services (228)
-* 12\. Protocols - Console Support (429)
-* 13\. Protocols - Media Access (493)
-* Appendix B - Console (2201)
-* Appendix D - Status Codes (2211)
+- 2\. Overview (14)
+- 4\. EFI System Table (89)
+- 7\. Services - Boot Services (140)
+- 8\. Services - Runtime Services (228)
+- 12\. Protocols - Console Support (429)
+- 13\. Protocols - Media Access (493)
+- Appendix B - Console (2201)
+- Appendix D - Status Codes (2211)
## Resources
-* [UEFI - OSDev Wiki](https://wiki.osdev.org/UEFI)
-* [Unified Extensible Firmware Interface (Wikipedia)](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface)
-* [UEFI Specifications](https://uefi.org/specifications)
+- [UEFI - OSDev Wiki](https://wiki.osdev.org/UEFI)
+- [Unified Extensible Firmware Interface (Wikipedia)](https://en.wikipedia.org/wiki/Unified_Extensible_Firmware_Interface)
+- [UEFI Specifications](https://uefi.org/specifications)
projects / rrq / jonasforth.git / blobdiff