spec

README

gb-cpu-tests

A collection of Game Boy CPU instruction tests provided as YAML specifications and a Go library for loading them.

Overview

The project provides comprehensive tests for each Game Boy CPU instruction. Each test includes the initial state, the expected final state, and the cycle-accurate bus operations.

• Specs: Located in spec/*.yaml, named by opcode (e.g., 0b.yaml).
• Data: Includes registers (A, B, C, D, E, H, L, F, PC, SP), RAM values, and bus cycles (address, data, and mode: read/write). A null bus cycle entry indicates no bus activity during that cycle.
• Format: YAML for easy parsing and human readability.

Go Library

The spec package provides a Go API for loading these tests, with the YAML files embedded in the binary.

Usage

import spec "github.com/nitwhiz/gb-cpu-tests"

// Load tests for a specific opcode
suite, err := spec.Load(0x0B, false)
if err != nil {
    log.Fatal(err)
}

fmt.Printf("Suite: %s, Tests: %d\n", suite.CanonicalName, len(suite.Tests))

// Iterate over all available test suites
for suite, err := range spec.LoadAll() {
    if err != nil {
        log.Fatal(err)
    }
    // Process suite
}

Data Source

The data in this repository is sourced from SingleStepTests/sm83.

Structure

• spec/: YAML test specifications for each opcode.
• spec.go: Go data structures and loading logic.
• cmd/gen/: Tools for generating or updating test specifications.
• data/: Raw test data sources.

Documentation

Index

• func LoadAll() iter.Seq2[*TestSuite, error]
• type BusState
  • func (b BusState) IsMemoryRequest() bool
  • func (b BusState) IsRead() bool
  • func (b BusState) IsWrite() bool
• type Opcode
  • func (o Opcode) String() string
• type OpcodeFlags
• type OpcodeOperand
  • func (o OpcodeOperand) String() string
• type Opcodes
• type RAMValue
• type Registers
• type State
• type Test
• type TestSuite
  • func Load(opcode uint8, prefixed bool) (suite *TestSuite, err error)

Functions

func LoadAll

func LoadAll() iter.Seq2[*TestSuite, error]

Types

type BusState

type BusState struct {
	Address uint16 `yaml:"address"`
	Data    uint8  `yaml:"data"`
	Mode    string `yaml:"mode"`
}

func (BusState) IsMemoryRequest

func (b BusState) IsMemoryRequest() bool

func (BusState) IsRead

func (b BusState) IsRead() bool

func (BusState) IsWrite

func (b BusState) IsWrite() bool

type Opcode

type Opcode struct {
	Code      string          `yaml:"opcode"`
	Mnemonic  string          `yaml:"mnemonic"`
	Bytes     int             `yaml:"bytes"`
	Cycles    []int           `yaml:"cycles,flow"`
	Immediate bool            `yaml:"immediate"`
	Operands  []OpcodeOperand `yaml:"operands,omitempty"`
	Flags     OpcodeFlags     `yaml:"flags,flow"`
}

func (Opcode) String

func (o Opcode) String() string

type OpcodeFlags

type OpcodeFlags struct {
	Z string `json:"z"`
	N string `json:"n"`
	H string `json:"h"`
	C string `json:"c"`
}

type OpcodeOperand

type OpcodeOperand struct {
	Name      string `json:"name"`
	Bytes     int    `json:"bytes"`
	Immediate bool   `json:"immediate"`
}

func (OpcodeOperand) String

func (o OpcodeOperand) String() string

type Opcodes

type Opcodes struct {
	Unprefixed [256]Opcode `yaml:"unprefixed"`
	Prefixed   [256]Opcode `yaml:"prefixed"`
}

var OpcodeData Opcodes

type RAMValue

type RAMValue struct {
	Address uint16 `yaml:"address"`
	Value   uint8  `yaml:"value"`
}

type Registers

type Registers struct {
	A  uint8  `yaml:"a"`
	B  uint8  `yaml:"b"`
	C  uint8  `yaml:"c"`
	D  uint8  `yaml:"d"`
	E  uint8  `yaml:"e"`
	H  uint8  `yaml:"h"`
	L  uint8  `yaml:"l"`
	F  uint8  `yaml:"f"`
	PC uint16 `yaml:"pc"`
	SP uint16 `yaml:"sp"`
}

type State

type State struct {
	Registers `yaml:"registers"`
	RAM       []RAMValue `yaml:"ram"`
}

type Test

type Test struct {
	Name         string      `yaml:"name"`
	InitialState State       `yaml:"initial"`
	FinalState   State       `yaml:"final"`
	BusCycles    []*BusState `yaml:"busCycles"`
}

type TestSuite

type TestSuite struct {
	Opcode        string `yaml:"opcode"`
	CanonicalName string `yaml:"canonicalName"`
	Tests         []Test `yaml:"tests"`
}

func Load

func Load(opcode uint8, prefixed bool) (suite *TestSuite, err error)