chip8

Documentation

Index

• Constants
• Variables
• type Assembly
  • func Assemble(program []byte, eti bool) (out *Assembly, err error)
• type Breakpoint
  • func (b Breakpoint) Error() string
• type CHIP_8
  • func LoadAssembly(asm *Assembly, eti bool) (*CHIP_8, error)
  • func LoadFile(file string, eti bool) (*CHIP_8, error)
  • func LoadROM(program []byte, eti bool) (*CHIP_8, error)
  • func (vm *CHIP_8) ClearBreakpoints()
  • func (vm *CHIP_8) DecSpeed() int
  • func (vm *CHIP_8) Disassemble(i uint) string
  • func (vm *CHIP_8) GetDelayTimer() byte
  • func (vm *CHIP_8) GetResolution() (int, int)
  • func (vm *CHIP_8) GetSoundTimer() byte
  • func (vm *CHIP_8) HighRes() bool
  • func (vm *CHIP_8) IncSpeed() int
  • func (vm *CHIP_8) PressKey(key uint)
  • func (vm *CHIP_8) Process(paused bool) error
  • func (vm *CHIP_8) ReleaseKey(key uint)
  • func (vm *CHIP_8) RemoveBreakpoint(address int)
  • func (vm *CHIP_8) Reset()
  • func (vm *CHIP_8) SaveROM(file string, includeInterpreter bool) error
  • func (vm *CHIP_8) SetBreakpoint(b Breakpoint)
  • func (vm *CHIP_8) Step() error
  • func (vm *CHIP_8) StepOut() error
  • func (vm *CHIP_8) StepOverBreakpoint() bool
  • func (vm *CHIP_8) ToggleBreakpoint()
• type SysCall
  • func (call SysCall) Error() string

Constants

const (
	TOKEN_END tokenType = iota
	TOKEN_CHAR
	TOKEN_LABEL
	TOKEN_ID
	TOKEN_INSTRUCTION
	TOKEN_OPERAND
	TOKEN_V
	TOKEN_R
	TOKEN_I
	TOKEN_EFFECTIVE_ADDRESS
	TOKEN_F
	TOKEN_HF
	TOKEN_K
	TOKEN_DT
	TOKEN_ST
	TOKEN_LIT
	TOKEN_TEXT
	TOKEN_BREAK
	TOKEN_ASSERT
	TOKEN_EQU
	TOKEN_VAR
	TOKEN_HERE
	TOKEN_SUPER
	TOKEN_EXTENDED
	TOKEN_ASCII
)

Lexical assembly tokens.

Variables

var (
	// AsciiTable is the 6-bit ASCII table for CHIP-8E.
	AsciiTable = `@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_ !"#$%&'()*+,-./0123456789:;<=>?`
)

var Boot = []byte{}/* 133 elements not displayed */

Boot is a CHIP-8 program that can be loaded in case nothing is.

var Dummy = []byte{0x12, 0x00}

A "dummy" program that does nothing but loop in on itself.

var EmulatorROM = [0x200]byte{}/* 512 elements not displayed */

First 512 bytes for the emulator.

var Interpreter = []byte{}/* 512 elements not displayed */

This is a CDP1802 interpreter for CHIP-8. It does NOT support CHIP-8E!

Types

type Assembly

type Assembly struct {
	// ROM is the final, assembled bytes to load.
	ROM []byte

	// Breakpoints is a list of addresses.
	Breakpoints []Breakpoint

	// Label mapping.
	Labels map[string]token

	// Addresses with unresolved labels.
	Unresolved map[int]string

	// Base address the ROM begins at (0x200 or 0x600 for ETI).
	Base int

	// Super is true if using additional super CHIP-8 instructions.
	Super bool

	// Extended is true if using additional CHIP-8E instructions.
	Extended bool
}

Assembly is a completely assembled source file.

func Assemble

func Assemble(program []byte, eti bool) (out *Assembly, err error)

Assemble an input CHIP-8 source code file.

type Breakpoint

type Breakpoint struct {
	// Address is the memory address where the PC should break.
	Address int

	// Reason is used to identify what id happening in code.
	Reason string

	// Conditional is true if the breakpoint only trips when VF != 0.
	Conditional bool

	// Once is true if the breakpoint should be removed once hit.
	Once bool
}

Breakpoint is an implementation of error.

func (Breakpoint) Error

func (b Breakpoint) Error() string

Error implements the error interface for a Breakpoint.

type CHIP_8

type CHIP_8 struct {
	// ROM memory for CHIP-8. This holds the reserved 512 bytes as
	// well as the program memory. It is a pristine state upon being
	// loaded that Memory can be reset back to.
	ROM [0x1000]byte

	// Memory addressable by CHIP-8. The first 512 bytes are reserved
	// for the font sprites, any RCA 1802 code, and the stack.
	Memory [0x1000]byte

	// Video memory for CHIP-8 (64x32 bits). Each bit represents a
	// single pixel. It is stored MSB first. For example, pixel <0,0>
	// is bit 0x80 of byte 0. 4x the video memory is used for the
	// CHIP-48, which is 128x64 resolution. There are 4 extra lines
	// to prevent overflows when scrolling.
	Video [0x440]byte

	// The stack was in a reserved section of memory on the 1802.
	// Originally it was only 12-cells deep, but later implementations
	// went as high as 16-cells.
	Stack [16]uint

	// SP is the stack pointer.
	SP uint

	// PC is the program counter. All programs begin at 0x200.
	PC uint

	// Base is the starting address of the program in hardware. This is
	// 0x200 for all ROMs except those running on the ETI-660, which start
	// at 0x600.
	Base uint

	// The size of the ROM.
	Size int

	// I is the address register.
	I uint

	// V are the 16 virtual registers.
	V [16]byte

	// R are the 8, HP-RPL user flags.
	R [8]byte

	// DT is the delay timer register. It is set to a time (in ns) in the
	// future and compared against the current time.
	DT int64

	// ST is the sound timer register. It is set to a time (in ns) in the
	// future and compared against the current time.
	ST int64

	// Clock is the time (in ns) when emulation begins.
	Clock int64

	// Cycles is how many clock cycles have been processed. It is assumed
	// one clock cycle per instruction.
	Cycles int64

	// Speed is how many cycles (instructions) should execute per second.
	// By default this is 700. The RCA CDP1802 ran at 1.76 MHz, with each
	// instruction taking 16-24 clock cycles, which is a bit over 70,000
	// instructions per second.
	Speed int64

	// W is the wait key (V-register) pointer. When waiting for a key
	// to be pressed, it will be set to &V[0..F].
	W *byte

	// Keys hold the current state for the 16-key pad keys.
	Keys [16]bool

	// Number of bytes per scan line. This is 8 in low mode and 16 when high.
	Pitch int

	// A mapping of address breakpoints.
	Breakpoints map[int]Breakpoint
}

CHIP_8 virtual machine emulator.

func LoadAssembly

func LoadAssembly(asm *Assembly, eti bool) (*CHIP_8, error)

Load a compiled assembly and return a new CHIP-8 virtual machine.

func LoadFile

func LoadFile(file string, eti bool) (*CHIP_8, error)

Load a ROM file and return a new CHIP-8 virtual machine.

func LoadROM

func LoadROM(program []byte, eti bool) (*CHIP_8, error)

Load a ROM from a byte array and return a new CHIP-8 virtual machine.

func (*CHIP_8) ClearBreakpoints

func (vm *CHIP_8) ClearBreakpoints()

ClearBreakpoints removes all breakpoints.

func (*CHIP_8) DecSpeed

func (vm *CHIP_8) DecSpeed() int

DecSpeed lowers CHIP-8 virtual machine performance.

func (*CHIP_8) Disassemble

func (vm *CHIP_8) Disassemble(i uint) string

Disassemble a CHIP-8 instruction.

func (*CHIP_8) GetDelayTimer

func (vm *CHIP_8) GetDelayTimer() byte

Converts a CHIP-8 delay timer register to a byte.

func (*CHIP_8) GetResolution

func (vm *CHIP_8) GetResolution() (int, int)

GetResolution returns the width and height of the CHIP-8.

func (*CHIP_8) GetSoundTimer

func (vm *CHIP_8) GetSoundTimer() byte

Converts the CHIP-8 sound timer register to a byte.

func (*CHIP_8) HighRes

func (vm *CHIP_8) HighRes() bool

HighRes returns true if the CHIP-8 is in high resolution mode.

func (*CHIP_8) IncSpeed

func (vm *CHIP_8) IncSpeed() int

IncSpeed increases CHIP-8 virtual machine performance.

func (*CHIP_8) PressKey

func (vm *CHIP_8) PressKey(key uint)

PressKey emulates a CHIP-8 key being pressed.

func (*CHIP_8) Process

func (vm *CHIP_8) Process(paused bool) error

Process CHIP-8 emulation. This will execute until the clock is caught up.

func (*CHIP_8) ReleaseKey

func (vm *CHIP_8) ReleaseKey(key uint)

ReleaseKey emulates a CHIP-8 key being released.

func (*CHIP_8) RemoveBreakpoint

func (vm *CHIP_8) RemoveBreakpoint(address int)

RemoveBreakpoint clears a breakpoint at a given ROM address.

func (*CHIP_8) Reset

func (vm *CHIP_8) Reset()

Reset the CHIP-8 virtual machine memory.

func (*CHIP_8) SaveROM

func (vm *CHIP_8) SaveROM(file string, includeInterpreter bool) error

Write the ROM file to disk.

func (*CHIP_8) SetBreakpoint

func (vm *CHIP_8) SetBreakpoint(b Breakpoint)

SetBreakpoint at a ROM address to the CHIP-8 virtual machine.

func (*CHIP_8) Step

func (vm *CHIP_8) Step() error

Step the CHIP-8 virtual machine a single instruction.

func (*CHIP_8) StepOut

func (vm *CHIP_8) StepOut() error

StepOut executes instructions until a RET instruction is executed.

func (*CHIP_8) StepOverBreakpoint

func (vm *CHIP_8) StepOverBreakpoint() bool

StepOverBreakpoint creates a one-time breakpoint on the next instruction if the current instruction is a CALL.

func (*CHIP_8) ToggleBreakpoint

func (vm *CHIP_8) ToggleBreakpoint()

ToggleBreakpoint at the current PC. Any reason is lost.

type SysCall

type SysCall struct {
	// Address is the memory location where the CDP1802 instructions
	// are located.
	Address uint
}

SysCall is an implementation of error.

func (SysCall) Error

func (call SysCall) Error() string

Error implements the error interface for a SysCall.