The cl-6502 Reference Manual

Table of Contents

The cl-6502 Reference Manual

This is the cl-6502 Reference Manual, generated automatically by Declt version 3.0 "Montgomery Scott" on Mon Apr 19 14:26:19 2021 GMT+0.

1 Introduction

cl-6502 - A Readable CPU Emulator

cl-6502 is a Common Lisp emulator, assembler and disassembler for the MOS 6502 processor. In case that sounds weird to you, the MOS 6502 is famous for its use in...

• the Apple II,
• the original NES,
• the Commodore 64,
• the BBC Micro,
• and Michael Steil's phenomenal talk at 27C3.

I gave a talk on cl-6502 called 'On Programmer Archaeology'. You can watch it on Vimeo or grab the slides. A few notes on why I'm writing it are here and minor notes on the design are here.

Reading

Inspired by Luke Gorrie's call for Readable Programs, there is a readable PDF book of the source. You can also produce it from the git repo with: cd repo/src && make book. You'll need make, pandoc, and some latex packages (texlive-luatex, texlive-xetex, and texlive-latex-extra on debian) installed to build it yourself.

Install

You are strongly encouraged to use this library via Quicklisp. Simply start your lisp and run: (ql:quickload 'cl-6502).

Getting Started

• Check out the docs for the cl-6502 package or have a look on quickdocs.
• Play around at the REPL!
• Use it to create your own wacky code artifacts.
• There is also a lower-level 6502 package if you really want to get your hands dirty. NOTE: The 6502 package shadows BIT and AND so you likely don't want to :use it in your own packages.

In particular, asm, disasm, execute, step-cpu, and reset are likely of interest.

A simple example:

1. Load cl-6502 and switch to the cl-6502 package.
2. Write some 6502 code and run it through asm (e.g. (asm "brk")) to get a bytevector to execute.
3. Load it into memory with (setf (get-range 0) *my-bytevector*).
4. Set the program counter to 0 with (setf (6502:cpu-pc *cpu*) 0).
5. Run it with (run *cpu*) or manually step through it with (step-cpu *cpu* (get-byte (cpu-pc *cpu*))).
6. (reset) the CPU as necessary and keep hacking! :)

Supported Assembler Syntax

There are sexp-based and string-based assemblers, both invoked via asm. The string-based assembler expects statements to be separated by newlines. The sexp-based assembler expects each statement to be in its own list. Disassembling to both formats is supported via disasm and disasm-to-list. Semicolons are treated as "comment to end-of-line" in the string assembler.

| Addressing Mode | SEXP-based format | String format  |
|-----------------|-------------------|----------------|
|   Implied       |  (:brk)           | "brk"          |
|   Immediate     |  (:lda :#$00)     | "lda #$00"     |
|   Accumulator   |  (:rol :a)        | "rol a"        |
|   Zero-page     |  (:lda :$03)      | "lda $03"      |
|   Zero-page, X  |  (:lda :$03.x)    | "lda $03, x"   |
|   Zero-page, Y  |  (:ldx :$03.y)    | "ldx $03, y"   |
|   Absolute      |  (:sbc :$0001)    | "sbc $0001"    |
|   Absolute, X   |  (:lda :$1234.x)  | "lda $1234, x" |
|   Absolute, Y   |  (:lda :$1234.y)  | "lda $1234, y" |
|   Indirect      |  (:jmp :@1234)    | "jmp ($1234)   |
|   Indirect, X   |  (:lda :@12.x)    | "lda ($12), x" |
|   Indirect, Y   |  (:lda :@34.y)    | "lda ($34), y" |
|   Relative      |  (:bne :&fd)      | "bne &fd"      |

Hacking

• Using Quicklisp: For local development, git clone this repository into the local-projects subdirectory of quicklisp.

To run the tests, after you've loaded cl-6502 just run (asdf:oos 'asdf:test-op 'cl-6502). You may need to (ql:quickload 'cl-6502-tests) to ensure that the fiveam dependency is satisfied first.

License

The code is under a BSD license except for docs/6502.txt and tests/6502_functional_test.a65 which are only present by 'mere aggregation' and not strictly part of my sources.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-6502

Author

Brit Butler <redline6561@gmail.com>

License

BSD

Description

An emulator for the MOS 6502 CPU

Dependencies

• alexandria
• cl-ppcre

Source

cl-6502.asd (file)

Components

• packages.lisp (file)
• conditions.lisp (file)
• addressing.lisp (file)
• cpu.lisp (file)
• disassemble.lisp (file)
• parser.lisp (file)
• assemble.lisp (file)
• opcodes.lisp (file)
• jit.lisp (file)
• utils.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-6502.asd

Location

/home/quickref/quicklisp/dists/quicklisp/software/cl-6502-20150923-git/cl-6502.asd

Systems

cl-6502 (system)

Packages

6502-conf

Exported Definitions

app-path (function)

Internal Definitions

*basedir* (special variable)

3.1.2 cl-6502/packages.lisp

Parent

cl-6502 (system)

Location

packages.lisp

Packages

• 6502
• cl-6502

3.1.3 cl-6502/conditions.lisp

Dependency

packages.lisp (file)

Parent

cl-6502 (system)

Location

conditions.lisp

Internal Definitions

• illegal-opcode (condition)
• invalid-mode (condition)
• invalid-syntax (condition)
• line (method)
• mode (method)
• opcode (method)

3.1.4 cl-6502/addressing.lisp

Dependency

conditions.lisp (file)

Parent

cl-6502 (system)

Location

addressing.lisp

Exported Definitions

• absolute (function)
• (setf absolute) (function)
• absolute-x (function)
• (setf absolute-x) (function)
• absolute-y (function)
• (setf absolute-y) (function)
• accumulator (function)
• (setf accumulator) (function)
• immediate (function)
• (setf immediate) (function)
• implied (function)
• (setf implied) (function)
• indirect (function)
• (setf indirect) (function)
• indirect-x (function)
• (setf indirect-x) (function)
• indirect-y (function)
• (setf indirect-y) (function)
• reader (generic function)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• relative (function)
• (setf relative) (function)
• writer (generic function)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• zero-page (function)
• (setf zero-page) (function)
• zero-page-x (function)
• (setf zero-page-x) (function)
• zero-page-y (function)
• (setf zero-page-y) (function)

Internal Definitions

• *address-modes* (special variable)
• defaddress (macro)
• make-getter (function)

3.1.5 cl-6502/cpu.lisp

Dependency

addressing.lisp (file)

Parent

cl-6502 (system)

Location

cpu.lisp

Exported Definitions

• *cpu* (special variable)
• *opcode-meta* (special variable)
• bytevector (function)
• cpu (structure)
• cpu-ar (function)
• (setf cpu-ar) (function)
• cpu-cc (function)
• (setf cpu-cc) (function)
• cpu-pc (function)
• (setf cpu-pc) (function)
• cpu-sp (function)
• (setf cpu-sp) (function)
• cpu-sr (function)
• (setf cpu-sr) (function)
• cpu-xr (function)
• (setf cpu-xr) (function)
• cpu-yr (function)
• (setf cpu-yr) (function)
• defenum (macro)
• get-byte (function)
• (setf get-byte) (function)
• get-range (function)
• (setf get-range) (function)
• get-word (function)
• (setf get-word) (function)
• make-cpu (function)
• nmi (generic function)
• nmi (method)
• reset (generic function)
• reset (method)
• status-bit (macro)
• u16 (type)
• u8 (type)
• wrap-byte (function)
• wrap-word (function)

Internal Definitions

• %status-bit (function)
• *opcode-funs* (special variable)
• *ram* (special variable)
• branch-if (macro)
• copy-cpu (function)
• cpu-p (function)
• defasm (macro)
• maybe-update-cycle-count (function)
• overflow-p (function)
• rotate-byte (function)
• set-flags-if (macro)
• set-status-bit (macro)
• stack-pop (function)
• stack-pop-word (function)
• stack-push (function)
• stack-push-word (function)
• wrap-page (function)

3.1.6 cl-6502/disassemble.lisp

Dependency

cpu.lisp (file)

Parent

cl-6502 (system)

Location

disassemble.lisp

Exported Definitions

• current-instruction (function)
• disasm (function)
• disasm-to-list (function)
• disasm-to-str (function)

Internal Definitions

• arg-formatter (function)
• bytes-to-keyword-syntax (function)
• disasm-ins (function)
• print-instruction (function)
• sexpify-instruction (function)
• with-disasm (macro)

3.1.7 cl-6502/parser.lisp

Dependency

disassemble.lisp (file)

Parent

cl-6502 (system)

Location

parser.lisp

Internal Definitions

• fetch-expression (function)
• fetch-label (function)
• fetch-literal (function)
• fetch-name (function)
• fetch-opcode (function)
• fetch-operand (function)
• fetch-term (function)
• make-stream (function)
• match-operand-address-modes (function)
• operand-possible-modes-and-value (function)
• parse-code (function)
• parse-line (function)
• skip-white-space (function)
• strip-comment (function)
• substream-advance (function)
• try-fetch (function)

3.1.8 cl-6502/assemble.lisp

Dependency

parser.lisp (file)

Parent

cl-6502 (system)

Location

assemble.lisp

Exported Definitions

• asm (generic function)
• asm (method)
• asm (method)

Internal Definitions

• +absolute-modes+ (special variable)
• +max-byte+ (constant)
• +relative-branch-size-byte+ (constant)
• +zero-page-modes+ (special variable)
• assemble-code-block (function)
• assemble-instruction (function)
• copy-instruction (function)
• decide-address-mode (function)
• find-opcode (function)
• get-opcode-address-modes (function)
• instruction (structure)
• instruction-address-mode (function)
• (setf instruction-address-mode) (function)
• instruction-label (function)
• (setf instruction-label) (function)
• instruction-opcode (function)
• (setf instruction-opcode) (function)
• instruction-p (function)
• instruction-value (function)
• (setf instruction-value) (function)
• list-to-instructions (function)
• make-and-resolve-byte (function)
• make-byte (function)
• make-instruction (function)
• match-opcode-data (function)
• process-args (function)
• resolve-byte (macro)
• transform-sexp-syntax (function)
• tuple-to-instruction (function)
• zero-page-address (function)

3.1.9 cl-6502/opcodes.lisp

Dependency

assemble.lisp (file)

Parent

cl-6502 (system)

Location

opcodes.lisp

3.1.10 cl-6502/jit.lisp

Dependency

opcodes.lisp (file)

Parent

cl-6502 (system)

Location

jit.lisp

Exported Definitions

jit-step (function)

Internal Definitions

• *jit-cache* (special variable)
• get-basic-block (function)
• jit-block (function)

3.1.11 cl-6502/utils.lisp

Dependency

jit.lisp (file)

Parent

cl-6502 (system)

Location

utils.lisp

Exported Definitions

• execute (function)
• step-cpu (function)

4 Packages

Packages are listed by definition order.

4.1 6502-conf

Source

/home/quickref/quicklisp/dists/quicklisp/software/cl-6502-20150923-git/cl-6502.asd

Exported Definitions

app-path (function)

Internal Definitions

*basedir* (special variable)

4.2 6502

Source

packages.lisp (file)

Use List

common-lisp

Exported Definitions

• *cpu* (special variable)
• *opcode-meta* (special variable)
• absolute (function)
• (setf absolute) (function)
• absolute-x (function)
• (setf absolute-x) (function)
• absolute-y (function)
• (setf absolute-y) (function)
• accumulator (function)
• (setf accumulator) (function)
• asm (generic function)
• asm (method)
• asm (method)
• bytevector (function)
• cpu (structure)
• cpu-ar (function)
• (setf cpu-ar) (function)
• cpu-cc (function)
• (setf cpu-cc) (function)
• cpu-pc (function)
• (setf cpu-pc) (function)
• cpu-sp (function)
• (setf cpu-sp) (function)
• cpu-sr (function)
• (setf cpu-sr) (function)
• cpu-xr (function)
• (setf cpu-xr) (function)
• cpu-yr (function)
• (setf cpu-yr) (function)
• current-instruction (function)
• defenum (macro)
• disasm (function)
• disasm-to-list (function)
• disasm-to-str (function)
• execute (function)
• get-byte (function)
• (setf get-byte) (function)
• get-range (function)
• (setf get-range) (function)
• get-word (function)
• (setf get-word) (function)
• immediate (function)
• (setf immediate) (function)
• implied (function)
• (setf implied) (function)
• indirect (function)
• (setf indirect) (function)
• indirect-x (function)
• (setf indirect-x) (function)
• indirect-y (function)
• (setf indirect-y) (function)
• jit-step (function)
• make-cpu (function)
• nmi (generic function)
• nmi (method)
• reader (generic function)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• reader (method)
• relative (function)
• (setf relative) (function)
• reset (generic function)
• reset (method)
• status-bit (macro)
• step-cpu (function)
• u16 (type)
• u8 (type)
• wrap-byte (function)
• wrap-word (function)
• writer (generic function)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• writer (method)
• zero-page (function)
• (setf zero-page) (function)
• zero-page-x (function)
• (setf zero-page-x) (function)
• zero-page-y (function)
• (setf zero-page-y) (function)

Internal Definitions

• %status-bit (function)
• *address-modes* (special variable)
• *jit-cache* (special variable)
• *opcode-funs* (special variable)
• *ram* (special variable)
• +absolute-modes+ (special variable)
• +max-byte+ (constant)
• +relative-branch-size-byte+ (constant)
• +zero-page-modes+ (special variable)
• arg-formatter (function)
• assemble-code-block (function)
• assemble-instruction (function)
• branch-if (macro)
• bytes-to-keyword-syntax (function)
• copy-cpu (function)
• copy-instruction (function)
• cpu-p (function)
• decide-address-mode (function)
• defaddress (macro)
• defasm (macro)
• disasm-ins (function)
• fetch-expression (function)
• fetch-label (function)
• fetch-literal (function)
• fetch-name (function)
• fetch-opcode (function)
• fetch-operand (function)
• fetch-term (function)
• find-opcode (function)
• get-basic-block (function)
• get-opcode-address-modes (function)
• illegal-opcode (condition)
• instruction (structure)
• instruction-address-mode (function)
• (setf instruction-address-mode) (function)
• instruction-label (function)
• (setf instruction-label) (function)
• instruction-opcode (function)
• (setf instruction-opcode) (function)
• instruction-p (function)
• instruction-value (function)
• (setf instruction-value) (function)
• invalid-mode (condition)
• invalid-syntax (condition)
• jit-block (function)
• line (generic function)
• line (method)
• list-to-instructions (function)
• make-and-resolve-byte (function)
• make-byte (function)
• make-getter (function)
• make-instruction (function)
• make-stream (function)
• match-opcode-data (function)
• match-operand-address-modes (function)
• maybe-update-cycle-count (function)
• mode (generic function)
• mode (method)
• opcode (generic function)
• opcode (method)
• operand-possible-modes-and-value (function)
• overflow-p (function)
• parse-code (function)
• parse-line (function)
• print-instruction (function)
• process-args (function)
• resolve-byte (macro)
• rotate-byte (function)
• set-flags-if (macro)
• set-status-bit (macro)
• sexpify-instruction (function)
• skip-white-space (function)
• stack-pop (function)
• stack-pop-word (function)
• stack-push (function)
• stack-push-word (function)
• strip-comment (function)
• substream-advance (function)
• transform-sexp-syntax (function)
• try-fetch (function)
• tuple-to-instruction (function)
• with-disasm (macro)
• wrap-page (function)
• zero-page-address (function)

4.3 cl-6502

Homepage: <a href="http://github.com/redline6561/cl-6502">Github</a>

Source

packages.lisp (file)

Use List

common-lisp

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *cpu*

The 6502 instance used by default during execution.

Package

6502

Source

cpu.lisp (file)

Special Variable: *opcode-meta*

A mapping of opcodes to metadata lists.

Package

6502

Source

cpu.lisp (file)

5.1.2 Macros

Macro: defenum NAME (&rest KEYS)

Define a function named %NAME, that takes KEY as an arg and returns the index of KEY. KEYS should be scalar values.

Package

6502

Source

cpu.lisp (file)

Macro: status-bit KEY

Test if KEY is set in the status register. KEY should be a keyword.

Package

6502

Source

cpu.lisp (file)

5.1.3 Functions

Function: absolute CPU

Function: (setf absolute) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: absolute-x CPU

Function: (setf absolute-x) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: absolute-y CPU

Function: (setf absolute-y) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: accumulator CPU

Function: (setf accumulator) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: app-path PATH &rest ARGS

Package

6502-conf

Source

/home/quickref/quicklisp/dists/quicklisp/software/cl-6502-20150923-git/cl-6502.asd

Function: bytevector SIZE

Return an array of the given SIZE with element-type u8.

Package

6502

Source

cpu.lisp (file)

Function: cpu-ar INSTANCE

Function: (setf cpu-ar) VALUE INSTANCE

Package

6502

Source

cpu.lisp (file)

Function: cpu-cc INSTANCE

Function: (setf cpu-cc) VALUE INSTANCE

Package

6502

Source

cpu.lisp (file)

Function: cpu-pc INSTANCE

Function: (setf cpu-pc) VALUE INSTANCE

Package

6502

Source

cpu.lisp (file)

Function: cpu-sp INSTANCE

Function: (setf cpu-sp) VALUE INSTANCE

Package

6502

Source

cpu.lisp (file)

Function: cpu-sr INSTANCE

Function: (setf cpu-sr) VALUE INSTANCE

Package

6502

Source

cpu.lisp (file)

Function: cpu-xr INSTANCE

Function: (setf cpu-xr) VALUE INSTANCE

Package

6502

Source

cpu.lisp (file)

Function: cpu-yr INSTANCE

Function: (setf cpu-yr) VALUE INSTANCE

Package

6502

Source

cpu.lisp (file)

Function: current-instruction CPU &optional PRINT-P

Return a list representing the current instruction. If PRINT-P is non-nil, print the current address and instruction and return NIL.

Package

6502

Source

disassemble.lisp (file)

Function: disasm START END

Disassemble memory from START to END.

Package

6502

Source

disassemble.lisp (file)

Function: disasm-to-list START END

Disassemble a given region of memory into a sexp-based format.

Package

6502

Source

disassemble.lisp (file)

Function: disasm-to-str START END

Call DISASM with the provided args and return its output as a string.

Package

6502

Source

disassemble.lisp (file)

Function: execute CPU

Step the CPU until a BRK instruction.

Package

6502

Source

utils.lisp (file)

Function: get-byte ADDRESS

Get a byte from RAM at the given ADDRESS.

Package

6502

Source

cpu.lisp (file)

Writer

(setf get-byte) (function)

Function: (setf get-byte) NEW-VAL ADDRESS

Set ADDRESS in *ram* to NEW-VAL.

Package

6502

Source

cpu.lisp (file)

Reader

get-byte (function)

Function: get-range START &optional END

Get a range of bytes from RAM, starting from START and stopping at END if provided.

Package

6502

Source

cpu.lisp (file)

Writer

(setf get-range) (function)

Function: (setf get-range) BYTEVECTOR START

Replace the contents of RAM, starting from START with BYTEVECTOR.

Package

6502

Source

cpu.lisp (file)

Reader

get-range (function)

Function: get-word ADDRESS &optional WRAP-P

Get a word from RAM starting at the given ADDRESS.

Package

6502

Source

cpu.lisp (file)

Writer

(setf get-word) (function)

Function: (setf get-word) NEW-VAL ADDRESS

Set ADDRESS and (1+ ADDRESS) in *ram* to NEW-VAL, little endian ordering.

Package

6502

Source

cpu.lisp (file)

Reader

get-word (function)

Function: immediate CPU

Function: (setf immediate) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: implied CPU

Function: (setf implied) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: indirect CPU

Function: (setf indirect) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: indirect-x CPU

Function: (setf indirect-x) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: indirect-y CPU

Function: (setf indirect-y) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: jit-step CPU PC

If the current block has been JIT compiled, run it, otherwise JIT compile it.

Package

6502

Source

jit.lisp (file)

Function: make-cpu &key (PC PC) (SP SP) (SR SR) (XR XR) (YR YR) (AR AR) (CC CC)

Package

6502

Source

cpu.lisp (file)

Function: relative CPU

Function: (setf relative) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: step-cpu CPU OPCODE

Step the CPU through the next OPCODE.

Package

6502

Source

utils.lisp (file)

Function: wrap-byte VALUE

Wrap VALUE so it conforms to (typep value ’u8), i.e. a single byte.

Package

6502

Source

cpu.lisp (file)

Function: wrap-word VALUE

Wrap VALUE so it conforms to (typep value ’u16), i.e. a machine word.

Package

6502

Source

cpu.lisp (file)

Function: zero-page CPU

Function: (setf zero-page) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: zero-page-x CPU

Function: (setf zero-page-x) VALUE CPU

Package

6502

Source

addressing.lisp (file)

Function: zero-page-y CPU

Function: (setf zero-page-y) VALUE CPU

Package

6502

Source

addressing.lisp (file)

5.1.4 Generic functions

Generic Function: asm SOURCE &optional INIT-ENV ORG-START

Assemble SOURCE into a bytevector and return it.

Package

6502

Source

assemble.lisp (file)

Methods

Method: asm (SOURCE string) &optional INIT-ENV ORG-START

Method: asm (SOURCE list) &optional INIT-ENV ORG-START

Generic Function: nmi OBJ

Generate a non-maskable interrupt. Used for vblanking in NES.

Package

6502

Source

cpu.lisp (file)

Methods

Method: nmi OBJ

Generic Function: reader MODE

Return a Perl-compatible regex suitable for parsing MODE.

Package

6502

Source

addressing.lisp (file)

Methods

Method: reader (MODE (eql relative))

Method: reader (MODE (eql indirect-y))

Method: reader (MODE (eql indirect-x))

Method: reader (MODE (eql indirect))

Method: reader (MODE (eql absolute-y))

Method: reader (MODE (eql absolute-x))

Method: reader (MODE (eql absolute))

Method: reader (MODE (eql zero-page-y))

Method: reader (MODE (eql zero-page-x))

Method: reader (MODE (eql zero-page))

Method: reader (MODE (eql immediate))

Method: reader (MODE (eql accumulator))

Method: reader (MODE (eql implied))

Method: reader MODE

Generic Function: reset OBJ

Reset the OBJ to an initial state.

Package

6502

Source

cpu.lisp (file)

Methods

Method: reset OBJ

Generic Function: writer MODE

Return a format string suitable for printing MODE.

Package

6502

Source

addressing.lisp (file)

Methods

Method: writer (MODE (eql relative))

Method: writer (MODE (eql indirect-y))

Method: writer (MODE (eql indirect-x))

Method: writer (MODE (eql indirect))

Method: writer (MODE (eql absolute-y))

Method: writer (MODE (eql absolute-x))

Method: writer (MODE (eql absolute))

Method: writer (MODE (eql zero-page-y))

Method: writer (MODE (eql zero-page-x))

Method: writer (MODE (eql zero-page))

Method: writer (MODE (eql immediate))

Method: writer (MODE (eql accumulator))

Method: writer (MODE (eql implied))

Method: writer MODE

5.1.5 Structures

Structure: cpu ()

A 6502 CPU with an extra slot for tracking the cycle count/clock ticks.

Package

6502

Source

cpu.lisp (file)

Direct superclasses

structure-object (structure)

Direct methods

initialize-instance (method)

Direct slots

Slot: pc

Type

|6502|:u16

Initform

65532

Readers

cpu-pc (function)

Writers

(setf cpu-pc) (function)

Slot: sp

Type

|6502|:u8

Initform

253

Readers

cpu-sp (function)

Writers

(setf cpu-sp) (function)

Slot: sr

Type

|6502|:u8

Initform

36

Readers

cpu-sr (function)

Writers

(setf cpu-sr) (function)

Slot: xr

Type

|6502|:u8

Initform

0

Readers

cpu-xr (function)

Writers

(setf cpu-xr) (function)

Slot: yr

Type

|6502|:u8

Initform

0

Readers

cpu-yr (function)

Writers

(setf cpu-yr) (function)

Slot: ar

Type

|6502|:u8

Initform

0

Readers

cpu-ar (function)

Writers

(setf cpu-ar) (function)

Slot: cc

Type

fixnum

Initform

0

Readers

cpu-cc (function)

Writers

(setf cpu-cc) (function)

5.1.6 Types

Type: u16 ()

Package

6502

Source

cpu.lisp (file)

Type: u8 ()

Package

6502

Source

cpu.lisp (file)

5.2 Internal definitions

5.2.1 Constants

Constant: +max-byte+

Package

6502

Source

assemble.lisp (file)

Constant: +relative-branch-size-byte+

Package

6502

Source

assemble.lisp (file)

5.2.2 Special variables

Special Variable: *address-modes*

A list of all the 6502 Address Modes.

Package

6502

Source

addressing.lisp (file)

Special Variable: *basedir*

Package

6502-conf

Source

/home/quickref/quicklisp/dists/quicklisp/software/cl-6502-20150923-git/cl-6502.asd

Special Variable: *jit-cache*

The JIT’s hot code cache. Currently never invalidated.

Package

6502

Source

jit.lisp (file)

Special Variable: *opcode-funs*

The opcode lambdas used during emulation.

Package

6502

Source

cpu.lisp (file)

Special Variable: *ram*

A lovely hunk of bytes.

Package

6502

Source

cpu.lisp (file)

Special Variable: +absolute-modes+

Package

6502

Source

assemble.lisp (file)

Special Variable: +zero-page-modes+

Package

6502

Source

assemble.lisp (file)

5.2.3 Macros

Macro: branch-if PREDICATE

Take a Relative branch if PREDICATE is true, otherwise increment the PC.

Package

6502

Source

cpu.lisp (file)

Macro: defaddress NAME (&key READER WRITER CPU-REG) &body BODY

Define an Addressing Mode, NAME, with READER and WRITER methods that take NAME as a symbol and return a regex or format expression, respectively, and a function and setf function to get and set the data pointed to by the given mode.

Package

6502

Source

addressing.lisp (file)

Macro: defasm NAME (&key DOCS RAW-P TRACK-PC) MODES &body BODY

Define a 6502 instruction NAME, storing its DOCS and metadata in *opcode-meta*, and a lambda that executes BODY in *opcode-funs*. Within BODY, the functions GETTER and SETTER can be used to get and set values for the current addressing mode, respectively. TRACK-PC can be passed nil to disable program counter updates for branching/jump operations. If RAW-P is true, GETTER will return the mode’s address directly, otherwise it will return the byte at that address. MODES is a list of opcode metadata lists: (opcode cycles bytes mode).

Package

6502

Source

cpu.lisp (file)

Macro: resolve-byte PLACE ENV

Given a place and an environment, if that place is a function, call that function with the environment and assign the result to the place.

Package

6502

Source

assemble.lisp (file)

Macro: set-flags-if &rest FLAG-PREDS

Takes any even number of arguments where the first is a keyword denoting a status bit and the second is a funcallable predicate that takes no arguments. It will set each flag to 1 if its predicate is true, otherwise 0.

Package

6502

Source

cpu.lisp (file)

Macro: set-status-bit KEY NEW-VAL

Set bit KEY in the status reg to NEW-VAL. KEY should be a keyword.

Package

6502

Source

cpu.lisp (file)

Macro: with-disasm (START END &key OP) &body BODY

Loop from START to END, passing each instruction to OP and execute BODY. OP is PRINT-INSTRUCTION by default. Within BODY, the return value of OP is bound to RESULT and the length of the instruction in bytes is bound to STEP.

Package

6502

Source

disassemble.lisp (file)

5.2.4 Functions

Function: %status-bit KEY

Package

6502

Source

cpu.lisp (file)

Function: arg-formatter ARG MODE

Given an instruction’s ARG, format it for display using the MODE’s WRITER.

Package

6502

Source

disassemble.lisp (file)

Function: assemble-code-block CODE-BLOCK &optional INIT-ENV ORG-START

Given a list of instructions, assemble each to a byte vector.

Package

6502

Source

assemble.lisp (file)

Function: assemble-instruction INSTRUCTION PC ENV

Given an instruction, and the current program counter, fill the environment with any labels and assemble instruction to a list of bytes.

Package

6502

Source

assemble.lisp (file)

Function: bytes-to-keyword-syntax BYTES MODE

Take BYTES and a MODE and return our assembly representation of the arguments.

Package

6502

Source

disassemble.lisp (file)

Function: copy-cpu INSTANCE

Package

6502

Source

cpu.lisp (file)

Function: copy-instruction INSTANCE

Package

6502

Source

assemble.lisp (file)

Function: cpu-p OBJECT

Package

6502

Source

cpu.lisp (file)

Function: decide-address-mode INSTRUCTION ENV

Finds the desired address mode, matching what the opcode allows to what was parsed from the operand’s syntax.

Package

6502

Source

assemble.lisp (file)

Function: disasm-ins INDEX &optional DISASM-OP

Lookup the metadata for the instruction at INDEX and pass it to DISASM-OP for formatting and display, returning the instruction length.

Package

6502

Source

disassemble.lisp (file)

Function: fetch-expression STREAM

Fetches an expression from the stream, either a term or a term plus another.

Package

6502

Source

parser.lisp (file)

Function: fetch-label STREAM

Fetches a label from the stream, or returns nil.

Package

6502

Source

parser.lisp (file)

Function: fetch-literal STREAM

Fetches a literal value from the stream and returns it as an alist containing the integer value and address mode, or returns nil.

Package

6502

Source

parser.lisp (file)

Function: fetch-name STREAM

Fetches a name from the stream, or returns nil.

Package

6502

Source

parser.lisp (file)

Function: fetch-opcode STREAM

Fetches an opcode from the stream as a keyword, or returns nil.

Package

6502

Source

parser.lisp (file)

Function: fetch-operand STREAM

Fetches the operand, returning its numerical value and possible address-modes.

Package

6502

Source

parser.lisp (file)

Function: fetch-term STREAM

Fetches a literal or name from the stream, or returns nil.

Package

6502

Source

parser.lisp (file)

Function: find-opcode OPCODE MODE

Finds an opcode matching OPCODE and MODE, raising ILLEGAL-OPCODE otherwise.

Package

6502

Source

assemble.lisp (file)

Function: get-basic-block CPU

Get the opcodes from the current PC to the next branch.

Package

6502

Source

jit.lisp (file)

Function: get-opcode-address-modes OPCODE

Given an opcode, return the possible address modes for that operation.

Package

6502

Source

assemble.lisp (file)

Function: instruction-address-mode INSTANCE

Function: (setf instruction-address-mode) VALUE INSTANCE

Package

6502

Source

assemble.lisp (file)

Function: instruction-label INSTANCE

Function: (setf instruction-label) VALUE INSTANCE

Package

6502

Source

assemble.lisp (file)

Function: instruction-opcode INSTANCE

Function: (setf instruction-opcode) VALUE INSTANCE

Package

6502

Source

assemble.lisp (file)

Function: instruction-p OBJECT

Package

6502

Source

assemble.lisp (file)

Function: instruction-value INSTANCE

Function: (setf instruction-value) VALUE INSTANCE

Package

6502

Source

assemble.lisp (file)

Function: jit-block OPCODES

Given a list of opcodes, JIT compile an equivalent function.

Package

6502

Source

jit.lisp (file)

Function: list-to-instructions INSTRUCTIONS

Given a list of assembly tuples, convert them to instructions.

Package

6502

Source

assemble.lisp (file)

Function: make-and-resolve-byte OPERAND PC TYPE ENV

Given an operand, convert it to a byte, resolving any delayed functions.

Package

6502

Source

assemble.lisp (file)

Function: make-byte VALUE PC TYPE

Given an integer, return a single byte for the required type. Given a label, return a delayed function to calculate the same, once labels are defined.

Package

6502

Source

assemble.lisp (file)

Function: make-getter NAME MODE RAW-P

Generate an appropriate GETTER for NAME based on RAW-P and whether or not it is a register shift operation.

Package

6502

Source

addressing.lisp (file)

Function: make-instruction &key (LABEL LABEL) (OPCODE OPCODE) (ADDRESS-MODE ADDRESS-MODE) (VALUE VALUE)

Package

6502

Source

assemble.lisp (file)

Function: make-stream TEXT

Make a string displaced onto the given text.

Package

6502

Source

parser.lisp (file)

Function: match-opcode-data DATA OPCODE &optional ADDRESS-MODE

Returns whether the asm metadata matches the given opcode, and address-mode if it is provided.

Package

6502

Source

assemble.lisp (file)

Function: match-operand-address-modes STREAM

Matches the stream against all address-mode readers, returning those that match, as well as the positions where the match occurs.

Package

6502

Source

parser.lisp (file)

Function: maybe-update-cycle-count CPU ADDRESS &optional START

If ADDRESS crosses a page boundary, add an extra cycle to CPU’s count. If START is provided, test that against ADDRESS. Otherwise, use the absolute address.

Package

6502

Source

cpu.lisp (file)

Function: operand-possible-modes-and-value STREAM

Returns all matching address-modes for the operand, along with positions where the match occurs.

Package

6502

Source

parser.lisp (file)

Function: overflow-p RESULT REG MEM

Checks whether the sign of RESULT is found in the signs of REG or MEM.

Package

6502

Source

cpu.lisp (file)

Function: parse-code TEXT

Parses the assembly source text and returns the assembled code as a list of alists.

Package

6502

Source

parser.lisp (file)

Function: parse-line TEXT

Converts a line of text into an instruction representing the assembly code.

Package

6502

Source

parser.lisp (file)

Function: print-instruction BYTES INDEX NAME DOCS MODE

Format the instruction at INDEX and its operands for display.

Package

6502

Source

disassemble.lisp (file)

Function: process-args VALUE ADDRESS-MODE PC

Given the operand value, address-mode, and program counter, return a list of assembled bytes, using delayed functions for labels or expressions.

Package

6502

Source

assemble.lisp (file)

Function: rotate-byte INTEGER COUNT CPU

Rotate the bits of INTEGER by COUNT. If COUNT is negative, rotate right.

Package

6502

Source

cpu.lisp (file)

Function: sexpify-instruction BYTES INDEX NAME DOCS MODE

Given BYTES and metadata, return a sexp-format representation of it.

Package

6502

Source

disassemble.lisp (file)

Function: skip-white-space STREAM

Fetches white space from the stream, ignores it and returns the stream.

Package

6502

Source

parser.lisp (file)

Function: stack-pop CPU

Pop the value pointed to by the SP and increment the SP.

Package

6502

Source

cpu.lisp (file)

Function: stack-pop-word CPU

Pop a 16-bit word off the stack.

Package

6502

Source

cpu.lisp (file)

Function: stack-push VALUE CPU

Push the byte VALUE on the stack and decrement the SP.

Package

6502

Source

cpu.lisp (file)

Function: stack-push-word VALUE CPU

Push the 16-bit word VALUE onto the stack.

Package

6502

Source

cpu.lisp (file)

Function: strip-comment TEXT

Removes comment and white space from end of string.

Package

6502

Source

parser.lisp (file)

Function: substream-advance STREAM START END

Set the stream to a substream at START positions ahead and finishing at END position.

Package

6502

Source

parser.lisp (file)

Function: transform-sexp-syntax SEXP-TOKEN

Given a SEXP-token using an indirect, *.x or *.y addressing mode, transform it to use the classic string assembly syntax.

Package

6502

Source

assemble.lisp (file)

Function: try-fetch STREAM REGEX

If the stream begins with a regex match, returns the matched text and move the stream past it. Otherwise, returns nil.

Package

6502

Source

parser.lisp (file)

Function: tuple-to-instruction OPCODE &optional OPERAND

Given an opcode and value, as symbols, convert them to an instruction.

Package

6502

Source

assemble.lisp (file)

Function: wrap-page ADDRESS

Wrap the given ADDRESS, ensuring that we don’t cross a page boundary. e.g. If we (get-word address).

Package

6502

Source

cpu.lisp (file)

Function: zero-page-address ADDR ENV

Returns whether the address is a zero page access.

Package

6502

Source

assemble.lisp (file)

5.2.5 Generic functions

Generic Function: line CONDITION

Package

6502

Methods

Method: line (CONDITION invalid-syntax)

Source

conditions.lisp (file)

Generic Function: mode CONDITION

Package

6502

Methods

Method: mode (CONDITION invalid-mode)

Source

conditions.lisp (file)

Generic Function: opcode CONDITION

Package

6502

Methods

Method: opcode (CONDITION illegal-opcode)

Source

conditions.lisp (file)

5.2.6 Conditions

Condition: illegal-opcode ()

Illegal opcodes are not currently implemented.

Package

6502

Source

conditions.lisp (file)

Direct superclasses

condition (condition)

Direct methods

opcode (method)

Direct slots

Slot: opcode

Initargs

:opcode

Readers

opcode (generic function)

Condition: invalid-mode ()

Only the 6502 addressing modes have readers and printers.

Package

6502

Source

conditions.lisp (file)

Direct superclasses

condition (condition)

Direct methods

mode (method)

Direct slots

Slot: mode

Initargs

:mode

Readers

mode (generic function)

Condition: invalid-syntax ()

Assembly must conform to the syntax in the README.

Package

6502

Source

conditions.lisp (file)

Direct superclasses

condition (condition)

Direct methods

line (method)

Direct slots

Slot: line

Initargs

:line

Readers

line (generic function)

5.2.7 Structures

Structure: instruction ()

Represents a single line of code.

Package

6502

Source

assemble.lisp (file)

Direct superclasses

structure-object (structure)

Direct slots

Slot: label

Type

(or null string)

Readers

instruction-label (function)

Writers

(setf instruction-label) (function)

Slot: opcode

Type

(or null symbol)

Readers

instruction-opcode (function)

Writers

(setf instruction-opcode) (function)

Slot: address-mode

Type

(or null symbol list)

Readers

instruction-address-mode (function)

Writers

(setf instruction-address-mode) (function)

Slot: value

Type

(or null |6502|:u16 list string)

Readers

instruction-value (function)

Writers

(setf instruction-value) (function)

Appendix A Indexes

A.1 Concepts

A.2 Functions