slithymatt/x16-assembly-tutorial

A tutorial for learning 65C02 Assembly Language using the Commander X16

x16-assembly-tutorial

A tutorial for learning 65C02 Assembly Language using the Commander X16.

This is a repo containing all the materials from my YouTube series. Available now are the following lessons:

• Lesson 1: The Basics
• Lesson 2: Addressing Modes
• Lesson 3: Branching and Subroutines
• Lesson 4: Arithmetic and Logic
• Lesson 5: The Stack
• Lesson 6: A Bit Advanced
• Lesson 7: The Rest
• Lesson 8: Meet the Kernal
• Lesson 9: Hello, VERA!
• Lesson 10: Interrupts
• Lesson 11: Advanced Math
• Lesson 12: Tiles
• Lesson 13: PSG Sound
• Lesson 14: Mouse and Joysticks
• Lesson 15: Bitmaps
• Lesson 16: All in the Timing
• Lesson 17: FM Synthesis
• Lesson 18: Sprites

More to come!

Each lesson has its own directory here. Please feel free to do what you want with these code examples - it is all free and open source.

Building with Windows (Cygwin)

The build toolchain for this project requires a GNU environment, which is natively available on most Linux and Unix (include Mac) platforms. For Windows, you will need a program called Cygwin that will provide a GNU userspace in Windows that will give you a Unix-like environment for development.

Installing and Configuring Cygwin

First, you will need to download the Cygwin setup program from here: https://cygwin.com/setup-x86_64.exe

When you run the program, it will ask you which packages you want to install. Make sure the following packages are selected:

• git
• gcc-core
• make

Then, when Cygwin is installed, open the Cygwin Terminal program (you can specify to have a shortcut put on your desktop during the install) and cd to whatever directory you want to maintain your workspace. In Cygwin, the drive letters are also second-level directories, so your C drive is /cygdrive/c/ and your D drive is /cygdrive/d/, etc. If my Windows username is Fred and I want to put a "workspace" directory in my profile alongside my "Documents" directory, I can do the following:

$ cd /cygdrive/c/Users/Fred
$ mkdir workspace
$ cd workspace

There, you can use git to clone this repository with the following command:

$ git clone https://github.com/SlithyMatt/x16-assembly-tutorial.git

You will also need to clone the cc65 repo:

$ git clone https://github.com/cc65/cc65.git

Now, you can first test your new build environment by building cc65:

$ cd cc65
$ make

This should create a "bin" subdirectory with all the cc65 tools you will need, like ca65.exe. You can either add this cc65/bin directory to your path, or add symbolic links within Cygwin in /usr/bin.

cc65 Option 1: Changing Path

Open up your Environment Variables control panel in your settings (you can find it by searching for "env"). Select the "Path" variable and click the "Edit..." button.

Then, in the editor dialog that pops up, add a new entry for your cc65/bin directory. You can find it by clicking on the "Browse..." button.

Then click the "OK" button. You should be all set to run the cc65 tools from anywhere on Windows. If your Cygwin Terminal was left open during this change, you will need to close it and reopen it for the new environment to take effect.

cc65 Option 2: Adding Symbolic Links

You can just add the cc65 tools that you need for the build as symbolic links to your Cygwin /usr/bin directory, which is already on the Cygwin bash path, but will not be on your general Windows path.

Simply create the following links (you don't need to worry about superuser privileges in Cygwin):

$ cd /usr/bin
$ ln -s /cygdrive/c/Users/Fred/workspace/cc65/bin/ca65.exe
$ ln -s /cygdrive/c/Users/Fred/workspace/cc65/bin/cc65.exe
$ ln -s /cygdrive/c/Users/Fred/workspace/cc65/bin/cl65.exe

Your environment should be all set now. You can go into any of the Lesson directories and build the code just as you have seen it in the videos.

Building with Debian/Ubuntu Linux

Chances are, you have most of what you need already in Linux, but to be sure, you can install all of the required packages in one command:

$ sudo apt-get install git build-essential

Then, you should create a workspace directory to hold all of your local repo clones, like ~/workspace.

$ cd
$ mkdir workspace
$ cd workspace

There, you can use git to clone this repository with the following command:

$ git clone https://github.com/SlithyMatt/x16-assembly-tutorial

You will also need to clone the cc65 repo:

$ git clone https://github.com/cc65/cc65.git

Now, you can first test your new build environment by building cc65:

$ cd cc65
$ make

This should create a "bin" subdirectory with all the cc65 tools you will need, like ca65.exe. You will need to add this directory to your PATH by adding the following line to ~/.bashrc:

export PATH=$PATH:$HOME/workspace/cc65/bin

To make this environment take hold, you will need to close and reopen your terminal. Then you can go into any of the Lesson directories and build the code just as you have seen it in the videos. Please note that if you already had the release build of cc65 installed that it will not work with the build scripts here, as they do not have X16 support built in. You will need to build the latest commit yourself. When you do this, make sure that you uninstall the release build of cc65 or at least remove it from your PATH. You should verify that the correct version is going to run with this simple command:

which cl65

If this does not print out the location of the version you just built, you need to get your PATH in the correct order.

Installing the Commander X16 Emulator

You can download pre-built binaries from the official website: https://www.commanderx16.com/forum/files/

Or, you can build the emulator and the ROM image yourself from the GitHub repos:

• https://github.com/commanderx16/x16-emulator
• https://github.com/commanderx16/x16-rom

If you followed the instructions above to build and install gcc and cc65, you are all set to build both of those repos already. Please note that building the Windows emulator using Cygwin is not recommended, and at the very least requires additional environmental setup. It is highly recommended to use the release build of the Windows emulator or to use the cross-platform build environment on a Mac if you absolutely need a custom build. Using mingw32/64 on Linux has not been done successfully, either.

For convenience, I recommend putting the emulator directory on your path to make your workflow exactly as seen in these videos.

Further Reading

• https://en.wikipedia.org/wiki/Hexadecimal
• https://en.wikipedia.org/wiki/Endianness
• https://en.wikipedia.org/wiki/Computer_memory
• https://en.wikipedia.org/wiki/Boolean_algebra
• https://en.wikibooks.org/wiki/6502_Assembly - Baseline 6502 instruction set
• http://www.6502.org/tutorials/65c02opcodes.html - Additional instructions and addressing modes for 65C02
• https://atom.io/packages/language-65asm - 6502 assembly syntax highlighting for Atom
• https://style64.org/petscii/ - An interactive PETSCII table

x16-assembly-tutorial's Issues

Licensing

Considering that the README says "feel free to do what you want with these code examples," I believe that the BSD or MIT licenses would be better choices for this repository.

Lesson10: stopwatch.asm appears to use old VRAM address

I believe the stopwatch lesson may need to be updated to work with the latest X16 release. I made these changes locally to get it to work:

% git diff origin
diff --git a/Lesson10/stopwatch.asm b/Lesson10/stopwatch.asm
index 4492aff..9834e0b 100644
--- a/Lesson10/stopwatch.asm
+++ b/Lesson10/stopwatch.asm
@@ -165,9 +165,10 @@ custom_irq_handler:

print_display:
stz VERA_ctrl

• lda #$20 ; stride = 2

• lda #$21 ; stride = 2
  sta VERA_addr_bank
  lda #DISPLAY_Y
• ora #$B0
  sta VERA_addr_high
  lda #(DISPLAY_X * 2)
  sta VERA_addr_low

I tried to create a pull request for this, but I either have something set-up wrong (new system/set-up), or I don't have permissions to write to your repo:

ERROR: Permission to SlithyMatt/x16-assembly-tutorial.git denied to ShawnLewis62.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

tips for setting up cgywin

Introduction

Here are some tips that could be added to the readme file

Selecting mirror

To get a more closer mirror type the following in your browser:

https://www.cygwin.com/mirrors.html

select the mirror for your country

figure 1

then paste into the setup option of 'User Url' as shown in figure 1
then click add

Adding default directory option

after doing the following

$ mkdir workspace
$ cd workspace

open the following file:

C:\cygwin64\home\User\.bashrc

append the following to the file

cd /cygdrive/c/Users/user

where 'user' is your login name

so next time you open the cgywin bash it will open in your workspace

Right click option

Alternatively use this option

On Windows:

1. Download Cygwin Setup.exe or run and install the chere package.
2. After install right click and Open Cygwin as Administrator.
3. type "chere -i" or "chere -i -t mintty" if you would like to use Mintty

when a folder is selected right click and select as shown in figure 2

` Bash Prompt Here

`

figure 2

installation guide

I just started getting cygwin set up on my Win10 machine, diligently following your instructions. Everything went well. I chose option 2 for the symbolic links (doing them inside the cygwin terminal rather than in my Windows path parameters). When I arrived at the x16 rom and emulator steps, it took me a while that I should git clone those repos as well. Downloading the binaries works well, but from a close-to-unix-noob status, I wanted to clone the repos so I can easily replace them as new versions arrive.

there doesn't seem to be a specific step for installing SDL2 on cygwin after the fact inside the terminal. I followed your other repo's readme (https://github.com/SlithyMatt/x16-assembly-tutorial) and I wish I would have just checked in SDL2 at that step.

The other missing step I found is that the cygwin environment is not finding ld65,exe, so I added it by going to /usr/bin and doing ln -s /cygdrive/c/users/whatever/workspace/cc65/bin/ld65.exe

Not doing so makes the rom make step complain about its absence. Just thought you'd add a line about these in the otherwise excellent readme files, which guided me well by the hand despite my 20 year old rust in unix navigation

edit - you already answered in the x16 community forums that it makes little sense to attempt a compilation of the emulator...inside the cygwin environment - just stick with the windows binary. makes sense! Although the ROM step was a very minor issue that would remain here if and only if they don't package the bleeding edge version every time in their win compiled binairies.