Using the 6502 Decoder on a Raspberry Pi 4
- Introduction
- Configuring the FX2 board
- Installing Raspberry Pi OS Lite
- Building the 6502 Decoder and fx2pipe
- Connecting the FX2 to the 6502
- Capturing Data
This guide covers building and running the 6502 decoder and fx2pipe capture software on a Raspberry Pi 4.
We have not tested other Pi Models, but it's very likely only the Raspberry Pi 4 will have suffient horse power to stream continuously from USB-2 to SD card without dropping packets.
This guide specifically covers capturing using hardware based on the Cyress FX2 (CY7C68013A) device. The developer board for this device is widely available for about £10. The most common type seen is the LCSoft CY7C68013A Mini Board.
The most widely used open source logic analyzer software is sigrok. The FX2 device is supported in sigrok, but this does not include ability to capture using an external clock. Using an external clock for appilcations like the 6502 decoder is critical for two reasons:
- it ensures the bus sample is taken at exactly the right point in the bus cycle
- it minimises the amount of data captured, to just one sample per bus cycle
To capture using an external clock requires the use of a seperate program, called fx2pipe, which uses libusb to talk to the FX2 hardware directly. The sources for fx2pipe are included in the 6502Decoder repository, and this guide covers building this program for the Raspberry Pi.
Using the fx2pipe program and the FX2 hardware, it's possible to make 16-bit captures using an external clock of upto 12MHz. The amount of data that can be captured is essentially unlimited, as the FX2 supports continuous streaming over USB-2, to a file on the file system.
The original source of the fx2pipe software is:
The version included in the 6502 Decoder repository has slighly modified FX2 firmware:
- the reset sequence is more reliable at purging any existing data buffered in the FX2
- the capture clock edge defaults to the falling edge (suitable for the 6502)
- the capture clock edge can be switched to the rising edge using the -ofclk=i option
The FX2 developer boards typically have a jumper that configures the USB PID/VID of the board:
- with the jumper off, the board will use: 04b4:8613 (Cypress FX2)
- with the jumper on, the board will use the VID/PID programmed into the EEPROM, which can vary:
- 1D50:608D (Sigrok 16-bit capable FX2)
- 0925:3881 (Salea Logic 8-bit capabile FX2)
It's recommended you leave the jumper off.
If the board had two jumpers, the second one just enables LED, so it can be left off as well.
Initially the FX2 board should be disconnected from the Pi.
This guide assumes you are starting with a blank SD Card inserted in your PC's card reader.
Install the latest version of Raspberry Pi OS Lite (32-bit) using the Raspbery Pi Imager:
- Click on Operating System and choose the Raspberry Pi OS Lite (32 bit) which can be found under the Raspberry Pi OS (Other menu)
- Click on Storage and choose the the SD card you have just inserted
- Click on the "Cog" icon and
- Enter a hostname
- Enter a default user name and password
- Select your WiFi network (and if necessary enter the credentials)
- Click the check-box to enable remote SSH access
- Click Write
The process will take a few minutes, after which you will be promted to remove the SD Card
Setup the Pi as follows:
- insert the SD Card
- connect a USB keyboard
- connect a HDMI monitor
Power up the Pi, and wait a few minutes while it resizes the SD card and reboots a couple of times.
Once the system has booted, login over ssh, or on the console, and run the following command:
echo "blacklist usbtest" | sudo tee /etc/modprobe.d/blacklist-usbtest.conf
The prevents the Kernel's usbtest model from loading when the fx2 device is plugged in.
Start by installing the necessary dependencies:
sudo apt-get update
sudo apt-get install git sdcc libusb-dev
Then clone the 6502Decoder repository:
git clone https://github.com/hoglet67/6502Decoder.git
Build and install the decode6502 program:
cd 6502Decoder
./build.sh
sudo cp decode6502 /usr/local/bin
cd -
Build and install the fx2pipe program:
cd 6502Decoder/fx2pipe
./build.sh
sudo cp fx2pipe/fx2pipe /usr/local/bin
cd -
There are various ways this can be done:
- Using a 40-pin DIP clip (e.g. 3M) and DuPont cables (any machine)
- Using KenLowe's 40-pin DIP breakout board (any machine)
- Using DuPont cables on the Acorn Tube connector (Model B only)
- Using Myelin's FX2 Cartridge (Master, Electron or Model B)
It's not recommened to do this using individual grabbers, as they invariably fall off.
If you are buying a 40-pin DIP test clip, I recommend the 3M or Pomona brands:
- 3M 923690-40 (alloy)
- 3M 923739-40 (gold)
- Pomona DIP CLIP 4140-A
(avoid the 3M versions with "nail" heads as it's not possible to connect DuPont cables to them).
This guide assumes you have a 40-pin DIP clip.
Connect the FX2 device to the 40-pin DIP clip using short DuPont cables:
* 6502 pin 1 (GND) => GND
* 6502 pin 33 (D0) => PB0
* 6502 pin 32 (D1) => PB1
* 6502 pin 31 (D2) => PB2
* 6502 pin 30 (D3) => PB3
* 6502 pin 29 (D4) => PB4
* 6502 pin 28 (D5) => PB5
* 6502 pin 27 (D6) => PB6
* 6502 pin 26 (D7) => PB7
* 6502 pin 34 (Rnw) => PD0
* 6502 pin 7 (Sync) => PD1
* 6502 pin 2 (Rdy) => PD2
* 6502 pin 40 (nRST) => PD6
* 6502 pin 37 (Phi0) => RDY1 (sometimes labelled SLWR)
You also need to make one connection on the FX2 board itself to enable the external clock mode:
- GND -> PA4
Start with the target machine powered off and the FX2 board unplugged from the Pi.
Connect the 40-pin DIP clip (plus attached FX2 board) to the unpowered target machine.
Plug the FX2 board in to one of the USB-2 ports on the Raspberry Pi.
Make sure the power switch on the FX board is depressed.
Run the following command on the Raspberry Pi:
sudo fx2pipe -a -n=4M > capture1.bin
You should see fx2pipe start, but then hang waiting for the external clock to start.
Finally, switch on the target machine.
You should see fx2pipe continue, run for about a second, then exit.
The capture1.bin file should be ~4MB in size (16-bits for 1 second at 2MHz)
To test the capture file, try processing it through the 6502 Decoder:
decode6502 --machine=beeb --phi2= -ahiys capture1.bin > capture1.log
(the --machine option picks appropriate defaults for the specified machine)
If everything has worked, capture1.log should contain 6502 instructions:
???? : : RESET !! A=?? X=?? Y=?? SP=?? N=? V=? D=? I=1 Z=? C=?
D9CD : A9 40 : LDA #40 A=40 X=?? Y=?? SP=?? N=0 V=? D=? I=1 Z=0 C=?
D9CF : 8D 00 0D : STA 0D00 A=40 X=?? Y=?? SP=?? N=0 V=? D=? I=1 Z=0 C=?
D9D2 : 78 : SEI A=40 X=?? Y=?? SP=?? N=0 V=? D=? I=1 Z=0 C=?
D9D3 : D8 : CLD A=40 X=?? Y=?? SP=?? N=0 V=? D=0 I=1 Z=0 C=?
D9D4 : A2 FF : LDX #FF A=40 X=FF Y=?? SP=?? N=1 V=? D=0 I=1 Z=0 C=?
D9D6 : 9A : TXS A=40 X=FF Y=?? SP=FF N=1 V=? D=0 I=1 Z=0 C=?
D9D7 : AD 4E FE : LDA FE4E A=80 X=FF Y=?? SP=FF N=1 V=? D=0 I=1 Z=0 C=?
D9DA : 0A : ASL A A=00 X=FF Y=?? SP=FF N=0 V=? D=0 I=1 Z=1 C=1
D9DB : 48 : PHA A=00 X=FF Y=?? SP=FE N=0 V=? D=0 I=1 Z=1 C=1
D9DC : F0 09 : BEQ D9E7 A=00 X=FF Y=?? SP=FE N=0 V=? D=0 I=1 Z=1 C=1
D9E7 : A2 04 : LDX #04 A=00 X=04 Y=?? SP=FE N=0 V=? D=0 I=1 Z=0 C=1
D9E9 : 86 01 : STX 01 A=00 X=04 Y=?? SP=FE N=0 V=? D=0 I=1 Z=0 C=1
D9EB : 85 00 : STA 00 A=00 X=04 Y=?? SP=FE N=0 V=? D=0 I=1 Z=0 C=1
D9ED : A8 : TAY A=00 X=04 Y=00 SP=FE N=0 V=? D=0 I=1 Z=1 C=1
D9EE : 91 00 : STA (00),Y A=00 X=04 Y=00 SP=FE N=0 V=? D=0 I=1 Z=1 C=1
D9F0 : C5 01 : CMP 01 A=00 X=04 Y=00 SP=FE N=1 V=? D=0 I=1 Z=0 C=0
D9F2 : F0 09 : BEQ D9FD A=00 X=04 Y=00 SP=FE N=1 V=? D=0 I=1 Z=0 C=0
D9F4 : C8 : INY A=00 X=04 Y=01 SP=FE N=0 V=? D=0 I=1 Z=0 C=0
D9F5 : D0 F7 : BNE D9EE A=00 X=04 Y=01 SP=FE N=0 V=? D=0 I=1 Z=0 C=0
Any errors will be marked with "fail", so you can try grepping through the file:
grep -n fail capture1.log
A wide range of options are available in decode6502; see the build-in help:
decode6502 --help
The 6502 Decoder supports the following CPUs:
- 6502
- 65C02
- 65C02 with Rockwell extensions
- 65C816
- Arlet's 6502 FPGA core
The seperate 6809 Decoder supports the following CPUs:
- 6809
- 6809E
- 6309 (to be added in the future)
The seperate Z80 Decoder supports the following CPUs:
- Z80
- Z80 (Zilog varient)
- Z80 (NEC varient)
- Z80 (CMOS varient)