From 055e0d7a31f5dc06a745f0790adb5fe63d5ec866 Mon Sep 17 00:00:00 2001 From: Virgil Dupras Date: Thu, 25 Apr 2019 16:03:45 -0400 Subject: [PATCH] Split parts in two: z80 and avr Also, clarify the role of recipes. --- README.md | 2 +- parts/README.md | 56 ++++--------------------------- parts/avr/README.md | 15 +++++++++ parts/z80/README.md | 53 +++++++++++++++++++++++++++++ parts/{ => z80}/acia.asm | 0 parts/{ => z80}/blockdev.asm | 0 parts/{ => z80}/blockdev_cmds.asm | 0 parts/{ => z80}/core.asm | 0 parts/{ => z80}/fs.asm | 0 parts/{ => z80}/mmap.asm | 0 parts/{ => z80}/shell.asm | 0 parts/{ => z80}/stdio.asm | 0 recipes/.gitignore | 1 + recipes/README.md | 21 +++++++++--- recipes/rc2014/Makefile | 7 ++++ recipes/rc2014/glue.asm | 9 +++-- 16 files changed, 107 insertions(+), 57 deletions(-) create mode 100644 parts/avr/README.md create mode 100644 parts/z80/README.md rename parts/{ => z80}/acia.asm (100%) rename parts/{ => z80}/blockdev.asm (100%) rename parts/{ => z80}/blockdev_cmds.asm (100%) rename parts/{ => z80}/core.asm (100%) rename parts/{ => z80}/fs.asm (100%) rename parts/{ => z80}/mmap.asm (100%) rename parts/{ => z80}/shell.asm (100%) rename parts/{ => z80}/stdio.asm (100%) create mode 100644 recipes/.gitignore create mode 100644 recipes/rc2014/Makefile diff --git a/README.md b/README.md index d482032..bc36d1b 100644 --- a/README.md +++ b/README.md @@ -85,7 +85,7 @@ to see what it can do) on a classic RC2014. Highlights: * Extremely flexible: this is not an OS, but a meta OS. You build your own OS through glue code. -* 1K binary (but size vary wildly depending on what parts you include. 1K is for +* 2K binary (but size vary wildly depending on what parts you include. 2K is for a shell using all parts) * Built with minimal tooling: only [scas][scas] is needed * Can read and write to memory through shell diff --git a/parts/README.md b/parts/README.md index c91b903..9e5afe2 100644 --- a/parts/README.md +++ b/parts/README.md @@ -1,53 +1,11 @@ # Parts -Bits and pieces of code that you can assemble to build an OS for your machine. +Pieces of code that you can assemble together to make your machine work as you +want them to work. -These parts are made to be glued together in a single `main.asm` file you write -yourself. +Collapse OS is built around the z80, but it doesn't mean that your machine can't +mix and match microcontrollers. This is why this folder is subdivided by +architectures. -As of now, the z80 assembler code is written to be assembled with [scas][scas], -but this is going to change in the future as a new hosted assembler is written. - -## Defines - -Each part can have its own constants, but some constant are made to be defined -externally. We already have some of those external definitions in platform -includes, but we can have more defines than this. - -Each part has a "DEFINES" section listing the constant it expects to be defined. -Make sure that you have these constants defined before you include the file. - -## Variable management - -Each part can define variables. These variables are defined as addresses in -RAM. We know where RAM start from the `RAMSTART` constant in platform includes, -but because those parts are made to be glued together in no pre-defined order, -we need a system to align variables from different modules in RAM. - -This is why each part that has variable expect a `_RAMSTART` -constant to be defined and, in turn, defines a `_RAMEND` constant to -carry to the following part. - -Thus, code that glue parts together coould look like: - - MOD1_RAMSTART .equ RAMSTART - #include "mod1.asm" - MOD2_RAMSTART .equ MOD1_RAMEND - #include "mod2.asm" - -## Code style - -The asm code used in these parts is heavily dependent on what scas offers. I -try to be as "low-tech" as possible because the implementation of the assembler -to be implemented for the z80 will likely be more limited. For example, I try -to avoid macros. - -One exception, however, is for the routine hooks (`SHELL_GETC` for example). At -first, I wanted to assign a label to a const (`SHELL_GETC .equ aciaGetC` for -example), but it turns out that scas doesn't support this (but it could: label -addresses are known at compile time and thus can be consts (maybe at the cost -of an extra pass though)). I went for macros instead, but that doesn't mean -that the z80 assembler will need to support macros. It just need to support -labels-as-consts. - -[scas]: https://github.com/KnightOS/scas +Obviously, different architectures can't be assembled together in the same +binary, but they can nevertheless be made to work well together. diff --git a/parts/avr/README.md b/parts/avr/README.md new file mode 100644 index 0000000..b49c02e --- /dev/null +++ b/parts/avr/README.md @@ -0,0 +1,15 @@ +# AVR parts + +The idea with the AVR parts is that you will design peripherals plugged into +your z80 that are controlled by AVR microcontrollers. + +AVR is a large family and although they all work more-or-less the same, +assembler code for one model can't be directly used on another model. Despite +this, parts are only written once. If the model you have on hand doesn't match, +you'll have to translate yourself. + +There are also tons of possible variants to some of those parts. You could want +to implement a feature with a certain set of supporting ICs that aren't the +same as implemented in the part. We can't possibly cover all combinations. We +won't. We'll try to have a good variety of problems we solve so that you have +good material for mix-and-matching your own solution. diff --git a/parts/z80/README.md b/parts/z80/README.md new file mode 100644 index 0000000..7d8fcd6 --- /dev/null +++ b/parts/z80/README.md @@ -0,0 +1,53 @@ +# Z80 Parts + +Bits and pieces of code that you can assemble to build an OS for your machine. + +These parts are made to be glued together in a single `main.asm` file you write +yourself. + +As of now, the z80 assembler code is written to be assembled with [scas][scas], +but this is going to change in the future as a new hosted assembler is written. + +## Defines + +Each part can have its own constants, but some constant are made to be defined +externally. We already have some of those external definitions in platform +includes, but we can have more defines than this. + +Each part has a "DEFINES" section listing the constant it expects to be defined. +Make sure that you have these constants defined before you include the file. + +## Variable management + +Each part can define variables. These variables are defined as addresses in +RAM. We know where RAM start from the `RAMSTART` constant in platform includes, +but because those parts are made to be glued together in no pre-defined order, +we need a system to align variables from different modules in RAM. + +This is why each part that has variable expect a `_RAMSTART` +constant to be defined and, in turn, defines a `_RAMEND` constant to +carry to the following part. + +Thus, code that glue parts together coould look like: + + MOD1_RAMSTART .equ RAMSTART + #include "mod1.asm" + MOD2_RAMSTART .equ MOD1_RAMEND + #include "mod2.asm" + +## Code style + +The asm code used in these parts is heavily dependent on what scas offers. I +try to be as "low-tech" as possible because the implementation of the assembler +to be implemented for the z80 will likely be more limited. For example, I try +to avoid macros. + +One exception, however, is for the routine hooks (`SHELL_GETC` for example). At +first, I wanted to assign a label to a const (`SHELL_GETC .equ aciaGetC` for +example), but it turns out that scas doesn't support this (but it could: label +addresses are known at compile time and thus can be consts (maybe at the cost +of an extra pass though)). I went for macros instead, but that doesn't mean +that the z80 assembler will need to support macros. It just need to support +labels-as-consts. + +[scas]: https://github.com/KnightOS/scas diff --git a/parts/acia.asm b/parts/z80/acia.asm similarity index 100% rename from parts/acia.asm rename to parts/z80/acia.asm diff --git a/parts/blockdev.asm b/parts/z80/blockdev.asm similarity index 100% rename from parts/blockdev.asm rename to parts/z80/blockdev.asm diff --git a/parts/blockdev_cmds.asm b/parts/z80/blockdev_cmds.asm similarity index 100% rename from parts/blockdev_cmds.asm rename to parts/z80/blockdev_cmds.asm diff --git a/parts/core.asm b/parts/z80/core.asm similarity index 100% rename from parts/core.asm rename to parts/z80/core.asm diff --git a/parts/fs.asm b/parts/z80/fs.asm similarity index 100% rename from parts/fs.asm rename to parts/z80/fs.asm diff --git a/parts/mmap.asm b/parts/z80/mmap.asm similarity index 100% rename from parts/mmap.asm rename to parts/z80/mmap.asm diff --git a/parts/shell.asm b/parts/z80/shell.asm similarity index 100% rename from parts/shell.asm rename to parts/z80/shell.asm diff --git a/parts/stdio.asm b/parts/z80/stdio.asm similarity index 100% rename from parts/stdio.asm rename to parts/z80/stdio.asm diff --git a/recipes/.gitignore b/recipes/.gitignore new file mode 100644 index 0000000..a8a0dce --- /dev/null +++ b/recipes/.gitignore @@ -0,0 +1 @@ +*.bin diff --git a/recipes/README.md b/recipes/README.md index 1ead8ed..5a995db 100644 --- a/recipes/README.md +++ b/recipes/README.md @@ -5,7 +5,7 @@ machine of your own design, there can't really be a build script. Not a reliable one anyways. Because the design of post-collapse machines is hard to predict, it's hard to -write a definitive assembly guide. +write a definitive guide to it. The approach we're taking here is a list of recipes: Walkthrough guides for machines that were built and tried pre-collapse. With a wide enough variety of @@ -14,10 +14,23 @@ recipes, I hope that it will be enough to cover most post-collapse cases. That's what this folder contains: a list of recipes that uses parts supplied by Collapse OS to run on some machines people tried. +In other words, parts often implement logic for hardware that isn't available +off the shelf, but they implement a logic that you are likely to need post +collapse. These parts, however *have* been tried on real material and they all +have a recipe describing how to build the hardware that parts have been written +for. + +## Structure + +Each top folder represent an architecture. In that top folder, there's a +`README.md` file presenting the architecture as well as instructions to +minimally get Collapse OS running on it. Then, in the same folder, there are +auxiliary recipes for nice stuff built around that architecture. + The structure of those recipes follow a regular pattern: pre-collapse recipe -and post-collapse recipe. That is, instructions to build and install Collapse -OS from a "modern" system, and then, instructions to build and install Collapse -OS from a system running Collapse OS. +and post-collapse recipe. That is, instructions to achieve the desired outcome +from a "modern" system, and then, instructions to achieve the same thing from a +system running Collapse OS. Initially, those recipes will only be possible in a "modern" system, but as tooling improve, we should be able to have recipes that we can consider diff --git a/recipes/rc2014/Makefile b/recipes/rc2014/Makefile new file mode 100644 index 0000000..5c3ff71 --- /dev/null +++ b/recipes/rc2014/Makefile @@ -0,0 +1,7 @@ +TARGET = os.bin +PARTS = ../../parts/z80 + +.PHONY: all +all: $(TARGET) +$(TARGET): glue.asm + scas -o $@ -L map -I $(PARTS) $< diff --git a/recipes/rc2014/glue.asm b/recipes/rc2014/glue.asm index a9b4a67..d1850f3 100644 --- a/recipes/rc2014/glue.asm +++ b/recipes/rc2014/glue.asm @@ -25,9 +25,12 @@ init: #include "core.asm" ACIA_RAMSTART .equ RAMSTART #include "acia.asm" -SHELL_RAMSTART .equ ACIA_RAMEND -.define SHELL_GETC call aciaGetC -.define SHELL_PUTC call aciaPutC +.define STDIO_GETC call aciaGetC +.define STDIO_PUTC call aciaPutC +STDIO_RAMSTART .equ ACIA_RAMEND +#include "stdio.asm" +SHELL_RAMSTART .equ STDIO_RAMEND .define SHELL_IO_GETC call aciaGetC +.define SHELL_IO_PUTC call aciaPutC SHELL_EXTRA_CMD_COUNT .equ 0 #include "shell.asm"