eris2010

README.md (21509B)

---

 # Overview
 
 ## Hardware
 
 Eris 2010 is homebrew 8-Bit computer in the style of the
 microcomputers of the 1970/80s. It is build around the WDC 65C02
 MPU. This is a slightly updated version of the legendary MOS 6502 used
 for example in the Commodore VIC20 and the Apple I and ][. The other
 main components are 32 KB RAM and 8 KB EEPROM. While the old home
 computers from the 1970/80s came with a keyboard and connected to a TV
 or monitor, this design provides a serial communication
 interface. Therefore it is more similar to modern microcontrollers or
 very early home computers like the Altair 8800 than to later computers
 of the home computer era like the Commodore 64 or the Apple ][. The
 serial interface is provided by a 6551 ACAI. This chip has been used
 in computers from the era like the Commodore PET and the Commodore
 Plus/4 to connect a modem. In the Eris 2010, the 6551 ACAI connects to
 a (modern) USB2Serial adapter. This allows to use a standard laptop or
 desktop computer as a terminal for the 8-bit machine.
 
 The second auxiliary chip is a 6522 VIA. Among other things, this chip
 provides a bunch of GPIO lines. A few of them are used to connect an
 SD card reader, providing a mass storage device to Eris 2010. The
 remaining lines are freely programmable I/O ports. SD cards are
 written in a very simple, proprietary data format. When the computer
 is powered, the "operating system" in EEPROM presents a list of the
 programs on the SD card and acts as a bootloader. Alternatively,
 programs can be uploaded via the serial interface.
 
 The bus is orchestrated by an ATF16V8 EEPLD. While the first chips
 with programmable logic were developed in the 1970/80s, most computers
 of the era did not use programmable logic, but discrete logic
 chips. Using an EEPLD allows to keep the chip count low, and I wanted
 to play with programmable logic a bit.
 
 Reset logic is based on the good old 555 chip. We find similar
 circuits in home computers as well.
 
 The first version of the computer was build on a breadboard. Once the
 breadboard design was functionally complete and stable at 4 Mhz, the
 design was fixed on a PCB in through-hole technology. In order to
 allow connection of additional peripheral devices and extensions, two
 interfaces were added: A user port to provide access to the free I/O
 ports, and an expansion port exposing the buses and other internal
 lines. The KiCad design files of the PCB are included in the
 repository.
 
 ## Software
 
 Eris 2010 can be programmed in assembler, C, and Forth. Directory
 `sw/` contains the games Snake and Tic-Tac-Toe (no fan of WarGames
 should go without one), the famous 10 PRINT program (check out [this
 book](https://10print.org/ "10 PRINT") on the cultural significance of
 10 PRINT if you do not know it already), and some test programs. The
 `contrib/` directory contains additional third party software ported
 to Eris 2010. Most notably, it contains a port of Tali Forth 2, a
 very capable Forth system for 65C02 MPUs. Other software includes
 Wozmon, Steve Wozniak's "operating system" for the Apple I,
 Microchess, the first commercial game for microcomputers, some other
 games, and a port of Eliza. The contrib directory also contains a port
 of Tiny BASIC, so you can even program the system in BASIC, just like
 in the old days.
 
 All components of the system (except for the third party software in
 `contrib/`) are free soft- and hardware. You can find all source code
 in the repository linked at the top of this page.
 
 ----------------------------------------------------------------
 
 # User Manual
 
 So you are one of the lucky few who got a pre-assembled Eris 2010
 computer including an SD card with some software!
 
 ## Getting started
 
 Insert the SD card that comes with your Eris 2010 into the SD card
 reader. The standard way to communication with this 8 bit computer is
 via the USB2Serial adapter. For this connect your Eris 2010 via a Mini
 USB cable to your computer. On your desktop or laptop computer, you
 need a terminal program.
 
 ### Linux
 
 Run a terminal program like `tio`. `tio` should be available in the
 package store of your distribution. If not try `minicom` or
 `picocom`. The interface is probably available as `/dev/ttyUSB0`. Make
 sure your user account has access rights to this device! Connect to
 Eris 2010 by
 
 `tio -b 19200 /dev/ttyUSB0`
 
 Press a key or the reset button on Eris 2010. If this does not work,
 try the command above with `/dev/ttyUSB1`, `/dev/ttyUSB2`, ...
 
 ### Windows
 
 When you connect Eris 2010 to your desktop or laptop computer, you
 first have to install the device driver for the USB2Serial
 connector. You can download it from [the
 manufacturer](https://www.ftdichip.com/Drivers/CDM/CDM21228_Setup.zip). Now
 connect Eris2010 to a USB port. Next, you have install a terminal
 program. For Windows users, a common terminal program is
 [PuTTY](https://www.putty.org/). After installation, there is a folder
 PuTTY in your start menu. From this folder, choose PuTTY.
 
 When putty starts, click the radio button "Serial". Set "Serial line"
 to "COM3", and "Speed" to "19200". Click "Open". In the terminal
 windows, type any character or push the reset button on Eris 2010. You
 should now be connected to the computer. If this does not work, try
 "COM1", "COM2", ... for "Serial Line".
 
 The default font of PuTTY does not support the Unicode characters used
 by the 10 PRINT program. I order to run this program, choose
 "Window/Appearance" and change the font to e.g. @NSimSun.
 
 ## Running programs
 
 You should now see a choice of programs. Typing a number starts the
 corresponding program. The more interesting programs are:
 
 ### Tic-Tac-Toe
 
 This should be self explanatory.
 
 ### Microchess
 
 Press 'c' to set up a new board. Enter moves by giving the field
 numbers followed by enter, e.g. '6444'<Enter>. Push 'p' for the next
 move of the computer. You can switch the board with 'e'. 'q' quits the
 game.
 
 Microchess is third party software.
 
 ### TINY BASIC
 
 All input must be in caps!
 
 Tiny BASIC is third party software.
 
 ## Abandoned Farmhouse
 
 A small text adventure game.
 
 ## Eliza
 
 A version of Weizenbaum's famous ELIZA. This version diverges quite a
 bit from Weizenbaum's original program, which was more advanced.
 
 ## Mastermind
 
 A version of Mastermind. There are some divergences from the original
 rules: When you a number appears once in the code but the player
 guesses it multiple times,"+" will be output for every wrong spot of
 the number.
 
 ## Wumpus
 
 Hunt the Wumpus, a classical computer game:
 <https://en.wikipedia.org/wiki/Hunt_the_Wumpus>.
 
 ----------------------------------------------------------------
 
 # Developer Documentation
 
 ## Repository Directory Structure
 
 - `case/` - Minimal case consisting of top and bottom plates for laser cutting.
 - `contrib/` - Third party software. See `contrib/README.md` for a description.
 - `hw/` - Hardware description
 - `tools/` - PC programs to upload programs and write SD card
 - `roms/` - ROM images. See `roms/README.md` for a description.
 - `sw/` - "Userland" software to be loaded into RAM by a suitable ROM. Eris2010
           can be programmed in assembler and C.
 
 ## Main Components
 
 The computer is based on a 65C02 running at 4 Mhz with 32K RAM
 (AS6C62256-70PCN) and 8 K EEPROM (AT28C64B-15PU). A W65C51N ACAI
 provides a serial communication interface. A VIA 65C22 provides a GPIO
 interface. Four of the lines connect an SD card reader via SPI. Bus
 logic is provided by a ATF16V8B EEPLD. The reset logic is based on a
 NE555 in a monostable configuration with a little help (an inverter on
 the AFT16V8B).
 
 The hardware design is rather straightforward; see
 `hw/pcb/eris2010/eris210.sch` for schematics (this is a KiCad file). The
 bus logic is documented in `hw/bus_logic/bus_logic.pld`. The only tricky
 part was getting RAM access synced with the CPU clock.
 
 ## Memory Map
 
 Lowest 32K are RAM, highest 8K are ROM. Up to 4 I/O devices (ACAI or
 VIA) can be accessed at addresses below the ROM. One ACAI and one VIA
 are required to operate the computer, because they provide a serial
 interface (ACIA) and an interface to the SD card reader (VIA). Two
 more devices can be connected via the Extension Port. The third I/O
 device is active when `io_select5` is high and `io_select4` low. The
 fourth I/O device is active when `io_select5` is low and `io_select4` is
 high. See `hw/bus_logic/BUS_LOGIC.PLD` for details.
 
 |Area |Content     |Location       |
 |---  |:----------:|--------------:|
 |ROM  | OS         | $E000 - $FFFF |
 |     |            |               |
 |IO   | EXP2       | $D800 - $DFFF |
 |     | EXP1       | $D000 - $D7FF |
 |     | VIA        | $C800 - $CFFF |
 |     | ACIA       | $C000 - $C7FF |
 |     |            |               |
 |RAM  | IRQ Vector | $7FFE - $7FFF |
 |     | Heap       |   ... - $7FFD |
 |     | ...        |      ...      |
 |     | Data Stack |      ...      |
 |     | Program    | $0200 - ...   |
 |     | HW Stack   | $0100 - $01FF |
 |     | Zero Page  | $0000 - $00FF |
 
 The reset vector points to $E000, the begin of the ROM. Programs are
 loaded to $0200. The IRQ handler jumps to the address stored in RAM at
 $7FFE. For assembler programs, the data stack is located right after
 the program code and grows up, as shown in the diagram above. For C
 programs, the RAM layout is different. They use two stacks in addition
 to the hardware stack: The assembler stack (used by assembler
 functions in ROM) is located at the top of the RAM below the IRQ
 vector ($7DFE - $7FFD), below it, the C stack occupies $6DFE -
 $7DFD. Everything in between the program and the stacks is heap.
 
 ## Reset logic
 
 Resets can be triggered in two ways: A reset button is connected to an
 NE555 in a monostable configuration. Alternatively, a reset can be
 triggered by setting DTR of the serial interface to high. The latter
 is used to automatically trigger a reset before program
 upload. `tools/boot.py` uses this to trigger a reset and get Eris 2010
 ready for program upload. The disadvantage of wiring DTR to rest is
 that Eris 2010 only operates when a terminal is connected; when no
 terminal is connected, it stays in reset mode. Therefore a hardware
 switch allows to disconnect DTR from the reset line, allowing Eris
 2010 to run even if no terminal is connected. In this configuration,
 resets for program upload have to be triggered manually. See also
 section Booting.
 
 Another way to run Eris 2010 even if no terminal program is running on
 your main computer is to configure your computer's serial interface
 to keep DTR low at all times (Linux: `stty -F <serial interface>
 -hup`).
 
 Note that the reset line of the 65C02 is active on low. We use the
 AFT16V8B - which mainly provides the bus logic - as an inverter.
 
 ## Booting
 
 The "standard" ROM is `roms/os/os.bin`. This ROM includes the standard
 library (for serial communication, accessing SD card, RNG, ...). It
 provides three methods to load a program:
 
 ### Via serial line
 
 After a reset, the ROM listens for a serial data transmission at 19200
 BPS 8N1. If byte $ff is sent, the download sequence is initiated. The
 next byte is the number of half-blocks of 256 bit to be loaded. (Block
 size is 512 bit, because this is the block size of SD cards.) The
 number of half-blocks is followed by the data. Data is stored at
 $0200. Once the upload is completed, the upload program returns a
 two-byte checksum. The first byte is the sum of all bytes transmitted
 mod 256. The second byte is the xor of all bytes transmitted. The
 upload program than starts executing the loaded program at $0200.
 
 On the PC, use `tools/boot.py` for upload.
 
 ### From SD Card
 
 The boot ROM includes `sw/load_from_card/load_from_card.asm`, the
 program to load programs from SD card. This program is executed when
 no program is transmitted via serial line.
 
 SD cards can store up to 10 programs. The file system format is as
 follows:
 
 Block $00000000 is loaded on initialization. The first two bytes
 should be $E215. This indicates the file system type. The third byte
 should be $00. This is the version of the file system. The fourth byte
 is the number of the program to start automatically, or $ff. In case
 of $ff, a menu of the programs on the card is presented for the user
 to choose.
 
 The storage space for the first program starts at $00000001. The
 storage space for the second program starts at $00010001, for the
 third program at $00020001, ... Thus, each program has a total of
 $ffff blocks of 512 bytes each available. The first block of each
 program is the program header. It contains the number of blocks to be
 loaded, and the app name, a null-terminated string. The actual program
 code starts with the next block. The program is loaded to address
 $0200 and executed.
 
 On the PC, use `tools/kfs.py` to write the SD card.
 
 ## Interfaces
 
 Two interface modules are part of the computer system: A serial
 interface connected to a USB2Serial adapter provides character I/O and
 program upload facilities. An SD card reader provides access to SD
 cards with a rudimentary file system. The default operating system
 allows to read and execute programs stored on an SD card.
 
 In addition, a user port on the PCB provides access to all GPIO lines
 not occupied by the SD card communication interface, and an expansion
 port provides access to the buses and other internal lines. The
 expansion port carries two select lines for additional peripheral
 devices. See section Memory Map above.
 
 ## Interrupts
 
 The I/O interfaces are wired to IRQ. NMI can be triggered by pushing a
 physical button. User programs can write their own ISRs for IRQs. The
 ISR for NMIs is set in the ROM. The default ISR dumps the
 RAM. Alternatively NMIs may jump into Wozmon. For this, set flag
 `WOZMON_ON_NMI` in `roms/os/os.asm`. Beware that compiling Wozmon into
 the kernel does not conform to the GNU GPL v3 license, because Wozmon
 is not offically free software. However I, Gerd Beuster, the author of
 the kernel, grant you the right to compile Wozmon into it.
 
 ## Toolchain
 
 ### Hardware
 
 You can find all files related to the hardware design in
 `hw/pcb/eris2010`. The design uses [some additional library
 symbols](https://github.com/Alarm-Siren/6502-kicad-library). These
 additional symbols are copyright (c) 2018, Nicholas Parks Young and
 licensed under the GNU LGPL v2.1. The hardware schematics and PCB
 layout were designed in KiCad. FreeRouting (part of LayoutEditor) has
 been used for routing.
 
 An ATF16V8B-15PU EEPLD is used for the bus logic. It is programmed in
 [GALasm](https://github.com/daveho/GALasm).
 
 Both the EEPROM and the EEPLD can be burned with
 [minipro](https://gitlab.com/DavidGriffith/minipro/).
 
 ### Assembler
 
 All core parts of Eris 2010 have written in assembler. They can be
 translated with 64tass. The Makefiles generate binary code both for
 Eris 2010 and Symon. [Symon](https://github.com/sethm/symon), a 6502
 emulator written in Java, has been used for debugging.
 
 ## Standard Library
 
 A standard library is part of the boot ROM located at `roms/os/`. In
 order to use it, import `roms/os/os.inc` into your program.
 
 The standard library includes a data stack with subroutines and macros
 for local variables and parameter passing. See `roms/os/os.asm` for
 documentation and `sw/stack_test/stack_test.asm` for examples.
 
 The following functionality is provided:
 
 - Serial communication interface  
 All serial communication is conducted at 19200BPS with 8N1. Various
 input and output functions are provided, including a function that
 initializes the RNG (see LFSR) by counting ticks when waiting for user
 input.
 
 - ANSI Terminal  
 On top of the serial communication interface, the core ANSI escape
 sequences are supported.
 
 - LFSR  
 A 16 bit LFSR with maximum period length is provided as PRNG.
 
 - SPI  
 SPI messages can be send via the VIA.
 
 - SD Card  
 SD cards can accessed in SPI mode. All addresses are 32 bit, referring
 to 512 bit blocks on the card. Note that this implementation does not
 work with all cards. See section [bugs](#bugs) below.
 
 - Data Stack  
 A data stack in software for local variables and parameter passing. In
 difference to most stacks, the stack grows from bottom to top. The
 recommended memory layout is program code, followed by heap (if
 applicable), followed by stack. You have to manually create and delete
 stack frames with calls to create_stack_frame and delete_stack_frame.
 Pull and push operations do not push actual data on the stack, but
 just move the stack pointer. Local variables on the stack are
 represented by integers and accessed by `lda_LOCAL \<number\>`,
 `sta_LOCAL \<number\>`, and similar macros. Parameters passed by
 `sta_PARAM \<number\>` can be accessed by the callee by `lda_LOCAL
 \<number\>`. Macro `CALL` may be used to call a subroutine with
 parameters. Refer to `sw/stack_test/stack_test.bin` and
 `sw/load_from_card/load_from_card.asm` for examples.
 
 ### C
 
 You can program Eris 2010 in C using the CC65 C compiler, available at
 <https://cc65.github.io/>. Suitable configuration and Makefiles, as
 well as implementations of the conio and dio libraries, are
 located in directory `sw/c/cc65_eris`. You have to run `make` once in
 this directory in order to generate `eris2010.lib`. After that, you
 can compile the programs in the other subdirectories. The programs
 here are simple test programs. Check out `contrib/c/` for ports of
 (more or less) useful programs.
 
 #### The conio Library
 
 The conio library for console input/output has been ported to use the
 serial connection. Since the serial connection is the main I/O
 connection of Eris 2010, conio and not the serial library is used to
 access it. Some functions of conio have not been ported because the
 functionality is not available via a serial line with ANSI encoding:
 
 - bgcolor
 - bordercolor
 - cpeekc
 - cpeekcolor
 - cpeekrevers
 - cpeeks
 
 #### The dio Library
 
 The dio library provides low level file system access. dio uses 16 bit
 sector numbers. Since SD cards use 32 bit sector numbers, we use a
 hack to be able to access all sectors of the SD card while maintaining
 compatibility to the dio library: The upper 16 bits of the sector
 number are encoded as the device handle.
 
 In order to access the SD card, you have to call `dio_open`
 once. Neither the `device` number you pass into this function nor the
 handle returned matter. `dio_write` and `dio_read` treat `handle` as
 an unsigned int indicating the upper 16 bits of the sector
 number. (`dio_write_verify` is not implemented.)
 
 Due to our file system structure, this `handle` is identical to the
 application number of the application whose data you are
 accessing. The application number is a (the) parameter of `main`. Use
 it to make sure that your program only writes to its own storage space.
 
 ### Forth
 
 Tali Forth 2 (<https://github.com/scotws/TaliForth2>) has been ported
 to Eris 2010. It resides in directory `contrib/forth`. Note that Tali
 Forth 2 is included as a submodule. Either checkout the Eris 2010
 repository with option `--recurse-submodules` or run `git submodule
 init && git submodule update` in the Eris 2010 directory. If you want
 to use Tali Forth 2 for any other purpose than running it on Eris
 2010, I recommend to use the version from the original repository, not
 the one adapted to Eris 2010 used here.
 
 Due to memory constraints, `ed` has been removed. Even after removing
 `ed`, only approximately 7 KB are free.
 
 Following the SD card structure of Eris 2010, the two upper bytes of
 the block number are fixed to $00 (MSB) and the application number
 (second MSB). Since SD card blocks are 512B, but Forth blocks are
 1024B, a total of $7fff blocks are available from within the Forth
 system. These blocks represent the SD card memory available to the
 Forth application, i.e. the Forth application itself resides in the
 blocks 0 to 31. If you write to any of these blocks, you overwrite the
 Forth system! Blocks above 31 are free to use.
 
 ## Tools
 
 ### kfs.py
 
 Program for formatting, listing, and writing SD card in a format
 readable by Eris 2010.
 
 ### boot.py
 
 Script to upload programs via serial line.
 
 ### reset.py
 
 Triggers a reset by toggling DTR.
 
 ## Case
 
 The main purpose of the case is to expose the mainboard. :-)
 Therefore it just consists of a top and bottom acrylic plates,
 separated by spacer bolts. Laser cutter cutout files are located in
 directory `case/`
 
 ## Bugs
 
 The communication protocol for SD cards is rather complex. The
 implementation for Eris 2010 worked with 5 out of 6 cards tested. If
 it does not work with your card, try a different card (or fix the
 protocol implementation). :-)
 
 ## ChangeLog
 
 - v1.2  
 Tali Forth 2 and Snake added.
 - v1.1  
 Support for C programming language.
 - v1.0  
 First public version.
 
 ## Copyright and License
 
 The software in directory `contrib/` comes from third parties. Check the
 subdirectories of `contrib/` for author, copyright, and licensing
 information.
 
 Everything else:
 
 Copyright © 2021 Gerd Beuster <gerd@frombelow.net>
 
 This project is free soft- and hardware: you can redistribute it
 and/or modify it under the terms of the GNU General Public License as
 published by the Free Software Foundation, either version 3 of the
 License, or (at your option) any later version.
 
 This project is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with this project.  If not, see <http://www.gnu.org/licenses/>.