eris2010

Documentation: http://frombelow.net/projects/eris2010/
Clone: git clone https://git.frombelow.net/eris2010.git
Log | Files | Refs | README | LICENSE

README.md (19805B)


      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 <gerd@frombelow.net>
    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/>.