1 # Overview 2 3 ## Hardware 4 5 Eris 2010 is homebrew 8-Bit computer in the style of the 6 microcomputers of the 1970/80s. It is build around the WDC 65C02 7 MPU. This is a slightly updated version of the legendary MOS 6502 used 8 for example in the Commodore VIC20 and the Apple I and ][. The other 9 main components are 32 KB RAM and 8 KB EEPROM. While the old home 10 computers from the 1970/80s came with a keyboard and connected to a TV 11 or monitor, this design provides a serial communication 12 interface. Therefore it is more similar to modern microcontrollers or 13 very early home computers like the Altair 8800 than to later computers 14 of the home computer era like the Commodore 64 or the Apple ][. The 15 serial interface is provided by a 6551 ACAI. This chip has been used 16 in computers from the era like the Commodore PET and the Commodore 17 Plus/4 to connect a modem. In the Eris 2010, the 6551 ACAI connects to 18 a (modern) USB2Serial adapter. This allows to use a standard laptop or 19 desktop computer as a terminal for the 8-bit machine. 20 21 The second auxiliary chip is a 6522 VIA. Among other things, this chip 22 provides a bunch of GPIO lines. A few of them are used to connect an 23 SD card reader, providing a mass storage device to Eris 2010. The 24 remaining lines are freely programmable I/O ports. SD cards are 25 written in a very simple, proprietary data format. When the computer 26 is powered, the "operating system" in EEPROM presents a list of the 27 programs on the SD card and acts as a bootloader. Alternatively, 28 programs can be uploaded via the serial interface. 29 30 The bus is orchestrated by an ATF16V8 EEPLD. While the first chips 31 with programmable logic were developed in the 1970/80s, most computers 32 of the era did not use programmable logic, but discrete logic 33 chips. Using an EEPLD allows to keep the chip count low, and I wanted 34 to play with programmable logic a bit. 35 36 Reset logic is based on the good old 555 chip. We find similar 37 circuits in home computers as well. 38 39 The first version of the computer was build on a breadboard. Once the 40 breadboard design was functionally complete and stable at 4 Mhz, the 41 design was fixed on a PCB in through-hole technology. In order to 42 allow connection of additional peripheral devices and extensions, two 43 interfaces were added: A user port to provide access to the free I/O 44 ports, and an expansion port exposing the buses and other internal 45 lines. The KiCad design files of the PCB are included in the 46 repository. 47 48 ## Software 49 50 Eris 2010 can be programmed in assembler and C. Directory `sw/` 51 contains the game of Tic-Tac-Toe (no fan of WarGames should go without 52 one), the famous 10 PRINT program (check out [this 53 book](https://10print.org/ "10 PRINT") on the cultural significance of 54 10 PRINT if you do not know it already), and some test programs. The 55 `contrib/` directory contains additional third party software ported 56 to Eris 2010. Besides Wozmon, Steve Wozniak's "operating system" for 57 the Apple I, this repository contains a port of Microchess, the first 58 commercial game for microcomputers, some other games, and a port of 59 Eliza. The contrib directory also contains a port of Tiny BASIC, so 60 you can even program the system in BASIC, just like in the old days. 61 62 All components of the system (except for the third party software in 63 `contrib/`) are free soft- and hardware. You can find all source code 64 in the repository linked at the top of this page. 65 66 ---------------------------------------------------------------- 67 68 # User Manual 69 70 So you are one of the lucky few who got a pre-assembled Eris 2010 71 computer including an SD card with some software! 72 73 ## Getting started 74 75 Insert the SD card that comes with your Eris 2010 into the SD card 76 reader. The standard way to communication with this 8 bit computer is 77 via the USB2Serial adapter. For this connect your Eris 2010 via a Mini 78 USB cable to your computer. On your desktop or laptop computer, you 79 need a terminal program. 80 81 ### Linux 82 83 Run a terminal program like tio. tio should be available in the 84 package store of your distribution. If not try minicom or picocom. The 85 interface is probably available as `/dev/ttyUSB0`. Connect to Eris 2010 86 by 87 88 `tio -b 19200 /dev/ttyUSB0` 89 90 Press a key or the reset button on Eris 2010. If this does not work, 91 try the command above with `/dev/ttyUSB1`, `/dev/ttyUSB2`, ... 92 93 ### Windows 94 95 When you connect Eris 2010 to your desktop or laptop computer, you 96 first have to install the device driver for the USB2Serial 97 connector. You can download it from [the 98 manufacturer](https://www.ftdichip.com/Drivers/CDM/CDM21228_Setup.zip). Now 99 connect Eris2010 to a USB port. Next, you have install a terminal 100 program. For Windows users, a common terminal program is 101 [PuTTY](https://www.putty.org/). After installation, there is a folder 102 PuTTY in your start menu. From this folder, choose PuTTY. 103 104 When putty starts, click the radio button "Serial". Set "Serial line" 105 to "COM3", and "Speed" to "19200". Click "Open". In the terminal 106 windows, type any character or push the reset button on Eris 2010. You 107 should now be connected to the computer. If this does not work, try 108 "COM1", "COM2", ... for "Serial Line". 109 110 The default font of PuTTY does not support the unicode characters ued 111 by the 10 PRINT program. I order to run this program, choose 112 "Window/Appearance" and change the font to e.g. @NSimSun. 113 114 ## Running programs 115 116 You should now see a choice of programs. Typing a number starts the 117 corresponding program. The more interesting programs are: 118 119 ### Tic-Tac-Toe 120 121 This should be self explanatory. 122 123 ### Microchess 124 125 Press 'c' to set up a new board. Enter moves by giving the field 126 numbers followed by enter, e.g. '6444'<Enter>. Push 'p' for the next 127 move of the computer. You can switch the board with 'e'. 'q' quits the 128 game. 129 130 Microchess is third party software. 131 132 ### TINY BASIC 133 134 All input must be in caps! 135 136 Tiny BASIC is third party software. 137 138 ## Abandoned Farmhouse 139 140 A small text adventure game. 141 142 ## Eliza 143 144 A version of Weizenbaum's famous ELIZA. This version diverges quite a 145 bit from Weizenbaum's original program, which was more advanced. 146 147 ## Mastermind 148 149 A version of Mastermind. There are some divergences from the original 150 rules: When you a number appears once in the code but the player 151 guesses it multiple times,"+" will be output for every wrong spot of 152 the number. 153 154 ## Wumpus 155 156 Hunt the Wumpus, a classical computer game: 157 <https://en.wikipedia.org/wiki/Hunt_the_Wumpus>. 158 159 ---------------------------------------------------------------- 160 161 # Developer Documentation 162 163 ## Repository Directory Structure 164 165 - `case/` - Minimal case consisting of top and bottom plates for laser cutting. 166 - `contrib/` - Third party software. See `contrib/README.md` for a description. 167 - `hw/` - Hardware description 168 - `tools/` - PC programs to upload programs and write SD card 169 - `roms/` - ROM images. See `roms/README.md` for a description. 170 - `sw/` - "Userland" software to be loaded into RAM by a suitable ROM. Eris2010 171 can be programmed in assembler and C. 172 173 ## Main Components 174 175 The computer is based on a 65C02 running at 4 Mhz with 32K RAM 176 (AS6C62256-70PCN) and 8 K EEPROM (AT28C64B-15PU). A W65C51N ACAI 177 provides a serial communication interface. A VIA 65C22 provides a GPIO 178 interface. Four of the lines connect an SD card reader via SPI. Bus 179 logic is provided by a ATF16V8B EEPLD. The reset logic is based on a 180 NE555 in a monostable configuration with a little help (an inverter on 181 the AFT16V8B). 182 183 The hardware design is rather straightforward; see 184 `hw/pcb/eris2010/eris210.sch` for schematics (this is a KiCad file). The 185 bus logic is documented in `hw/bus_logic/bus_logic.pld`. The only tricky 186 part was getting RAM access synced with the CPU clock. 187 188 ## Memory Map 189 190 Lowest 32K are RAM, highest 8K are ROM. Up to 4 I/O devices (ACAI or 191 VIA) can be accessed at addresses below the ROM. One ACAI and one VIA 192 are required to operate the computer, because they provide a serial 193 interface (ACIA) and an interface to the SD card reader (VIA). Two 194 more devices can be connected via the Extension Port. The third I/O 195 device is active when `io_select5` is high and `io_select4` low. The 196 fourth I/O device is active when `io_select5` is low and `io_select4` is 197 high. See `hw/bus_logic/BUS_LOGIC.PLD` for details. 198 199 |Area |Content |Location | 200 |--- |:----------:|--------------:| 201 |ROM | OS | $E000 - $FFFF | 202 | | | | 203 |IO | EXP2 | $D800 - $DFFF | 204 | | EXP1 | $D000 - $D7FF | 205 | | VIA | $C800 - $CFFF | 206 | | ACIA | $C000 - $C7FF | 207 | | | | 208 |RAM | IRQ Vector | $7FFE - $7FFF | 209 | | Heap | ... - $7FFD | 210 | | ... | ... | 211 | | Data Stack | ... | 212 | | Program | $0200 - ... | 213 | | HW Stack | $0100 - $01FF | 214 | | Zero Page | $0000 - $00FF | 215 216 The reset vector points to $E000, the begin of the ROM. Programs are 217 loaded to $0200. The IRQ handler jumps to the address stored in RAM at 218 $7FFE. For assembler programs, the data stack is located right after 219 the program code and grows up, as shown in the diagram above. For C 220 programs, the RAM layout is different. They use two stacks in addition 221 to the hardware stack: The assembler stack (used by assembler 222 functions in ROM) is located at the top of the RAM below the IRQ 223 vector ($7DFE - $7FFD), below it, the C stack occupies $6DFE - 224 $7DFD. Everything in between the program and the stacks is heap. 225 226 ## Reset logic 227 228 Resets can be triggered in two ways: A reset button is connected to an 229 NE555 in a monostable configuration. Alternatively, a reset can be 230 triggered by setting DTR of the serial interface to high. The latter 231 is used to automatically trigger a reset before program 232 upload. `tools/boot.py` uses this to trigger a reset and get Eris 2010 233 ready for program upload. The disadvantage of wiring DTR to rest is 234 that Eris 2010 only operates when a terminal is connected; when no 235 terminal is connected, it stays in reset mode. Therefore a hardware 236 switch allows to disconnect DTR from the reset line, allowing Eris 237 2010 to run even if no terminal is connected. In this configuration, 238 resets for program upload have to be triggered manually. See also 239 section Booting. 240 241 Another way to run Eris 2010 even if no terminal program is running on 242 your main computer is to configure your computer's serial interface 243 to keep DTR low at all times (Linux: `stty -F <serial interface> 244 -hup`). 245 246 Note that the reset line of the 65C02 is active on low. We use the 247 AFT16V8B - which mainly provides the bus logic - as an inverter. 248 249 ## Booting 250 251 The "standard" ROM is `roms/os/os.bin`. This ROM includes the standard 252 library (for serial communication, accessing SD card, RNG, ...). It 253 provides three methods to load a program: 254 255 ### Via serial line 256 257 After a reset, the ROM listens for a serial data transmission at 19200 258 BPS 8N1. If byte $ff is sent, the download sequence is initiated. The 259 next byte is the number of half-blocks of 256 bit to be loaded. (Block 260 size is 512 bit, because this is the block size of SD cards.) The 261 number of half-blocks is followed by the data. Data is stored at 262 $0200. Once the upload is completed, the upload program returns a 263 two-byte checksum. The first byte is the sum of all bytes transmitted 264 mod 256. The second byte is the xor of all bytes transmitted. The 265 upload program than starts executing the loaded program at $0200. 266 267 On the PC, use `tools/boot.py` for upload. 268 269 ### From SD Card 270 271 The boot ROM includes `sw/load_from_card/load_from_card.asm`, the 272 program to load programs from SD card. This program is executed when 273 no program is transmitted via serial line. 274 275 SD cards can store up to 10 programs. The filesystem format is as 276 follows: 277 278 Block $00000000 is loaded on initialization. The first two bytes 279 should be $E215. This indicates the filesystem type. The third byte 280 should be $00. This is the version of the file system. The fourth byte 281 is the number of the program to start automatically, or $ff. In case 282 of $ff, a menu of the programs on the card is presented for the user 283 to choose. 284 285 The storage space for the first program starts at $00000001. The 286 storage space for the second program starts at $00010001, for the 287 third program at $00020001, ... Thus, each program has a total of 288 $ffff blocks of 512 bytes each available. The first block of each 289 program is the program header. It contains the number of blocks to be 290 loaded, and the app name, a null-terminated string. The actual program 291 code starts with the next block. The program is loaded to address 292 $0200 and executed. 293 294 On the PC, use `tools/kfs.py` to write the SD card. 295 296 ## Interfaces 297 298 Two interface modules are part of the computer system: A serial 299 interface connected to a USB2Serial adapter provides character I/O and 300 program upload facilities. An SD card reader provides access to SD 301 cards with a rudimentary file system. The default operating system 302 allows to read and execute programs stored on an SD card. 303 304 In addition, a user port on the PCB provides access to all GPIO lines 305 not occupied by the SD card communication interface, and an expansion 306 port provides access to the buses and other internal lines. The 307 expansion port carries two select lines for additional peripheral 308 devices. See section Memory Map above. 309 310 ## Interrupts 311 312 The I/O interfaces are wired to IRQ. NMI can be triggered by pushing a 313 physical button. While user programs can write their own ISRs for 314 IRQs, the standard ROM fixes NMI servicing to an ISR that dumps the 315 RAM. 316 317 ## Toolchain 318 319 ### Hardware 320 321 You can find all files related to the hardware design in 322 `hw/pcb/eris2010`. The design uses [some additional library 323 symbols](https://github.com/Alarm-Siren/6502-kicad-library). These 324 additional symbols are copyright (c) 2018, Nicholas Parks Young and 325 licensed under the GNU LGPL v2.1. The hardware schematics and PCB 326 layout were designed in KiCad. FreeRouting (part of LayoutEditor) has 327 been used for routing. 328 329 An ATF16V8B-15PU EEPLD is used for the bus logic. It is programmed in 330 [GALasm](https://github.com/daveho/GALasm). 331 332 Both the EEPROM and the EEPLD can be burned with 333 [minipro](https://gitlab.com/DavidGriffith/minipro/). 334 335 ### Assembler 336 337 All core parts of Eris 2010 have written in assembler. They can be 338 translated with 64tass. The Makefiles generate binary code both for 339 Eris 2010 and Symon. [Symon](https://github.com/sethm/symon), a 6502 340 emulator written in Java, has been used for debugging. 341 342 ## Standard Library 343 344 A standard library is part of the boot ROM located at `roms/os/`. In 345 order to use it, import `roms/os/os.inc` into your program. 346 347 The standard library includes a data stack with subroutines and macros 348 for local variables and parameter passing. See `roms/os/os.asm` for 349 documentation and `sw/stack_test/stack_test.asm` for examples. 350 351 The following functionality is provided: 352 353 - Serial communication interface 354 All serial communication is conducted at 19200BPS with 8N1. Various 355 input and output functions are provided, including a function that 356 initializes the RNG (see LFSR) by counting ticks when waiting for user 357 input. 358 359 - ANSI Terminal 360 On top of the serial communication interface, the core ANSI escape 361 sequences are supported. 362 363 - LFSR 364 A 16 bit LFSR with maximum period length is provided as PRNG. 365 366 - SPI 367 SPI messages can be send via the VIA. 368 369 - SD Card 370 SD cards can accessed in SPI mode. All addresses are 32 bit, referring 371 to 512 bit blocks on the card. Note that this implementation does not 372 work with all cards. See section [bugs](#bugs) below. 373 374 - Data Stack 375 A data stack in software for local variables and parameter passing. In 376 difference to most stacks, the stack grows from bottom to top. The 377 recommended memory layout is program code, followed by heap (if 378 applicable), followed by stack. You have to manually create and delete 379 stack frames with calls to create_stack_frame and delete_stack_frame. 380 Pull and push operations do not push actual data on the stack, but 381 just move the stack pointer. Local variables on the stack are 382 represented by integers and accessed by `lda_LOCAL \<number\>`, 383 `sta_LOCAL \<number\>`, and similar macros. Parameters passed by 384 `sta_PARAM \<number\>` can be accessed by the callee by `lda_LOCAL 385 \<number\>`. Macro `CALL` may be used to call a subroutine with 386 parameters. Refer to `sw/stack_test/stack_test.bin` and 387 `sw/load_from_card/load_from_card.asm` for examples. 388 389 ### C 390 391 You can program Eris 2010 in C using the CC65 C compiler, available at 392 <https://cc65.github.io/>. Suitable configuration and Makefiles, as 393 well as ports of the conio and dio libraries, are located in directory 394 `sw/c/cc65_eris`. You have to run `make` once in this directory in 395 order to generate `eris2010.lib`. After that, you can compile the 396 programs in the other subdirectories. The programs here are simple 397 test programs. Check out `contrib/c/` for ports of (more or less) 398 useful programs. 399 400 #### The conio Library 401 402 The conio library for console input/output has been ported to use the 403 serial connection. Since the serial connection is the main I/O 404 connection of Eris 2010, conio and not the serial library is used to 405 access it. Some functions of conio have not been ported because the 406 functionality is not available via a serial line with ANSI encoding: 407 408 - bgcolor 409 - bordercolor 410 - cpeekc 411 - cpeekcolor 412 - cpeekrevers 413 - cpeeks 414 415 #### The dio Library 416 417 The dio library provides low level file system access. dio uses 16 bit 418 sector numbers. Since SD cards use 32 bit sector numbers, we use a 419 hack to be able to access all sectors of the SD card while maintaining 420 compatibility to the dio library: The upper 16 bits of the sector 421 number are encoded as the device handle. 422 423 In order to access the SD card, you have to call `dio_open` 424 once. Neither the `device` number you pass into this function nor the 425 handle returned matter. `dio_write` and `dio_read` treat `handle` as 426 an unsigned int indicating the upper 16 bits of the sector 427 number. (`dio_write_verify` is not implemented.) 428 429 Due to our file system structure, this `handle` is identical to the 430 application number of the application whose data you are 431 accessing. The application number is a (the) parameter of `main`. Use 432 it to make sure that your program only writes to its own storage space. 433 434 ## Tools 435 436 ### kfs.py 437 438 Program for formatting, listing, and writing SD card in a format 439 readable by Eris 2010. 440 441 ### boot.py 442 443 Script to upload programs via serial line. 444 445 ### reset.py 446 447 Triggers a reset by toggling DTR. 448 449 ## Case 450 451 The main purpose of the case is to expose the main board. :-) 452 Therefore it just consists of a top and bottom acrylic plates, 453 separated by spacer bolts. Laser cutter cutout files are located in 454 directory `case/` 455 456 ## Bugs 457 458 The communication protocol for SD cards is rather complex. The 459 implementation for Eris 2010 worked with 5 out of 6 cards tested. If 460 it does not work with your card, try a different card (or fix the 461 protocol implementation). :-) 462 463 ## Changelog 464 465 - v1.1 466 Support for C programming language. 467 - v1.0 468 First public version. 469 470 ## Copyright and License 471 472 The software in directory `contrib/` comes from third parties. Check the 473 subdirectories of `contrib/` for author, copyright, and licensing 474 information. 475 476 Everything else: 477 478 Copyright © 2021 Gerd Beuster <firstname.lastname@example.org> 479 480 This project is free soft- and hardware: you can redistribute it 481 and/or modify it under the terms of the GNU General Public License as 482 published by the Free Software Foundation, either version 3 of the 483 License, or (at your option) any later version. 484 485 This project is distributed in the hope that it will be useful, but 486 WITHOUT ANY WARRANTY; without even the implied warranty of 487 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 488 General Public License for more details. 489 490 You should have received a copy of the GNU General Public License 491 along with this project. If not, see <http://www.gnu.org/licenses/>.