Split parts in two: z80 and avr

Also, clarify the role of recipes.

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

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
+Collapse OS is built around the z80, but it doesn't mean that your machine can't
-yourself.
+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],
+Obviously, different architectures can't be assembled together in the same
-but this is going to change in the future as a new hosted assembler is written.
+binary, but they can nevertheless be made to work well together.
-
-## 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 `<PARTNAME>_RAMSTART`
-constant to be defined and, in turn, defines a `<PARTNAME>_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

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.

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 `<PARTNAME>_RAMSTART`
+constant to be defined and, in turn, defines a `<PARTNAME>_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

recipes/.gitignore

@@ -0,0 +1 @@
+*.bin

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
+and post-collapse recipe. That is, instructions to achieve the desired outcome
-OS from a "modern" system, and then, instructions to build and install Collapse
+from a "modern" system, and then, instructions to achieve the same thing from a
-OS from a system running Collapse OS.
+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

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) $<

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 STDIO_GETC	call aciaGetC
-.define SHELL_GETC	call aciaGetC
+.define STDIO_PUTC	call aciaPutC
-.define SHELL_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"