Gwilym's blog

Git rebase like a pro

Wed, 31 Mar 2021 17:02:01 +0100

I felt a lot like I was fumbling in the dark when using git for the first year or so. Tools like learngitbranching were great for getting me going, but I often felt like I didn’t have as much control over my commits and the history as I would like. And when working in a team, merge conflicts become quite common. The race to be the first to merge the PR so you don’t have to deal with the conflict becomes quite heated.

I used to get upset whenever I had to resolve a merge conflict because it would take ages to work out what I would have to fix. Or if I realised that I’d made a mistake about 10 commits ago and don’t want anyone to know. And sometimes you want to develop on someone else’s feature branch rather than off main. What do you do when the feature branch you’ve been working on gets merged?

Learning about interactive rebases felt (and still feels like) a super power.

Note however that rebasing can cause a bit of pain if you’re working with people less familiar with git. But hopefully with these few commands and explanations you’ll be git rebasing like a pro in no time!

The most important step

The most important step before doing a rebase you’re not 100% sure will work fine is put down a temporary branch to jump back to. I’ll repeat that in big so that people skipping through this spot it

Put down a temporary branch before a big rebase

Just doing git branch tmp/before-rebasing before you rebase will save you a big headache if you do something horribly wrong. Yes there are always ways back, but if git decides to garbage collect your commit before you notice you’ll be in a difficult space with potential losses of work.

So, now that you’ve done that, I’ll continue this article.

This article is quite long, and the subsections and sub-subsections I’ve used for some reason make this a little difficult to navigate. So here are some quick links if you know what you want to do:

1 My PR has a merge conflict

2 My branch’s history makes no sense

3 Someone rebased a branch I was looking at locally

4 I branched of someone else’s branch, now that’s merged and I want my branch off main

What does a rebase actually do?

A rebase is a kind of ‘history rewriting’ command. In essence, it lets you take a group of commits, and apply them to on top of a different commit.

But, as I will show in some of the examples below, it lets you do all sorts of other operations too.

Note I will always run a so called interactive rebase. This causes git to show you what it plans to do, and gives you a chance to change your mind, cancel the rebase etc.

I think the easiest way to show what a rebase does and why you’d use it is to give some examples of when it is useful and how to use it.

1 My PR has a merge conflict

This is probably the easiest and most common time that I would rebase in my day-to-day work. It is also where I would recommend people get their feet wet and practice before moving on to some of the more advanced use cases below.

I’m going to assume your PR is against a branch named main and that the remote location is called origin. Both of these can be swapped for any branches (note that you’ll need to refer to a later section if the branch your PR is against has itself been rebased).

You are currently working on the branch feature in this example of what we’re going to do, and suppose that there is a merge conflict.

Normally the way I see people do this is by first merging main into their own branch, and then later merging their branch into main. I argue that this is ugly and also less useful:

It is harder for you because you have to fix every single merge conflict at the same time. What I mean by that is if you have multiple files conflicting, you have to fix them all. And this can get pretty complex if you have made some deep refactor.
It is harder for the reviewer because you could change anything in that merge commit, and it can be very difficult to follow that commit specifically.
Also, looking commit-by-commit at the resulting code requires knowledge of how the system used to be rather than how it is currently.
And finally, aesthetically it makes the code graph look really ugly.

This is what your history will end up looking like with the git merge strategy mentioned above

And this with git rebase

Please forgive the strange arrow directions here, not sure what’s going on with the visualiser…

1.1 Put down a temporary branch

Okay, I’ll admit that in this case I would normally not. But if this is the first time you’re doing a git rebase, please do it.

$ git branch tmp/before-rebasing

Remember that git branch creates a branch pointing to your current commit, but doesn’t switch to it. You can go back to this if something goes horribly wrong in the next step.

1.2 Start the interactive rebase

This is the magic of rebasing. I will always rebase interactively. If only to know exactly what git is going to do once it starts.

Firstly, ensure your local pointer to the origin/main is up to date with

$ git fetch

Then, do the rebase

$ git rebase -i origin/main

This will open your currently configured text editor (controlled by the EDITOR environment variable if you want to change it), showing you the list of commits it will replay.

If you’re happy with the list, then save and close the file and git will get to work reapplying your commits one at a time.

1.3 Merge conflict!

You’re doing this to resolve a merge conflict, so you will get one eventually. At this point you have to do something you may not be entirely familiar with. Look at the commit you’re in at the moment. This will be important.

The current state of your files will be as-if you’ve done the commits up to this point on top of main rather than your historical version that you actually did the work in. So when you fix the merge conflict, you have to leave those files in the state you would’ve had it in at this point in your branch (not the end result) had main looked like it does now. This is because after you’ve fixed this conflict, the rebase will continue to run the remaining commits.

Once you’re happy with the changes, you can git add the files you’ve updated to tell git you’ve fixed the conflict.

And then run

$ git rebase --continue

to continue the rebase.

Once that’s all done, push your branch up to origin with

$ git push --force-with-lease

and you’re good to go.

1.4 Help, something went wrong!

It happens sometimes. How to fix it depends on at what point you’re at for your rebase.

1.4.1 The rebase totally failed but it claims to have finished

Good thing you put a temporary branch down at the start. Simply resetting your git branch to that temporary place will fix the issue.

$ git reset --hard tmp/before-rebase

If you were a terrible person and didn’t put a temporary branch down, all is not lost (but it is definitely slightly harder). Provided you haven’t pushed your changes yet, you can jump to the old location according to where it is in origin, with

$ git reset --hard origin/feature

If you’ve pushed, you may be able to get an old commit hash for the end of your old feature branch from somewhere, and then you can do

$ git reset --hard <commit hash>

And if you’ve done none of those things, take this as a lesson to read the text in big writing. Or look up the git reflog and have a go at working with that.

1.4.2 The rebase is still in progress but I don’t want to do it any more

This is a nice easy fix.

$ git rebase --abort

will take you back to where you started.

1.4.3 I thought I wanted this commit, but I don’t really

Running

$ git rebase --skip

allows you to completely skip this commit and continue with the next ones. This comes up occasionally when you fix a bug in some existing code because your new feature is exercising it but someone beat you to the fix. Then it makes no sense to keep this commit, so skip it.

2 My branch’s history makes no sense

This is probably my favourite usage of git rebasing. Not only is it super useful in making the reviewer’s job easier, but it also hides your silly mistakes which will make you look like a l33t haxxor.

I do this if I want to

Change a commit message for a commit a little bit back in the history
Split some commits into more pieces
Combine multiple commits into one
Reorder some commits to makes more sense to a reviewer
Pretend I wrote the tests first

2.1 Put down a temporary branch

You bored of me saying this already? I’ve had more complaints about people not doing this step then anything else with git rebasing. So hopefully this’ll stop that

Something along the lines of the following will save you.

$ git branch tmp/before-rebasing

2.2 Start the interactive rebase

In this case, we’re not going to be rebasing to the tip of main (although you could decide to do that if you want). So here we will instead find the commit hash of the oldest commit in your branch. I like to find it using git log and scrolling back but you can do this any way you want.

Lets say my commit hash is deadbeef, use the command

git rebase -i deadbeef

and this time we’re actually going to change the contents of the file a little.

You’ll see something along the lines of this in the file.

# Commands:
# p, pick <commit> = use commit
# r, reword <commit> = use commit, but edit the commit message
# e, edit <commit> = use commit, but stop for amending
# s, squash <commit> = use commit, but meld into previous commit
# f, fixup <commit> = like "squash", but discard this commit's log message
# x, exec <command> = run command (the rest of the line) using shell
# b, break = stop here (continue rebase later with 'git rebase --continue')
# d, drop <commit> = remove commit
# l, label <label> = label current HEAD with a name
# t, reset <label> = reset HEAD to a label
# m, merge [-C <commit> | -c <commit>] <label> [# <oneline>]
# .       create a merge commit using the original merge commit's
# .       message (or the oneline, if no original merge commit was
# .       specified). Use -c <commit> to reword the commit message.
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out

Pretty much the rest of this section will be what these do, ordered from most useful to least.

2.2.1 pick

You’ll see a lot of these by default. One for every commit hash in your branch. Reorder them in any order, and importantly remove any for commits you don’t want any more.

2.2.2 fixup

If you did a commit, and then the next commit is just fixing a typo in something in the previous commit (or you have a commit that fixes a typo in a commit some time in the past), you can follow up your old commit with this fixup.

As an example, suppose it looked something like this

pick deadbeef1 Add an article about the C preprocessor
pick deadbeef2 Add an article about PAL video processing
pick deadbeef3 Fix typo in C preprocessor article

Change the file to the following before rebasing and the end result is your commit adding the article about the C preprocessor will also contain the typo fix.

pick deadbeef1 Add an article about the C preprocessor
fixup deadbeef3 Fix typo in C preprocessor article
pick deadbeef2 Add an article about PAL video processing

The difference between fixup and squash is that squash awkwardly adds the commit message of the squashed commit to the commit message of the commit it is being squashed into. So I use fixup much more often then squash.

2.2.3 edit

Maybe you want to edit an entire commit. This is super useful if you accidentally commit something you didn’t mean to. For example, maybe you stuck a debugger statement in a js file somewhere while you were developing it and accidentally committed it.

Putting edit before that commit will allow you to remove the debugger line once git gets to that point in the rebase. There is something very important to do here though (and a lot of people get this wrong the first time).

Once you’ve fixed up that commit, git add the files you’ve modified and then run git rebase --continue. DO NOT COMMIT THE CHANGES. The git rebase --continue will do the commit with the old commit message for you.

2.2.4 Removing the line entirely

If you don’t want the commit any more, just don’t include the line with that commit in the rebase command list. Then when git does the rebase, that commit won’t be included.

2.3 After rebasing

Once you’re done, if you have already pushed your branch you’ll have to force push it to origin like the merge conflict example above.

$ git push --force-with-lease

And now it looks like you never make any mistakes. I’m sure your colleagues will be incredibly impressed.

2.4 Help, something went wrong!

The same advice applies as from the previous section

3 Someone rebased a branch I was looking at locally

This can be annoying if you’ve not seen it before. You run git pull and you get some strange errors or it is telling you it needs to commit something.

If you have done some of your own work on this branch too, then put down a temporary branch first, and then after this do step 4 on that temporary branch.

Afterwards, git fetch to update your local copy and then git reset --hard origin/branchname gets you back in place.

4 I branched of someone else’s branch, now that’s merged and I want my branch off main

This is a long title, but I couldn’t come up with a more descriptive name. This works very similarly to problem #1 but with a slight modification.

Just running git rebase origin/main will cause the rebase to pick up not only your changes but also all of the changes in the branch you branched off. And git really doesn’t like applying a diff twice.

Firstly, put down a temporary branch to go back to in case things go horribly wrong with git branch tmp/before-rebase.

So, you need to find the point at which you branched off (for example by using git log or similar), and then run

$ git rebase -i <commit hash> --onto=origin/main

At this point, everything will go ahead like in #1. And of course you could also apply the steps in #2 to change what your branch history looks like.

Conclusion

Hopefully with these tips you’ll be rebasing like a pro. This was a difficult article to write because I wasn’t sure how to organise it. However, hopefully once you’ve mastered these techniques, you’ll really understand not only the power of git, but also how helpful having a clean history in your project is.

Virtual joystick on Linux

Sun, 28 Feb 2021 00:00:00 +0000

A few months ago, I built a home made retropie based handheld console built around the raspberry pi 3B+. There probably wasn’t anything too exciting in the build itself (it was made mainly using standard parts with a 3d printed shell). However, I believe the way I got the input working isn’t as well documented as I believe it should be.

The end result of this project was a battery powered console that is incredibly uncomfortable to hold, so I’m not going to put together a full build explanation. I’m only going to talk about the arduino code and the driver I put together.

What was I trying to achieve?

Most people seem to use an arduino leonardo or a teensy microcontroller with their handheld raspberry pi consoles. Or they would connect the buttons on the console directly to the GPIO pins on the raspberry pi. This is a perfectly good option, but I wanted my console to have two analog joysticks, and due to the lack of analog to digital converter (ADC) on the raspberry pi, I needed to use something external.

I had a couple of atmega 328p’s, the microcontroller that powers the arduino uno among others, lying around so this seemed like a good option.

In the end, I wanted 4 analog axes and 14 buttons (up, down, left, right, start, select, A, B, X, Y, L1, L2, R1 and R2). An atmega 328p has 6 analog inputs and 14 digital IO ports. So it seems like my desired button scheme would just fit on a single chip.

The hardware

The wiring and hardware for this project wasn’t particularly interesting so I’ll skip over most of the details here. I wanted to keep the serial output of the arduino free, so no buttons were hooked up to digital pins 0 and 1 (which are used for this protocol). The analog joysticks were attached to analog inputs A0 - A3 with the remaining buttons on A4 and A5. This meant that every single pin was used on the microcontroller (literally the first project I’ve done where this is the case).

For size and cost reasons, this was also built as a minimal system, so no arduino uno inside my games console. Maybe I’ll write an article at some point about the easiest way to solder up an arduino compatible microcontroller on a perf board.

The software

This is where things get exciting. The code for this post can be found here: https://github.com/gwilymk/arduino-joystick. I recommend opening this up if you plan on following how this was done at home.

The atmega chip was programmed using the arduino environment (which I’ll refer to as the firmware), and the driver is written in rust.

The joystick firmware

Running on the atmega chip, is a very simple sketch that reads the state of all the buttons and sends packed bytes containing the result along the serial bus every 10ms. This isn’t particularly interesting, but the format of the data will be important when looking at the driver code.

The data format is:

Start marker:
1111111111111111

Which buttons are pressed, 1 means pressed in some order
0011101000101111

The state of the 4 joystick axes
0000000101000101
0000001001001000
0000001001001100
0000001001110010

So a single frame is a total of 12 bytes split into 2 byte sections. Since there are a total of 14 buttons, the first two bits of the button state will always be 0. Similarly, since the ADC of the arduino has 10-bit precision, the first 6 bits of the joystick state will always be 0s.

Therefore, the start marker is unique in that it is the only 2 byte field that starts with 1s (which is how the driver and the firmware line themselves up when the firmware starts up).

You can have a look at the code for this in the joystick-firmware folder in the repo if you want to see how this is implemented.

The joystick driver

This is where things get more exciting. Under the hood, we use udev to emulate the joystick. The gnarly bits of this are hidden by the input-linux crate which is used quite heavily. There are a few potential things that you might run into while trying to emulate a joystick yourself.

However hard you try to tell Linux that you are emulating a joystick, if it doesn’t have a trigger button, it won’t believe you. From my list of buttons above, there wasn’t a trigger. But I had to include it or my joystick wouldn’t show up.
There seem to be some strange rules about when you have to run as root or as a regular user. On my desktop I could run as my regular user, but on the raspberry pi I had to run it as root.

I’m going to quickly describe the code here in detail. I will assume some familiarity with rust, but it probably isn’t massively important to get the idea across :).

Creating the virtual joystick

let uinput_file = fs::File::create("/dev/uinput")?;
let device = input_linux::UInputHandle::new(uinput_file);

let input_id = input_linux::InputId {
    bustype: sys::BUS_VIRTUAL,
    vendor: 34,
    product: 10,
    version: 1,
};

The first thing we need to do is open the /dev/uinput file for writing. This is the file that udev expects to write to. We also assign some random vendor, product and version information to our joystick. It doesn’t really matter what you put here, but I guess you don’t want to clash with existing ones? (I’m pretty sure I just typed random numbers here myself).

device.set_evbit(input_linux::EventKind::Absolute)?;
device.set_evbit(input_linux::EventKind::Key)?;
device.set_keybit(input_linux::Key::ButtonTrigger)?;

for button in Button::all_buttons() {
    device.set_keybit(button.to_evdev_button())?;
}

Here we set various configuration options for our virtual joystick. The first says we’ll send absolute positioning events (this will be for the analog inputs). Then that we’re going to also send key events (which will be the buttons).

The keybits are listing all the key events we could possibly send. As mentioned above, you have to include ButtonTrigger otherwise Linux doesn’t work out that it is a joystick. The rest are the remaining buttons which are stored in an enum elsewhere.

let standard_info = input_linux::AbsoluteInfo {
    value: 0,
    minimum: -512,
    maximum: 512,
    fuzz: 0,
    flat: 0,
    resolution: 50,
};

device.create(
    &input_id,
    b"arduino-virtual-joystick",
    0,
    &Axis::all_axes()
        .map(|axis| input_linux::AbsoluteInfoSetup {
            axis: axis.to_evdev_axis(),
            info: standard_info,
        })
        .collect::<Vec<_>>(),
)?;

Now we create our device in /dev/uinput. The standard_info stores information about the joystick. I didn’t need to change many values here, but since the 10-bit ADC on the atmega produces numbers between 0 and 1024 with 512 being the neutral position, we scale this to -512 to 512 for each axis.

For some reason, you have to set up the axis information when creating the device but buttons beforehand.

At this point, if you run just this code, you’ll find a virtual joystick registered in your list of input devices.

However, in order to do anything you’ll need to send ‘events’ to udev.

Pressing buttons

pub fn button_press(&self, button: Button, is_pressed: bool) -> Result<(), Error> {
    let value = if is_pressed {
        input_linux::KeyState::PRESSED
    } else {
        input_linux::KeyState::RELEASED
    };

    self.write_event(input_linux::KeyEvent::new(
        empty_event_time(),
        button.to_evdev_button(),
        value,
    ))
}

A button press is actually a key event. All events come with an EventTime which didn’t seem to mind always being set to 0. I can’t remember if this meant something special (too long since I wrote this code).

A button press or release is just a key press or release with the correct button code. However, if you just do this, then not much is going to happen.

Since you could in theory press multiple buttons at once, and these multiple buttons at once could be important, after every event you send you must also send a synchronise event. This event will cause all the events since the last synchronise event to be processed.

pub fn synchronise(&self) -> Result<(), Error> {
    self.write_event(input_linux::SynchronizeEvent::report(empty_event_time()))
}

There isn’t much more to say about button events here.

Moving axes

pub fn move_axis(&self, axis: Axis, position: i32) -> Result<(), Error> {
    // error handling omitted

    self.write_event(input_linux::AbsoluteEvent::new(
        empty_event_time(),
        axis.to_evdev_axis(),
        position,
    ))
}

Moving an axis is an AbsoluteEvent. In this case, the position should be between -512 and 512 as set up earlier.

Hooking up the Serial connection

I wanted to minimise the number of external components. So the atmega’s serial connection is connected straight through to the raspberry pi. Since the raspberry pi runs at 3.3V, to simplify the voltage handling the microcontroller is also run at 3.3V. This works perfectly well according to the acceptable voltages ranges for an atmega 328p and means that it and the pi can be wired directly to each other.

Serial (or UART) can be found on GPIO pins 14 and 15 (physical pin 8 and 10) on the raspberry pi’s GPIO port. You need to set it up in the pi configuration as described here. With that set up, you can access the serial port on /dev/serial0.

So, I copied the executable built on the raspberry pi (or cross compiled) to /usr/local/bin/arduino-joystick-daemon and then in /etc/rc.local added /usr/local/bin/arduino-joystick-daemon /dev/serial0 &. Retropie immediately recognised the joystick and allowed me to configure it.

Conclusion

You don’t need to hook anything up to the USB port on your raspberry pi if all you need is a few analog inputs. Also, you should think about ergonomics a little if you want to design a games console with a raspberry pi inside it.

Grayscale PAL signals

Sat, 30 Jan 2021 11:55:56 +0000

I was inspired by Ben Eater’s video on the world’s worst video card to make my own. But in order to prove to myself that I fully understood how it worked, I decided to output composite PAL signals rather than VGA. This post is going to explain how composite signals work rather than how my implementation of the world’s even worsterer graphics card works.

I live in the UK, so here we use PAL signals rather than NTSC. When talking about grayscale, both are very similar, but just different enough to be annoying. I won’t be covering how they differ in this post, because I wouldn’t be able to confirm its accuracy.

How did CRT televisions work?

Although a strange question to ask first, the whole composite signal standard is based around the behaviour of CRT (or cathode ray tube) televisions. Technology connections has a wonderful video explaining the general concepts here, which I will recommend watching for further detail about how the television would produce the signal. I am going to go into much more depth about the actual signal itself, rather than the behaviour of the electron beam as the drawing happens.

Hopefully from this explanation, you should be able to create a terrible graphics card of your own!

Lines

A CRT doesn’t have pixels. Instead, the electron beam gets scanned across in lines. Each line has effectively got an infinite resolution, as you can change the intensity of the electron beam as much as you like (although capacitance will probably stop you from changing it too much).

Potential epilepsy trigger warning in the following video.

With a PAL signal, there are a total of 625 lines per frame, running at 25 frames per second. However, changing data at 25 frames per second produces noticeable flicker, so rather than update the entire screen 25 times per second, the odd lines get updated first and then the even lines. This is called interlacing. So 312.5 lines are updated at 50 frames per second, made up of 313 odd lines, and 312 even lines. Note that it is no coincidence that the updates happen at exactly the frequency of the AC power. This provided a very convenient source of a 50Hz timing signal for the TV to use to synchronise with the signal.

A single line takes 1/625/25 = 64μs to draw.

To control the brightness of a point in a line, set the voltage to a value between 0.3V and 1V. With 0.3V being black, and 1V being pure white.

However, we also need to tell the TV that the line has started, and also give it time to take the beam from the far end of the previous line to the start of the current one. In order to do that, a line starts with 4.6-4.8μs of 0V. This tells the TV that the line has started. There is then something called a back porch. This is a period of 0.3V which if you try to draw into, will be off the left of the screen. This time is around 5.6μs before the beam becomes visible on the screen. After this, voltages between 0.3V and 1V will draw the various brightnesses on the screen. Eventually, the line disappears off the end of the right hand side of the screen (slightly before the end of the line), at which point the next line starts.

So now we understand how a single line is drawn, and how we tell the TV that we have started drawing a line. Next, we need to cover how to tell the TV that we’re starting to draw a frame.

Synchronisation pulses

We need to tell the TV that a frame is about to start. However, we don’t just need to tell it that we’re about to start a frame, we also need to tell it that whether it is an odd or ever ‘half frame’. An odd frame will be one which draws all the odd lines, and an even frame one which only sends data for even lines.

It is helpful at this stage to think about ‘half lines’ for reasons that will be clear later. A half line is exactly as the name implies. It takes 32μs to draw a half line.

A half line will either be a short sync pulse or a long sync pulse. A long sync pulse is at 0.3V for 30μs and 0V for 2μs. A short sync pulse is at 0.3V for 2μs and 0V for 30μs.

To say you’re going to start an odd frame, send 6 short sync pulses, 5 long sync pulses followed by 5 short sync pulses. At that point, send the normal line information for the remaining 305 lines until the end of this half-frame. Then start the even frame with 5 short sync pulses, 5 long pulses and 4 short pulses. And the remaining 305 lines contain the even lines.

Non-interlaced video

In order to simplify video hardware (and what I ultimately ended up doing for my breadboard video card), you can send the information non-interlaced to the TV. If doing this, effectively send the odd half frame repeatedly rather than switching between odd and even half frames. Note that this means your frame rate will be 1 / (64μs × 313) = 49.92Hz.

However, according to this source, the PS2 on a non-interlaced game will use 304 lines rather than 305. I haven’t personally tried 305 lines to see what happens here, so the way I implemented this was to copy the non-interlaced format and use the odd frame cycle but with 304 lines resulting in a frame rate of 1 / (64μs × 313) = 50.0801Hz. TVs don’t seem to have an issue with this (or at least mine doesn’t).

Implementation notes

You’ll have noticed that I spoke about voltages the entire time here. One thing to note is that the input impedance for a composite cable is 75Ω (you can measure this with a multimeter). In order to actually produce these voltages required, you’ll have to use a suitable resistor to bring your control signal voltage to 0.3V or the analog value for the brightness.

Full demo

Using what Ben Eater teaches in his video about the world’s worst video card, and my research which unearthed the above information, I was able to put together my own video card.

And the result is a 128x128 image on a CRT. Here is a 960FPS video of the output from this circuit.

Another potential epilepsy trigger

The C preprocessor is awesome part III

Mon, 21 Dec 2020 22:09:06 +0000

This is the third part of a 3 part series on why the C preprocessor is awesome and showing you some tricks you should never use. In this part, we’re finally going to implement the TRY, CATCH and FINALLY macros I’ve been promising you since the beginning.

In part 1 of this series, we implemented a very nice test harness that let us write unit tests much more simply. In part 2, we implemented a LOCK macro for making it ‘easier’ to use mutexes. This will build on the ideas from both parts, so I recommend reading them first if you haven’t already.

Introduction

As you are probably aware, C doesn’t really do error handling. Depending on the function you’re calling can vastly change how you do the error handling. For example, some will return a non-zero value on error. Some will return a zero value on error. Some will not return anything and instead set errno.

In this post we’re going to add yet another way to signal errors! Exactly what everyone needs.

This would have been much harder without some prior art which I started with. The initial implementation came from here but this didn’t handle all the cases I wanted. I wanted the ability to catch all exceptions as well, so I implemented a solution which allowed either CATCH_ALL or FINALLY or neither. However, I was never happy with this solution so in the end I now have a mostly original implementation using hacks as never before seen (or at least I’ve never seen them before).

Another limitation of the approach above is it didn’t really handle calling other functions that throw exceptions. And what if you wanted to nest your exceptions a few layers deep?

Aim

The end goal here is to have an ergonomic exception system. Complete with ‘unwinding’ and no need to check statuses of every method in a slightly different way.

In the end, we’d like to be able to write code such as:

TRY {
    doSomethingDangerous();
} CATCH(SOME_EXCEPTION) {
    // this will only run if doSomethingDangerous throws SOME_EXCEPTION
} FINALLY {
    // this code will always run
}

Exceptions can be thrown using the THROW macro.

We’d also like to be able to return within the TRY and CATCH blocks, while still having the content of the FINALLY block run. We’ll try to add support for that too.

Unfortunately, I wrote this code in 2017 (currently almost 2021), so I’m not entirely sure how I came up with some of these hacks. I am therefore documenting how it was done, and commenting on the implementation, rather than building this up from scratch.

I recommend loading up exceptions.h from the repo you can find here and referring to it along with the article.

The general approach

At it’s heart, the exception system provides a stack of longjmp locations to jump to. When we get to a TRY block, we push onto the stack of exception handling places, and when THROW gets called we longjmp back to the most recent TRY block. However, a few hacks were needed to get the ergonomics that we’re used to in other languages.

The TRY macro

Let’s have a closer look at the TRY block (this is the most complicated since it contains the code for all the other cases, but worth understanding how it works).

#define TRY                                                           \
    for (TryData__ tryData__ =                                        \
             {setjmp(exceptionStack__[try__(__FILE__, __LINE__)]), 0, \
              (void *)0, (void *)0};                                  \
         tryData__.runFourTimes <= 3; tryData__.runFourTimes++)       \
        if (tryData__.runFourTimes == 0)                              \
        {                                                             \
            __label__ continueLabel;                                  \
            tryData__.continueLabel = &&continueLabel;                \
        continueLabel:;                                               \
        }                                                             \
        else if (tryData__.runFourTimes == 3)                         \
        {                                                             \
            if (!catchHandled__())                                    \
            {                                                         \
                RETHROW;                                              \
            }                                                         \
            endTry__();                                               \
            if (tryData__.returnTo)                                   \
            {                                                         \
                goto *tryData__.returnTo;                             \
            }                                                         \
        }                                                             \
        else if (tryData__.runFourTimes == 1 && tryData__.tryAttempt == 0)

We have defined above an exceptionStack__ of jmp_bufs. This has some defined size, and externally we keep track of the top of the stack. The try__ method returns the current index of the top (and prints and terminates if the call stack is exceeded). It keeps track of the current file and line number to generate nice stack traces (thought they were just for java did you?).

We now save the current location to the stack. TryData is a simple struct defined as follows:

typedef struct
{
    int tryAttempt;
    int runFourTimes;
    void *returnTo;
    void *continueLabel;
} TryData__;

This is used because we can only define a single variable in the initialiser of a for loop. So if I could, these would be defined as individual local variables. For the rest of this article, I’ll be referring to these as local variables, because that’s what they really are. Importantly, when we get longjmpd back to where we setjmpd, this is re-initialised to the 0 state. Except tryAttempt which set to 0 the first time, and to something non-zero by the longjmp in the case of an exception.

runFourTimes is incredibly well named. This is our loop counter, and surprisingly, counts from 0 to 4 to cover all the cases (see the LOCK macro implementation in part 2 of this series for a better explanation of why this is needed).

There is some massive abuse of the gcc extension local labels. We’re going to need to be able to jump out of the current block later, so just keep in mind the runFourTimes == 0 case. Let’s skip the runFourTimes == 3 case for now.

The final case, when runFourTimes is 1 and tryAttempt is 0. Because tryAttempt is 0, we haven’t been longjmpd to, and because runFourTimes is 1, the initialisation code has run.

In this case, we finally execute the code inside the TRY block.

The CATCH macro

#define CATCH(value)                                                                                    \
    else if (tryData__.runFourTimes == 1 && tryData__.tryAttempt == (value) && (catchHandled__() || 1))

This is reasonably simple. We check that runFourTimes is 1 (so just after the initialisation has run), that tryAttempt is equal to the exception value we care about and then a slightly confusing call to catchHandled__() || 1.

catchHandled__() is a call that informs the exception system that we’ve actually handled this exception. Since all the previous conditions passed, we want to call this state mutating function. However, we can’t actually put that inside the if statement, because then it wouldn’t be able to follow the CATCH with some braces the way we want to. So by relying on the short circuiting behaviour of &&, we only call catchHandled__() if we have actually got a matching CATCH statement. Since catchHandled__() can return both 1 and 0, and we would like to ensure that this statement is true regardless, we || this with 1 to guarantee that it is truthy.

So the content of this block will only run if we are actually catching the exception with the value we intend to, and if the currently throwing exception is handled, then the catchHandled__() function is called.

The CATCH_ALL macro

The CATCH_ALL macro is used in place of catch (Throwable e) in Java. It will catch any exception not previously caught in the chain (another reason to use else if here, only one catch statement will ever execute).

The macro is defined as follows:

#define CATCH_ALL(e)                                                         \
    else if (tryData__.runFourTimes == 1 && tryData__.tryAttempt > 0 &&      \
             (catchHandled__() ||                                            \
              1)) for (volatile Exception e = {.type = tryData__.tryAttempt, \
                                               .message = catchMessage__()}; \
                       (e).type != -1; (e).type = -1)

This similarly contains some hacks to improve ergonomics and also compiler warnings. We would like to be able to store the exception itself in some local variable, but this variable needs the correct scope. It works very similarly to the CATCH macros, except we fetch the construct the exception object. Since we need a new variable declared, using a for loop which only executes once does this perfectly. We have something silly in the test and next parts to ensure the loop runs exactly once.

The FINALLY macro

The FINALLY macro is by far the simplest.

#define FINALLY else if (tryData__.runFourTimes == 2)

runFourTimes == 2 has been reserved for this case. This will run after all CATCH blocks and the TRY block which happen on run 1.

The RETURN macro and the return of runFourTimes == 3

Let’s have a look at the RETURN macro:

#define RETURN(x)                                                              \
    do {                                                                       \
        __label__ returnPoint;                                                 \
        __auto_type retValue = (x);                                            \
        tryData__.returnTo = &&returnPoint;                                    \
        goto *tryData__.continueLabel;                                         \
    returnPoint:                                                               \
        return retValue;                                                       \
    } while (0)

Isn’t it nice to be back in the wonderful world of matching brackets, terminated statements and the like? And also a do {} while(0) loop again?

This, once again uses local labels, except this time I’ll actually explain how they’re used. Notice the __auto_type. This is equivalent to C++'s auto and Java and C#’s var. You can find __auto_type mentioned here.

But why is the RETURN macro so complicated?

We would like code in the FINALLY block to run after the code declared in x has run, but before we actually return. Mainly this useful for code like:

Resource someResource = createResource();
TRY {
   int value = doSomeCalculationWith(someResource);
   RETURN(value); 
} FINALLY {
    cleanupResource(someResource);
}

And in this case, not only will the FINALLY block run if doSomeCalculationWith throws an exception, but also just before we return value.

Unfortunately, because of our limitations with just simple text substitution with C macros, we have to put the return statement where RETURN is.

So, in this case, we set returnTo to the point in the code where we actually return, and then jump to the continueLabel. But where continueLabel?

Remember all the way back in the TRY macro?

if (tryData__.runFourTimes == 0)                              \
{                                                             \
    __label__ continueLabel;                                  \
    tryData__.continueLabel = &&continueLabel;                \
continueLabel:;                                               \
}                                                             \
else if (tryData__.runFourTimes == 3)                         \
{                                                             \
    if (!catchHandled__())                                    \
    {                                                         \
        RETHROW;                                              \
    }                                                         \
    endTry__();                                               \
    if (tryData__.returnTo)                                   \
    {                                                         \
        goto *tryData__.returnTo;                             \
    }                                                         \
}

Continue label will take us inside this if statement, where we can then immediately jump out of and do the next stage of the loop. So now runFourTimes will be 2 (and run any FINALLY blocks) and then get to the case where runFourTimes is 3.

catchHandled__() will return 0 if it hasn’t already been called and an exception has been thrown. In this case, we should bubble the exception up the stack. endTry__() will pop the top value off the stack without jumping to it, effectively announcing that we’re done in this TRY block. And then the magic of the local labels will jump us right back to the line above the return statement and we can actually return. If we don’t want to return, returnTo will still be NULL and no jump happens.

Conclusion

This is a bit of a whirlwind tour of this code I wrote just over 3 years ago. It was too good to share, but I appologise that this probably isn’t the most coherent account of how it works.

If you have any questions or comments, feel free to contact me, and have a dig around the exception code and the enhanced test helper in the full repo.

The C preprocessor is awesome part II

Wed, 30 Sep 2020 17:14:44 +0100

This is the second part of a 3 part series on why the C preprocessor is awesome and showing you some tricks you should never use. This part is going to be the shortest, showing off a really simple trick that makes your macros look like actual keywords. But this is a very important section for showing how to implement TRY, CATCH and FINALLY in the final part.

In part 1 of this series, we implemented a very nice test harness that let us write unit tests much more simply. This will build on the ideas from part 1 so I recommend reading that first if you haven’t already.

Introduction

In this installment, I’m going to run through creating a LOCK macro that works like lock in C# or synchronized in Java. Have you ever looked at those languages and wished that C could do that too? Well look no further. And also wish you’d never asked. By the end of this post, you’ll have a library that lets you use pthread mutexes as follows:

pthread_mutex_t myMutex;
pthread_mutex_init(&myMutex, NULL);
// ...
LOCK(&myMutex) {
    // do something
}

and because we’re writing C and goto fail is a thing that will never happen, we would like to be able to use our macro as if it were an actual keyword:

LOCK(&myMutex) functionCall();

and have the mutex get locked and unlocked properly.

What do we want out of this?

As with part 1, it is useful to decide what we want our macro to expand to in the end. In this case, we would want the above to expand to something like:

pthread_mutex_t myMutex;
pthread_mutex_init(&myMutex, NULL);
// ...
pthread_mutex_lock(&myMutex);
{
    // do something
}
pthread_mutex_unlock(&myMutex);

which leads us to a small problem. In our LOCK usage, the macro is at the beginning and we want code to run both at the start and at the end of our block. Turns out, there is a really simple way we can get this to work.

One small trick

Let’s try rewriting the above in a way that { // do something } is at the end.

for (int i = 0; i < 3; i++) {
    if (i == 0) {
        pthread_mutex_lock(&myMutex);
    } else if (i == 2) {
        pthread_mutex_unlock(&myMutex);
    } else {
        // do something
    }
}

and with a careful bit of bracket removal, we have our LOCK macro:

#define LOCK(mutex)                            \
    for (int i__ = 0; i__ < 3; i__++)          \
        if (i__ == 0) {                        \
            pthread_mutex_lock(mutex);        \
        } else if (i__ == 2) {                 \
            pthread_mutex_unlock(mutex);      \
        } else

It is almost too good to be true. You can use this with or without brackets, so both of the above examples of how we’d want to use this macro work perfectly. And both clang and gcc will completely optimise the loop away entirely! But there are some issues you need to consider (and why you should never use this in production).

Issues

Lets start with an unfortunate problem here. You cannot return inside the block following LOCK. That would cause i = 2 to never happen so the mutex is never unlocked, which is definitely a bad thing.

Similarly, a break statement or continue statement inside the block following LOCK would effect the for loop defined in the LOCK macro rather than the outer statements. For example, the following will execute both // do something and // do something else and leave myMutex locked!

switch (i) {
    case 1:
        LOCK(&myMutex) {
            // do something
            break;
        }
    case 2:
        // do something else
        break;
}

Given that I recommend never using this in production anyway, it doesn’t matter too much. But we should try to make these compiler errors!

Nested functions

Let’s dive off ISO C spec once again and delve into the wonderful world of GCC extensions. We’re going to need the CONCAT macro from last time, and we’ll use a feature called nested functions. This lets you define a function inside another function. And the nested function can access all the variable of the containing function up to the point of its definition. So in some ways, it is almost indistinguishable from a block! Except that you can’t continue or break on the outer scope.

A useless example of how they can be used is as follows:

int main() {
    int returnTwo(void) { return 2; }

    return returnTwo();
}

One thing to note is that if you need to declare the nested function before its definition, you need to use auto, so as follows:

int main() {
    auto int returnTwo(void);
    
    int i = returnTwo();
    int returnTwo(void) { return 2; }

    return i;
}

That’s all you need to know about nested functions before we show the final macro it all its glory!

LOCK with nested functions

This unfortunately loses the ability to use the lock statement without braces. But given my preferences to always include braces, this isn’t a massive downside to me.

I think this is easiest to just show the final macro and explain it afterwards rather than build up to it

#define LOCK(mutex)                                         \
    auto void CONCAT(lockNestedFunction__, __LINE__)(void); \
    pthread_mutex_lock(mutex);                              \
    CONCAT(lockNestedFunction__, __LINE__)();               \
    pthread_mutex_unlock(mutex);                            \
    void CONCAT(lockNestedFunction__, __LINE__)(void)

This looks very different to before!

Similar to the previous part, we need a unique name for each function, so using __LINE__ will at least mean you can use a LOCK once per line. We lock the mutex, call the newly defined nested function and unlock the mutex on the other side. The final line starts the definition of the nested function, but leaves it up to the user of the macro to add the braces.

This has a few advantages over the previous version of this macro with the for loop. Trying to compile the switch example above results in the compiler error of:

error: a label can only be part of a statement and a declaration is not a statement
     auto void CONCAT(lockNestedFunction__, __LINE__)(void); \

hmm… Not quite the error we expected.

This is a fun side effect of labels in C. A label must precede a statement in C. There is an easy fix for this. An empty statement counts as a statement, so we can either fix our macro by starting it with a ; or put a ; after the : in the case statement.

After doing either of those (at this point, we’re so far from doing something sensible that either is okay), we get the compiler error:

file.c: In function ‘lockNestedFunction__33’:
file.c:36:13: error: break statement not within loop or switch
             break;
             ^~~~~

which is what we wanted!

Unfortunately this doesn’t fix the return issue from before, but at least it won’t leave the mutex permanently locked. And if you try and return something that isn’t void, you’ll get a compiler error.

Conclusion

NEVER DO THIS!

The C test framework from part I could be considered vaguely sensible. Especially if it convinced people to write unit tests in their C programs that they wouldn’t have before. But this is so full of issues, for example which key words can’t be used within the block, that you’ll end up with something hard to debug in the future. However, this was a fun look into some silly tricks you can use to get some code defined after the macro to run in the middle of the macro, which will be a very useful idea for part III of this series.

Stay tuned!

The C preprocessor is awesome part I

Sat, 15 Aug 2020 16:40:40 +0100

Well… It probably isn’t. But in this series of posts, I’m going to walk you through some terrible ideas which somehow vaguely work. None of this is a good idea, but it is fun to push simple text preprocessing and the C programming language to it’s illogical limit.

This series of posts was inspired by the crazy definition of ARRAY_SIZE somewhere floating in the Linux kernel source code, which I first became aware of in a post by a friend of mine. And of course I was also inspired by this classic which helped me come up with a few solutions to issues I was having while developing these.

All these examples are compiled with gcc. Your success with other compilers may vary.

I will assume familiarity with the C programming language and some comfort with the C preprocessor for the duration of this series.

Introduction

This series will come in three parts, with this being the first. I believe I’m staying away from undefined behaviour at least for the first 2 parts. The final part is probably very unsafe and I was only lucky that it worked for me, but it is fun nonetheless! In this post, I’ll show you how to write a simple unit test framework allowing you to write your unit tests in C as follows:

TEST("my fist test") {
    // do some unit testy stuff
}

TEST("my second test") {
    // more unit testy stuff
}

In the second part, I’ll show you how to write pseudo C# / Java constructs like lock or using as follows:

LOCK(my_mutex) {
    // do something with threads
}

USING(my_resource) {
    // this'll be disposed after use
}

And in the final part, I’ll show you how to (probably with loads of undefined behaviour) write a try-catch implementation:

TRY {
    do_something_dangerous();
} CATCH(SOME_EXCEPTION) {
    // this code will only throw if do_something_dangerous THROWS(SOME_EXCEPTION)
} FINALLY {
    // this code will always run
}

Along the way, I hope you’ll learn a few tricks that you should never use in production, but are cool anyway.

The problem I was trying to solve

Writing unit tests for your code is definitely a very good thing. Automated regression testing is essential for any project. But tests are often a pain to write. And if they are a pain to write, you are tempted to write fewer of them. This is clearly a bad thing. So what we’re going to put together here is a really simple unit testing framework for your project entirely in GNU C99. By the end of this, we’ll be able to write tests like this:

#include <test_helper.h>

TEST("my awesome test") {
    assert(1 == 1);
}

and, although I won’t spend too long working on the output system for this, you’ll be able to run all these tests easily!

An approach to automation

You could try writing crazy macros straight off, but it is probably easier to start with what we want the eventual code to look like first. So lets take the example above. We’ll assume the existence of some test_main.c file, which would contain code similar to this:

static void my_awesome_test(void) {
    // equivalent of assert(1 == 1) here
}

typedef void (*TestFunction)(void);

TestFunction testFunctions[] = {
    my_awesome_test
};

int main() {
    int numTests = sizeof(testFunctions) / sizeof(testFunctions[0]);
    for (int i = 0; i < numTests; i++) {
        testFunctions[i]();
    }
}

So I guess the test macro can be something like:

#define TEST(name) \
    static void name(void)

but this forces the test name to be a valid C identifier. And we might want to use a nicer string name for the test name (just because we can). So maybe we want to store the test along with its name in the test_main.c file?

Also, we want to store the name of the test along with the function anyway, since we would like to print the test names as we run them. That way, if a test fails, we know exactly which one it is.

#include <stdlib.h>

typedef void (*TestFunction)(void);

struct NamedTest {
    TestFunction test_function;
    const char *test_name;
    struct NamedTest *next;
};

struct NamedTest *tests;

void register_test(TestFunction test_function, const char *test_name) {
    struct NamedTest *test = malloc(sizeof(struct NamedTest));
    test->test_function = test_function;
    test->test_name = test_name;
    test->next = tests;
    tests = test;
}

int main() {
    register_test(my_awesome_test, "My awesome test");

    struct NamedTest *current_test = tests;
    while (current_test) {
        printf("Running test %s\n", current_test->test_name);
        current_test->test_function();

        struct NamedTest *next_test = current_test->next;
        free(current_test);
        current_test = next_test;
    }
}

This is pretty much the final form of the test main file. But using it does have one pretty major annoyance. If you want add a new test, you have to manually register it. So you end up repeating the test function name twice, and the string name is nowhere near the actual test definition. We will attempt to fix both of these problems.

GCC to the rescue

If you have a look through the GCC function annotations, you can find some interesting ones. The one we’re interested in here is constructor. This lets us state that a function should run before main(). If we can somehow register our test function as part of the TEST declaration, and therefore allow us to not have to repeat ourselves.

So we end up with a TEST macro that looks something like this:

#define TEST(test_name, test_function_name)                    \
    static void test_function_name(void);                      \
    __attribute__((constructor))                               \
    static void CONCAT(register_, test_function_name)(void) {   \
        register_test(&test_function_name, test_name);         \
    }                                                          \
    static void test_function_name (void)

Ignore the CONCAT definition for now. It concatenates two literals, but its definition is non-obvious. So I’ll cover that in the next section.

There’s a lot going on in the macro above, so it is probably easiest if we expand it

// This
TEST("My awesome test", my_awesome_test) {
    /* ... */
}

// Turns into this:
static void my_awesome_test(void);
__attribute__((constructor))
static void register_my_awesome_test(void) {
    register_test(&my_awesome_test, "My awesome test");
}
static void my_awesome_test(void) {
    /* ... */
}

The forward declaration is necessary because we don’t want to have to put anything after the final }. So all the work needs to be done in the TEST macro.

It’s slightly annoying that we still have to repeat ourselves here with both the test name and the function name. An easy way around that is using the __LINE__ ‘macro’. __LINE__ is defined to be the current line number. Since we expect users to write tests on different lines, if we put the line number after the test name, we can make all the function names unique without forcing the user to repeat themselves.

So we could instead write the macro as follows:

#define TEST(test_name)                                              \
    static void CONCAT(test_function_, __LINE__)(void);              \
    __attribute__((constructor))                                     \
    static void CONCAT(register_test_, __LINE__)(void) {             \
        register_test(&CONCAT(test_function_, __LINE__), test_name); \
    }                                                                \
    static void CONCAT(test_function_, __LINE__) (void)

Aside: The CONCAT macro

The C preprocessor provides the ability to concat two identifiers together. This is done using the ## operator. There are some annoyances with it however, which I’ll go into detail here.

Firstly, we had to use the CONCAT macro in the above example, because if we would have instead written test_function_ ## __LINE__ would end up expanding to test_function___LINE__. Which would obviously not be unique for each test in the same file, and also misses the line number which we wanted.

This behaviour is well documented in this wikipedia article. But I’ll summarise here.

The C preprocessor expands macros in the following stages

Stringification operations are replaced, without performing expansion (this is the # operator which isn’t covered here)
Parameters are replaced with their replacement, without performing expansion
Concatenation operations are replaced with the concatenated result without expanding the resulting token
Tokens originating from parameters are expanded
The resulting tokens are expanded

So if we look through the list above considering test_function_ ## __LINE__, then we can see that concatenation in step 3 is performed before step 5 which would turn __LINE__ into the current line.

One way we can get around that is to create a macro which we’ll call CONCAT, which simply concatenates the arguments. However, this doesn’t work:

#define CONCAT(a, b) a ## b

Suppose you wrote CONCAT(test_function_ ## __LINE__). Let’s follow the substitution pattern above.

Initially, by rule 5, it expands to test_function_ ## __LINE__. Then, by rule 3, the two fields are concatenated. Before rule 4 where the tokens originated from parameters are expanded.

The way around this, and the way we define the CONCAT macro above is as follows

#define CONCAT2(a, b) a ## b
#define CONCAT(a, b) CONCAT2(a, b)

This seems a bit silly, but it’ll now mean that the expansion behaves as you want it to. Let’s try expanding CONCAT(test_function_, __LINE__) again. Firstly, by rule 5 this expands to CONCAT2(test_function_, __LINE__). Then, by rule 4, the tokens originating from parameters are expanded, so you get CONCAT2(test_function_, 3) (say this is on line 3). This then gets expanded by rule 5 again to test_function_ ## 3 which finally by rule 3 is concatenated to the desired test_function_3.

Conclusion

You can create a really simple test framework in C using the macro

#define CONCAT2(a, b) a ## b
#define CONCAT(a, b) CONCAT2(a, b)

#define TEST(test_name)                                              \
    static void CONCAT(test_function_, __LINE__)(void);              \
    __attribute__((constructor))                                     \
    static void CONCAT(register_test_, __LINE__)(void) {             \
        register_test(&CONCAT(test_function_, __LINE__), test_name); \
    }                                                                \
    static void CONCAT(test_function_, __LINE__) (void)

and some simple helper functions.

It would be reasonably easy to extend the runner to, for example, only run tests who’s names matched command line arguments. I hope this gives you some ideas as to how you can metaprogram in C in ways you never thought were possible. And maybe persuades you to write a few unit tests for your project that doesn’t currently have any.

Stay tuned for the next two parts of this series!

Gwilym's blog

Git rebase like a pro

The most important step

Contents

What does a rebase actually do?

1 My PR has a merge conflict

1.1 Put down a temporary branch

1.2 Start the interactive rebase

1.3 Merge conflict!

1.4 Help, something went wrong!

1.4.1 The rebase totally failed but it claims to have finished

1.4.2 The rebase is still in progress but I don’t want to do it any more

1.4.3 I thought I wanted this commit, but I don’t really

2 My branch’s history makes no sense

2.1 Put down a temporary branch

2.2 Start the interactive rebase

2.2.1 pick

2.2.2 fixup

2.2.3 edit

2.2.4 Removing the line entirely

2.3 After rebasing

2.4 Help, something went wrong!

3 Someone rebased a branch I was looking at locally

4 I branched of someone else’s branch, now that’s merged and I want my branch off main

Conclusion

Virtual joystick on Linux

What was I trying to achieve?

The hardware

The software

The joystick firmware

The joystick driver

Creating the virtual joystick

Pressing buttons

Moving axes

Hooking up the Serial connection

Conclusion

Grayscale PAL signals

How did CRT televisions work?

Lines

Synchronisation pulses

Non-interlaced video

Implementation notes

Full demo

The C preprocessor is awesome part III

Introduction

Aim

The general approach

The TRY macro

The CATCH macro

The CATCH_ALL macro

The FINALLY macro

The RETURN macro and the return of runFourTimes == 3

Conclusion

The C preprocessor is awesome part II

Introduction

What do we want out of this?

One small trick

Issues

Nested functions

LOCK with nested functions

Conclusion

The C preprocessor is awesome part I

Introduction

The problem I was trying to solve

An approach to automation

GCC to the rescue

Aside: The CONCAT macro

Conclusion