Let's get the ball rolling!

LICENSE

@@ -0,0 +1,19 @@
+Copyright 2019 Virgil Dupras
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -97,42 +97,47 @@ and prove useless to many post-collapse communities.
 But nevertheless, this idea seems too powerful to not try it. And even if it
 proves futile, it sounds like a lot of fun to try.
 
+## Organisation of this repository
+
+There's very little done so far, but here's how it's organized:
+
+* `parts`: Pieces of code to be assembled by the user into an OS.
+* `recipes`: collection of recipes that assemble parts together on a specific
+             machine.
+
+Each folder has a README with more details.
+
 ## Roadmap
 
 I'm still fiddling with things, honing my skills and knowledge, so the
 project's roadmap is still hazy.
 
-Initially, I wanted to start the implementation in AVR because that's the only
+The primary target for Collapse OS is the z80 architecture. There's a good
-MCU I know and because I like it, but AVR's architecture doesn't fit well with
+amount of great z80-related hacks all around the internet, and the z80 CPU is
-the idea of an OS. Very limited RAM and no reasonable way of running programs
+very scavenge-friendly: it's been (and is) included in tons of devices.
-from RAM.
-
-I've been looking at z80 and it's very interesting. There's a good amount of
-great z80-related hacks all around the internet, and the z80 CPU is very
-scavenge-friendly: it's been (and is) included in tons of devices.
-
-[KnightOS][knightos] is a very good starting point. Of course, it can't be
-directly used in the context of Collapse OS because it's an OS for a specific
-set of machines rather than improvised designs, but there are many interesting
-bits and pieces of assembly in there that can be used.
-
-The first question that needs answering is: how feasible is it to write a
-self-assembling z80 assembler that runs on 56K of RAM and compiles an OS? Once
-that question is answered positively, then the project becomes much more solid.
 
 After a good proof of concept is done in z80, then more architectures can be
 added into the mix. I have the intuition that we can mix AVR and z80 in a very
 elegant minimal and powerful machine and it would be great if a Collapse OS
 spawn could be built for such machine.
 
-Of course, there are so many PIC chips around that the project would be much
+I'm planning to go forward with this project by doing three things:
-more useful with a way to program some of them, so there's also that to do.
 
-Then comes the thinking about how to anticipate the need for ad-hoc terminals
+1. Gather knowledge and hone skills.
-and storage devices. Modern computer screens are rather fragile and will be
+2. Build useful parts of code to be assembled into an OS by the user.
-hard to repair. Post-collapse engineers will need to hack their way around
+3. Write "recipes", examples of assembly on real machines using parts I wrote
-scavenged display devices. What kind of tools will they need? Same question for
+   to serve as a guide for post-collapse assembly.
-storage.
+
+Recipes should contain both "pre-collapse" instructions (how to build Collapse
+OS from a "modern" system) and "post-collapse" instructions (how to build
+Collapse OS from itself).
+
+Initially, we of course only have "pre-collapse" instructions, but as tooling
+improve, the "post-collapse" part will become more and more complete. When we
+have complete "post-collapse" recipes, we can call it a win.
+
+If you're interested in being part of this project, I have no idea how to
+include you, but please, let me know, we'll manage something.
 
 ## 32-bit? 16-bit?
 
@@ -151,6 +156,25 @@ programming an ARM or RISC-V chip.
 
 That being said, the MSP430 seems like a really nice and widely used chip...
 
+## Prior art
+
+I've spent some time doing software archeology and see if something that was
+already made could be used. There are some really nice and well-made programs
+out there, such as CP/M, but as far as I know (please, let me know if I'm wrong,
+I don't know this world very well), these old OS weren't made to be
+self-replicating. CP/M is now open source, but I don't think we can recompile
+CP/M from CP/M.
+
+Then comes the idea of piggy-backing from an existing BASIC interpreter and
+make a shell out of it. Interesting idea, and using Grant Searle's modified
+nascom basic would be a good starting point, but I see two problems with this.
+First, the interpreter is already 8k. That's a lot. Second, it's
+copyright-ladden (by Searle *and* Microsoft) and can't be licensed as open
+source.
+
+Nah, maybe I'm working needlessly, but I'll start from scratch. But if someone
+has a hint about useful prior art, please let me know.
+
 ## Risking ridicule
 
 Why publish this hazy roadmap now and risk ridicule? Because I'm confident
@@ -164,4 +188,3 @@ sound more or less crazy to you than what you've been reading in this text so
 far?), I will probably need help to pull this off.
 
 [searle]: http://searle.hostei.com/grant/z80/SimpleZ80.html
-[knightos]: https://knightos.org/

parts/README.md

@@ -0,0 +1,8 @@
+# Parts
+
+Bits and pieces of code that you can assemble to build an OS for your machine.
+
+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.
+
+[scas]: https://github.com/KnightOS/scas

parts/shell/shell.asm

@@ -0,0 +1,65 @@
+; shell
+;
+; Runs a shell over an asynchronous communication interface adapter (ACIA).
+
+; *** STATUS ***
+; Incomplete. This just outputs the welcome prompt then halts
+
+; *** PLATFORM ***
+; this is specific to a classic RC2014 setup (8K ROM + 32K RAM). This will be
+; reorganized into something better.
+
+RAMEND		.equ	0xa000
+ACIA_CTL	.equ	0x80	; Control and status. RS off.
+ACIA_IO		.equ	0x81	; Transmit. RS on.
+
+; *** CONSTS ***
+CR	.equ	0x0d
+LF	.equ	0x0a
+
+; *** CODE ***
+	jr	init
+
+init:
+	di			; no need for interrupts yet
+
+	; setup stack
+	ld	hl, RAMEND
+	ld	sp, hl
+
+	; setup ACIA
+	; CR7 (1) - Receive Interrupt enabled
+	; CR6:5 (00) - RTS low, transmit interrupt disabled.
+	; CR4:2 (101) - 8 bits + 1 stop bit
+	; CR1:0 (10) - Counter divide: 64
+	ld	a, 0b10010110
+	out	(ACIA_CTL), a
+
+	; print prompt
+	ld	hl, d_welcome
+	call	printstr
+	halt
+
+; spits character in A in port SER_OUT
+printc:
+	push	af
+.stwait:
+	in	a, (ACIA_CTL)	; get status byte from SER
+	bit	1, a		; are we still transmitting?
+	jr	z, .stwait	; if yes, wait until we aren't
+	pop	af
+	out	(ACIA_IO), a	; push current char
+	ret
+
+; print null-terminated string pointed to by HL
+printstr:
+	ld	a, (hl)		; load character to send
+	or	a		; is it zero?
+	ret	z		; if yes, we're finished
+	call	printc
+	inc	hl
+	jr	printstr
+	; no ret because our only way out is ret z above
+
+; *** DATA ***
+d_welcome:	.byte	"Welcome to Collapse OS", CR, LF, 0

recipes/README.md

@@ -0,0 +1,24 @@
+# Recipes
+
+Because Collapse OS is a meta OS that you assemble yourself on an improvised
+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.
+
+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
+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.
+
+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.
+
+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
+complete.

recipes/rc2014.md

@@ -0,0 +1,74 @@
+# RC2014
+
+The [RC2014][rc2014] is a nice and minimal z80 system that has the advantage
+of being available in an assembly kit. Assembling it yourself involves quite a
+bit of soldering due to the bus system. However, one very nice upside of that
+bus system is that each component is isolated and simple.
+
+The machine used in this recipe is the "Classic" RC2014 with an 8k ROM module
+, 32k of RAM, a 7.3728Mhz clock and a serial I/O.
+
+The ROM module being supplied in the assembly kit is an EPROM, not EEPROM, so
+you can't install Collapse OS on it. You'll have to supply your own.
+
+There are many options around to boot arbitrary sources. What was used in this
+recipe was a AT28C64B EEPROM module. I chose it because it's compatible with
+the 8k ROM module which is very convenient. If you do the same, however, don't
+forget to set the A14 jumper to high because what is the A14 pin on the AT27
+ROM module is the WE pin on the AT28! Setting the jumper high will keep is
+disabled.
+
+## Goal
+
+Have the shell running and accessible through the Serial I/O.
+
+## Pre-collapse
+
+You'll need specialized tools to write data to the AT28 EEPROM. There seems to
+be many devices around made to write in flash and EEPROM modules, but being in
+a "understand everything" mindset, I [built my own][romwrite]. This is the
+device I use in this recipe.
+
+### Gathering parts
+
+* `shell.asm` from `parts`
+* [scas][scas]
+* [romwrite][romwrite] and its specified dependencies
+* [GNU screen][screen]
+* A FTDI-to-TTL cable to connect to the Serial I/O module of the RC2014
+
+### Build the image
+
+We only have the shell to build, so it's rather straightforward:
+
+    scas -o rom.bin shell.asm
+
+### Write to the ROM
+
+Plug your romwrite atmega328 to your computer and identify the tty bound to it.
+In my case (arduino uno), it's `/dev/ttyACM0`. Then:
+
+    screen /dev/ttyACM0 9600
+    CTRL-A + ":quit"
+    cat rom.bin | pv -L 10 > /dev/ttyACM0
+
+See romwrite's README for details about these commands.
+
+### Running
+
+Put the AT28 in the ROM module, don't forget to set the A14 jumper high, then
+power the thing up. Connect the FTDI-to-TTL cable to the Serial I/O module and
+identify the tty bound to it (in my case, `/dev/ttyUSB0`). Then:
+
+    screen /dev/ttyUSB0 115200
+
+Press the reset button on the RC2014 and you should see the Collapse OS prompt!
+
+## Post-collapse
+
+TODO
+
+[rc2014]: https://rc2014.co.uk
+[romwrite]: https://github.com/hsoft/romwrite
+[scas]: https://github.com/KnightOS/scas
+[screen]: https://www.gnu.org/software/screen/