Awesome/awesome-copilot
1
0
Fork 0
mirror of https://github.com/github/awesome-copilot.git synced 2026-02-20 02:15:12 +00:00
Code Issues Packages Projects Releases Wiki Activity

add reference files for new skill legacy-circuit-mockups

Browse Source
This commit is contained in:
jhauga
2026-01-19 20:26:57 -05:00
parent 927594eab8
commit 9c5665cbec
9 changed files with 1989 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
skills/legacy-circuit-mockups/SKILL.md
View File

@@ -260,9 +260,17 @@ Detailed component specifications are available in the bundled reference files:
- [28256-eeprom.md](references/28256-eeprom.md) - AT28C256 EEPROM specification
- [6C62256.md](references/6C62256.md) - 62256 SRAM details
- [7400-series.md](references/7400-series.md) - TTL logic gate pinouts
- [assembly-compiler.md](references/assembly-compiler.md) - Assembly compiler specification
- [assembly-language.md](references/assembly-language.md) - Assembly language specification
- [basic-electronic-components.md](references/basic-electronic-components.md) - Resistors, capacitors, switches
- [breadboard.md](references/breadboard.md) - Breadboard specifications
- [common-breadboard-components.md](references/common-breadboard-components.md) - Comprehensive component reference
- [connecting-electronic-components.md](references/connecting-electronic-components.md) - Step-by-step build guides
- [emulator-28256-eeprom.md](references/emulator-28256-eeprom.md) - Emulating 28256-eeprom specification
- [emulator-6502.md](references/emulator-6502.md) - Emulating 6502 specification
- [emulator-6522.md](references/emulator-6522.md) - Emulating 6522 specification
- [emulator-6C62256.md](references/emulator-6C62256.md) - Emulating 6C62256 specification
- [emulator-lcd.md](references/emulator-lcd.md) - Emulating a LCD specification
- [lcd.md](references/lcd.md) - LCD display interfacing
- [minipro.md](references/minipro.md) - EEPROM programmer usage
- [t48eeprom-programmer.md](references/t48eeprom-programmer.md) - T48 programmer reference

258
skills/legacy-circuit-mockups/references/assembly-compiler.md Normal file
View File

@@ -0,0 +1,258 @@
# 6502 SBC Assembly Compilation & ROM Build Specification
## Overview
This document defines a **complete specification for compiling 6502 assembly language** for a single-board computer consisting of:
* **MOS 6502 CPU**
* **MOS 6522 VIA**
* **AS6C62256 (32 KB SRAM)**
* **AT28C256 (32 KB EEPROM / ROM)**
* **DFRobot FIT0127 (HD44780-compatible 16x2 LCD)**
The focus is on **toolchain behavior, memory layout, ROM construction, and firmware conventions**, not electrical wiring.
---
## Target System Architecture
### Memory Map (Canonical)
```
$0000-$00FF Zero Page (RAM)
$0100-$01FF Stack (RAM)
$0200-$7FFF General RAM (AS6C62256)
$8000-$8FFF 6522 VIA I/O space
$9000-$FFFF ROM (AT28C256)
```
> Address decoding may mirror devices; assembler assumes this canonical layout.
---
## ROM Organization (AT28C256)
| Address | Purpose |
| ----------- | -------------------- |
| $9000-$FFEF | Program code + data |
| $FFF0-$FFF9 | Optional system data |
| $FFFA-$FFFB | NMI vector |
| $FFFC-$FFFD | RESET vector |
| $FFFE-$FFFF | IRQ/BRK vector |
ROM image size: **32,768 bytes**
---
## Reset & Startup Convention
On reset:
1. CPU fetches RESET vector at `$FFFC`
2. Code initializes stack pointer
3. Zero-page variables initialized
4. VIA configured
5. LCD initialized
6. Main program entered
---
## Assembler Requirements
Assembler **MUST** support:
* `.org` absolute addressing
* Symbolic labels
* Binary output (`.bin`)
* Little-endian word emission
* Zero-page optimization
Recommended assemblers:
* **ca65** (cc65 toolchain)
* **vasm6502**
* **64tass**
---
## Assembly Source Structure
```asm
;---------------------------
; Reset Vector Entry Point
;---------------------------
.org $9000
RESET:
sei
cld
ldx #$FF
txs
jsr init_via
jsr init_lcd
MAIN:
jsr lcd_print
jmp MAIN
```
---
## Vector Table Definition
```asm
.org $FFFA
.word nmi_handler
.word RESET
.word irq_handler
```
---
## 6522 VIA Programming Model
### Register Map (Base = $8000)
| Offset | Register |
| ------ | -------- |
| $0 | ORB |
| $1 | ORA |
| $2 | DDRB |
| $3 | DDRA |
| $4 | T1CL |
| $5 | T1CH |
| $6 | T1LL |
| $7 | T1LH |
| $8 | T2CL |
| $9 | T2CH |
| $B | ACR |
| $C | PCR |
| $D | IFR |
| $E | IER |
---
## LCD Interface Convention
### LCD Wiring Assumption
| LCD | VIA |
| ----- | ------- |
| D4-D7 | PB4-PB7 |
| RS | PA0 |
| E | PA1 |
| R/W | GND |
4-bit mode assumed.
---
## LCD Initialization Sequence
```asm
lcd_init:
lda #$33
jsr lcd_cmd
lda #$32
jsr lcd_cmd
lda #$28
jsr lcd_cmd
lda #$0C
jsr lcd_cmd
lda #$06
jsr lcd_cmd
lda #$01
jsr lcd_cmd
rts
```
---
## LCD Command/Data Interface
| Operation | RS | Data |
| --------- | -- | --------------- |
| Command | 0 | Instruction |
| Data | 1 | ASCII character |
---
## Zero Page Usage Convention
| Address | Purpose |
| ------- | ------------ |
| $00-$0F | Scratch |
| $10-$1F | LCD routines |
| $20-$2F | VIA state |
| $30-$FF | User-defined |
---
## RAM Usage (AS6C62256)
* Stack uses page `$01`
* All RAM assumed volatile
* No ROM shadowing
---
## Build Pipeline
### Step 1: Assemble
```bash
ca65 main.asm -o main.o
```
### Step 2: Link
```bash
ld65 -C rom.cfg main.o -o rom.bin
```
### Step 3: Pad ROM
Ensure `rom.bin` is exactly **32768 bytes**.
---
## EEPROM Programming
* Target device: **AT28C256**
* Programmer: **MiniPro / T48**
* Verify after write
---
## Emulator Expectations
Emulator must:
* Load ROM at `$9000-$FFFF`
* Emulate VIA I/O side effects
* Render LCD output
* Honor RESET vector
---
## Testing Checklist
* Reset vector execution
* VIA register writes
* LCD displays correct text
* Stack operations valid
* ROM image maps correctly
---
## References
* [MOS 6502 Programming Manual](http://archive.6502.org/datasheets/synertek_programming_manual.pdf)
* [MOS 6522 VIA Datasheet](http://archive.6502.org/datasheets/mos_6522_preliminary_nov_1977.pdf)
* [AT28C256 Datasheet](https://ww1.microchip.com/downloads/aemDocuments/documents/MPD/ProductDocuments/DataSheets/AT28C256-Industrial-Grade-256-Kbit-Paged-Parallel-EEPROM-Data-Sheet-DS20006386.pdf)
* [HD44780 LCD Datasheet](https://www.futurlec.com/LED/LCD16X2BLa.shtml)
* [cc65 Toolchain Docs](https://cc65.github.io/doc/cc65.html)
---
## Notes
This specification is intentionally **end-to-end**: from assembly source to EEPROM image to running hardware or emulator. It defines a stable contract so ROMs, emulators, and real SBCs behave identically.

226
skills/legacy-circuit-mockups/references/assembly-language.md Normal file
View File

@@ -0,0 +1,226 @@
# 6502 Assembly Language with AT28C256 EEPROM
A practical specification for writing **6502/65C02 assembly language programs** intended to be stored in and executed from an **AT28C256 (32 KB) parallel EEPROM** in single-board computers (SBCs) and retro systems.
---
## 1. Scope and Assumptions
This document assumes:
* A **6502-family CPU** (6502, 65C02, or compatible)
* Program code stored in an **AT28C256 (32K x 8) EEPROM**
* Memory-mapped I/O (e.g., 6522 VIA)
* Reset and interrupt vectors located in EEPROM
* External RAM mapped elsewhere (e.g., 62256 SRAM)
---
## 2. AT28C256 EEPROM Overview
| Parameter | Value |
| -------------- | ------------------- |
| Capacity | 32 KB (32768 bytes) |
| Address Lines | A0-A14 |
| Data Lines | D0-D7 |
| Access Time | ~150 ns |
| Supply Voltage | 5 V |
| Package | DIP-28 / PLCC |
### Typical Memory Map Usage
| Address Range | Usage |
| ------------- | ----------------------- |
| `$8000-$FFFF` | EEPROM (code + vectors) |
| `$FFFA-$FFFF` | Interrupt vectors |
---
## 3. 6502 Memory Map Example
```
$0000-$00FF Zero Page (RAM)
$0100-$01FF Stack
$0200-$7FFF RAM / I/O
$8000-$FFFF AT28C256 EEPROM
```
---
## 4. Reset and Interrupt Vectors
The 6502 reads vectors from the **top of memory**:
| Vector | Address | Description |
| ------- | ------------- | ---------------------- |
| NMI | `$FFFA-$FFFB` | Non-maskable interrupt |
| RESET | `$FFFC-$FFFD` | Reset entry point |
| IRQ/BRK | `$FFFE-$FFFF` | Maskable interrupt |
### Vector Definition Example
```asm
.org $FFFA
.word nmi_handler
.word reset
.word irq_handler
```
---
## 5. Assembly Program Structure
### Typical Layout
```asm
.org $8000
reset:
sei ; Disable IRQs
cld ; Clear decimal mode
ldx #$FF
txs ; Initialize stack
main:
jmp main
```
---
## 6. Essential 6502 Instructions
### Registers
| Register | Purpose |
| -------- | ---------------- |
| A | Accumulator |
| X, Y | Index registers |
| SP | Stack pointer |
| PC | Program counter |
| P | Processor status |
### Common Instructions
| Instruction | Function |
| ----------- | ---------------------- |
| LDA/STA | Load/store accumulator |
| LDX/LDY | Load index registers |
| JMP/JSR | Jump / subroutine |
| RTS | Return from subroutine |
| BEQ/BNE | Conditional branch |
| SEI/CLI | Disable/enable IRQ |
---
## 7. Addressing Modes (Common)
| Mode | Example | Notes |
| --------- | ------------- | ------------ |
| Immediate | `LDA #$01` | Constant |
| Zero Page | `LDA $00` | Fast |
| Absolute | `LDA $8000` | Full address |
| Indexed | `LDA $2000,X` | Tables |
| Indirect | `JMP ($FFFC)` | Vectors |
---
## 8. Writing Code for EEPROM Execution
### Key Considerations
* Code is **read-only at runtime**
* Self-modifying code not recommended
* Place jump tables and constants in EEPROM
* Use RAM for variables and stack
### Zero Page Variable Example
```asm
counter = $00
lda #$00
sta counter
```
---
## 9. Timing and Performance
* EEPROM access time must meet CPU clock requirements
* AT28C256 supports ~1 MHz comfortably
* Faster clocks may require wait states or ROM shadowing
---
## 10. Example: Simple LED Toggle (Memory-Mapped I/O)
```asm
PORTB = $6000
DDRB = $6002
.org $8000
reset:
sei
ldx #$FF
txs
lda #$FF
sta DDRB
loop:
lda #$FF
sta PORTB
jsr delay
lda #$00
sta PORTB
jsr delay
jmp loop
```
---
## 11. Assembling and Programming Workflow
1. Write source (`.asm`)
2. Assemble to binary
3. Pad or relocate to `$8000`
4. Program AT28C256 via T48 / minipro
5. Insert EEPROM and reset CPU
---
## 12. Assembler Directives (Common)
| Directive | Purpose |
| ---------- | --------------------------- |
| `.org` | Set program origin |
| `.byte` | Define byte |
| `.word` | Define word (little-endian) |
| `.include` | Include file |
| `.equ` | Constant definition |
---
## 13. Common Mistakes
| Issue | Result |
| -------------------------- | ------------------ |
| Missing vectors | CPU hangs on reset |
| Wrong `.org` | Code not executed |
| Using RAM addresses in ROM | Crash |
| Stack not initialized | Undefined behavior |
---
## 14. Reference Links
* [https://www.masswerk.at/6502/6502_instruction_set.html](https://www.masswerk.at/6502/6502_instruction_set.html)
* [https://www.nesdev.org/wiki/6502](https://www.nesdev.org/wiki/6502)
* [https://www.westerndesigncenter.com/wdc/documentation](https://www.westerndesigncenter.com/wdc/documentation)
* [https://en.wikipedia.org/wiki/MOS_Technology_6502](https://en.wikipedia.org/wiki/MOS_Technology_6502)
---
**Document Scope:** 6502 assembly stored in AT28C256 EEPROM
**Audience:** Retrocomputing, SBC designers, embedded hobbyists
**Status:** Stable reference

214
skills/legacy-circuit-mockups/references/breadboard.md Normal file
View File

@@ -0,0 +1,214 @@
# Solderless Breadboard
A practical Markdown specification and reference for **common solderless breadboards**, intended for electronics prototyping, education, and hobbyist development.
---
## 1. Overview
A **solderless breadboard** is a reusable prototyping platform that allows electronic components to be interconnected without soldering. Connections are made via internal spring clips.
### Typical Uses
* Rapid circuit prototyping
* Educational labs
* Logic and microcontroller experiments
* Low-power analog and digital circuits
### Not Suitable For
* High current (>1A)
* High voltage (>36V)
* RF / high-frequency designs
* Vibration-prone or permanent installations
---
## 2. Physical Construction
### Materials
* ABS or polystyrene body
* Phosphor bronze or nickel-plated spring contacts
* Adhesive backing (optional)
### Standard Hole Pitch
* **2.54 mm (0.1 in)** - compatible with DIP ICs and standard headers
### Contact Characteristics
| Parameter | Typical Value |
| ------------------ | ------------- |
| Contact resistance | 10-50 mΩ |
| Insertion cycles | ~5,000 |
| Wire gauge | 20-28 AWG |
---
## 3. Internal Electrical Connections
### Terminal Strips (Main Area)
* Rows of **5 interconnected holes**
* Horizontal connectivity
* Center trench isolates left and right halves
```
A B C D E | F G H I J
──────────┼──────────
Connected | Connected
```
### Power Rails
* Vertical buses on each side
* Often **split in the middle** (not always continuous)
* Usually marked **red (+)** and **blue (-)**
```
+ + + + + (may be split)
- - - - -
```
> ? Always verify continuity with a multimeter
---
## 4. Common Breadboard Sizes
| Type | Tie Points | Typical Use |
| --------- | ---------- | ------------------------ |
| Mini | 170 | Small test circuits |
| Half-size | 400 | Microcontroller projects |
| Full-size | 830 | Complex prototypes |
| Modular | Variable | Expandable systems |
---
## 5. Component Compatibility
### Compatible Components
* DIP ICs (300 mil, 600 mil)
* Axial resistors and diodes
* LEDs
* Tactile switches
* Jumper wires
* Pin headers
### Problematic Components
| Component | Issue |
| -------------------- | -------------------------- |
| TO-220 | Too wide / stress contacts |
| SMD | Requires adapter |
| Large electrolytics | Mechanical strain |
| High-power resistors | Heat |
---
## 6. Electrical Characteristics
### Typical Limits
| Parameter | Recommended Max |
| ------------------- | ------------------ |
| Voltage | 30-36 V |
| Current per contact | 500-1000 mA |
| Frequency | <1 MHz (practical) |
### Parasitics (Approximate)
| Type | Value |
| ----------- | ------------------- |
| Capacitance | 1-5 pF per node |
| Inductance | 10-20 nH per jumper |
---
## 7. Best Practices
### Power Distribution
* Run **ground and Vcc** to both sides
* Bridge split power rails if needed
* Decouple ICs with **0.1µF ceramic capacitors**
### Wiring
* Keep wires short and tidy
* Use color coding:
* Red: Vcc
* Black/Blue: GND
* Yellow/White: Signals
### IC Placement
* Place DIP ICs **straddling the center trench**
* Avoid forcing pins
---
## 8. Common Mistakes
| Mistake | Result |
| ----------------------------- | ------------------ |
| Assuming rails are continuous | Power loss |
| Long jumper wires | Noise, instability |
| No decoupling capacitors | Erratic behavior |
| Exceeding current limits | Melted contacts |
---
## 9. Testing & Debugging
### Continuity Check
* Verify rails and rows using a multimeter
### Signal Integrity Tips
* Avoid breadboards for:
* High-speed clocks
* ADC precision circuits
---
## 10. Typical Breadboard Layout Example
```
[ + ] [ - ] Power Rails
[ + ] [ - ]
A B C D E | F G H I J
A B C D E | F G H I J
A B C D E | F G H I J
```
---
## 11. Accessories
| Item | Purpose |
| ----------------------- | ----------------- |
| Jumper wire kits | Connections |
| Breadboard power module | 5V / 3.3V supply |
| Adhesive base | Mounting |
| Logic probe | Digital debugging |
---
## 12. Reference Links
* [https://en.wikipedia.org/wiki/Breadboard](https://en.wikipedia.org/wiki/Breadboard)
* [https://learn.sparkfun.com/tutorials/how-to-use-a-breadboard](https://learn.sparkfun.com/tutorials/how-to-use-a-breadboard)
* [https://www.allaboutcircuits.com/technical-articles/using-a-breadboard/](https://www.allaboutcircuits.com/technical-articles/using-a-breadboard/)
---
**Document Scope:** Solderless breadboard reference
**Audience:** Hobbyist, student, engineer
**Status:** Stable reference

245
skills/legacy-circuit-mockups/references/emulator-28256-eeprom.md Normal file
View File

@@ -0,0 +1,245 @@
# AT28C256 EEPROM Emulation Specification
## Overview
This document specifies how to **emulate the AT28C256 (32 KB Parallel EEPROM)** in a 6502-based system emulator. The goal is *behavioral accuracy* suitable for SBCs, monitors, and real ROM images, not just generic file-backed storage.
The AT28C256 is commonly used as **ROM** in 6502 systems, but it is *electrically writable* and has timing behaviors that differ from SRAM.
---
## Chip Summary
| Parameter | Value |
| -------------- | ---------------------- |
| Capacity | 32 KB (256 Kbit) |
| Organization | 32,768 x 8 |
| Address Lines | A0-A14 |
| Data Lines | D0-D7 |
| Supply Voltage | 5V |
| Typical Use | ROM / Firmware storage |
---
## Pin Definitions
| Pin | Name | Function |
| ------ | ------------- | ---------------------- |
| A0-A14 | Address | Byte address |
| D0-D7 | Data | Data bus |
| /CE | Chip Enable | Activates chip |
| /OE | Output Enable | Enables output drivers |
| /WE | Write Enable | Triggers write cycle |
| VCC | +5V | Power |
| GND | Ground | Reference |
---
## Read Cycle Behavior
A read occurs when:
```
/CE = 0
/OE = 0
/WE = 1
```
### Read Rules
* Address must be stable before `/OE` is asserted
* Data appears on D0-D7 after access time (ignored in most emulators)
* Output is **high-impedance** when `/OE = 1` or `/CE = 1`
### Emulator Behavior
```text
if CE == 0 and OE == 0 and WE == 1:
data_bus = memory[address]
else:
data_bus = Z
```
---
## Write Cycle Behavior
A write occurs when:
```
/CE = 0
/WE = 0
```
(`/OE` is typically HIGH during writes)
### Important EEPROM Characteristics
* Writes are **not instantaneous**
* Each write triggers an **internal programming cycle**
* During programming, reads may return undefined data
---
## Write Timing Model (Simplified)
### Real Hardware
| Parameter | Typical |
| --------------- | -------- |
| Byte Write Time | ~200 µs |
| Page Size | 64 bytes |
| Page Write Time | ~10 ms |
### Emulator Simplification Options
#### Option A - Instant Writes (Common)
* Write immediately updates memory
* No busy state
* Recommended for early emulators
#### Option B - Cycle-Based Busy State (Advanced)
* Track a "write in progress" timer
* Reads during write return last value or `0xFF`
* Writes ignored until cycle completes
---
## Page Write Emulation (Optional)
* Page size: **64 bytes**
* Writes within same page before timeout commit together
* Crossing page boundary wraps within page (hardware quirk)
Simplified rule:
```text
page_base = address & 0xFFC0
page_offset = address & 0x003F
```
---
## Write Protection Behavior
Some systems treat EEPROM as **ROM-only** after programming.
Emulator may support:
* Read-only mode (writes ignored)
* Programmable mode (writes allowed)
* Runtime toggle (simulates programming jumper)
---
## Power-Up State
* EEPROM retains contents
* No undefined data on power-up
Emulator should:
* Load contents from image file
* Preserve data across resets
---
## Bus Contention Rules
| Condition | Behavior |
| ------------------- | ----------------- |
| /CE = 1 | Data bus = Z |
| /OE = 1 | Data bus = Z |
| /WE = 0 and /OE = 0 | Undefined (avoid) |
Emulator may:
* Prioritize write
* Or flag invalid state
---
## Memory Mapping in 6502 Systems
Common layout:
```
$0000-$7FFF RAM
$8000-$FFFF AT28C256 EEPROM
```
### Reset Vector Usage
| Vector | Address |
| ------ | ----------- |
| RESET | $FFFC-$FFFD |
| NMI | $FFFA-$FFFB |
| IRQ | $FFFE-$FFFF |
---
## Emulator API Model
```c
typedef struct {
uint8_t memory[32768];
bool write_enabled;
bool busy;
uint32_t busy_cycles;
} AT28C256;
```
### Read
```c
uint8_t eeprom_read(addr);
```
### Write
```c
void eeprom_write(addr, value);
```
---
## Recommended Emulator Defaults
| Feature | Setting |
| ------------- | ----------- |
| Write Delay | Disabled |
| Page Mode | Disabled |
| Write Protect | Enabled |
| Persistence | File-backed |
---
## Testing Checklist
* Reset vector fetch
* ROM reads under normal execution
* Writes ignored in read-only mode
* Correct address masking (15 bits)
* No bus drive when disabled
---
## References
* [AT28C256 Datasheet (Microchip)](https://ww1.microchip.com/downloads/aemDocuments/documents/MPD/ProductDocuments/DataSheets/AT28C256-Industrial-Grade-256-Kbit-Paged-Parallel-EEPROM-Data-Sheet-DS20006386.pdf)
* [Ben Eater 6502 Computer Series](https://eater.net/6502)
* <https://www.youtube.com/watch?v=oO8_2JJV0B4>
* [6502.org Memory Mapping Notes](https://6502.co.uk/lesson/memory-map)
---
## Notes
This specification intentionally mirrors **real hardware quirks** while allowing emulator authors to choose between simplicity and accuracy. It is suitable for:
* Educational emulators
* SBC simulation
* ROM development workflows
* Integration with 6502 + 6522 + SRAM emulation

251
skills/legacy-circuit-mockups/references/emulator-6502.md Normal file
View File

@@ -0,0 +1,251 @@
# 6502 CPU Emulation Specification
A technical Markdown specification for **emulating the MOS Technology 6502 CPU family**, suitable for software emulators, educational tools, testing frameworks, and retrocomputing projects.
---
## 1. Scope
This specification describes the functional requirements for emulating:
* MOS 6502
* WDC 65C02 (where noted)
Out of scope:
* Cycle-exact analog behavior
* Physical bus contention
* Undocumented silicon defects (unless explicitly implemented)
---
## 2. CPU Overview
### Core Characteristics
| Feature | Value |
| ------------- | ------------- |
| Data width | 8-bit |
| Address width | 16-bit |
| Address space | 64 KB |
| Endianness | Little-endian |
| Clock | Single-phase |
---
## 3. Registers
| Register | Size | Description |
| -------- | ------ | -------------------------- |
| A | 8-bit | Accumulator |
| X | 8-bit | Index register |
| Y | 8-bit | Index register |
| SP | 8-bit | Stack pointer (page $01xx) |
| PC | 16-bit | Program counter |
| P | 8-bit | Processor status flags |
### Status Flags (P)
| Bit | Name | Meaning |
| --- | ---- | ----------------------------- |
| 7 | N | Negative |
| 6 | V | Overflow |
| 5 | - | Unused (always 1 when pushed) |
| 4 | B | Break |
| 3 | D | Decimal |
| 2 | I | IRQ disable |
| 1 | Z | Zero |
| 0 | C | Carry |
---
## 4. Memory Model
### Addressing
* 16-bit address bus (`$0000-$FFFF`)
* Byte-addressable
### Required Emulator Interfaces
```text
read(address) -> byte
write(address, byte)
```
### Stack Behavior
* Stack base: `$0100`
* Push: `write($0100 + SP, value); SP--`
* Pull: `SP++; value = read($0100 + SP)`
---
## 5. Reset and Interrupt Handling
### Reset Sequence
1. Set `I = 1`
2. Set `SP = $FD`
3. Clear `D`
4. Load `PC` from `$FFFC-$FFFD`
### Interrupt Vectors
| Interrupt | Vector Address |
| --------- | -------------- |
| NMI | `$FFFA-$FFFB` |
| RESET | `$FFFC-$FFFD` |
| IRQ/BRK | `$FFFE-$FFFF` |
---
## 6. Instruction Fetch-Decode-Execute Cycle
### Execution Loop (Conceptual)
```text
opcode = read(PC++)
decode opcode
fetch operands
execute instruction
update flags
increment cycles
```
---
## 7. Addressing Modes
| Mode | Example | Notes |
| ---------------- | ------------- | --------------------- |
| Immediate | `LDA #$10` | Constant |
| Zero Page | `LDA $20` | Wraps at $00FF |
| Absolute | `LDA $2000` | Full address |
| Indexed | `LDA $2000,X` | Optional page penalty |
| Indirect | `JMP ($FFFC)` | Page wrap bug |
| Indexed Indirect | `LDA ($20,X)` | ZP indexed |
| Indirect Indexed | `LDA ($20),Y` | ZP pointer |
---
## 8. Instruction Set Requirements
### Categories
* Load/Store
* Arithmetic (ADC, SBC)
* Logic (AND, ORA, EOR)
* Shifts & Rotates
* Branches
* Stack operations
* System control
### Decimal Mode (NMOS 6502)
* Applies to `ADC` and `SBC`
* Uses BCD arithmetic when `D = 1`
---
## 9. Flags Behavior Rules
| Instruction Type | Flags Affected |
| ---------------- | -------------- |
| Loads | N, Z |
| ADC/SBC | N, V, Z, C |
| CMP/CPX/CPY | N, Z, C |
| INC/DEC | N, Z |
| Shifts | N, Z, C |
---
## 10. Cycle Counting
### Cycle Accuracy Levels
| Level | Description |
| -------------------- | -------------------- |
| Functional | Correct results only |
| Instruction-accurate | Fixed cycle counts |
| Cycle-accurate | Page-cross penalties |
### Page Boundary Penalties
* Branch taken: +1 cycle
* Branch crosses page: +2 cycles
* Indexed load crosses page: +1 cycle
---
## 11. Known Hardware Quirks (NMOS 6502)
| Quirk | Description |
| ---------------- | ------------------------------- |
| JMP indirect bug | High byte wrap at page boundary |
| BRK sets B flag | Only when pushed |
| Unused flag bit | Always reads as 1 |
---
## 12. Illegal / Undocumented Opcodes (Optional)
* Many opcodes perform composite operations
* Behavior varies by silicon revision
* Should be disabled or explicitly enabled
---
## 13. Timing and Clocking
* One instruction executed per multiple clock cycles
* Emulator may execute instructions per host tick
* Cycle counter required for I/O timing
---
## 14. Integration with Peripherals
### Memory-Mapped I/O
```text
if address in IO range:
delegate to device
```
Examples:
* 6522 VIA
* UART
* Video hardware
---
## 15. Testing and Validation
### Recommended Test ROMs
* Klaus Dormann 6502 functional tests
* Interrupt and decimal mode tests
### Validation Checklist
* All instructions execute correctly
* Flags match reference behavior
* Vectors handled properly
* Stack operations correct
---
## 16. Reference Links
* [https://www.masswerk.at/6502/6502_instruction_set.html](https://www.masswerk.at/6502/6502_instruction_set.html)
* [https://www.nesdev.org/wiki/6502](https://www.nesdev.org/wiki/6502)
* [https://github.com/Klaus2m5/6502_65C02_functional_tests](https://github.com/Klaus2m5/6502_65C02_functional_tests)
* [https://en.wikipedia.org/wiki/MOS_Technology_6502](https://en.wikipedia.org/wiki/MOS_Technology_6502)
---
**Document Scope:** Software emulation of the 6502 CPU
**Audience:** Emulator developers, retrocomputing engineers
**Status:** Stable technical reference

288
skills/legacy-circuit-mockups/references/emulator-6522.md Normal file
View File

@@ -0,0 +1,288 @@
# 6522 VIA (Versatile Interface Adapter) Emulation Specification
A technical Markdown specification for **emulating the MOS Technology / WDC 6522 VIA**, suitable for 6502-family emulators, SBC simulators, and retrocomputing software environments.
---
## 1. Scope
This document defines the functional behavior required to emulate:
* MOS Technology 6522 VIA
* WDC 65C22 VIA (CMOS variant, where noted)
Out of scope:
* Analog electrical characteristics
* Bus contention and propagation delay
* Undocumented silicon race conditions
---
## 2. Chip Overview
### Core Features
| Feature | Description |
| ---------------- | ------------------------------------ |
| I/O Ports | Two 8-bit bidirectional ports (A, B) |
| Timers | Two programmable timers |
| Shift Register | 8-bit serial shift register |
| Interrupt System | Maskable, prioritized |
| Handshaking | CA1/CA2, CB1/CB2 control lines |
---
## 3. External Signals (Logical Model)
| Signal | Direction | Purpose |
| -------- | --------- | ------------------------ |
| PA0-PA7 | I/O | Port A |
| PB0-PB7 | I/O | Port B |
| CA1, CA2 | I/O | Control lines A |
| CB1, CB2 | I/O | Control lines B |
| IRQ | Output | Interrupt request to CPU |
| CS1, CS2 | Input | Chip select |
| R/W | Input | Read / write |
| RS0-RS3 | Input | Register select |
---
## 4. Register Map
Registers are selected using RS3-RS0.
| Address | Name | R/W | Description |
| ------- | ----------- | --- | -------------------------------- |
| 0 | ORB / IRB | R/W | Output/Input Register B |
| 1 | ORA / IRA | R/W | Output/Input Register A |
| 2 | DDRB | R/W | Data Direction Register B |
| 3 | DDRA | R/W | Data Direction Register A |
| 4 | T1C-L | R | Timer 1 Counter Low |
| 5 | T1C-H | R | Timer 1 Counter High |
| 6 | T1L-L | W | Timer 1 Latch Low |
| 7 | T1L-H | W | Timer 1 Latch High |
| 8 | T2C-L | R | Timer 2 Counter Low |
| 9 | T2C-H | R | Timer 2 Counter High |
| 10 | SR | R/W | Shift Register |
| 11 | ACR | R/W | Auxiliary Control Register |
| 12 | PCR | R/W | Peripheral Control Register |
| 13 | IFR | R/W | Interrupt Flag Register |
| 14 | IER | R/W | Interrupt Enable Register |
| 15 | ORA (no HS) | R/W | Output Register A (no handshake) |
---
## 5. Data Direction Registers
* Bit = 1  Output
* Bit = 0  Input
```text
output = ORx & DDRx
input = external & ~DDRx
```
---
## 6. Port Behavior
### Read
* Returns input pins for bits configured as input
* Returns output latch for bits configured as output
### Write
* Updates output latch only
* Actual pin value depends on DDR
---
## 7. Timers
### Timer 1 (T1)
* 16-bit down counter
* Can generate interrupts
* Optional PB7 toggle
### Timer 2 (T2)
* 16-bit down counter
* One-shot or pulse counting (CB1)
### Timer Emulation Rules
* Decrement once per CPU cycle
* Reload from latch when appropriate
* Set interrupt flag on underflow
---
## 8. Shift Register (SR)
Modes controlled via ACR:
* Disabled
* Shift in under CB1 clock
* Shift out under system clock
Emulator requirements:
* 8-bit shift
* Correct bit order
* Optional external clock handling
---
## 9. Control Registers
### Auxiliary Control Register (ACR)
Controls:
* Timer 1 mode
* Timer 2 mode
* Shift register mode
* PB7 behavior
### Peripheral Control Register (PCR)
Controls:
* CA1/CB1 edge sensitivity
* CA2/CB2 handshake / pulse / output modes
---
## 10. Interrupt System
### Interrupt Flag Register (IFR)
| Bit | Source |
| --- | -------------------------- |
| 0 | CA2 |
| 1 | CA1 |
| 2 | Shift Register |
| 3 | CB2 |
| 4 | CB1 |
| 5 | Timer 2 |
| 6 | Timer 1 |
| 7 | Any interrupt (logical OR) |
### Interrupt Enable Register (IER)
* Bit 7 = set/clear mode
* Bits 0-6 enable individual sources
### IRQ Logic
```text
IRQ = (IFR & IER & 0x7F) != 0
```
---
## 11. Handshaking Lines
### CA1 / CB1
* Edge-detect inputs
* Trigger interrupts
### CA2 / CB2
* Input or output
* Pulse or handshake modes
Emulator must:
* Track pin state
* Detect configured edges
---
## 12. Reset Behavior
On reset:
* DDRx = $00
* ORx = $00
* Timers stopped
* IFR cleared
* IER cleared
* IRQ inactive
---
## 13. Read/Write Side Effects
| Register | Side Effect |
| ----------- | ------------------------ |
| ORA/ORB | Clears handshake flags |
| T1C-H write | Loads and starts Timer 1 |
| IFR write | Clears written bits |
| IER write | Sets or clears enables |
---
## 14. Emulation Timing Levels
| Level | Description |
| -------------- | ------------------------- |
| Functional | Correct register behavior |
| Cycle-based | Timers tick per CPU cycle |
| Cycle-accurate | Matches real VIA timing |
---
## 15. Integration with 6502 Emulator
```text
CPU cycle  VIA tick  update timers  update IRQ
```
* VIA must be clocked in sync with CPU
* IRQ line sampled by CPU at instruction boundaries
---
## 16. Testing and Validation
### Recommended Tests
* VIA timer test ROMs
* Port read/write tests
* Interrupt priority tests
### Validation Checklist
* Timers count correctly
* IRQ asserts and clears properly
* DDR behavior correct
* Side effects implemented
---
## 17. Differences: 6522 vs 65C22 (Summary)
| Feature | 6522 | 65C22 |
| -------------- | ------ | -------- |
| Power | Higher | Lower |
| Decimal quirks | N/A | Fixed |
| Timer accuracy | NMOS | Improved |
---
## 18. Reference Links
* [https://www.westerndesigncenter.com/wdc/documentation](https://www.westerndesigncenter.com/wdc/documentation)
* [https://www.princeton.edu/~mae412/HANDOUTS/Datasheets/6522.pdf](https://www.princeton.edu/~mae412/HANDOUTS/Datasheets/6522.pdf)
* [https://www.nesdev.org/wiki/6522](https://www.nesdev.org/wiki/6522)
---
**Document Scope:** Software emulation of the 6522 VIA
**Audience:** Emulator developers, SBC designers
**Status:** Stable technical reference

233
skills/legacy-circuit-mockups/references/emulator-6C62256.md Normal file
View File

@@ -0,0 +1,233 @@
# AS6C62256 (32K x 8 SRAM) Emulation Specification
A technical Markdown specification for **emulating the AS6C62256 / 62256-family static RAM**, suitable for 6502-family emulators, SBC simulators, and memory subsystem modeling.
---
## 1. Scope
This document specifies functional behavior for emulating:
* Alliance Memory **AS6C62256**
* Compatible **62256 (32K x 8) SRAM** devices
Out of scope:
* Analog electrical timing margins
* Bus contention and signal rise/fall times
* Power consumption characteristics
---
## 2. Chip Overview
### Core Characteristics
| Feature | Value |
| -------------- | -------------------- |
| Memory Type | Static RAM (SRAM) |
| Capacity | 32,768 bytes (32 KB) |
| Data Width | 8-bit |
| Address Width | 15-bit (A0-A14) |
| Access Type | Asynchronous |
| Supply Voltage | 5 V (typical) |
---
## 3. External Signals (Logical Model)
| Signal | Direction | Purpose |
| ------ | --------- | -------------------------- |
| A0-A14 | Input | Address bus |
| D0-D7 | I/O | Data bus |
| CE# | Input | Chip enable (active low) |
| OE# | Input | Output enable (active low) |
| WE# | Input | Write enable (active low) |
> `#` indicates active-low signals.
---
## 4. Address Space Mapping
* Address range: `0x0000-0x7FFF`
* Address lines select one byte per address
### Typical 6502 System Mapping Example
| CPU Address Range | Device |
| ----------------- | -------------- |
| `$0000-$7FFF` | AS6C62256 SRAM |
| `$8000-$FFFF` | ROM / EEPROM |
---
## 5. Read and Write Behavior
### Read Cycle (Logical)
Conditions:
* `CE# = 0`
* `OE# = 0`
* `WE# = 1`
Behavior:
```text
D[7:0]  memory[A]
```
If `OE# = 1` or `CE# = 1`, data bus is **high-impedance**.
---
### Write Cycle (Logical)
Conditions:
* `CE# = 0`
* `WE# = 0`
Behavior:
```text
memory[A]  D[7:0]
```
* `OE#` is ignored during writes
* Write occurs on active WE#
---
## 6. Control Signal Priority
| CE# | WE# | OE# | Result |
| --- | --- | --- | --------------- |
| 1 | X | X | Disabled (Hi-Z) |
| 0 | 0 | X | Write |
| 0 | 1 | 0 | Read |
| 0 | 1 | 1 | Hi-Z |
---
## 7. Emulator Interface Requirements
An emulator must expose:
```text
read(address) -> byte
write(address, byte)
```
Internal storage:
```text
uint8_t ram[32768]
```
Address masking:
```text
address = address & 0x7FFF
```
---
## 8. Timing Model (Abstracted)
### Emulation Levels
| Level | Description |
| -------------- | ------------------------- |
| Functional | Instantaneous access |
| Cycle-based | Access per CPU cycle |
| Cycle-accurate | Honors enable transitions |
For most systems, **functional emulation** is sufficient.
---
## 9. Power and Data Retention
* SRAM contents persist as long as power is applied
* Emulator shall retain contents until explicitly reset
### Reset Behavior
* **No automatic clearing** on reset
* Memory contents undefined unless initialized
---
## 10. Bus Contention and Hi-Z Modeling (Optional)
Optional advanced behavior:
* Track when SRAM drives the data bus
* Detect illegal simultaneous writes
Most emulators may ignore Hi-Z state.
---
## 11. Error Conditions
| Condition | Emulator Response |
| -------------------- | ----------------------------- |
| Out-of-range address | Mask or ignore |
| Read when disabled | Return last bus value or 0xFF |
| Write when disabled | Ignore write |
---
## 12. Integration with 6502 Emulator
```text
CPU memory access
 address decode
 if in SRAM range:
AS6C62256.read/write
```
* SRAM access is typically single-cycle
* No wait states required
---
## 13. Testing and Validation
### Basic Tests
* Write/read patterns
* Boundary addresses ($0000, $7FFF)
* Randomized memory tests
### Validation Checklist
* Writes persist
* Reads return correct values
* Address wrapping correct
---
## 14. Common Mistakes
| Mistake | Result |
| --------------------- | --------------------------- |
| Clearing RAM on reset | Breaks software assumptions |
| Wrong address mask | Mirrored memory errors |
| Treating as ROM | Writes ignored |
---
## 15. Reference Links
* [Alliance Memory AS6C62256 Datasheet](https://www.alliancememory.com/wp-content/uploads/AS6C62256-23-March-2016-rev1.2.pdf)
* [https://en.wikipedia.org/wiki/Static_random-access_memory](https://en.wikipedia.org/wiki/Static_random-access_memory)
---
**Document Scope:** Software emulation of AS6C62256 SRAM
**Audience:** Emulator developers, retro SBC designers
**Status:** Stable technical reference

266
skills/legacy-circuit-mockups/references/emulator-lcd.md Normal file
View File

@@ -0,0 +1,266 @@
# DFRobot FIT0127 LCD Character Display Emulation Specification
## Overview
This document specifies how to **emulate the DFRobot FIT0127 LCD Character Display module**. FIT0127 is a **16x2 character LCD** compatible with the **HD44780 controller**, commonly used in 6502 and microcontroller breadboard systems.
The goal is **functional correctness** for SBC emulators, firmware testing, and UI visualization rather than electrical signal simulation.
---
## Module Summary
| Feature | Value |
| ---------------- | ----------------------- |
| Display Type | Character LCD |
| Resolution | 16 columns x 2 rows |
| Controller | HD44780-compatible |
| Interface | 8-bit or 4-bit parallel |
| Character Matrix | 5x8 dots |
| Supply Voltage | 5V |
---
## Pin Definitions
| Pin | Name | Function |
| ---- | ----- | ---------------- |
| 1 | GND | Ground |
| 2 | VCC | +5V |
| 3 | VO | Contrast control |
| 4 | RS | Register Select |
| 5 | R/W | Read / Write |
| 6 | E | Enable |
| 7-14 | D0-D7 | Data bus |
| 15 | A | Backlight + |
| 16 | K | Backlight - |
---
## Logical Registers
| RS | Register |
| -- | -------------------- |
| 0 | Instruction Register |
| 1 | Data Register |
---
## Instruction Set (Subset)
| Command | Code | Description |
| --------------- | ----------- | ------------------------- |
| Clear Display | `0x01` | Clears DDRAM, cursor home |
| Return Home | `0x02` | Cursor to home position |
| Entry Mode Set | `0x04-0x07` | Cursor direction |
| Display Control | `0x08-0x0F` | Display, cursor, blink |
| Cursor/Shift | `0x10-0x1F` | Shift cursor/display |
| Function Set | `0x20-0x3F` | Data length, lines |
| Set CGRAM Addr | `0x40-0x7F` | Custom chars |
| Set DDRAM Addr | `0x80-0xFF` | Cursor position |
---
## Internal Memory Model
### DDRAM (Display Data RAM)
* Size: 80 bytes
* Line 1 base: `0x00`
* Line 2 base: `0x40`
Emulator mapping:
```text
Row 0: DDRAM[0x00-0x0F]
Row 1: DDRAM[0x40-0x4F]
```
### CGRAM (Character Generator RAM)
* Stores up to 8 custom characters
* 8 bytes per character
---
## Data Write Cycle
A write occurs when:
```
RS = 1
R/W = 0
E: HIGH  LOW
```
### Emulator Behavior
* On falling edge of `E`, latch data
* Write data to DDRAM or CGRAM depending on address mode
* Auto-increment or decrement address based on entry mode
---
## Instruction Write Cycle
A command write occurs when:
```
RS = 0
R/W = 0
E: HIGH  LOW
```
---
## Read Cycle (Optional)
Reads are uncommon in hobby systems.
```
RS = 0/1
R/W = 1
E: HIGH
```
Emulator may simplify:
* Ignore reads entirely
* Or return busy flag + address counter
---
## Busy Flag Emulation
### Real Hardware
* Busy flag = D7
* Commands take 37-1520 µs
### Emulator Options
| Mode | Behavior |
| ---------- | ----------------- |
| Simplified | Always ready |
| Timed | Busy for N cycles |
Recommended default: **Always ready**
---
## Power-Up State
On reset:
* Display OFF
* Cursor OFF
* DDRAM cleared or undefined
* Address counter = 0
Emulator should:
* Clear DDRAM
* Set cursor to (0,0)
* Display enabled
---
## Cursor and Display Model
State variables:
```text
cursor_row
cursor_col
display_on
cursor_on
blink_on
```
Cursor moves automatically after writes based on entry mode.
---
## 4-bit vs 8-bit Interface
### 8-bit Mode
* Full byte transferred on D0-D7
### 4-bit Mode
* High nibble sent first
* Two enable pulses per byte
Emulator simplification:
* Accept full byte writes
* Ignore nibble timing
---
## Rendering Model (Emulator UI)
Recommended approach:
* Maintain 16x2 character buffer
* Render ASCII subset
* Substitute unsupported glyphs
* Optionally render custom CGRAM chars
---
## Emulator API Model
```c
typedef struct {
uint8_t ddram[80];
uint8_t cgram[64];
uint8_t addr;
bool display_on;
bool cursor_on;
bool blink_on;
uint8_t entry_mode;
} FIT0127_LCD;
```
---
## Common Wiring in 6502 Systems
```
VIA Port  LCD D4-D7 (4-bit mode)
RS  VIA bit
E  VIA bit
R/W  GND
```
---
## Testing Checklist
* Clear display command
* Cursor positioning via DDRAM addresses
* Sequential character writes
* Line wrap behavior
* Custom character display
---
## References
* [HD44780U Datasheet (Hitachi)](https://academy.cba.mit.edu/classes/output_devices/44780.pdf)
* [Ben Eater LCD Interface Notes](https://hackaday.io/project/174128-db6502/log/181838-adventures-with-hd44780-lcd-controller)
* [Ben Eater's 6502 Computer](https://github.com/tedkotz/be6502)
* [Build a 6502 Computer](https://eater.net/6502)
---
## Notes
This spec intentionally prioritizes **firmware-visible behavior** over electrical accuracy, making it ideal for:
* SBC emulators
* ROM and monitor development
* Automated testing of LCD output
* Educational CPU projects