diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..812c4c7 --- /dev/null +++ b/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. diff --git a/README.md b/README.md index 9c6ed74..2746a63 100644 --- a/README.md +++ b/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 -MCU I know and because I like it, but AVR's architecture doesn't fit well with -the idea of an OS. Very limited RAM and no reasonable way of running programs -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. +The primary target for Collapse OS is the z80 architecture. 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. 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 -more useful with a way to program some of them, so there's also that to do. +I'm planning to go forward with this project by doing three things: -Then comes the thinking about how to anticipate the need for ad-hoc terminals -and storage devices. Modern computer screens are rather fragile and will be -hard to repair. Post-collapse engineers will need to hack their way around -scavenged display devices. What kind of tools will they need? Same question for -storage. +1. Gather knowledge and hone skills. +2. Build useful parts of code to be assembled into an OS by the user. +3. Write "recipes", examples of assembly on real machines using parts I wrote + to serve as a guide for post-collapse assembly. + +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/ diff --git a/parts/README.md b/parts/README.md new file mode 100644 index 0000000..ea2087f --- /dev/null +++ b/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 diff --git a/parts/shell/shell.asm b/parts/shell/shell.asm new file mode 100644 index 0000000..97eb0a7 --- /dev/null +++ b/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 diff --git a/recipes/README.md b/recipes/README.md new file mode 100644 index 0000000..1ead8ed --- /dev/null +++ b/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. diff --git a/recipes/rc2014.md b/recipes/rc2014.md new file mode 100644 index 0000000..e1edf1c --- /dev/null +++ b/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/