HOWTO: use `ihex` and `go` on the Planck with assembly snippet

Here are the steps that I went through to use the new ihex and go words that Jonathan has provided for the Planck. My host computer is a Mac, so my notes are oriented to that environment.

  1. Change into your projects directory. Mine is called workspace: cd ~/workspace
  2. Get vasm: git clone Vasm seems much more appropriate for this sort of work than ca65, which seems oriented to producing entire ROMs full of code.
  3. cd vasm
  4. Compile the code with make CPU=6502 SYNTAX=oldstyle. This is covered in Ben Eater’s video number 3.
  5. This will create a binary called: vasm6502_oldstyle.
  6. Copy binary to /usr/local/bin or add ~/workspace/vasm to path.
  7. Edit assembly code in your favorite editor.
  8. Save code.
  9. Compile with vasm6502_oldstyle -wdc02 -L leds.list -Fbin leds.asm. Substitute the name of your file for leds.asm and leds.list
  10. This will create a listing file (leds.list) as well as a raw binary output file called a.out. Leds.list will help spot common assembly mistakes like leaving off the # before a label name that refers to a value. You can use the -o filename.bin argument if you don’t like a.out as a name.
  11. Now you need a tool to convert the a.out file, which is in a raw binary format, into Intel hex format so that it can be copied to the Planck to be run. That way, you don’t need to burn an entire 32K ROM just to experiment with a snippet of assembly language.
  12. Switch back to your projects directory: cd ~/workspace
  13. Install a binary to Intel hex converter: git clone
  14. cd bin2hex
  15. make
  16. Copy the bin2hex binary to /usr/local/bin/
  17. Switch back to the directory with a.out.
  18. Convert the bin file to ihex: bin2hex a.out leds.ihex 0x6000. In this example, I’ve named the output leds.ihex. I’ve also set the code to start at hex address 0x6000, which appears to be available on my Planck system. I just picked a location above the number given by hex here u. on the Planck. This may or may not be the correct way to do this. My suspicion is that go is probably meant to be used with the unallocated space on the RAM expansion. In any case, you can change the load point for the code when you create the ihex file, which is very cool.
  19. On the host computer, display the ihex file so that you can copy it to the Planck: cat leds.ihex
  20. Copy the displayed text.
  21. On the Planck, type ihex and hit enter. It will silently wait for your input. Paste it in. If everything goes smoothly, you’ll get a beep and an ok from the Planck machine, and it will echo the pasted code.
  22. To convince yourself that the bytes really were copied correctly, you can do hexdump -C a.out on the host computer. Dump the loaded file on the Planck computer with hex 6000 100 dump and you should be able to verify that the bytes are the same.
  23. Now you can run the assembly by typing hex 6000 go on the Planck. With my little assembly file, this almost works. I get a stack underflow error. There’s some sort of error I need to track down.

I hope this will help someone else as you are playing around with this little computer!