Ben Calderon

The Adventures of Writing a CHIP8 Emulator - Part 1

2023-06-04T00:00:00Z

A few days ago I decided to write a CHIP8 emulator. Why? Because it's fun! As for a programming language, I decided to use C. Wait a minute, isn't that illegal? This might surprise you but, it is not! You are not forced to use Rust for all new projects henceforth! Seriously though, in the past couple of months I decided to actually learn C and it has quickly become my absolute favorite language.

Another big reason for writing a CHIP8 emulator is because I truly enjoy really understanding something deeply. With today's crazy complexity in software (I'd argue mostly unnecessary, but I digress), tons of levels of indirections, abstractions, solving most problems by adding Yet Another NPM Package®, and so on, emulating a system like CHIP8 with a language like C feels like a breath of fresh air.

Let's set our expectations, I'm not going to tell you how to write a CHIP8 emulator, or what to put on your pizza (!pineapple). It'd be like spoiling a really good book, or telling you the clue to solving an interesting puzzle, or telling you how to get the Master Sword in TOTK without letting you figure it out! If you ask me, I think you should write a CHIP8 emulator too, and have tons of fun doing it! What I plan to do is more like take you along a leisurely walk through my journey, show you the parts that I thought were particularly interesting, while encouraging you to look at the landscape for yourself, dig in and come up with your own favorite parts!

And thus, armed with some amazing resources, I fired up Microsoft Word, made a main.c file, and with gcc main.c -o chip8 I was good to go.

When I started this project I had a foggy idea of how a CPU works from reading a little about assembly, or for that matter, how a compiler/interpreter sorta kinda works from reading another interesting book but here's the TLDR;

CPU reads instruction, also called opcode, from memory (fetch step)
CPU interprets the instruction (decode step)
CPU does what the instruction says (execute step)
Rinse and repeat (until it crashes, of course, and you contact IT and they tell you to turn it off and on again...)

Sure, it's a bit more complicated than that, but that's enough to get one started.

Fetch, or the thing you wish your cat did!

Let's break down those steps a bit more. First the CPU* fetches an instruction from memory. But, how does the CPU know which instruction to read? Good question! Most CPUs have a register in it called Program Counter (PC) that keeps track of the memory location that the CPU should read the next instruction from. In the case of CHIP8 the PC generally has an initial value of 0x200. That is, when you first turn on the CHIP8 it will read 0x200 from memory and do what that instruction says.

Whoa there, hold your horses! Register what!? (that was my question!) A register is simply a very small memory inside the CPU that the CPU uses to store data. For example if I'm going to add two numbers, the CPU needs to have access to the two numbers and then it also needs some place to put the results of adding those numbers. That's what the registers are used for. Btw, if you have heard about 32 bit, 64 bit, or even 16 bit CPUs, that's one of the things that it means, how many bits fit in its registers. CHIP8, if the name hasn't given it away, is an 8 bit CPU, so the registers can store 8 bits (or one byte) of data. If you are wondering why use registers when computers has tons of memory already? Well, the registers are A LOT FASTER than accessing memory. Also, the CPU can perform operations directly on them, for example, increment or decrement a register directly, AND or OR one register with another, and so on. Getting data from memory takes extra steps, time, and generally can't (at least in CHIP8) be manipulated directly.

Talking about registers and memory, let's talk about the groundbreaking features of the CHIP8.

a whopping 4kB of memory
16 V registers, named V0, V1 ... VF
a 16 bit I register usually used to store a memory address
the aforementioned PC register, also 16 bit
a stack
a 64x32 monochrome display
other things that I don't know about yet because I haven't implemented them (hey, this is just Part 1 ¯\_(ツ)_/¯)

If you are wondering how this looks in code, this is what I came up with.

typedef struct {
    uint8_t  memory[4096];
    uint8_t  v[16];
    uint16_t i;
    uint16_t pc;
    uint8_t  stack[16];
    uint8_t  display[64 * 32];
} Chip8

There are other fields like stack_top, or a mysterious display_image that I left out and we might talk about later... but I said that I wasn't going to spoil this for you!

And while talking about a stack, if you are like me and have mostly done web development, and the sound of "data structures and algorithms" makes you shudder, don't despair. A stack is pretty muck like an array in JavaScript but you only have two operations, you can .push(item) or .pop() something from it. And the way you do that when you don't have the niceties of a high level language is simply to have a variable that tells you how many items you have added to your stack (stack_top), which gets incremented when you push something to it, and decremented when you pop something from it. Some people call this behavior LIFO, but is much better to actually understand what it's going on than have a fancy language that impresses nobody.

Here's an example:

int stack_top = 0;

push_to_stack(item1); // add item to index 0 (stack_top) and increment stack_top
push_to_stack(item2); // add item to index 1 (stack_top) and increment stack_top

// stack_top is 2

pop_stack(); // decrement stack_top and get stack[stack_top], or item2
pop_stack(); // decrement stack_top and get stack[stack_top], or item1

// stack_top is 0

Decode and execute, or how to impress your manager 10 out of FF times!

Alright, remember the steps that CPU takes, mentioned, like, forever ago? Let's talk about the last two, that is, decode and execute. But for that we need to talk a little about CHIP8 programs. All they are is simple binary files, with instructions two bytes long (there can be data in there, but we don't need to worry about that). Now, before you run for the hills at the mention of binary, I promise, it's not as complicated as it sounds! Let's start by looking at a hex dump of a CHIP8 program.

// 00e0 6101 6008 a250 d01f 6010 a25f d01f
// 6018 a26e d01f 6020 a27d d01f 6028 a28c
// d01f 6030 a29b d01f 6110 6008 a2aa d01f
// 6010 a2b9 d01f 6018 a2c8 d01f 6020 a2d7
// d01f 6028 a2e6 d01f 6030 a2f5 d01f 124e

If you have never seen a hex dump, it is simply a more readable way to see 1s and 0s, which is all that computers speak. Each character above represents 4 bits, that is 0 in hex would be 0 0 0 0 in binary and 0 in decimal, while F would be 1 1 1 1 in binary and 16 in decimal. You might have seen this in colors such as #FFFFFFbeing the color white, or #FF0000 the color red. All those are hex numbers to represent the value of red, green, and blue in three bytes. You see, you know more binary than you think! Ok, back to the hex dump. One character (as in e in 00e0) is called a "nibble" and two characters (or 8 bits) is called a byte. (I love how a nibble is... a small bite!)

If you want to understand more binary/hex, there's nothing like trying stuff, so pick up a programmer calculator and play around!

Another tip about binary is that sometimes you'll see some puzzling numbers like 0x80... what does that mean? Well, if you look at that number in binary it is 1000 0000, so all they really needed was the 8th bit to be a one, but writing 0x80 is more compact (and obscure) than other alternatives.

Anyways, back to our hex dump. Each CHIP8 instruction is 2 bytes long, or 16bit, or 4 nibbles or 4 characters on the hex dump above (isn't it great how you can say the same thing in so many ways?). That is, the first instruction would be 00e0 and the next one would be 6101. Simple enough.

Now, the CHIP8 uses the leftmost nibble to identify what the instruction does. For example, if the instruction starts with a that means the CPU will set register I to the value of the following 3 nibbles. So our fourth instruction a250 simply tells the CPU "set the I register to 250". That's it!

Another example, the 6... family of instructions tells the CPU to set the register Vx to some value. Let's look at the second and third instruction to get an idea of what this means. 6101 is simply telling the CPU "set V1 (1 comes from the 3rd nibble) to the value of 0c" while 6008 would mean "set V0 to the value of 08". You see, not too hard!

You can look around in other areas of the dump and you'll see other instructions just like that. On the third line, third instruction, could you guess what a29b means? Look at you reading binary like it's nothing! (It's an interesting conversation starter for talking with your manager about a raise... "So, the other day I was reading a hex dump, as one does...")

Anyways, I think that's enough for this post. On the next one I'll share some of my follies and blunders, how I made such an obscure bug that I ended up writing a debugger for my emulator, how to write a program that your OS will send a kill 9 signal (the way my wife tells it is, a kill signal is like asking somebody with an apple in their hand, "can you please drop the apple?"; a kill 9 signal is chopping off the hand!), and the joys (as in frustration, but the amazing satisfaction of cracking a hard nut!) of low-level graphics programming. :-)

See you on the next one!

* technically CHIP8 is not a CPU, but that's a story for another day.

Reply via email

The Adventures of Writing a CHIP8 Emulator - Part 2

2023-06-11T00:00:00Z

In my last installment of "How to continually stub your toe with C"... Uhhh, I mean, The Adventures of Writing a CHIP8 Emulator - Part 1 I took you on my journey of writing a CHIP8 Emulator in C. BTW, here's the code and a gif of how it looks :-)

Well, I'm now afraid that I might have given you an impression of competency. If that's so, I need to profusely apologize and quickly correct your assumption by pulling the curtain back from that "polished" blog post. The goal with this is simple, if my pain can help you in any way avoid my errors, then my sufferings are not in vain!

Why clever code == bad code! 🤓🤦‍♂️

One of the first ROMs traditionally used to test a CHIP8 emulator is an old ROM that displays an IBM logo. Here is how that looks rendering at 10Hz:

Yep, CHIP8 is that old! Anyways, the goal was very clear, I only needed to implement a handful of instructions (opcodes) to run that ROM and so I did. I then loaded the ROM and... nothing happened! I looked at my code again, everything looked correct! still, nothing. The output of the CHIP8 is a 64x32 display, so I dumped that to the terminal to see if anything was displaying, nothing. I added printf everywhere, added a scanf() to step through every instruction, looked at the registers after every instruction, but still nothing. The registers were updating properly, the PC (program counter register) was incrementing correctly, it all was working properly but for some reason the emulator would not work.

I decided to blame the ROM and to look for other beginner ROM to test on my emulator with. After a quick search I came across this one which, when I loaded it on my emulator... worked! But you see, that's terrible news! It showed me that my emulator worked, but only sometimes!? Only for some ROMs!?
It's like if you order your favorite Chipotle burrito, asking for the exact same thing every single time, but you get what you asked for only if you pay with $1 bills on Tuesdays!
Both ROMs were very similar in the instructions they required to operate, so why was it working only on one!?

Well, I proceeded to try everything I could think of. I talked softly and lovingly to my computer... nothing. I talked loudly and threateningly... nothing. I tried to make bargains with my computer... nothing. I changed my compiler flags... nothing. I changed my wallpaper... nothing. Asked my rubber ducky for advice... nothing. Asked ChatGPT for advice... nothing. I bought Sublime Text 4... nothing (in retrospect, Idk how this could have helped, but I still tried it!)

After about two days of no progress at all I came to the conclusion that I would have to take things into my own hands. I'd need to write a debugger for my emulator *dun dun DUN*.

So I did. It was a whole three days detour, which was absolutely fascinating and SO worth it! (But that's a topic for another post.) It was such a success that in the first two minutes of running the half-cooked debugger I was able to see the issue! Mind you, not the cause, but the problem.

Take a look at this screenshot of my debugger showing the bytes currently loaded in memory:

CHIP8 Emu Debugger Memory Window

And now take a look at this hexdump (Cutter) of the ROM I'm trying to load to memory:

Cutter hexdump of IBM.ch8

Do you see the difference? Look, I might not pay attention to details, like the milk I picked up at the grocery store, and just pick up the "red box with cursive letters" only to realize that it's the milk I don't like (true story!)... But I've spent A LOT of time staring at the back of breakfast cereal boxes, so, I've gotten pretty good at "spot the difference" games, if I say so myself... and, my emulator is missing data! What gives!? And the annoying part is that it only happened with the IBM ROM! 🤦‍♂️

Well, at least now I know how my emulator doesn't work... it's not reading the whole file! Let's take a look at the function that loads the ROM file to memory:

void chip8_load_rom(Chip8 *chip8, char *path, uint16_t offset) {
    FILE *f = fopen(path, "r"); // open path as readonly

    int8_t b; // temporary byte to store read data
    uint16_t i = offset; // data is usually loaded with a 0x200 offset
    while ((b = fgetc(f)) != EOF) {
        chip8->memory[i++] = b;
    }
}

This is a very simple function. Read one byte from the file, set memory to byte. Repeat until End of File (EOF). See, there's nothing wrong with it! 🤦‍♂️ I mean, it worked for some files but it didn't for others? People complain about segmentation faults, but those are preferable to this!

So I decided to take a closer look at the file that my emulator was having trouble with, and you'll never believe what I found!

Take a look above and notice what is the very next byte missing in memory, or where reading the file stopped. On the emulator memory the lasts bytes are 0x1228 and nothing else is read after that. In the ROM the very next byte after that is 0xFF... Well, that is interesting... Why would my program stop reading when it finds 0xFF? To confirm this theory I changed that byte with 0xFE and yep, the emulator read 0xFE without a problem, all the way to the next 0xFF! Well well well, the plot thickens!

I then decided to take a look at getc() to see if there was something I was missing. And interestingly enough, take a look at what the signature for that function is:

int getc( FILE *stream );

Did you notice it? it returns an integer, not a character! The function is called getc, presumably for "get character" but it returns an integer... interesting 🤔. So, on a whim I decided to change my b variable above to and int, and BOOM!, it worked!

Now, why would that be?

Take a look at the problematic byte one more time in ImHex, which conveniently shows us the value of a byte in various data types:

ImHex

Did you see it? At the right side, in the data inspector, notice what 0xFF is as an int8_t... it is -1! And why would that be relevant? Because EOF == -1! 🤦‍♂️

You see, I had some esoteric idea that EOF was some magical signal or something that the OS sent my program when the filesystem detected that I had reached the end of a file. NOPE. It's just a plain -1 (it might be something else in different platforms, that's why EOF is used instead of -1).

So, this is what was happening, my function would go on merrily, reading my file to memory, one byte at a time. It would come to a byte 0xFF and be like "La la la la... oh, what have we here? A 0xFF? This is obviously EOF and thus I'm done here and can go back to picking up berries in the forest for Granny! La la la la..."

Well, while I don't mind C programs wandering off trails to gather questionable berries for their ancestors in the woods, that is most certainly NOT what I wanted my program to do. But by trying to be clever and setting my variable to be exactly one byte int8_t, I created that bug.

And that's how, a full 5 days of work and... let me check... ~600 LOC led to changing int8_t to int!! 😅

So, what is the moral of the story? To not be clever and try to save some imaginary space? (My computer is 64 bit, so a 64 bit operation or a 8 bit operation take the exact same space and time...) To not optimize early, and instead get my program working and look for optimizations later? Are they even necessary? That being sidetracked and spending 5 days in a pet project actually pays off? Well... I don't know what the moral is, but I learned nothing and made the variable a int16_t! 😂

Reply via email

Because I can't ever remember SDL

2023-08-09T00:00:00Z

From time to time I want to make a quick 'n dirty SDL window to play with some graphic something. The current curiosity is learning 3D rendering "by hand".

Well, every single time I need to do this I find myself having to research SDL and relearn it all over again 🤦‍♂️. I know I need to init sdl and then... create a window, right? a renderer or a surface? how was it that I handled events? something double loop... I think? Or did I just waited for events?

Another pet peeve that I have with SDL is that it can be a bit verbose. Nothing against that though, the flexibility and control that that verbosity provides makes it worth it for me, something that often makes C libraries superior IMHO. But with that said, I like how tidy raylib is even though it can be limiting is some cases.

And thus, after so much pain and searching for the same things over and over again, I finally decided to write a single header wrapper around SDL called sdlsimple.h.

Here's how it works:

First, include the header in the project

#define SDLSIMPLE_IMPLEMENTATION // use this only once in the your project
#include "sdlsimple.h"

Next initialize it.

sdlsimple_context_t *ctx = malloc(sizeof(sdlsimple_context_t));
sdlsimple_init(ctx, WIDTH, HEIGHT);

All the magic then happens between in your main loop between sdlsimple_start(ctx) and sdlsimple_end(ctx).

while(!sdlsimple_should_quit(ctx)) {
    sdlsimple_start(ctx);

    sdlsimple_clear(ctx, 0, 0, 0);

    // draw red line at y = 100
    for (int i = 0; i < WIDTH; i++)
			sdlsimple_set_pixel(ctx, i, 100, 255, 0, 0);
    
    sdlsimple_end(ctx);
}

And that is that. On the background sdlsimple uses an SDL_Renderer, instead of a surface, to draw and the events are not blocking, that is, we are not waiting for events but drawing as fast as our computer let's us.

I guess I should say that this is not a production ready library. It uses the OS as garbage collector (100% free of free()!), there's very little error checking and all the rest of the stuff needed to make software reliable.

But at the end of the day, done is better than perfect and this is enough to move on and actually start drawing pixels to my window.

Until next time!

Reply via email

Binary Ninja! 🔪🍉 - CSS Edition

2023-08-28T00:00:00Z

🥷 Binary Ninja!

When learning a new programming language there's usually a section that I look at, expressly to not to use! You see, for whatever reason most languages would ship with a real "AND", and then with another "AND", just confuse me! It'd be like this in JS, for example:

// "real" AND
true && false // => false

and then there's this... this thing!

// what in the world!?
true & false // => 0

Same thing with OR || vs. | and with NOT ! vs. ~ and a few others.

Well, it seems like some wise people called those bitwise operator, and for the longest time I've intentionally avoided them, and got scared when I came across code that used them! Well, on the CHIP8 project I had no choice but to face my fears and in this post I want to share with you how cool bitwise operator really are! My goal is not to be exhaustive and tell you everything about them, your programming language manual would be the place for that. Instead I want to share with you a use case and hopefully encourage you to find out more and add them to your programming toolbox!

Ok, buckle up and let's ge to it!

And it all starts with the name.

Bitwise, some wise person once said about a bit... maybe. (sorry) 🤦‍♂️

Paying close attention to the name of these operators we get the biggest clue we need. Bit! The bitwise operators, curiously enough, operate on bits.

Back in the day, before every developer everywhere worked solely inside an App.jsx file, people used to think about how the data inside the computer looked like. You see, computers are not too clever. They only know how to say two things: 0 and 1. That is all. When you put a bunch of those together and assign meaning to them you can fool yourself into thinking that computers are clever. Nah, people are, but people got tired of being clever and thus made computers to pretend to be instead of them.

Anyways, it is 2023, so let's get on with the times and do what everybody is doing nowadays, making websites pretty! 🎨

Imagine that we have the color OliveDrab (not to be confused with a drab olive, which might be moldy and thus not recommended for human consumption). That color in Hex is 0x6B8E23, of you might see it as #6B8E23 in a CSS file, same thing. Well, from our frontend dev knowledge we know that that number is actually three numbers that represent red, green, and blue values. And from a quick glance we can see that red would be 0x6B, green 0x8E, and blue 0x23. Well, that's easy, but that's because you are not a computer! The computer only sees 0110 1011 1000 1110 0010 0011.

So anyways, all the computer sees is 0x6B8E23 as one number, which in decimal is the number 7048739 or the binary 0110 1011 1000 1110 0010 0011 without any notion that there actually three pieces of data in that one number.

Now, we have received the task to convert all the hex numbers in our CSS files to rgb values (I know is hard to imagine such a ridiculous and meaningless task, but have you ever worked in tech?). Well, that's where our bitwise operators come to help us!

Let's start with the wrong "AND" &. This, obviously, can be used to perform the logic AND function on two number, but is can also be used to mask bits (The term "mask" confused the heck out of me for many years! Hang on and hopefully after this it might make sense). By making we mean that it can let some bits "pass" and some others don't. Another way to think about it is, it can "hide" bits we don't care about.

Let's give it a try!

0x6B8E23 & 0x0000FF // => 0x23

Would you look at that! We where able to get rid of all the pesky red and green and now we have the value of blue by itself. If you run this code you might see the value 35, which is the value of 0x23 in decimal.

Very nifty, but what is happening? Why 0xFF? Well, let's look at the... ready? Bits!

  0110 1011 1000 1110 0010 0011    // => 0x6B8E23
& 0000 0000 0000 0000 1111 1111    // => 0xFF
  -----------------------------
  0000 0000 0000 0000 0010 0011

Uff, that's a bunch of zeros and ones! But notice what is happening, when we & the original number with our "mask", all the places where both the original 1 and our mask are 1 result in 1. In the places where our mask is 0 the result is 0 regardless.

It's like multiplying! Which is exactly right! Bitwise AND can be sort of thought of as multiplication in boolean algebra, while bitwise OR can be thought as addition.

As you might have noticed, writing number in binary is tending towards the painful side of things. Let's start using the hexadecimal number system, or hex for short to both, save some typing and possible errors. A hex number let's us represent each group of four bits (a nibble), with one number/letter between 0 and F. So, from our color above you can see how each nibble (4 bits) represent one number/letter on the hex number (3 == 0011, 2 == 0010, E == 1110, and so on).

Awesome, let's keep going, how about getting the green value?

0x6B8E23 & 0xFF00 // => 0x8E00

Well, that's progress, we are able to get 8E alone, but there are two extra 00 there. How do we get rid of them? This is the Ninja part!

Shift like you are driving manual! 🏎️

Among the bitwise operators there are these curious looking << and >> operators. Initially what they do might seem obscure. I mean with a description like this from mdn web docs:

The left shift (<<) operator returns a number or BigInt whose binary representation is the first operand shifted by the specified number of bits to the left.

It's accurate, terse, and initially left me like, wat?

But let's look what it does, maybe we can spot a pattern or something.

1 << 0 // => 0000 0001
1 << 1 // => 0000 0010
1 << 2 // => 0000 0100
1 << 3 // => 0000 1000
1 << 4 // => 0001 0000
1 << 5 // => 0010 0000

Did you see that? All that that operator is doing is shifting to the left the 1 on the left by the number on the right. Not bad!

As you might have guessed we can shift something else than 1, say, 6 (0110) and it would shift that whole number too.

6 << 0 // => 0000 0110
6 << 1 // => 0000 1100
6 << 2 // => 0001 1000
6 << 3 // => 0011 0000
6 << 4 // => 0110 0000
6 << 5 // => 1100 0000

And we can do it reverse too!

0010 0000 >> 1 // => 0001 0000
0010 0000 >> 2 // => 0000 1000
0010 0000 >> 3 // => 0000 0100

With this now we know how to get rid of the extra 0s in 0x8E00!

0x8E00 >> 2 // => 0x2380

Wait, what? (I spent and embarrassingly amount of time trying to figure this one out...)

Remember the nibbles up there? how four bits represent one digit in hex? That means that to get rid of one 0 in hex we need to get rid of 4 bits. And thus, to get rid of a whole nibbles we'd need to shift in multiples of 4.

0x8E00 >> 4 // => 0x8E0 --- closer!
0x8E00 >> 8 // => 0x8E  --- let's go!!

Ok, let's recap super quick where are we, we can use & to mask out the stuff that we don't want from a number, and then we can shift away the number that we don't want. Thus in order to get the green value out of 0x6B8E23 we would do:

(0x6B8E23 & 0x00FF00) >> 8 // => 0x8E

(0x6B8E23 & 0xFF0000) >> 16 // => 0x6B

That's neat! Now we can very easily get our values for our hex CSS ro rgb function

let hexColor = 0x6B8E23

let r = (0x6B8E23 & 0xFF0000) >> 16
let g = (0x6B8E23 & 0x00FF00) >> 8
let b = (0x6B8E23 & 0x0000FF) >> 0

console.log(`the rbg value is rgb(${r}, ${g}, ${b})`)
// the rbg value is rgb(107, 142, 35)

Et Voilà!!

There's definitively a lot more to binary an bitwise operators, we just learned a little bit (or a nibble... I'm so sorry) of the chopping part, we can stick them together (imagine another ridiculous task to convert all the rgb values to hex 🤦‍♂️), we can... well, do more, but chopping and sticking stuff is enough for a CHIP8 emulator.

See you on the next time!

Reply via email