
                      Ŀ
                       CHIP8 Emulator Version 2.1.1 
                        By David WINTER (HPMANIAC)  
                      

        Contents :

            1 - CHIP8 features

                1.1 - History

                    1.1.1 - The original CHIP8
                    1.1.2 - CHIP8 Today
                    1.1.3 - Why a CHIP8 emulator ?

                1.2 - Programs and memory
                1.3 - Registers
                1.4 - Graphics
                1.5 - Instructions
                1.6 - Keyboard
                1.7 - CHIP8/SCHIP games and programs

            2 - The CHIP8 emulator

                2.1 - CHIP8 configuration
                2.2 - Using CHIP8
                2.3 - The FIX_CHIP utility
                2.4 - The UNCHIP disassembler
                2.5 - The CHIP8 DEBUGer
                2.6 - The BINHEX and HEXBIN utilities
                2.7 - The CHIPPER assembler

            3 - Contacts

            4 - POSTWARE



    1 - CHIP8 features

        1.1 - History

            1.1.1 - The original CHIP8

        CHIP8 is an interpreter used in the late 70's on the TELMAC 1800 and
    some "do-it yourself computers" (ETI 660, RCA COSMAC VIP, DREAM 6800...)
    to program easily video games. The TELMAC 1800 was based on the CDP-1802
    processor from RCA, and was sold with an audio cassette containing more
    than 12 games, dated 1977. This interpreter has less than 40 instructions
    including arithmetic, control flow, graphics and sound.
    Due to the 4Kb memory of the TELMAC 1800, the interpreter has to be very
    compact. The CHIP8 implementation was 512 bytes long.
    Some games we used to see at this early time of the video games, like
    "Pong", "Brix", "Invaders", "Tank", could be directly programmed in
    hexadecimal in less than 256 bytes.



            1.1.2 - CHIP8 today

    CHIP8 was not only used in the late 70's and early 80's. It was used in
    the early 90's on the HP48 calculator, as there was no way to program
    fast games on it. Most of the original CHIP8 games work with the CHIP48
    interpreter, and some new ones were programed. Refer to the games list
    in section 1.7.
    Then, a better version of CHIP8 appeared: SUPER-CHIP. This interpreter
    has all the CHIP8 features and some new ones like the 128*64 resolution.
    There is a special CHIP8/SCHIP library on HP48G, programed by the author
    of this emulator, which has more than 12 games.
    This is why there is the FIX_CHIP utility, made to convert the CHIP8
    games of the HP48 to the PC format. Refer to section 2.2 for more infos.



            1.1.3 - Why a CHIP8 emulator ?

        A lot of users like emulators, because they can replay the games they
    used to play many years ago. The most surprising is that a lot of games
    known by everyone, that we can play on come emulators, are not reprogramed
    on today's computers.
    So, I decided to program a CHIP8 emulator. It emulates the oldest home
    computer emlated still today.



        1.2 - CHIP8 programs and memory

        All the Telmac CHIP8 programs start at address 200h. This is due to
    the interpreter whih used to reside in the 000h-1FFh area.
    The entire memory, which is 4Kb long, is accessible and byte addressable.
    As the instructions are 16 bits long, their addresses are always even.
    SCHIP programs run like CHIP8 programs. The only differences between them
    are some new instructions in the SCHIP mode.



        1.3 - Registers

    - the data registers: they are 16, all 8 bits coded, named V0...VF. VF is
      used as carry and collision detector while drawing sprites.

    - the address register: there is only one, named I, 16 bits coded. As the
      memory is 4Kb, only its 12 low bits are used.

    - the timers: they are two. One is the delay timer, and the other the
      sound timer. Both are 8 bits coded, and count down about 60 times per
      second when non zero.
      The speaker will beep while the sound timer is non zero.
      The delay timer is generaly used to make delay loops.
      It seems that both count down every 16ms.

    - the stack: it has 16 levels, allowing 16 successive subroutine calls. 



        1.4 - Graphics

        The CHIP8 resolution is 64*32. Some modified machines could use a
    64*48 or 64*64 resolution. As no program was found using the two last
    ones, CHIP8 will only use the 64*32 resolution.

    Graphics are drawn in 8*1...15 sprites (as they are byte coded).
    The origin of the screen is the upper left corner. All the coodrinates
    are positive, start at 0 and are calculated mod 64 for X, and 32 for Y
    when drawing sprites.

    All drawing is done in XOR mode. When one or more pixels are erased
    when drawing sprites, the VF register is set to 01, otherwise 00.

    CHIP8 has a 4*5 hexadecimal font to draw easily chars. These chars are
    0-9 and A-F.

    The SCHIP mode can allow a 128*64 resolution. Pixels coordinates ranges
    are 00h-7Fh for X, 00h-3Fh for Y and are calculated mod 128 for X, mod
    64 for Y.

    The SCHIP mode provides a 8*10 hexadecimal character font, and a 16*16
    sprite. Their drawing modes are the same than in CHIP8.



        1.5 - Instructions

    NNN is an address,
     KK is an 8 bit constant
    X,Y are two 4 bits constants

    0NNN    Call the 1802 machine code program at NNN (not implemented)
    00CN    Scroll down N lines (***)
    00FB    Scroll 4 pixels right (***)
    00FC    Scroll 4 pixels left (***)
    00FD    Quit the emulator (***)
    00FE    Set CHIP8 mode (***)
    00FF    Set SCHIP mode (***)
    00E0    Erase the screen
    00EE    Return from a CHIP8 sub-routine
    1NNN    Jump to NNN
    2NNN    Call CHIP8 sub-routine at NNN (16 successve calls max)
    3XKK    Skip next instruction if VX == KK
    4XKK    Skip next instruction if VX != KK
    5XY0    Skip next instruction if VX == VY
    6XKK    VX = KK
    7XKK    VX = VX + KK
    8XY0    VX = VY
    8XY1    VX = VX OR VY
    8XY2    VX = VX AND VY
    8XY3    VX = VX XOR VY (*)
    8XY4    VX = VX + VY, VF = carry
    8XY5    VX = VX - VY, VF = not borrow (**)
    8XY6    VX = VX SHR 1 (VX=VX/2), VF = carry
    8XY7    VX = VY - VX, VF = not borrow (*) (**)
    8XYE    VX = VX SHL 1 (VX=VX*2), VF = carry
    9XY0    Skip next instruction if VX != VY
    ANNN    I = NNN
    BNNN    Jump to NNN + V0
    CXKK    VX = Random number AND KK
    DXYN    Daws a sprite at (VX,VY) starting at M(I). VF = collision.
            If N=0, draws the 16*16 sprite, else an 8*N sprite.
    EX9E    Skip next instruction if key VX pressed
    EXA1    Skip next instruction if key VX not pressed
    FX07    VX = Delay timer
    FX0A    Waits a keypress and stores it in VX
    FX15    Delay timer = VX
    FX18    Sound timer = VX
    FX1E    I = I + VX
    FX29    I points to the 4*5 font sprite of hex char in VX
    FX33    Store BCD representation of VX in M(I)...M(I+2)
    FX55    Save V0...VX in memory starting at M(I)
    FX65    Load V0...VX in memory starting at M(I)
    FX75    Save V0...VX (X<8) in the HP48 flags (***)
    FX85    Load V0...VX (X<8) from the HP48 flags (***)

    (*): Used to be undonumented (but fonctional) in the original docs.

   (**): When you do VX - VY, VF is set to the negation of the borrow. This
         means that if VX is superior or equal to VY, VF will be set to 01,
         as the borrow is 0. If VX is inferior to VY, VF is set to 00, as
         the borrow is 1.

  (***): SCHIP Instruction.

  NOTES: As the interpreter is emulated, all the 0NNN instructions cannot
         be implemented. Only 00E0, 00EE and the SCHIP instructions are
         available.



        1.6 - Keyboard

        Most of the original CHIP8 programs used a 16 key hex keyboard which
    looked like this:

                        Ŀ
                         1  2  3  C 
                        Ĵ
                         4  5  6  D 
                        Ĵ
                         7  8  9  E 
                        Ĵ
                         A  0  B  F 
                        

    This keyboard is emulated like this on the PC:

                        Ŀ
                        Num C  D  E 
                        Ĵ
                         1  2  3    
                        Ĵ F 
                         4  5  6    
                        Ĵ
                         7  8  9    
                        Ĵ B 
                           A    0    
                        


    To switch between the VIDEO and the LCD mode, press V.
    To perform a SNAPSHOT, press Tab.
    To reset CHIP8, press BACKSPACE.
    To capture the screen, press C.
    To turn sound ON/OFF, press S.
    To quit CHIP8, press Esc.



        1.7 - CHIP8/SCHIP games and programs

        BLINKY      Pacman clone
        BLITZ       BOMBER like game
        BRIX        Arkanoid variant
        CONNECT4    Connect-4
        KALEID      Kaleidoscop
        MAZE        Draws random mazes
        MERLIN      SIMON game
        MISSILE     Shooter game
        PONG        The first video game dated 1972: ping-pong !!!
        PONG2       Same, improved by me
        PUZZLE      4*4 puzzle
        PUZZLE2     The same, better
        SYZYGY      Tron with a growing snake (SNAFU like)
        TANK        Tank battle
        TETRIS      Guess...
        TICTAC      Tic-Tac-Toe game
        UFO         Space shoot game
        WIPEOFF     Brix variant


    Newer games were surely programmed since 1977. If you want to add them
    to the emulator, send them via E-Mail.
    Please respect the copyrights if there are some.



    2 - The CHIP8 emulator

        2.1 - CHIP8 configuration

    The SET_CHIP utility allows you to configure CHIP8.
    You can:
        - Choose the display (TEXT or VGA),
        - Enable or disable the beeper by default,
        - Enable or disable the sound while loading a program,
        - Change the color of the screen border,
        - Change the color of the pixels when lighted or not.

    To make your configuration, run SET_CHIP. All the instructions are
    displayed on the screen. You only have to press the keys corresponding
    to the configuration you want.
    SET_CHIP gives you the keys you can press for any choice.
    The configuration is saved in CHIP8.INI.
    Note that the VGA mode can provide two display modes: "LCD" draws the
    pixels like those of a LCD screen, whereas "VIDEO" draws them in the
    normal mode.


        2.2 - Using CHIP8

    If you run CHIP8 with no argument, the emulator runs BOOT-128.
    BOOT-128 is a small 128 bytes programm (99% in CHIP8) placed in 100-180.
    It allows you to type manually a CHIP8 program in hexadecimal. Don't
    forget that this program uses the original CHIP8 keyboard, so you may
    have some confusions with the PC keyboard...
    BOOT-128 is accessible by performing a jump in 100. Note that BOOT-128 is
    not the original CHIP8 boot (whick is written in 1802 machine code).
    To run the program you typed in BOOT-128, RESET CHIP8. BOOT-128 doesn't
    allow you to make corrections if you typed an incorrect code.

    To run a CHIP8 program, type CHIP8 Program_Name. You can specify the
    path of the program. The emulator loads in (an error message will appear
    if it is not found). Then, you are under emulation.

    You can perform a text screen capture by pressing C. This capture will
    be saved as "SCREEN". Refer to section 1.6 for the keys. This is only
    available in CHIP8 mode.

    Concerning the VGA display, you can put the display mode in VIDEO or in
    VGA whenever you want by pressing V.

    You can also make a SNAPSHOT of the surrent emulation by pressing Tab.
    This SNAPSHOT will be saved as "SNAPSHOT", and the emulation saved can
    be continued by typing CHIP8 SNAP. This is only available in CHIP8 mode.


        2.3 - The FIX_CHIP utility

        On HP48, CHIP8 programs are stored as strings, which are object
    coded. If you transfer a program and try to run it under CHIP8, it will
    never run, because it has to be converted to the PC format with FIX_CHIP.
    To do this, type FIX_CHIP SourceName TargetName.
    Note that lots of games given with the emulator are imported from HP48.
    As far as I know, the only original CHIP8 game is UFO, dated 1977...



        2.4 - The UNCHIP disassembler

        UNCHIP is a little CHIP8/SCHIP disassembler made to help you in
    programing games, making changes in some programs (bugs, improvements...).
    To use it, type UNCHIP SourceName TargetName. SourceName is the name of
    the program you want to disassemble, TargetName is the name of the source
    you will obtain. If you want to look the contents of a SNAPSHOT file,
    UNCHIP will not disassemble it as a program, but will give you the data
    of the snapshot.

    UNCHIP can also take two optional arguments: -l and -o.

    '-l' is used to keep all the instructions addresses (else, only those
    where CHIP8 makes jumps, sub-routine calls, or a reference for register I
    are kept).

    '-o' is used to keep the OPCs (CHIP8 hexadecimal instructions).

    You can combine these arguments as you wish:

        UNCHIP PONG PONG.SRC -L -O
        UNCHIP TETRIS TETRIS.SRC -O
        UNCHIP UFO UFO.SRC -O -L
        ...


        2.5 - The CHIP8 DEBUGer

        DEBUG is a little CHIP8 debuger. It is still in construction, so
    some features are not yet avalaible.

    It shows you all the registers, the current instruction with the three
    last and four next ones. All are commented.

    You can see the CHIP8 screen in two modes:

        -Pause: the screen is shown and DEBUG waits a keypress,

        -Real Time: like the emulator, but slower to help you in debuging.


    Every illegal instruction will be mentioned in the WARNING area, and
    asked to be skiped or not (program termination).


    The keys are:

    BACKSPACE : Reset CHIP8
          ESC : Quit
          TAB : Pause on CHIP8 screen
           F1 : Swap DEBUG<->CHIP8 screen

    The CHIP8 keyboard is avalaible.



        2.6 - The BINHEX and HEXBIN utilities

        These two programs are made to simplify the programer's life in
    programing CHIP8 games. They allow to convert binary to hexadecimal
    files (BINHEX), and hexadecimal to binary files (HEXBIN). Both require
    two arguments: the names of the source and the target.
    For example, to convert PONG in an hexadecimal file named PONG.TXT,
    type BINHEX PONG PONG.TXT. To convert PONG.TXT in a binary file, type
    HEXBIN PONG.TXT PONG.

    These utilities are very useful to make corrections or improvements in
    CHIP8 programs. Instead of using UNCHIP and recompile everything, just
    convert the file in Hexadecimal, modify it, and re-convert it in binary.
    This is the way I used to improve PONG in less than 3 minutes.

    Little astuce: if you want to add several instructions somewhere in the
    program WITHOUT changing all the jump instructions, replace the
    intruction where you want to put several ones by a call to a subroutine
    at the end of the program. Then, put at the begining of the subroutine
    the instruction you replaced by the subroutine call. Make sure the sub-
    routine doesn't modify the registers that must not change, otherwise
    save them before putting your own code, and restore them just before
    returning from the subroutine. Now, your subroutine can do whatever you
    want.



        2.7 - The CHIPPER assembler

    CHIPPER is a powerfull symbolic CHIP8 (also CHIP48 and SCHIP) assembler
    written by Christian Egeberg. A complete doc is given in the directory
    of this program. Don't forget to put "OPTION BINARY" at the begining of
    your sources, or your programs won't be usable on your PC. You can also
    put "ALIGN OFF" to save some space. This option allows to put some 8 bit
    data, instead of 16 bit.



    3 - Contacts

        If you want to contact me, send an E-Mail to the following address:
    winter@worldnet.net. I will answer your questions in the time I have to,
    and take the time to appreciate your suggestions.
    For the POSTWARE, you can also write to me at the following address:

                             David WINTER
                             19 rue de Noailles
                             78100 St-Germain-en-Laye
                             FRANCE
    

    Many thanks to:

        Andreas Gustafsson, author of CHIP8 for HP48 for his great detailed
        docs of CHIP8.

        Erik Bryntse for his SCHIP docs.

        Carolyn alias "Steve" for her encouragements and patience,

        Massimiliano Zattera for his keyboard routine which allows to
        make a real emulation of the original Chip-8 keyboard.



    4 - POSTWARE

    This software is diffused as a POSTWARE. A POSTWARE is like a FREEWARE,
    whereas you have to post (via post-card, letter, EMail, fax) a message 
    to the author if you decide to use its software. The minimum you have to
    put in it is your Name and First Name. The rest is generally your own
    appreciaitons and/or suggestions.
    
    The rules of the FREEWARE means that:

        - You MUST obtain your copy FREELY.

        - You can give it ONLY IN ITS ORIGINAL INTEGRITY, so you MUST NOT
          ADD, ERASE, MODIFY any file of it.

          Note: CHIP8 must have these files:

            * DOC.FR directory (french documentations):
                - CHIP8.TXT    : CHIP8's doc
                - EXPRESS.TXT  : The last infos to know
                - FAQ.TXT      : The frequently asked questions
                - JEUX.TXT     : The infos of the CHIP8 programs/games
                - VERSIONS.TXT : The versions infos

            * DOC.ENG directory (english documentations):
                - CHIP8.TXT    : CHIP8's doc
                - EXPRESS.TXT  : The last infos to know
                - FAQ.TXT      : The frequently asked questions
                - GAMES.TXT    : The infos of the CHIP8 programs/games
                - HISTORY.TXT  : The versions infos

            * CHIP8 directory:
                - FILE_ID.DIZ  : Brief file description
                - BINHEX.EXE   : Binary to hexadecimal file converter
                - HEXBIN.EXE   : Hexadecimal to binary file converter
                - CHIP8.EXE    : The CHIP8 emulator
                - CHIP8.INI    : CHIP8's configuration backup
                - CHIP8.ROM    : CHIP8's ROM
                - DEBUG.EXE    : The CHIP8 debuger [temporary removed]
                - SET_CHIP.EXE : Utility to configure CHIP8
                - FIX_CHIP.EXE : The FIX_CHIP utility
                - UNCHIP.EXE   : The CHIP8 disassembler
                - SVGA256.BGI  : The SVGA drivers
                - BACKUP.DAT   : The SCHIP data backup

            * CHIPPER directory:
                - CHIPPER.DOC  : CHIPPER's doc
                - CHIPPER.EXE  : CHIPPER itself

                Some games are added to the software as I am not the author
                of them.

        - You MUST NOT sell it

        - You MUST NOT distribute it for any charge excepeted:
                - The shipping charges,
                - The price of the medium (diskette, tape...) of THE copy
                  you GIVE.

        - If you require some money to distribute it, you MUST obtain my
          express written permission.

        - This software is distributable on diskette, tape or free server
          ONLY if it agrees with this entire section.
