Back to BASIC

Recently, I went to BASICs and I found it fascinating. It is much more interesting programming paradigm then compiled languages development as C like languages since you can program in BASIC interpreter and in assembly at once and get feedback instantly. Also, 6502 CPU is quite easy to understand and memory mapping of the 6502 is also straightforward and interesting to play with.

The only issue is that I find it tedious to type the code in the Commodore 64 emulator directly. But there is a solution, it is possible to import files in D64, RPG and other formats that the emulator supports. It means that you can write BASIC or assembly code in your favorite editor and then import it.

How can you do it?

To be able to do this it there is a need to convert the text file to a format that is supported by Commodore 64. If you search you’ll be able to find a number of tools that people wrote to do just that. Since I have a PC with Windows 11 so I am using a Windows based tool. This tool is called C64List and it comes in handy to be able to convert BASIC files into text files and vice versa.

Prerequisites

Operating System: Windows

Download and extract C64List tool

(Optional) Review supporting documentation file with a very detailed and helpful

A text file with BASIC code

Let’s do it

• Download and extract the C64List tool.

• Extract the zip file where you want it and review the contents of the folder

Inside you’ll find the tool itself and if you need to know how to use it in more detail there is a user guide.

Now let’s create a text file with the BASIC code and then convert it using C64List tool.

Now let’s convert it to PRG format that Commodore emulator can import.

• Open Windows Command Prompt (aka cmd).
• Run the command below to convert the text file to prg format.

C64List basic.txt -prg

If it worked correctly you should see similar output

If you review the folder you’ll find a new basic.prg file created

If you open that file as hex dump you’ll see something like below

Now let’s go to the Commodore 64 online emulator website and import our file.

And then drug and drop that basic.prg file into the drop field on the website as shown in the screenshot below

What you’ll see that the emulator window above will show that it started to load a file

As you can see the file was imported correctly and the lower case lines 30 and 40 in the original text file were converted to upper case in PRG file.

Below comes the video of the process above.

Take care.

This story begins around 1988-89 when I first saw ZX Spectrum clone based on Zilog Z80 microprocessor. It had Sinclair BASIC and ran off the cassette recorder. This first computer was responsible for the interest in computers that I have ever since.

Fast-forward to nowadays, I continue to be interested in how hardware and software work and watched quite a few reverse engineering videos on YouTube, like Apollo Guidance Computer restoration series on CuriousMarc channel and others. Due to this YT algorithm suggests me similar videos. A couples of days ago it suggested me to watch the 27c3: Reverse Engineering the MOS 6502 CPU video about how 6502 CPU was reverse engineered by peeling layers from the chip, taking photographs and then reconstructing actual transistors from the photos. The talk was given by Michael Steil who extensively contributed to documenting everything there is about MOS 6502 CPU and various types of BASIC it ran.
The people who reversed engineered the MOS 6502, Greg James, Brian and Barry Silverman also wrote a JavaScript visualization of the inner workings of the 6502 as it chugs alone.

It turns out that Michael Steil implemented a C based simulation of the MOS 6502 and hooked it up to the Commodore BASIC emulator to see how it worked. And it worked indeed!

In the rest of the post I’ll explain how to run that perfect MOS 6502 CPU simulation that runs Commodore 64 BASIC V2 emulator in WSL2 Ubuntu. So hold on.

Prerequisites

• Interest in this topic 🙂
• Operating System: Linux or Windows 10 with Windows Subsystem For Linux 2 (WSL2)
• Source control software: git (should come preinstalled on WSL) to be able to check out the implementation of the 6502 CPU and BASIC
• make tool installed
• C compiler like, gcc installed

What to expect?

First I’ll explain how to install WSL2 if you don’t have one.

Then I’ll explain who to clone locally the repository that contains MOS 6502 and BASIC simulators.

Then we’ll build them and run them locally.

I’ll provide references to good resources on the subject.

Let’s begin

Install WSL and Ubuntu

As I mentioned Michael’s implementation requires a Linux distribution to run. So if you have Windows as I do then there is a need to install Windows Subsystem For Linux (aka WSL) to be able to run Ubuntu natively on Windows. The whole installation process is easy and takes a couple of minutes. To know how to do it just follow one of the tutorials below

• How to install Linux on Windows with WSL
• Install Ubuntu on WSL2 and get started with graphical applications

What you should see when Ubuntu is up and running

Clone GitHub repository

Now, that we have Ubuntu installed let’s download (clone) the MOS 6502 repository from GitHub to be able to build it locally.

• When you navigated to that repository in GitHub click on the code button in the right upper hand side,
• and click on copy icon

Create directory to clone repository into

Then go back to Ubuntu and run the following commands.

First, let’s create a directory for the MOS 6502 project.

mkdir perfect6502
cd perfect6502

Then clone the repository locally

git clone https://github.com/mist64/perfect6502.git

You should see similar output when git clones the repository locally

Cloning into 'perfect6502'...
remote: Enumerating objects: 643, done.
remote: Total 643 (delta 0), reused 0 (delta 0), pack-reused 643
Receiving objects: 100% (643/643), 997.31 KiB | 4.96 MiB/s, done.
Resolving deltas: 100% (391/391), done.

Install make and gcc on Ubuntu

After this we can build the project using Linux make tool. But since it’s not installed on Ubuntu WSL we need to install it first.

Also, make tool requires C compiler in order to compile the code. So we need to install one of the available C compilers for Linux. We’ll use gcc compiler.

Install make, by running the command below.

sudo apt install make

Next, let’s install gcc compiler. If you’ll be asked Do you want to continue? type Y.

sudo apt install gcc

Now that both of the tools are installed let’s run make command

make

What you’ll see that there will be an error and it has to do with the source code that we cloned

amc@MINE-LAPTOP-130JJTQ6:~/perfect6502$ make
cc -Werror -Wall -O3   -c -o perfect6502.o perfect6502.c
cc -Werror -Wall -O3   -c -o netlist_sim.o netlist_sim.c
netlist_sim.c: In function ‘getGroupValue’:
netlist_sim.c:390:1: error: control reaches end of non-void function [-Werror=return-type]

To fix this issue there is a need to apply Pull Request (PR) one of the users submitted.

To do this run this command

git fetch origin pull/10/head:pr_number10

You’d think that’s it. But you are wrong and there is a need to update Makefile to be able to build the project. To do this we need to comment out the line below in the file

OBJS+=measure.o

Commenting out is done using ‘#’ character as a first one in the line.

I am using vi editor to do this. On WSL it is possible to edit this file even in notepad.

Update Makefile using Windows notepad

When you are in the perfect6502 directory type

explorer.exe .

You should see Windows File Explorer opens

Now, you can select open with notepad and comment out that line in notepad.

Okay, now we are good to run make

amc@MINE-LAPTOP-130JJTQ6:~/perfect6502$ make
cc -Werror -Wall -O3   -c -o perfect6502.o perfect6502.c
cc -Werror -Wall -O3   -c -o netlist_sim.o netlist_sim.c
cc -Werror -Wall -O3   -c -o cbmbasic/cbmbasic.o cbmbasic/cbmbasic.c
cc -Werror -Wall -O3   -c -o cbmbasic/runtime.o cbmbasic/runtime.c
cc -Werror -Wall -O3   -c -o cbmbasic/runtime_init.o cbmbasic/runtime_init.c
cc -Werror -Wall -O3   -c -o cbmbasic/plugin.o cbmbasic/plugin.c
cc -Werror -Wall -O3   -c -o cbmbasic/console.o cbmbasic/console.c
cc -Werror -Wall -O3   -c -o cbmbasic/emu.o cbmbasic/emu.c
cc -o cbmbasic/cbmbasic perfect6502.o netlist_sim.o cbmbasic/cbmbasic.o cbmbasic/runtime.o cbmbasic/runtime_init.o cbmbasic/plugin.o cbmbasic/console.o cbmbasic/emu.o

If you saw similar output then there were no errors and we can finally run the Commodore 64 BASIC emulator on MOS 6502 CPU simulator.

cbmbasic/cbmbasic

And hooray you should see the screen below

What can you do now?

Well, the sky is the limit. Pay attention that since the MOS 6502 simulator simulates real transistors it’s quite slow. Also, there are still some bugs in the Commodore BASIC emulator so not all commands will work as expected. But most will do.

For example, below comes “Hello, world!” program that will print this sentence, and then concatenate two words in one string and print it out.

You can do even more pretty trick using BASIC to print “Hello, world!” in Assembly code. I saw this implementation in the “Hello World” on Commodore 64 in Assembly Language, Machine Code video.

If you’ll watch that video you’ll understand what’s going on in the program below.

You can watched how it worked in real time below

Some useful commands to know

Pay attention, that BASIC requires upper case for all commands.

Clear screen

PRINT CHR$(147)

Clean memory

NEW

Reset computer (hence emulator)

SYS 64738

List your program so far

LIST

To update particular line there is a need to retype it in this emulator, while in other emulators you can edit them. As you can see on the C64 online emulator

SUMMARY

Well, there you have it you can use your locally running BASIC with pretty good functionality or you can switch to that C64 online emulator which is faster and supports all of the commands.

REFERENECES

Revers engineering MOS 6502 CPU videos

• 27c3: Reverse Engineering the MOS 6502 CPU
• World of Commodore 2011 – The Visual 6502 Project

6502 simulation GitHub repository of Michael Steil

• perfect6502 is a MOS 6502 CPU emulator

Programming on Commodore

• “Hello World” on Commodore 64 in Assembly Language, Machine Code
• Bill Gates’ Personal Easter Eggs in 8 Bit BASIC

Commodore Programming references

• Commodore 64 Programmers Reference Manual

Commodore BASIC wiki

• BASIC

Commodore BASIC Emulators

• Commodore PET BASIC
• Commodore 64 BASIC V2

Interactive article about Commodore way of programming

• The Lost Ways of Programming: Commodore 64 BASIC

Background

Having seen a short YouTube video by Lex Fridman about Donut-shaped C code that generates a 3D spinning donut where in comments he encouraged to look at the code and play with I did just that.

But before this, I went to the Donut math: how donut.c works link where the author of that code Andy Sloane described how he came from geometry and math to implementation of the donut in C.

The Andy Sloane’s tutorial has two visualizations that you can launch and also the JavaScript implementation of the donut. One visualization is of ASCII donut while another one uses <canvas>: The Graphics Canvas element to create a visualization.

Playing with the code

The easiest way to play with the 3D spinning donut in JavaScript is to use JSFiddle online editor. When the editor is opened you see four main areas, just like in almost any other JS editor, which are HTML, CSS, JavaScript and Result.

To be able to start playing with donut code like crazy we need to do a number of things.

First

First, there is a need to create a basic HTML page with a number of buttons, a <pre> tag to store ASCII generated donut and a <canvas> tag to be able to show another type of donut animation. To do this just copy and paste into HTML area of JSFiddle editor the code below

<html>
  <body>
    <button onclick="anim1();">toggle ASCII animation</button>
    <button onclick="anim2();">toggle canvas animation</button>
    <pre id="d" style="background-color:#000; color:#ccc; font-size: 10pt;"></pre>
    <canvas id="canvasdonut" width="300" height="240">
    </canvas>
  </body>
</html>

Second

Second, there is a need to copy and past JS code from Andy’s page or copy and paste the code below into JS area of the JSFiddle editor

(function() {
var _onload = function() {
  var pretag = document.getElementById('d');
  var canvastag = document.getElementById('canvasdonut');

  var tmr1 = undefined, tmr2 = undefined;
  var A=1, B=1;

  // This is copied, pasted, reformatted, and ported directly from my original
  // donut.c code
  var asciiframe=function() {
    var b=[];
    var z=[];
    A += 0.07;
    B += 0.03;
    var cA=Math.cos(A), sA=Math.sin(A),
        cB=Math.cos(B), sB=Math.sin(B);
    for(var k=0;k<1760;k++) {
      b[k]=k%80 == 79 ? "\n" : " ";
      z[k]=0;
    }
    for(var j=0;j<6.28;j+=0.07) { // j <=> theta
      var ct=Math.cos(j),st=Math.sin(j);
      for(i=0;i<6.28;i+=0.02) {   // i <=> phi
        var sp=Math.sin(i),cp=Math.cos(i),
            h=ct+2, // R1 + R2*cos(theta)
            D=1/(sp*h*sA+st*cA+5), // this is 1/z
            t=sp*h*cA-st*sA; // this is a clever factoring of some of the terms in x' and y'

        var x=0|(40+30*D*(cp*h*cB-t*sB)),
            y=0|(12+15*D*(cp*h*sB+t*cB)),
            o=x+80*y,
            N=0|(8*((st*sA-sp*ct*cA)*cB-sp*ct*sA-st*cA-cp*ct*sB));
        if(y<22 && y>=0 && x>=0 && x<79 && D>z[o])
        {
          z[o]=D;
          b[o]=".,-~:;=!*#$@"[N>0?N:0];
        }
      }
    }
    pretag.innerHTML = b.join("");
  };

  window.anim1 = function() {
    if(tmr1 === undefined) {
      tmr1 = setInterval(asciiframe, 50);
    } else {
      clearInterval(tmr1);
      tmr1 = undefined;
    }
  };

  // This is a reimplementation according to my math derivation on the page
  var R1 = 1;
  var R2 = 2;
  var K1 = 150;
  var K2 = 5;
  var canvasframe=function() {
    var ctx = canvastag.getContext('2d');
    ctx.fillStyle ='#000';
    ctx.fillRect(0, 0, ctx.canvas.width, ctx.canvas.height);

    if(tmr1 === undefined) { // only update A and B if the first animation isn't doing it already
      A += 0.07;
      B += 0.03;
    }
    // precompute cosines and sines of A, B, theta, phi, same as before
    var cA=Math.cos(A), sA=Math.sin(A),
        cB=Math.cos(B), sB=Math.sin(B);
    for(var j=0;j<6.28;j+=0.3) { // j <=> theta
      var ct=Math.cos(j),st=Math.sin(j); // cosine theta, sine theta
      for(i=0;i<6.28;i+=0.1) {   // i <=> phi
        var sp=Math.sin(i),cp=Math.cos(i); // cosine phi, sine phi
        var ox = R2 + R1*ct, // object x, y = (R2,0,0) + (R1 cos theta, R1 sin theta, 0)
            oy = R1*st;

        var x = ox*(cB*cp + sA*sB*sp) - oy*cA*sB; // final 3D x coordinate
        var y = ox*(sB*cp - sA*cB*sp) + oy*cA*cB; // final 3D y
        var ooz = 1/(K2 + cA*ox*sp + sA*oy); // one over z
        var xp=(150+K1*ooz*x); // x' = screen space coordinate, translated and scaled to fit our 320x240 canvas element
        var yp=(120-K1*ooz*y); // y' (it's negative here because in our output, positive y goes down but in our 3D space, positive y goes up)
        // luminance, scaled back to 0 to 1
        var L=0.7*(cp*ct*sB - cA*ct*sp - sA*st + cB*(cA*st - ct*sA*sp));
        if(L > 0) {
          ctx.fillStyle = 'rgba(255,255,255,'+L+')';
          ctx.fillRect(xp, yp, 1.5, 1.5);
        }
      }
    }
  }


  window.anim2 = function() {
    if(tmr2 === undefined) {
      tmr2 = setInterval(canvasframe, 50);
    } else {
      clearInterval(tmr2);
      tmr2 = undefined;
    }
  };

  asciiframe();
  canvasframe();
}

if(document.all)
  window.attachEvent('onload',_onload);
else
  window.addEventListener("load",_onload,false);
})();

Third

After HTML and JavaScript areas were populated click on the Run button (as indicated by me with number 1) in the screenshot below and you should see in the Result area on the right two buttons and two donuts (indicated with number 2).

When each button is clicked relevant animation is turned on. Both of them could run in parallel.

This is how it looks like in real-time

Playground

If you want understand the math of how it’s done then first read the explanation by Andy Sloane here. If you want jump right into messing around with the code then stay here.

Need for speed

To change the speed of the animations Ctrl + F in the JSFiddle and search for setInterval function

tmr1 = setInterval(asciiframe, 50);

tmr2 = setInterval(canvasframe, 50);

The second argument controls the speed of rotation of the donut. Increasing it makes it rotate faster and vice versa.

Paint it black

To change the background color of the donut created with the <canvas> animation search for ctx.fillStyle =’#000′;

ctx.fillStyle='#000'; //this is currently black

To change the color of the donut created with the <canvas> animation search for ctx.fillStyle = ‘rgba(255,255,255,’+L+’)’;

ctx.fillStyle = 'rgba(255,255,255,'+L+')'; // update any of the first three arguments which stand for Red, Green, Black in RGB.

See you

There are plenty other things you can try with this code. So why are you waiting? Just do it!