SkyLyrac

BlocksDS SDK Version 1.1.0

Wed, 15 May 2024 02:19:00 +0000

It’s been over a year since the first release of BlocksDS, and over half year since this blog post, which was written after version 0.8.1 was released. The current version is 1.1.0, which means it’s time to write a new post with the current state of BlocksDS!

First of all, check this up-to-date introduction if you have never heard of BlocksDS. Feel free to skip it if you are already familiar with it! In short, it is an actively maintained SDK to develop applications for the DS in C or C++.

There are too many changes between versions 1.1.0 and 0.8.1 to list them here. You can check the changelog for more details, but this is a list of the most important changes:

NitroFS has been fully reimplemented by asie, which increased filesystem performance by orders of magnitude. The previous system (NitroFAT) was a workaround implemented by me which required two levels of FAT filesystem access, and that was very slow.
There is experimental and preliminary support for the Teak DSP of the DSi. It isn’t ready to be used by most people, but it’s in a good enough state that developers can use the current toolchain and libraries to make incremental improvements.
A new API has been added to use Slot-2 peripherals like RAM expansion packs, rumble, gyroscopes and tilt sensors.
The default Makefiles have been simplified and they now use compiler-provided .specs files (which will make it easier to keep up-to-date with potential compiler and linker flags changes).
A race condition between scanKeys() and touchRead() has been fixed.
The RTC interrupt is no longer used to update the RTC time. Most emulators didn’t support it, and it wasn’t supported by the 3DS in DS/DSi mode.
The documentation of BlocksDS and all its libraries has been dramatically improved and it is now available online: https://blocksds.skylyrac.net
Lots and lots of examples have been added.

Some minor changes that are also significant:

There are new helper functions to set and get the current RTC time in a convenient way. The old setter function didn’t work.
glTexImage2D() now accepts sizes in pixels as well as GL_TEX_SIZE_ENUM values. This is something that has always bothered me, the requirement to use the enumeration values always made using this function very awkward.
There have been some improvements to grit to improve the grf format. libnds now has functions to read graphics from grf files, and they are used in some examples.
dlditool has been replaced by dldipatch, which is less buggy.
Some libc locking functions (_retarget_lock_*()) have been implemented to allow libc functions to work in a multithreaded environment.
The following libc functions have been implemented: realpath(), utime(), utimes(), scandir(), alphasort(), versionsort().
Added nitroFSOpenById() and nitroFSFopenById() functions, allowing opening files directly without paying the cost of a directory lookup. Accordingly, NitroFS file systems which contain a FAT table but no FNT table can now be opened.
There is now a function to get the name of the default drive (sd: for DSi, fat: for DS).
The value of the RAM size field in REG_SCFG_EXT in the ARM9 is now set to 16 MB or 32 MB instead of being fixed to 32 MB even in retail DSi units.

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Dual screen 3D on the NDS

Thu, 12 Oct 2023 21:36:00 +0000

The Nintendo DS has a GPU with a 3D engine that supports a surprising amount of features. Normally it can only be used to display 3D graphics on one screen, but it is possible to display 3D on both screens by using a special video capture circuit.

This technique isn’t straightforward. The video hardware of the NDS is very flexible, and there are several ways to achieve 3D graphics on both screens.

Over the last few weeks I’ve been working on improving the dual screen 3D support of Nitro Engine. It has never been particularly reliable (when the framerate drops, the same output is shown in both screens), and it is important that it is reliable because games that use dual 3D are also likely to push the 3D hardware to the limit, and to have framerate drops every now and then.

This post is a very detailed explanation of how I’ve implemented things in Nitro Engine. I’ve explained the reasons why each mode may be used, as well as their limitations.

If this post is too long for you to read, just use NE_InitDual3D_DMA() in your games and skip the read! However, feel free to keep reading if you care about the details about how all of it is implemented.

Something that applies to all the systems is that the 3D engine can only send the output to one of the two screens during a specific frame. Any dual 3D setup implies saving that 3D engine output to VRAM and displaying it on the other screen during the following frame. Essentially, the main graphics engine and sub graphics engine need to switch from one screen to the other after every frame.

A huge thanks to mtheal and JustBurn for the NDS Homebrew VRAM Banks Selector and the NDS Homebrew VRAM BG Allocation Conflict Viewer, tools that made my life a lot easier when working on this. Check them out, and their source code on GitHub.

1. Memory usage

First of all, it is important to mention that dual 3D comes at a big cost. It is impossible to have dual 3D without using two of the main VRAM banks (A, B, C and D) as framebuffers. This means that half of the memory that the developer can allocate for textures won’t be available at all. There are two main things to consider:

Compressed textures: They are the most efficient way to have textures in VRAM, and they need to be stored in a combination of VRAM A and B or VRAM B and C. All the dual 3D modes of Nitro Engine leave VRAM banks A and B available for textures, so compressed textures can be used.
Clear bitmap: It is possible to store a bitmap with its own depth map (sort of a Z-buffer for the bitmap) in VRAM banks C and D. While this is an interesting feature, it isn’t used nearly enough to worry about it, as it is a very inefficient way to use VRAM (it requires 50% of the texture VRAM). In dual 3D mode the developer can only use only 50% of the total memory available for textures, so clear bitmaps aren’t useful.

This is a comparative table of all modes supported by Nitro Engine and how the different VRAM banks are used. Each mode will be explained in each own section:

	Single screen 3D	Dual screen 3D	Dual 3D FB	Dual 3D DMA
VRAM A	3D textures [1]	3D textures [1]	3D textures [1]	3D textures [1]
VRAM B	[1]	[1]	[1]	[1]
VRAM C	[1]	Framebuffer 1	Framebuffer 1	Framebuffer 1 + Debug console [3]
VRAM D	[1]	Framebuffer 2	Framebuffer 2	Framebuffer 2
VRAM E	3D palettes	3D palettes	3D palettes	3D palettes
VRAM F	Debug console	Debug console	[2]
VRAM G
VRAM H
VRAM I				Pseudo FB + Debug console [3]

Note [1]: It is possible to tell Nitro Engine to not use specific VRAM banks out of A, B, C and D. This is useful when using Nitro Engine at the same time as some other library like NFlib. It is also possible to tell Nitro Engine to not use VRAM banks A or B in dual 3D mode, but this isn’t normally useful.

Note [2]: The debug console isn’t supported in this mode.

Note [3]: The debug console is replicated in both VRAM I and the space of VRAM C that isn’t used by the video capture. This also means that enabling the debug console doesn’t require any additional memory banks, unlike in other modes (however, it uses a bit of CPU). More details below.

2. The capture unit

The capture unit allows you to capture the output of the main graphics engine. It is possible to capture the 3D output by itself before any layering effect, or the combined 2D+3D output. This last mode is useful if you want to display a 2D background on top of the 3D output, and then display that on the other screen. In Nitro Engine this is used to display the debug console on top of the 3D output.

It is a very flexible unit. It lets you select the size of the capture, the VRAM bank used as destination (A, B, C or D), and even an offset for the destination bank (for example, if you want to start saving the captured output after the first fourth of the bank). Check GBATEK for more information.

The only problem with this unit is that the destination bank must be mapped to the CPU (LCD mode if you are using libnds). This restricts a lot what you can do. There is a mode that lets you use the contents in VRAM as a framebuffer even when it is mapped to the CPU, but it doesn’t let you layer anything on top of it.

3. Single screen 3D mode

Before talking about dual 3D, let’s start with single screen 3D, which is easier to explain. VRAM banks are used like this:

VRAM A, B, C, D: Textures.
VRAM E: Texture palettes.
VRAM F: Debug console (if it is enabled).

The output in the main screen is:

Layer 0: 3D output

When the debug console is enabled, it changes a bit. The priorities of layers 0 and 1 are swapped so that the debug console appears on top of the 3D output. VRAM F is setup as main engine background memory, and:

Layer 0: 3D output, priority 1.
Layer 1: Debug console, priority 0.

4. Dual screen 3D mode

The source code for regular dual 3D mode is here and the source code for the console initialization is here.

This is the traditional way to handle dual 3D, and it is used in multiple examples that can be found online.

VRAM banks are used like this:

VRAM A, B: Textures.
VRAM C, D: Framebuffers.
VRAM E: Texture palettes.
VRAM F: Debug console of main screen (if it is enabled).

Odd frames:

VRAM C is mapped as sub engine background. It holds a 16 bit framebuffer.
VRAM D is mapped to the CPU.
VRAM F is mapped as main engine background. It holds the debug console.

The output of the main screen is the combined output of the 3D engine and the main 2D engine, which displays the debug console.

The output of the sub screen is the background stored in VRAM C.

The capture unit takes as input the same output as the main screen.

Even frames:

VRAM C is mapped to the CPU.
VRAM D is mapped as sub engine sprites. It holds a 16 bit framebuffer.
VRAM F isn’t used.

The output of the main screen is the combined output of the 3D engine and the main 2D engine, which isn’t showing anything right now.

The output of the sub screen is the background stored in VRAM D. However, it isn’t possible to use VRAM D as sub engine background memory, so a grid of 64x64 sprites is setup so that they display the contents of VRAM D as a 256x192 image.

The capture unit takes as input the same output as the main screen.

Advantages:

The latency of the 3D rendered image is zero. It is directly displayed on the screen without any delay.
The screen effects based on changing the horizontal scroll every scanline work.
The debug console is supported.
No CPU or DMA processing is needed.
All 256x192 pixels of the screens are used.

Disadvantages:

If the framerate ever drops below 60 FPS, the same 3D output will be displayed on both screens until the next frame is rendered. It can happen when loading assets at runtime, for example. This happens because only one frame is actually displayed from a framebuffer. The other one depends on the actual output of the 3D graphics engine.

While screen A is displayed from a framebuffer, the framebuffer of screen B is capturing the output of the new screen B. During the next frame, if screen A can’t be drawn, the framebuffer of screen B will be displayed from a framebuffer while the 3D engine still displays the previous screen, which is screen B.
The textures and palettes of the NDS use 15 bit colors, that is, they use 5 bits per component (R, G, B). However, the LCD screen of the NDS uses 6 bits per component. Normally the least significant bit isn’t used, but it can be used if two poligons are blended together, for example.

This is a problem because the video capture unit doesn’t capture the 6 bits. If the output switches between actual 3D output and captured 3D output the user may notice that the image changes slightly between frames.
The debug console requires an additional VRAM bank, even if it’s one of the small ones.

Conclusion:

I discourage you from using this mode. It’s too easy to fall below 60 FPS and hit the issue where both screens will show the same output.

5. Dual screen 3D FB mode

The source code for dual 3D FB mode is here.

This is another well-known way to handle dual 3D, but it prevents you from using the 2D engine in the screen that is being updated in that frame. This prevents us from displaying a debug console in one screen because it would only be displayed there half of the frames.

It is named after the MODE_FB2 and MODE_FB3 constants of libnds.

VRAM banks are used like this:

VRAM A, B: Textures.
VRAM C, D: Framebuffers.
VRAM E: Texture palettes.

Odd frames:

VRAM C is mapped as sub engine background. It holds a 16 bit framebuffer.
VRAM D is mapped to the CPU.

The main engine is setup in direct VRAM display mode, so the output of the main screen is the contents of VRAM D.

The output of the sub screen is the background stored in VRAM C.

The capture unit takes as input the 3D output directly, and it saved it to VRAM D, which can be accessed by the capture hardware because it’s mapped to the CPU.

Even frames:

VRAM C is mapped to the CPU.
VRAM D is mapped as sub engine sprites. It holds a 16 bit framebuffer.

The main engine is setup in direct VRAM display mode, so the output of the main screen is the contents of VRAM C.

The capture unit takes as input the 3D output directly, and it saved it to VRAM C, which can be accessed by the capture hardware because it’s mapped to the CPU.

Advantages:

If the framerate ever drops below 60 FPS, the output of both screens will be stable, no matter how long the wait is until the next frame is rendered.
No CPU or DMA processing is needed.
All 256x192 pixels of the screens are used.

Disadvantages:

The latency of the 3D rendered image is high. The capture unit saves the 3D output to the same bank that is being used as framebuffer, but it is saved at the same time the framebuffer is sent to the screen, which means the actual output is frame stored in the framebuffer from the last time it was drawn, 2 frames ago.
The screen effects based on changing the horizontal scroll every scanline don’t work.
The debug test console can’t be used. The main screen always uses the contents of VRAM directly, it isn’t possible to layer anything on top of it. The main and sub screens switch every frame, so it wouldn’t be possible to display a stable console on any screen.

Conclusion:

The high latency of this mode may make it unsuitable for fast-paced games. Also, due to the lack of a usable debug text console, it may not be useful for developers.

If latency isn’t an issue in your game, it is possible to use this mode for the release version of the game, after you don’t rely on the debug console for anything.

6. Dual screen 3D DMA mode

The source code for this mode is here and this is the code to initialize the debug console.

Thanks to Gericom for all the advice regarding this system!

This system is the most complex one, by far. It combines the ability of having stable output with low framerates, the ability of showing special effects, and the ability to have a debug console. However, this has a cost in CPU time.

It is always required to use 2 VRAM banks to hold the two framebuffers of the screens. This mode is similar to the previous one, but it takes the current VRAM bank used as destination of the video capture unit, and it copies it to a pseudo framebuffer in VRAM I with DMA. By copying every line right after it has been drawn it is possible to use VRAM I as a 16 bit bitmap.

The main problem is that VRAM I isn’t big enough to hold a full 256x192. The workaround is to either write out of bounds and rely on the mirroring of addresses of VRAM I, or to only copy to the first line of VRAM I, and to stretch it to fill the whole screen. Nitro Engine uses this last system so that the rest of VRAM I can be used for other things.

VRAM banks are used like this:

VRAM A, B: Textures.
VRAM C: Framebuffer of main screen and debug console of main screen.
VRAM D: Framebuffer.
VRAM E: Texture palettes.
VRAM I: Pseudo framebuffer and debug console of sub screen.

As you can see, there are two copies of the console. This is done to save VRAM. In short, there is a lot of unused memory in VRAM C, D and I with this setup. In odd frames the console is displayed on the sub screen from VRAM I; in even frames it is displayed in the main screen from VRAM C.

Odd frames:

VRAM C is mapped to the CPU.
VRAM D is mapped as main engine background. It holds a 16 bit framebuffer.
VRAM I is mapped as sub engine background. It holds one line of a 16 bit framebuffer, as well as the debug console.

The output of the main screen is the framebuffer stored in VRAM D.

The output of the sub screen is the pseudo framebuffer stored in VRAM I, with the debug console on top of it.

The capture unit takes as input the 3D output. This is stored in VRAM C. The important thing is that the image is written to VRAM C at the same rate it would be drawn on the screen. If the DMA is setup to copy from VRAM C to VRAM I right after each line is written to VRAM C, it is possible to display the captured image right away. The only problem with this is that there is a one scanline delay in the copy, so the first line of the screen won’t be able to show anything useful. In Nitro Engine, the vertical blank interrupt handler sets it to black so that it doesn’t show different values every frame.

Finally, that one line is stretched to fill the whole screen, and that’s how by simply copying the line every horizontal blanking period the screen can be filled with different lines.

This is different than in the dual 3D FB mode. In the FB mode it isn’t possible to have this delay, so the image displayed on the screen is the one rendered 2 frames ago. In DMA mode the image being displayed is the one rendered this frame.

Even frames:

VRAM C is mapped as main engine background. It holds a 16 bit framebuffer.
VRAM D is mapped to the CPU.
VRAM I is mapped as sub engine background. It holds one line of a 16 bit framebuffer, as well as the debug console (but the debug console isn’t used right now).

The output of the main screen is the framebuffer stored in VRAM C, with the debug console stored in VRAM C on top of it.

The output of the sub screen is the pseudo framebuffer stored in VRAM I.

The capture unit takes as input the 3D output. The same notes about the DMA apply as in odd frames.

Note that VRAM D doesn’t require a copy of the console, only VRAM C and I. Also, libnds only supports printing to one console at a time, so it is needed to load the font to both VRAM C and I, setup the map there, and then synchronize both maps manually. Which bank to use as main console bank? VRAM I, because it is always mapped as sub background RAM. Nitro Engine copies the map from VRAM I to VRAM C whenever VRAM C is mapped as main background RAM.

VRAM C (128 KB) is arranged like this:

Memory range	Size	Used as
0x06000000 - 0x06001000	4 KB	Tile base 0
		Free
0x06004000 - 0x06004800	2 KB	Map base 8
		Free
0x06008000 - 0x06020000	96 KB	BMP base 0 (256x192)

VRAM viewer: https://mtheall.com/vram.html#T1=3&NT1=128&MB1=8&TB1=0&T2=6&MB2=2&S2=1

The reason to shift the framebuffer is that map bases over index 31 can’t be accessed normally. It requires setting DISPCNT map base 64 KB step to a non-zero value, which would affect all backgrounds. By shifting the bitmap it is possible to use low indices and not have to worry about DISPCNT.

VRAM I (16 KB) is arranged like this:

Memory range	Size	Used as
0x06208000 - 0x06209000	4 KB	Tile base 2
		Free
0x0620B000 - 0x0620B200	512 B	Framebuffer (one line, 256 pixels)
		Free
0x0620B800 - 0x0620C000	2 KB	Map base 23

VRAM viewer: https://mtheall.com/vram.html#SUB=1&T1=3&NT1=128&MB1=23&TB1=2&T2=6&MB2=2&S2=0

Yes, there is an overlap between the framebuffer and the tileset. The size of each tileset slot is 16 KB, so there is only space for one tileset in VRAM I. Unfortunately, there is also only one slot for bitmaps in VRAM I, as they are organized in 16 KB slots. Both slots need to share the space.

Luckily, the tileset of the console doesn’t use the whole 16 KB. The current console of libnds uses up to 256 characters, which requires (for a 4 bpp tileset) 8 KB of VRAM. This means that anything in the second half of the bank (VRAM I is 16 KB in size) can be used for maps or to store the pseudo framebuffer line.

8 KB is the same size as 16 lines in a 16-bit background. We can setup our 16-bit bitmap as if it started at the same base as the tileset, and we can store our line bitmap at some point between 16 and 32 lines.

Now, remember that the map uses the last 2 KB of the VRAM bank, and that uses as much memory as 8 lines of a 16-bit bitmap. The free lines of the bitmap are actually 16 to 24.

Nitro Engine uses line 20, located at offset 0x3000 from the start of the bank.

Advantages:

If the framerate ever drops below 60 FPS, the output of both screens will be stable, no matter how long the wait is until the next frame is rendered.
The latency of the 3D rendered image is zero. It is directly displayed on the screen without any delay.
The screen effects based on changing the horizontal scroll every scanline work.
The debug console is supported.

Disadvantages:

Some CPU and DMA processing is needed.
Display lists can’t be sent to the GPU using the DMA in GFX FIFO mode because of the conflicts with the HBL DMA used to copy frames from VRAM C and D to VRAM I. This adds a bit of overhead to the process (but not that much)
The first row of the screens remains unused. Only 256x191 pixels are used.

Conclusion:

This is the mode I’d recommend everyone to use for your applications. The CPU overhead is well worth the reliability under low framerates, the availability of the debug console and the low latency of the 3D output.

7. Conclusion

Yes, this is complicated.

I’ve tried to give as much flexibility to the developers as possible, and this is the result. It is certainly overwhelming for someone who has never done anything similar. I’ve also tried to keep compatibility with the old unreliable dual 3D system, just in case the new ones break some game created with old versions of Nitro Engine.

My advice is to use the DMA method and forget about the others. The classic dual 3D system is too unreliable, you can’t expect to have a game that always draws exactly 60 FPS. The FB method has a pretty big latency when displaying the 3D output, so it is only useful for slow-paced games.

I hope that this post has helped you understand how tricky this is, and how flexible the NDS video hardware is!

Update (2026-01-14)

Updated links from GitHub to Codeberg.

BlocksDS SDK

Fri, 18 Aug 2023 17:44:00 +0000

A few months ago I created BlocksDS, a new SDK for Nintendo DS. It uses libnds, DS WiFI and Maxmod, so it is compatible with projects that use devkitARM. The toolchain it uses comes from Wonderful Toolchain by asie.

Its main objective is to remain as compatible as possible with old projects that use devkitARM, while adding new features that have been needed for a long time, but that would have never been added to the original repositories of devkitPro.

In order to achieve this, the libraries have been forked, and there are some visible improvements over devkitARM already:

Binaries are smaller and they use less RAM. The main reasons for that are:
- Instead of using newlib, BlocksDS uses picolibc (thanks to Wonderful Toolchain). The tinystdio of picolibc has smaller versions of stdio functions (like scanf(), printf() or fopen()) than newlib.
- There have been some changes that optimize memory usage in libnds: [1], [2] and [3].
- BlocksDS doesn’t have anything similar to devoptab, which is used in devkitARM. While this is very flexible, and very useful in platforms like the Wii or Switch, it’s too big for the GBA or NDS, where it doesn’t offer almost any benefit. There is more information about this change further down this article.
The licensing status of all libraries has been clarified and documented. This is important. Anything that doesn’t have a license defaults to “all rights reserved”, not “public domain”. Many things that devkitPro distributes don’t have a license. The examples don’t have a license, but that’s not the worst thing, as it can be argued that most of them are trivial and copyright doesn’t apply to them. However, it is a problem for non-trivial code, and it looks like the devkitPro maintainers seem to mistakenly believe that the lack of a license is fine, and that it leaves the code in the public domain.

They also may be in violation of the GPLv3 by distributing build scripts for GPLv3-licensed software under incompatible restrictive terms. Any build scripts for GPLv3 software must also be released under the GPLv3:

The “Corresponding Source” for a work in object code form means all the source code needed to generate, install, and (for an executable work) run the object code and to modify the work, including scripts to control those activities.

The biggest practical problem for BlocksDS is that a library crucial for NDS development doesn’t have any license: NitroFS. I tried to contact the original author in every way I could think of with no luck. This means that the library isn’t open source, and it can’t be used without permission from the author. The devkitPro maintainers aren’t interested in fixing this situation.

BlocksDS does thing in a different way. devkitARM uses libfat by Chishm to access FAT filesystems and interface with the DS hardware, and libfilesystem to use the filesystem embedded in the NDS ROM (and it uses the official filesystem format of the official SDK provided by Nintendo).

BlocksDS uses FatFs by Elm and a thin wrapper on top of libnds to access libnds functions. Instead of using the official format of Nintendo, BlocksDS uses what I’ve decided to call NitroFAT, which appends a FAT filesystem image to the NDS ROM, and it uses FatFs to access it. This allows BlocksDS to reuse code, as accessing the filesystem of the SD card and the filesystem of the ROM uses the same code. This is one of the reasons why NDS programs built with BlocksDS are smaller than with devkitARM.

This took a lot of effort to get working, and it is the best example I can think of about why it is important to license your code so that people can reuse it when you move on and stop caring about it.

So, in order to ensure that this project can survive over time, all files in all repositories of BlocksDS use SPDX identifiers, so that the licensing status of all individual files is always clear, which will allow other projects to reuse the code of BlocksDS easily if they want. It also allows other people to fork BlocksDS if something happens in the future.

I also talked to the author to change the license of GL2D to Zlib, like the rest of libnds.
There is now basic multithreading support. libnds wasn’t thread-safe, so it had to be modified so that multithreading works safely. Thread-local storage support has also been added. You can define variables that are unique per thread like this:
1 2

__thread int my_variable = 1000; __thread int other_variable;
DLDI can now be used from both the ARM9 and ARM7.

You can make the ARM9 ask the ARM7 to load files in one thread. While the ARM7 load files the ARM9 can be doing other things in other threads, so you aren’t blocked. This can also be done when loading files from the SD card of the DSi. This has always been one of the limitations that annoyed me about creating games with devkitARM, and now it’s fixed.

There is a big issue with DLDI drivers, and it’s that some of them have been compiled for the ARM9 and can’t run on the ARM7. This is why, by default, BlocksDS makes them run from the ARM9. The code must explicitly set ARM7 mode, or the user needs to use a DLDI driver built with a new configuration flag.
The DSi camera is supported (thanks, asie!). It’s still quite basic, but enough to be able to take photos from the front and back cameras.
libnds has been documented in many places, like the MPU setup, the FIFO system, and the code that allows a program to return to the loader if the loader supports it.
BlocksDS includes versions of memcpy(), memset() and memmove() optimmized for the CPUs of the NDS by using ndsabi, a fork of agbabi by felixjones.
ndstool now supports multiple languages in the banner, as well as icons in formats like PNG or GIF (even animated GIFs!).
libxm7 has been added as an alternative to Maxmod.
no$gba debug messages are now supported in the ARM7, not only ARM9.
A few people have started to contribute with bugfixes, like asie, lifehackerhansol and Pk11, which I’m very grateful about!

There is guide that helps new users port devkitARM projects to BlocksDS. Even though most code is compatible, there are a few things to consider:

BlocksDS is available on Windows and Linux. If you’re using Mac, you can use the Docker images distributed by BlocksDS. There is no native way to use BlocksDS on Mac, and currently there are no immediate plans to support it.
The Makefiles are completely different from the ones used in devkitARM. For most users this won’t be a problem, the migration is very easy (it only involves copying folder names from the old Makefiles to the new ones).
There is no devoptab support. Most likely you’ve never heard of it or used it directly, but devoptab is the way that devkitARM uses to make things like filesystem functions work (fopen(), etc), or things like getting the time and date from the OS (with time()).

BlocksDS supports the same features without any intermediate layers (like devoptab) between libc functions and the hardware functions. This is one of the reasons why binaries generated by BlocksDS are smaller and require less RAM to run.

However, in rare situations where user code uses devoptab, it won’t be possible to migrate to BlocksDS without big changes.

Here is a list of projects that now benefit from using BlocksDS:

Thanks to the work of the maintainers of the projects it was possible to exhaustively test BlocksDS, and it’s now stable enough to be used by real projects. A lot of work has been put into all of this by several people, so it’s great that some projects have started to use it for real!

Finally, I’d like to mention NFlib and Nitro Engine.

NFlib is a library that NightFox created many years ago. It helps developers create 2D games (and it has very basic 3D support). I’ve spent quite a bit of time cleaning it up and documenting the library and examples properly by adding Doxygen comments and translating everything from Spanish to English (sorry, but it’s too easy for the documentation to be outdated if it’s in multiple languages!).

I also talked to the author to change the license to MIT instead of Creative Commons. Note that Creative Commons is a license that shouldn’t be used for code.
Nitro Engine is a library that I created many years ago as well. It’s used to develop 3D games. I’ve spent some time over the last few years cleaning it up and improving it. In fact, I came up with the idea of BlocksDS when I was frustrated because I couldn’t implement a system to load assets from the filesystem asynchronously with devkitARM.

Both libraries are now fully supported in BlocksDS. The examples in both repositories will build with BlocksDS, and Nitro Engine comes with an example of how to use both libraries in the same project, which can be found here.

At the time of writing this post, the latest version of BlocksDS is 0.8.1. Give it a try! If you find any problems, or you have questions, feel free to open issues in the repository (or send a pull request with a fix!).

P.S.: I haven’t written anything in this blog for over 3 years… I still have a few more updates to post in the coming days!

Update (2023-09-06)

This post has been updated to reflect the fact that Windows is now supported by Wonderful Toolchain, which enables BlocksDS to work on Windows natively.

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Raspberry Pi LED ambient lamp

Sat, 27 Jun 2020 13:27:00 +0000

A few months ago (before the lockdown started) I was shopping at the Cambridge city center, I popped by the Raspberry Pi Store and I saw something called Mood Light - Pi Zero W Project Kit. This is basically a kit that contains:

Raspberry Pi Zero W: Pretty nice, as it has integrated WiFI.
Unicorn HAT: 32x4 RGB LED matrix with a pretty simple Python library to control it.
A plastic case to put everything in, for decoration.

I thought it looked pretty nice, and decided to buy it to play with it during when the lockdown started.

I wrote a Telegram bot a couple of years ago with Telepot, and I thought that it would be a good idea to repurpose it to control the lamp remotely. However, that was only supposed to be the first step. Nobody really wants to have to type a command to change the color of the lights, right? Also, it looks like that Telepot has been deprecated, so it’s likely going to break at some point in the future.

The actual objective was to create a web user interface with Flask, expose it to my home network, and to be able to control the lights pressing buttons in a website from my phone, PC, and even let any guest that come to my home control the lights by connecting to the WiFi network.

This is a video of the result (it’s missing one effect that simulates fire, though):

https://www.youtube.com/watch?v=xjQCvFdkGJw

How does it work?

There are 3 main parts:

LED server: Script that has to be run with root permissions. It listens to connections to a specific port and affects the LEDs. It can also reboot or shutdown your Raspberry Pi.
Telegram bot: Telegram bot that runs with regular user permissions. It can send commands to the LED server.
HTML server: HTML server that sets up a website with some buttons that can be used to control the LEDs. It sends commands to the LED server.

Note that you don’t need the Telegram bot and HTML server at the same time. Just one is enough. Also, any program that connects to the right port can send the same commands to the LED server. Both the Telegram bot and the web interface can control the lights at the same time.

All you have to do is turn the Raspberry Pi on anywhere in the flat and it will connect to the WiFi network, start the servers, and from that point you can talk to the Telegram bot or use the web interface to control it!

The only problem is that you have to turn it off manually from the web interface before switching the power off, that’s why both the web interface and the Telegram bot support that command.

For more information, check the code in my GitHub account:

https://codeberg.org/SkyLyrac/led-bot

Update (2026-01-14)

Updated links from GitHub to Codeberg.

RGBDS - Rednex Game Boy Development System

Mon, 05 Feb 2018 23:42:00 +0000

RGBDS is a toolchain to develop in assembly for the Game Boy. It is used by many projects nowadays, and I’m not talking about small ones:

Disassemblies of games released during the lifetime of the GB:
Completely new projects:
- https://github.com/ISSOtm/Aevilia-GB
Of course, it’s the toolchain I use for my own projects:

The only real alternative is WLA DX, as far as I know. I personally don’t like the syntax (because of small things like using parentheses instead of square brackets for indirection) but it is probably as powerful as RGBDS, and it’s worth taking a look at it if you want to do something serious for the GB.

History

It was released in 1997 as ASMotor by Carsten Sørensen as a general-purpose assembler for DOS/Win32. In 1999, it was modified by Justin Lloyd and released as RGBDS. In 2009, Vegard Nossum adapted the code for the toolchain to be more UNIX-like and released it as rgbds-linux. In 2010, Anthony J. Bentley forked the repository and improved on it, becoming the reference implementation of RGBDS. Then, in February 2017, he asked me if I wanted to be its new maintainer, I accepted, and he moved the repository to a neutral username. Basically, I was one of the few people still proposing new changes and fixes, so it was a safe choice.

Nowadays, this project is located here: https://github.com/gbdev/rgbds

It is important to know that during all this time (20 years!) many people have contributed to it, not only the main maintainers mentioned above. This had left the codebase in a really complicated licensing situation. The original code was released without a license, and pretty much every new contributor used a variation of the BSD or MIT license for new changes.

This is why I tried (and succeeded!) to get all the main authors to agree to change the license so that all the codebase would have the same one. In the end, all of the main contributors answered and gave permission to relicense their code, and the MIT license was chosen: https://github.com/rednex/rgbds/pull/225

In any case, because of its story, I don’t think it makes sense to consider this the project of a specific person in particular. At some point it just becomes a project of the community.

How it works

RGBDS is divided into rgbasm, rgblink, rgbfix and rgbgfx. In the past, there was another tool called rgblib, but it was quite pointless as nobody really used it, and the object format breaks quite often when adding new features to the toolchain.

rgbasm: Assembler.

It takes a file with source code as input and generates an object file as output. It uses yacc/bison to parse files, which is a bit problematic because of the source code syntax and how hard it is to resolve conflicts.

It is really flexible. It has support for macros, unions, even for referencing local labels through the parent label. Of course, the address of labels is not always known at compile time, it is only known if the value is directly assigned, or if the base address of the section is directly assigned. In order to be able to resolve their address at linking time, or even be able to calculate simple expressions with them (addition, bit masks…) there is a RPN language that is used in object files to tell the linker how to operate with them. Each value that has to be modified by the linker generates a patch of RPN instructions.
rgblink: Linker.

It reads all object files generated by rgbasm (and potentially a linkerscript with information about where to place sections) and generates a raw GB ROM, that is not generally ready to directly use in a GB.

In short, it places all sections in their final locations and calculates the final value of all RPN patches. It can also generate files with a list of labels and addresses to help debugging.
rgbfix: ROM fixer.

Used to fix a finished GB ROM. There are some fields in the header that must have the correct value for the game to boot in a real GB. Some of this fields are difficult to fill at linking time, so it’s easier to have an external tool for it, that’s where rgbfix comes in handy. It also pads a ROM if the size isn’t a power of two.
rgbgfx: Graphics converter.

This tool converts png files into the format that the GB uses. I must admit that I’ve never used this tool, but it is used in disassemblies extensively.

Conclusion

I find it really interesting that this toolchain has managed to survive for such a long time, and that it is still used so much. It’s mostly used by disassemblers, I must admit, but hey!

As I’ve said before, this project wouldn’t be nearly as useful if it wasn’t thanks to all of its contributors. Because of it, it is always open to contributions. They don’t have to be big or fancy, even small bug reports (or bug fixes!) are welcome. So yeah, let’s keep this project alive!

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Port of Trusted Firmware-A to the Raspberry Pi 3

Thu, 01 Feb 2018 23:54:00 +0000

This is a small project I worked on before Christmas. The Trusted Firmware-A is a reference implementation of a secure firmware for ARMv8-A CPUs. It has ports to both AArch64 (64-bit Arm Instruction Set Architecture) and AArch32 (32-bit Arm ISA). AArch32 is almost the same as ARMv7-A, for backwards compatibility.

The SoC of the Raspberry Pi 3 is the Broadcom BCM2937, which has 4 Cortex-A53 cores. The Cortex-A53 is a microarchitecture that implements the ARMv8-A ISA with both 64 and 32-bit modes, so it is possible to port the Trusted Firmware-A. At work I’m one of the engineers working on the Trusted Firmware-A, and I really like the Raspberry Pi, so I simply couldn’t resist, I needed to have the Trusted Firmware running on it.

Even though the Trusted Firmware has ports to both AArch64 and AArch32, the one that interests me is AArch64. There is no real advantage for making the port for Raspberry Pi run in AArch32 mode. The firmware runs in EL3, the highest privilege execution level. The architecture allows to downgrade from 64 to 32-bit when reducing the privilege level, but not to increase it. That means that, for example, if the firmware is running in 64-bit mode, it is possible to have a 64 or a 32-bit hypervisor in EL2. Similarly, an operating system in 64-bit mode in EL1 can execute both 64 and 32-bit user applications in EL0. In short, a 64-bit firmware allows any other privilege level to use 64 or 32-bit mode, but a 32-bit firmware would restrict them to execute in 32-bit mode.

Also, it is important that this port works with Raspbian. It is the Linux distribution for the Raspberry Pi with the best support, as it has the support of the Raspberry Pi Foundation itself. If a port of the Trusted Firmware is to be done, it’s a good idea to make it work with Raspbian.

This port is based on the work of Ard Biesheuvel @ardbiesheuvel, explained in this article. The port is in this repository. The port has been heavily modified. For starters, that port didn’t manage to boot Linux or to release the secondary CPUs from their wait loop (the RAM used as a mailbox wasn’t initialized to 0 before entering the wait loop).

Important note: Even though the Trusted Firmware-A is a reference of a secure boot flow, the Raspberry Pi 3 doesn’t isn’t a secure platform. The memory available to the CPUs is the DRAM, which can be accessed when the CPU is in Non-secure and Secure modes. However, in order to emulate the normal bootflow, the memory map is divided in a few regions.

In short, this is a port that can be used to play around with, implement standard services that the OS can use, etc. This is not meant to be used to implement secure services in any way.

It could be possible to emulate secure RAM by using the hypervisor translation tables to hide some memory from the OS, which would act as SRAM. This is non-trivial, and it is outside of the scope of this project.

Getting the Trusted Firmware-A to boot

First of all, I connected a UART to USB cable to the Mini UART located in the pin header. I verified that the connection was working by using screen to connect to Linux through it. To enable this connection, the file config.txt on the root of the SD card must contain a line that says enable_uart=1. Also, I added console=serial0,115200 console=tty1 to the file cmdline.txt. Once I verified that it was working, I started to take a look at the code of the port.

The port was quite old by the time I started to work on this project, so the first thing that I did was to rebase the branch, replace some old APIs and libraries by the new ones, and made sure that it compiled. I also enabled some CPU errata workarounds that can affect the Cortex-A53. Then, I had to figure out how to make it run. I needed to get all CPU cores running the same binary at EL3 in AArch64 mode.

The booting process of the Raspberry Pi is quite unusual. The SoC has a VideoCore IV located between all the Arm cores and the DRAM. It has its own MMU and tricks the Arm cores into thinking that the physical memory map is different than it actually is! This VideCore is also the one that has a ROM bootloader that loads the rest of the files from the SD card. The file config.txt tells it how to load them, but most of the options of interest to this project are undocumented. After some googling I managed to find the ones I needed and got all 4 cores booting in AArch64 mode in EL3. For more details about it, check the documentation of the port in the official repository of the Trusted Firmware:

https://github.com/ARM-software/arm-trusted-firmware/blob/master/docs/plat/rpi3.rst

In short, the kernel has to be renamed to kernel8.img and the firmware has to be packaged as one single binary and named armstub8.bin. Then, in the config.txt file I added the following lines to tell the loader where to load the files in DRAM.

enable_uart=1
kernel_address=0x01000000
device_tree_address=0x02000000

One good thing about this unusual bootflow is that it is literally impossible to brick the Raspberry Pi, you just need to write the correct files to your SD card and it will boot again. Also, it gives the user a lot of flexibility on how to boot the Arm cores. Normally it’s not that simple to select AArch64 or AArch32 at the highest Execution Level, that’s fixed by the platform. In the Raspberry Pi, that can be changed by changing a value in the configuration file.

This demo by Stephen Warren was useful to test that my code was running in the conditions I needed. That demo shows the same message per each CPU with the values of some registers, like CurrentEL, that shows the EL in which the code is running.

Once this was ready, I just needed to replace that demo by my binary of the firmware and check if the port was working. I decided to use the binary of the demo BL33 image, the final payload to be loaded by the firmware, where it jumps after initializing everything. I got the following output:

VERBOSE: Reserved 0x12000 bytes (discarded 0x7000 bytes above)
VERBOSE: Trusted SRAM seen by this BL image: 181000 - 0x200000
VERBOSE: Code region: 0 - 0x5f90
ERROR:   mmap_add_region_check() failed. error -22
ASSERT:  lib/xlat_tables_v2/xlat_tables_internal.c:753:0

Success! Sort of, anyway. That error is EINVAL. It means that there is some sort of overlap of memory regions, or that the platform is trying to map regions with invalid values for some reason. I initially thought that it was just that there wasn’t enough memory reserved to setup the translation tables. Anyway, easy enough to fix! I eventually got this output:

NOTICE:  Booting Trusted Firmware
NOTICE:  BL1: v1.4(debug):v1.4-308-g2082b0ad
NOTICE:  BL1: Built : 02:47:22, Nov  4 2017
INFO:    BL1: RAM 0x3ee000 - 0x3f7000
INFO:    BL1: cortex_a53: errata workaround for 835769 was applied
INFO:    BL1: cortex_a53: errata workaround for 843419 was applied
INFO:    BL1: cortex_a53: errata workaround for 855873 was applied
INFO:    BL1: Loading BL2
INFO:    Loading image id=1 at address 0x3b4000
INFO:    Image id=1 loaded: 0x3b4000 - 0x3ba1f0
NOTICE:  BL1: Booting BL2
INFO:    Entry point address = 0x3b4000
INFO:    SPSR = 0x3c5
NOTICE:  BL2: v1.4(debug):v1.4-308-g2082b0ad
NOTICE:  BL2: Built : 02:47:22, Nov  4 2017
INFO:    BL2: Doing platform setup
INFO:    BL2: Loading image id 3
INFO:    Loading image id=3 at address 0x3e0000
INFO:    Image id=3 loaded: 0x3e0000 - 0x3e8080
INFO:    BL2: Loading image id 5
INFO:    Loading image id=5 at address 0x600000
INFO:    Image id=5 loaded: 0x600000 - 0x6003f4
NOTICE:  BL1: Booting BL31
INFO:    Entry point address = 0x3e0000
INFO:    SPSR = 0x3cd
NOTICE:  BL31: v1.4(debug):v1.4-308-g2082b0ad
NOTICE:  BL31: Built : 02:47:22, Nov  4 2017
INFO:    BL31: Initializing runtime services
INFO:    BL31: cortex_a53: errata workaround for 835769 was applied
INFO:    BL31: cortex_a53: errata workaround for 843419 was applied
INFO:    BL31: cortex_a53: errata workaround for 855873 was applied
INFO:    BL31: Preparing for EL3 exit to normal world
INFO:    Entry point address = 0x600000
INFO:    SPSR = 0x3c9

Hello, world!
this_cpuid:0
MPIDR:0000000080000000
r0:0000000000000000
r1:0000000000000000
r2:0000000000000000
r3:0000000000000000
CurrentEL:8
SPSel:1

The exception level is encoded in bits 3 and 2 of register CurrentEL, which means that this code is running at EL2, as we want! As you can see, the demo only prints the registers of one CPU. This is normal, as all secondary cores are supposed to wait for the OS to power them ON (or, in this case, release them from a wait loop).

Getting Linux to boot

The next step was to actually get the Linux kernel booting. The Linux kernel image simply replaces the demo I was using as BL33 image.

I didn’t have a 64-bit kernel to test with, though, just a 32-bit one (the one that comes with Raspbian). According to the Linux boot documentation for the Arm 32-bit kernel (located in Documentation/arm/Booting in the Linux kernel tree), it likes to start in Hypervisor mode. I just needed to tweak the final step of the firmware (the jump to the BL33 entrypoint) so that it jumped to this mode instead of EL2 in AArch64 mode.

This is easy, it is only needed to modify the value of SPSR at the time it jumps to BL33. With the correct value, it jumps to the entrypoint in AArch32 in hypervisor mode. I didn’t want to close the door to a 64-bit kernel, so I just created a build option, RPI3_BL33_IN_AARCH32, that would let the developer choose EL2 in AArch64 or Hypervisor in AArch32.

NOTICE:  Booting Trusted Firmware
NOTICE:  BL1: v1.4(debug):v1.4-310-gf49906c8-dirty
NOTICE:  BL1: Built : 23:55:50, Nov  4 2017
NOTICE:  BL1: Booting BL2
NOTICE:  BL2: v1.4(debug):v1.4-310-gf49906c8-dirty
NOTICE:  BL2: Built : 23:55:50, Nov  4 2017
NOTICE:  BL1: Booting BL31
NOTICE:  BL31: v1.4(debug):v1.4-310-gf49906c8-dirty
NOTICE:  BL31: Built : 23:55:50, Nov  4 2017
[    1.060413] CPU1: failed to come online
[    2.101140] CPU2: failed to come online
[    3.141884] CPU3: failed to come online
[    3.327640] bcm2835-aux-uart 3f215040.serial: could not get clk: -517

Raspbian GNU/Linux 9 raspberrypi ttyS0
raspberrypi login:

The secondary cores couldn’t come online because this kernel doesn’t know about PSCI, which is the standard way of powering on Arm cores. But that’s not a problem, there is a workaround, the kernel also has support for booting secondary cores by making them wait in a wait loop.

Getting the secondary cores to work

The port I used as a base already had an implementation of the SMC (System Monitor Call) PSCI_CPU_ON that made the secondary cores wait in a loop until it was called, at which point it released them and jumped to the given address.

Unfortunately, this can’t work with the kernel if it doesn’t know about PSCI, and that was trickier that I expected. In the end, I decided to simply add some glue code by creating a small bootstrap that would be used as BL33 image and run in EL2. It would act like a really simple UEFI or U-Boot. The idea is to use this bootstrap to release the locks from the firmware by calling PSCI_CPU_ON and make them wait in a wait loop that uses the mailbox that Raspbian knows how to use to boot the secondary cores. I didn’t really know how to do this, so I just checked how it is done in the official distribution of Raspbian. The following 2 links contain the bootstraps for a 32-bit kernel and a 64-bit kernel respectively:

https://github.com/raspberrypi/tools/blob/master/armstubs/armstub7.S

https://github.com/raspberrypi/tools/blob/master/armstubs/armstub8.S

armstub7.S is used by the Raspberry Pi 2, which has 4 Cortex-A7, but also by the Raspberry Pi 3 when booting a 32-bit kernel, and it has 4 Cortex-A53. armstub8.S is used by the Raspberry Pi 3 when booting a 64-bit kernel. The compiled bootstraps are embedded on one of the elf files that are loaded by the VideoCore at boot.

After some reverse engineering I created my own versions of the bootstraps:

https://codeberg.org/SkyLyrac/rpi3-arm-tf-bootstrap

As a side effect of my reverse engineering efforts, I checked the Technical Reference Manuals of the Cortex-A53 and Cortex-A7 and found some really small bugs in the official bootstrap for the 32-bit kernel. I created a pull request to fix them:

https://github.com/raspberrypi/tools/pull/85

However… After all that effort, the secondary cores still refused to work. I decided to resort to printf-powered debugging and found out that the cores were actually crashing before the kernel had had the chance to claim them. It took me some time to understand the reason. Again, Documentation/arm/Booting had the answer: The kernel copies itself to a different memory region at boot:

The zImage may also be placed in system RAM and called there. The kernel should be placed in the first 128MiB of RAM. It is recommended that it is loaded above 32MiB in order to avoid the need to relocate prior to decompression, which will make the boot process slightly faster.

During this copy, the code of my waitloop was being overwritten. I checked that moving the firmware to a location far away fixed the problem, but now I really needed to find a way to protect he memory region used by the firmware. The whole point of BL31 is to have some services that can be used by the operating system. If Linux is free to use the memory used by the firmware, this can’t work.

I eventually found out the solution: To add memmap=256M$16M to the file cmdline.txt. This option tells the kernel that at the address 256 MiB there are 16 MiB that it shouldn’t use, even if that range of memory contains valid ram specified in the device tree that tells it about all the hardware in the system.

NOTICE:  Booting Trusted Firmware
NOTICE:  BL1: v1.4(debug):v1.4-308-g65c55091-dirty
NOTICE:  BL1: Built : 20:33:44, Nov  5 2017
NOTICE:  BL1: Booting BL2
NOTICE:  BL2: v1.4(debug):v1.4-308-g65c55091-dirty
NOTICE:  BL2: Built : 20:33:44, Nov  5 2017
NOTICE:  BL1: Booting BL31
NOTICE:  BL31: v1.4(debug):v1.4-308-g65c55091-dirty
NOTICE:  BL31: Built : 20:33:44, Nov  5 2017
[    0.266483] bcm2835-aux-uart 3f215040.serial: could not get clk: -517

Raspbian GNU/Linux 9 raspberrypi ttyS0
raspberrypi login: pi
Password:
Last login: Sun Nov  5 20:41:18 GMT 2017 on tty1
Linux raspberrypi 4.9.41-v7+ #1023 SMP Tue Aug 8 16:00:15 BST 2017 armv7l

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
pi@raspberrypi:~$ cat /proc/cpuinfo
processor       : 0
model name      : ARMv7 Processor rev 4 (v7l)
BogoMIPS        : 38.40
Features        : half thumb fastmult vfp edsp neon vfpv3 tls vfpv4 idiva
idivt vfpd32 lpae evtstrm crc32
CPU implementer : 0x41
CPU architecture: 7
CPU variant     : 0x0
CPU part        : 0xd03
CPU revision    : 4

processor       : 1
model name      : ARMv7 Processor rev 4 (v7l)
BogoMIPS        : 38.40
Features        : half thumb fastmult vfp edsp neon vfpv3 tls vfpv4 idiva
idivt vfpd32 lpae evtstrm crc32
CPU implementer : 0x41
CPU architecture: 7
CPU variant     : 0x0
CPU part        : 0xd03
CPU revision    : 4

processor       : 2
model name      : ARMv7 Processor rev 4 (v7l)
BogoMIPS        : 38.40
Features        : half thumb fastmult vfp edsp neon vfpv3 tls vfpv4 idiva
idivt vfpd32 lpae evtstrm crc32
CPU implementer : 0x41
CPU architecture: 7
CPU variant     : 0x0
CPU part        : 0xd03
CPU revision    : 4

processor       : 3
model name      : ARMv7 Processor rev 4 (v7l)
BogoMIPS        : 38.40
Features        : half thumb fastmult vfp edsp neon vfpv3 tls vfpv4 idiva
idivt vfpd32 lpae evtstrm crc32
CPU implementer : 0x41
CPU architecture: 7
CPU variant     : 0x0
CPU part        : 0xd03
CPU revision    : 4

Hardware        : BCM2835
Revision        : a02082
Serial          : 000000001528876b
pi@raspberrypi:~$ sudo shutdown now
[   64.551587] reboot: Power down

And a photo I took to commemorate the moment. :)

At last, everything was working! Linux could detect all 4 cores! All I needed to do now is to make sure that my port would also work with a 64-bit kernel, but… well, I didn’t have any 64-bit kernel and I didn’t know where to get one from. I ended up compiling my own.

Getting a 64-bit kernel to work

It is really simple, actually, you just have to clone the Linux tree fork maintained by the Raspberry Pi Foundation and compile it for 64-bit:

git clone --depth=1 -b rpi-4.14.y https://github.com/raspberrypi/linux
cd linux
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- bcmrpi3_defconfig
make -j 6 ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

Then, copy the kernel image and the device tree to the SD card.

``sh cp arch/arm64/boot/Image /path/to/boot/kernel8.img cp arch/arm64/boot/dts/broadcom/bcm2710-rpi-3-b.dtb /path/to/boot/


Finally, install the kernel modules.

```sh
make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu- \
    INSTALL_MOD_PATH=/path/to/filesystem modules_install

I also had to create a bootstrap in a similar way as I did for the 32-bit kernel. It was easier now, though. All the booting information is in the file Documentation/arm64/booting.txt, like with the 32-bit kernel.

After a bit of work, I finally got the kernel booting and releasing all secondary cores from their loops! The console output for this kernel, however, is really verbose, so I’ve cut significant parts of it:

NOTICE:  Booting Trusted Firmware
NOTICE:  BL1: v1.4(debug):v1.4-331-gac96a37f
NOTICE:  BL1: Built : 22:59:37, Nov 13 2017
NOTICE:  BL1: Booting BL2
NOTICE:  BL2: v1.4(debug):v1.4-331-gac96a37f
NOTICE:  BL2: Built : 22:59:37, Nov 13 2017
NOTICE:  BL1: Booting BL31
NOTICE:  BL31: v1.4(debug):v1.4-331-gac96a37f
NOTICE:  BL31: Built : 22:59:37, Nov 13 2017
[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Linux version 4.14.0-rc8-v8+ (antonio@antonio-debian-laptop)
(gcc version 7.1.1 20170707 (Linaro GCC 7.1-2017.08)) #1 SMP PREEMPT Sun Nov
12 19:55:59 GMT 2017
[    0.000000] Boot CPU: AArch64 Processor [410fd034]
[    0.000000] Machine model: Raspberry Pi 3 Model B Rev 1.2
[    0.000000] efi: Getting EFI parameters from FDT:
[    0.000000] efi: UEFI not found.
[    0.000000] cma: Reserved 8 MiB at 0x000000003ac00000
[    0.000000] random: fast init done
[    0.000000] percpu: Embedded 22 pages/cpu @ffffffe77ab7e000 s50456 r8192
d31464 u90112
[    0.000000] Detected VIPT I-cache on CPU0
[    0.000000] CPU features: enabling workaround for ARM erratum 845719
[    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 238896
[    0.000000] Kernel command line: 8250.nr_uarts=1 bcm2708_fb.fbwidth=656
bcm2708_fb.fbheight=416 bcm2708_fb.fbswap=1 vc_mem.mem_base=0x3ec00000
vc_mem.mem_size=0x40000000  dwc_otg.lpm_enable=0 console=ttyS0,115200
console=tty1 root=PARTUUID=5cd2ad4c-02 rootfstype=ext4 elevator=deadline
fsck.repair=yes rootwait memmap=256M$16M
[    0.000000] PID hash table entries: 4096 (order: 3, 32768 bytes)
[    0.000000] Dentry cache hash table entries: 131072 (order: 8, 1048576
bytes)
[    0.000000] Inode-cache hash table entries: 65536 (order: 7, 524288
bytes)
[    0.000000] Memory: 930484K/970752K available (6972K kernel code, 884K
rwdata, 2304K rodata, 2624K init, 697K bss, 32076K reserved, 8192K
cma-reserved)

... several lines of output ...

[    0.012143] smp: Bringing up secondary CPUs ...
[    0.019337] Detected VIPT I-cache on CPU1
[    0.019402] CPU1: Booted secondary processor [410fd034]
[    0.026438] Detected VIPT I-cache on CPU2
[    0.026480] CPU2: Booted secondary processor [410fd034]
[    0.033553] Detected VIPT I-cache on CPU3
[    0.033594] CPU3: Booted secondary processor [410fd034]
[    0.033729] smp: Brought up 1 node, 4 CPUs
[    0.033857] SMP: Total of 4 processors activated.
[    0.033885] CPU features: detected feature: 32-bit EL0 Support
[    0.034111] CPU: All CPU(s) started at EL2
[    0.034160] alternatives: patching kernel code

... several lines of output ...

Raspbian GNU/Linux 9 raspberrypi ttyS0
raspberrypi login: pi

Password:
Last login: Thu Sep  7 16:23:37 UTC 2017 on ttyS0
Linux raspberrypi 4.14.0-rc8-v8+ #1 SMP PREEMPT Sun Nov 12 19:55:59 GMT 2017
aarch64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
pi@raspberrypi:~$ uname -a
Linux raspberrypi 4.14.0-rc8-v8+ #1 SMP PREEMPT Sun Nov 12 19:55:59 GMT 2017
aarch64 GNU/Linux
pi@raspberrypi:~$ cat /proc/cpuinfo
processor       : 0
BogoMIPS        : 38.40
Features        : fp asimd evtstrm crc32 cpuid
CPU implementer : 0x41
CPU architecture: 8
CPU variant     : 0x0
CPU part        : 0xd03
CPU revision    : 4

processor       : 1
BogoMIPS        : 38.40
Features        : fp asimd evtstrm crc32 cpuid
CPU implementer : 0x41
CPU architecture: 8
CPU variant     : 0x0
CPU part        : 0xd03
CPU revision    : 4

processor       : 2
BogoMIPS        : 38.40
Features        : fp asimd evtstrm crc32 cpuid
CPU implementer : 0x41
CPU architecture: 8
CPU variant     : 0x0
CPU part        : 0xd03
CPU revision    : 4

processor       : 3
BogoMIPS        : 38.40
Features        : fp asimd evtstrm crc32 cpuid
CPU implementer : 0x41
CPU architecture: 8
CPU variant     : 0x0
CPU part        : 0xd03
CPU revision    : 4

pi@raspberrypi:~$ sudo shutdown now

... several lines of output ...

[   78.768742] reboot: Power down

The final thing to do was to write the documentation of this port and to create a pull request:

https://github.com/ARM-software/arm-trusted-firmware/pull/1157

It was reviewed and merged, and now the Trusted Firmware-A has an upstream port for the Raspberry Pi 3! It was a pretty interesting project, I learned a lot about the Linux kernel boot process and about the kind of problems that people that do the bringup of a platform have to face.

I hope you found this article interesting!

Update (2018-03-23):

The name of the project is Trusted Firmware-A. All references to Arm Trusted Firmware have been replaced by the new name.

Update (2026-01-14)

Updated links from GitHub to Codeberg.

µCity v1.2

Wed, 31 Jan 2018 02:10:00 +0000

Hello again!

It’s a bit late to publish this, but hey, it only comes 7 months late! I had no website to upload this to, anyway…

In any case, here it is, µCity, the open-source city-building game for Game Boy Color! It can also be spelled ‘uCity’, but it’s pronounced ‘micro-city’.

This game is completely free, licensed under the GPLv3+. Just download the ROM, install a Game Boy Color emulator, and play! The last release of the game should be here:

https://codeberg.org/SkyLyrac/ucity/releases

You can also play on real hardware. Even though the game has been developed using mainly emulators, it has been verified to work on hardware. The game detects how much available space there is and adjust the maximum number of saved cities accordingly.

Here’s a video, in case you are too lazy to test the ROM. If needed, there is a short manual with instructions for the player in the file manual.rst.

I’ve been asked quite a few times about this, so I might as well clarify it. A direct port of this game to the monochrome Game Boy isn’t possible. This game uses most of the extra RAM that was added to the Game Boy Color, which isn’t available in a regular Game Boy. While the Game Boy Color has 32 KiB of WRAM, the Game Boy only has 8 KB, and this game currently uses 30 KB more or less. Only a really limited version of this game with a much smaller map and much fewer features would fit in a Game Boy.

Oh, and this game has its own article in Hackaday!

https://hackaday.com/2017/06/20/writing-a-new-game-for-the-game-boy-color/

If you want to actually take a look at it, the source code is available here. An open-source project is a lot worse without documentation, though! That’s why the code has a lot of comments and why there is a highly detailed documentation in the docs folder. And also because assembly code without comments can’t be understood even by the developer who wrote it originally. :) To compile it, you’ll just need RGBDS. It should be possible to compile the game on Linux, MinGW, Cygwin, etc.

Other tools used to create the game are:

Open ModPlug Tracker: This is just a program to edit tracker style music. It has been used to compose the music used by GBT Player, my music player library. It can be found here.
GBTD (Game Boy Tile Designer) and GBMB (Game Boy Map Builder): Graphics edition tools (for Windows, but they run on Wine).

Thanks to:

beware: For the emulator BGB, extremely useful tool used to develop this game.
Pan of Anthrox, Marat Fayzullin, Pascal Felber, Paul Robson, Martin Korth (nocash) and kOOPa for the pandocs.
Otaku No Zoku (Justin Lloyd) for the Gameboy Crib Sheet.
Everyone that has contributed to develop RGBDS over the years, specially Carsten Sorensen, Justin Lloyd, Vegard Nossum and Anthony J. Bentley.

PS: If the name of the game breaks your website, fix your website. :P

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Welcome to my new blog!

Mon, 29 Jan 2018 01:54:00 +0000

Hello!

After almost a year of having my website down, I decided it was time to do something about it! This is my attempt at creating a new website.

I’m using Pelican. Let’s see how code looks like, for example…

#include <stdio.h>

int main(int argc, char *argv[])
{
    /* Print string */
    printf("Hello, world!\n");
    return 0;
}

It will take some time to create articles about my latest projects, and I’ve reuploaded all the entries of my old blog and website!

Old website

Unfortunately, this change means that any comment left on my old blog will be lost, but well, there weren’t that many…

Antonio

Geometrix [GBC Game][GBDev 2015]

Fri, 04 Dec 2015 16:32:00 +0000

Hello!

This is my entry for the GBdev Game Boy Coding Compo 2015! Sadly, only one more game entered the compo. But anyway, here it is!

Video: https://www.youtube.com/watch?v=qAvW2n8Qbeg

Source, binary and more information:

https://codeberg.org/SkyLyrac/geometrix

Screenshots:

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Tetris made with a PIC18F2550

Sun, 20 Sep 2015 23:06:00 +0000

Hello again!

This time I’m writing to show you my newest electronic creation: a “videogame console” made with a PIC18F2550 as its brain. It has a 8x16 LED matrix as main display and 4 seven segment displays to show the player score, for example. It has 8 buttons (4 in a pad, the rest like a Game Boy or similar). The PIC doesn’t have enough pins to control everything easily, so I’ve used a few 74HC595 to control the LED matrix and the seven segment displays, and a 74HC166 to read the state of all buttons.

The game I’ve decided to code for the demonstration is a simple Tetris, written in 100% assembly. YouTube video here:

https://www.youtube.com/watch?v=5fmSbreJsDI

Buttons:

Move left/right.
Rotate clockwise/counterclockwise.
Go down quickly, go down instantly.
Pause, reset.

At the moment I haven’t decided if I should post the schematics and the source code for various reasons:

I used different systems to power the LED matrix and the seven segment displays. A decent design should use the same system.
Some resistors are too high and the LEDs, when lit, are too dim. I didn’t consider the scanline refresh when calculating the resistors, so the actual intensity is a lot lower than I thought.
The source code of the game is a bit messy (the “drivers” code is good, though).

Well, I hope you like it!

EDIT: Well, whatever, I’ll just put the schematics and the code… :P

Schematics

Code

Don’t expect it to be clean and/or human readable. The file ‘main.asm’ contains the ‘drivers’, and ’tetris.asm’ contains the game. It’s fairly easy to modify it to change some of the pin assignments.

Download (gEDA schematics + assembly code + assembled .hex file)

New version (2015/10/06), with a small modification to prevent “ghosting” between displays when performing the scanline change. Also fixed a bug that didn’t remove completed lines before checking if game over.

Download

Possible improvements

Change pull-down resistors for the buttons (R29-R36) by 10K resistors.
Change LED resistors (330 Ohm) by 300 or maybe 220 resistors (R1-R16 and R37-R44).
Make the LED matrix and the seven segment displays work the same way (changing the displays by common-anode equivalents and the transistors used to drive them).

Electronic dice

Sun, 12 Jul 2015 20:15:00 +0000

Well, after a few weeks not doing almost anything I’ve decided to post the last useless device I’ve made. It’s a simple electronic dice using a decade counter and some inverters (used for logic and as oscillator). I decided not to use a microcontroller because it felt like it was cheating for a circuit this simple… There’s not much to say: pressing the button will enable the counter and releasing the button will stop it and show a “random” number. The counter is very fast so it’s impossible to guess what number is going to show when the button is released. Here are a few pictures:

I used foam to hold the board and the battery in place so that it could be put into a handmade box.

And, at last, a video of the circuit working:

https://www.youtube.com/watch?v=t7blrTmsfKg

While it’s a really simple circuit to design and make, I’ve decided to create schematics in case someone wants to make this:

Almost all components are specified in the schematic. The ones that aren’t completely specified are the voltage regulator (78L05), the inverter IC (74LS04) and the decade counter (HFC4017).

There are two interesting things about this circuit, and the reason of both of them is that I didn’t want to buy many components, so I decided to use whatever I had at home:

The first one is that the oscillator is made of two inverters (and a capacitor and resistor). The values I’ve used for R and C make it oscillate at 390Hz approximately.
The second one is that I don’t use an IC with OR gates. I’ve decided to use some diodes and resistors to create them (https://en.wikipedia.org/wiki/Diode_logic).

The circuit uses a 9 V battery. The logic of the circuit needs about 11 mA, and the LEDs need around 9 mA each. That means it uses from 20 mA (when only 1 LED is on) to 65 mA (when 6 LEDs are on). The 7 LEDs can’t be turned on at the same time, obviously.

GBT Player usage

Wed, 08 Apr 2015 01:36:00 +0000

Over the last months I’ve seen a few tutorials about GB programming that use my GBT Player for music. I have to say a few things about that.

First: Thanks a lot for using my library! The fact that you like it enough to use it in your projects is what keeps it alive. Version 2 only happened because I was asked to add a few things to previous versions.

Second: You are using it wrong!

Ok, it’s partly my fault, but it’s your fault too, obviously: You are using GBDK… I mean, you just don’t understand the implications of the ROM banking system the GB uses. I know I don’t really have to explain this kind of things, but I feel a bit responsible for my library, so I’m going to explain why you are using it wrong and how to fix it. Let’s see…

My (now old) example does something like this:

#include <gb/gb.h> // Include GBDK lib
#include "gbt_player.h" // Include player

// Reference to song data
extern const unsigned char * song_Data[];

void main()
{
    // Disable interrupts while they are being configured
    disable_interrupts();

    gbt_play(song_Data, 2, 7); // Setup song
    gbt_loop(0); // The default is 0, this could be removed

    add_VBL(gbt_update); // Add callback for VBL interrupt (*)

    set_interrupts(VBL_IFLAG); // Enable VBL interrupt
    enable_interrupts();

    while (1)
    {
        wait_vbl_done(); // Wait loop with reduced CPU usage
    }
}

While the new one does this:

#include <gb/gb.h> // Include GBDK lib
#include "gbt_player.h" // Include player

// Reference to song data
extern const unsigned char * song_Data[];

void main()
{
    // Disable interrupts while they are being configured
    disable_interrupts();

    gbt_play(song_Data, 2, 7); // Setup song
    gbt_loop(0); // The default is 0, this could be removed

    set_interrupts(VBL_IFLAG); // Enable VBL interrupt
    enable_interrupts();

    while (1)
    {
        wait_vbl_done(); // Wait loop with reduced CPU usage

        gbt_update(); // Update player (*)
    }
}

So what’s the big deal?

Well, let’s explain how the GB banking system works. You should know that. If you don’t know that, you shouldn’t be coding for GB, but whatever… The first 16 KB of the ROM are always mapped to addresses 0000h-3FFFh. This means that this code and data is always available to read! That’s the place where you want your game engine to be. But GBT code doesn’t go there by default. It goes to bank 1. Why? Because 16 KB is not much space. GBT player needs quite a bit of space and it’s stupid to put it in bank 0 when GBDK is already using a lot of that space. It would leave you even less space for your code!

Banks 1 and beyond are mapped to addresses 4000h-7FFFh. Only one of them can be mapped at once there, so they must be switched when the program needs to access to data in other bank. This means that you can have as much 16 KB banks as you need (so you could have ROMs with infinite banks), but you have to take care to switch to the correct bank whenever you are trying to get some data or execute some code.

So GBT runs in bank 1, again, what’s the big deal?

The problem here is that the first example uses interrupt for the player update function. If your game loop is small, and your ROM is small, and your game is more or less a “Hello World!” this won’t be a problem because you won’t use bank switching and bank 1 will always be available. If your game is big and you need to load data from other banks, there are problems because you will sometimes use data from other banks (in fact, GBT Player loads data from the bank where the song is placed, but it returns to bank 1 afterwards to execute its code).

An interrupt means that the CPU jumps to an interrupt vector, executes its code and then returns to its previous state. Again, you should know that. If you don’t, something is wrong and you should stop and learn this kind of things first. But you won’t, that’s why I’m explaining this. This is useful to know when hardware events happen, like screen redraw. Vertical blanking period is entered when the current frame has been drawn, so it happens once every frame (around 60 times per second). This interrupt is very useful to synchronize the game, and GBT Player uses it to update itself.

Let’s say you want to load a background placed in bank 4. You switch to bank 4, start copying… and vertical blank period is reached. An interrupt is triggered and CPU jumps to the VBL interrupt vector at address 0040h. It eventually calls gbt_update(), which switches to bank 1, and returns. The CPU returns to the same state as before the interrupt… but the ROM bank is still bank 1, so the copy won’t work because it’s reading incorrect data! This can also happen with code. In that case, the game is likely to crash immediately. If you only had banks 0 and 1, this couldn’t happen. That’s why small demos and games run fine, but they will eventually crash if they are more than 32 KB big (2 banks).

That’s why the code of gbt_player.h says “this changes to bank 1!”. To warn you that this does changes to the memory that you have to revert. I don’t know what system GBDK uses to know what ROM bank is being used or anything like that. When I made a game (that I didn’t finish) I created a ROM bank stack to keep track of the banks that I used, so I could save the bank that was being used when gbt_update() was called and I could restore it afterwards. I suppose most of you won’t be able to do something like that, so the new example is an alternative.

The new example calls gbt_update() every frame in the main loop of the game. You need to put it in EVERY main loop, and you need to synchronize the game to VBL with wait_vbl_done(). That’s it. No more problems of banking. Well, there still can be problems, but it’s more difficult. If you can write code that has that kind of problems, you should be able to fix them.

In fact, if your game doesn’t use wait_vbl_done(), your game is evil. This function enters a low consumption state until VBL is entered, and it should be used whenever it’s possible. I’ve seen code of “games” that don’t use it. They are bad. No, seriously, use that function. Please.

Examples of bad tutorials (I could only find 2 right now, both in Spanish):

http://www.elotrolado.net/hilo_desarrollo-software-proyectos-de-darkryoga_1901847

http://www.fasebonus.net/foro/index.php?topic=36662.msg60626#msg60626

PS: But you are, in fact, using GBDK, which should be avoided. :P It’s better if you try to learn ASM and use RGBDS or WLA-DX assemblers instead. The GB CPU is very slow, so you need every CPU cycle you can get. Maybe you are doing a text-only game, and then GBDK should be fine, but you are wasting a lot of CPU power. GBDK functions are mostly written in ASM. I know it’s harder and you want to see results right now, but it’s better.

PS2: Anyway, update to the latest version (2.1.1 at the time of writing this, the same as 2.1.0 but with a new GBDK example):

https://codeberg.org/SkyLyrac/gbt-player

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Game Boy Camera documentation

Thu, 12 Mar 2015 13:20:00 +0000

Over the last few weeks I’ve been doing some reverse engineering on the GB Camera and I think I’ve documented it good enough for most things. I’ve reversed the cartridge controller registers and measured the capture timings. The only thing that I can’t understand is the level/gain control of the sensor (its datasheet is really bad) but it shouldn’t matter for an emulator. I’ve implemented this in GiiBiiAdvance and it’s working perfectly (you’ll have to wait for the next version if you want to check it, though), so I guess that’s all that matters.

And a pic of my hardware setup (click to zoom):

The repository is here: https://codeberg.org/SkyLyrac/gbcam-rev-engineer

The first release is here:

https://codeberg.org/SkyLyrac/gbcam-rev-engineer/releases/tag/v1.0

PS: Did I mention before that I won the GBdev 2014 compo?

http://gbdev.gg8.se/forums/viewtopic.php?id=244

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Pong 3DS v1.0

Wed, 18 Feb 2015 00:21:00 +0000

Well, after a few weeks of coding at last I have a release of this game. :)

This is just a 3D pong, inspired by my old Pong 3DS for Nintendo DS.

This was a test to see if I could manage to setup a correct perspective for stereoscopic 3D, but I decided to make a simple game out of it.

I haven’t used hardware accelerated graphics because I couldn’t manage to compile any shader assembler (except from Picasso, but it’s a bit outdated). I originally made this 3D software engine for GBA, so there are still a few files from Tonc’s library for GBA. Anyway, this game always runs at 60 FPS. :)

If anyone cares, the 3D engine can draw lines, triangles, quads, line strips, triangle strips and quad strips, all of them With alpha blending. Quads are drawn using a function used just for them to draw them faster, not by drawing two triangles. It supports directional lighting (up to 32 lights, limited to 2 because why more) and ambient lighting. It can sort polygons with painter’s algorithm (no buffer-Z). It doesn’t support textured polygons.

Oh, the 3D slider actually does something when you change its position. The engine renders each top screen in a separate core when working in 3D mode to make it run always at the same FPS.

Press Y to take a screenshot in PNG format (2 files in 3D mode, 1 in 2D mode) or SELECT to exit. Use the joystick to move the pad, and A to jump in the 2.5D room.

For now, in the main menu, press a button in the touchscreen to enter a game room. Pressing START in a room will return the game to the main menu.

Holding L and R at the same time will show the FPS and the CPU usage.

This game is licensed under the GPL Version 3.

Binaries here:

https://codeberg.org/SkyLyrac/pong-3ds/releases

Source code and more information here:

https://codeberg.org/SkyLyrac/pong-3ds

And a few screenshots:

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Pong 3DS, now in an actual Nintendo 3DS!

Sat, 24 Jan 2015 17:16:00 +0000

Ok, this has nothing to do with this other game.

This is just a stupid stereoscopic 3D software rendering test. Oh, the 3D slider actually does something when you change its position.

No screenshot because it’s just a bunch of wireframe boxes IN THREE DIMENSIONS. Maybe next time.

Link: https://codeberg.org/SkyLyrac/pong-3ds

Update (2015-01-25):

Well, I’ve updated it a bit. Filled polygons, lighting, screenshots…

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Back to Color [GBC Demo][GBDev 2014]

Mon, 30 Jun 2014 00:01:00 +0000

Hello again!

This time I’m here to show you my first GBC demo! Made specially for the 2014 GBDev Game Boy Coding Compo. In fact, I started it like four years ago, but stopped after doing 3 scenes (the first effect, the text scroller at the end of the first song and the colorful horizontal bars before the matrix effect). I’ve coded the rest in just a few weeks, in fact I started doing new effects a few days before the GBDev compo announcement. I’ve coded it and made the music, the only thing I haven’t done is the train screen graphics and the credits graphics (by jordirafel). I’m not a very good musician, so… Oh, and it shows a little credits screen in non-color GBs! Some screenshots here:

And here it is, the download link:

Download

If you want to test it in an emulator (like BGB, Gambatte or VBA-M, most of them have a “Frame Blending” option, enable it if possible. It works in real hardware, of course! Tested in DMG, MGB, GBC, GBA and GBA SP. If you want to skip some parts, hold up/right/down/left when the demo is loading if you want to skip 1/2/3/4 songs. Non-color GB only show the reduced credits screen!

I have also recorded a video with VBA-M in case you are too lazy to download an emulator! :P The shadows in the bouncing balls effect are incorrect, they should be the same color, but the rest is correct. In a real GBC or an emulator it looks fine.

https://www.youtube.com/watch?v=eSEsd1OGA74

The demo has been coded using my fork of RGBDS (with a few bugfixes), a GBT Player version modified to use only the first ROM bank, OpenMPT to make the music, GBTK and GBMB. To test it I’ve used BGB, Gambatte, VBA-M, my GiiBiiAdvance… and real hardware.

I hope you like it! :)

…

Oh…

One last thing…

Source code

Yeah, that’s everything. :P

Update (2018-01-31)

This demo should be able to compile with the upstream RGBDS, located here.

Update (2026-01-14)

This demo is now hosted in Codeberg.

Faceball 2000 Double Speed Mod v0.1

Wed, 04 Jun 2014 16:29:00 +0000

Hello!

A few days ago I discovered this game, I tried it, and got disappointed because it has a painfully low framerate video… So I opened it with BGB and decided to fix it! :)

I’ve changed the initial jump to an empty area just before the ROM header. I just switch to CPU double speed mode, wait for VBL, load greyscale palettes for BGs and sprites and jump to real start point. Of course, it only works in GBC and GBA now! Header’s GBC flag has been changed, and checksums have been fixed.

Just to make it clear: This makes the CPU faster, so everything changes. Music is still the same because it uses interrupts for synchronization, framerate is multiplied by at least 2, but timer countdown is affected! Also, link communications are affected.

You’ll need an IPS patcher like Lunar IPS
And, of course, the “Faceball 2000 (USA).gb” ROM, which I won’t provide here.

The patch you have to apply is here:

Download

I haven’t tested Link functions, but it should work between modified copies of the game. I haven’t changed the way the game works. It still copies VRAM data manually instead of using GDMA or something like that, but that would need some extra work, and it runs fine now. I hope you like it!

Bye!

GBT Player v1.2

Thu, 01 May 2014 15:36:00 +0000

Hello again!

This is just a bugfix release. I’ve modified the samples included in the mod file in order to avoid transposing notes when converting it with mod2gbt. This means that you can use all notes from C3 to B8.

You can find source, binaries and examples (RGBDS and GBDK) for version 1.2 here:

https://codeberg.org/SkyLyrac/gbt-player/releases/tag/v1.2

And any other improvements, here:

https://codeberg.org/SkyLyrac/gbt-player

Bye!

Update (2026-01-14)

Updated links from GitHub to Codeberg.

Switch GBA into GBC mode by software

Sun, 20 Apr 2014 20:46:00 +0000

Hello!

I know dwedit did something like this a few years ago, but I never managed to compile its code and make it run (even though the precompiled binary worked fine). Anyway, the code was incomprehensible:

http://www.dwedit.org/dwedit_board/viewtopic.php?id=339

This morning I’ve read that the GBA bios still had the piece of code that switches the GBA into GBC mode, like Nintendo planned to do in the beginning (before deciding that it would be better to do it with a hardware switch).

I’ve disassembled the part that performs this switch and made a little demo to show that it works! Here it is:

https://codeberg.org/SkyLyrac/gba-switch-to-gbc

But it doesn’t end here! It can also apply an affine transformation to the GBC video output, and even enable mosaic effect or GREENSWP register! The GREENSWP register works a bit different than in GBA mode, by the way.

The bad thing is that the video output only works in GB Micro, in GBA and GBA SP it shows a black screen, and in DS it doesn’t work at all (it doesn’t have a GB CPU).

I’ve also uploaded a video:

https://www.youtube.com/watch?v=-SkR8SAdS9w

Bye!

Update (2026-01-14)

Updated links from GitHub to Codeberg.

GiiBiiAdvance 0.2.0

Fri, 04 Apr 2014 12:43:00 +0000

Hello!

After a few years, at last I continue with this emulator. :P I’ve been coding for a few weeks and at last I have a release.

The main change is that it now uses SDL2 for the GUI, not WinAPI. It can compile under Windows or Linux with the included Code::Blocks project file (I want to add a Makefile later). You can check the source code here:

https://codeberg.org/SkyLyrac/giibiiadvance

Some screen captures:

This time I’ve included GB Camera emulation again. In GiiBiiAdvance 0.1.0 was removed (GiiBii had it). This time I’ve documented it all, and I’m planning on doing some reverse engineering on the real hardware (I’ve bought a few cartridges just in case I break one). For now, I’ve only used the GB Camera software to see how it works, and I’ve managed to emulate almost everything (contrast, dithering and brightness). It is quite complicated to do emulate brightness because it depends on the webcam and on the GB Camera software, so it changes weirdly sometimes. The documentation is in “/docs/” folder in GitHub.

Of course, there is a debugger. I’ve improved it since 0.1.0, and now it allows to dump any image that it displays. There are more changes, see the changelog in the source code if you are interested.

The binaries are here. There are binaries for Windows and Linux Mint/Ubuntu, with and without webcam support:

https://codeberg.org/SkyLyrac/giibiiadvance/releases

I hope you like it!

Update (2026-01-14)

Updated links from GitHub to Codeberg.

32x8 Yellow LED Matrix

Sat, 30 Mar 2013 00:53:00 +0000

Hello!

I’ve been messing around with electronics lately (after all, that’s what I’m studying :P), and this is the result! A 32x8 LED Matrix controlled by a PIC18F2550. You can click in the pictures for full size! At the end of the post there is a video of the screen running.

It can show any image you want, and the microcontroller can hold more than 900 of them! You can set individual times for displaying each frame. Apart from that, you can connect it to a UART port and stream data directly from the computer. The UART connector is the 2x13 pin connector, but only 3 pin are soldered. I did it this way because it is easier to connect it to the Raspberry Pi without making errors.

I’ve used the 18F2550 because I had a few of them at home, and I want to make a driver for streaming using USB instead of UART. It is running at 20MHz from an external crystal oscillator.

Connected to the Raspberry Pi and power:

Now, some pictures of the boards. First, the simple (but a REAL pain to solder, it took about 6 hours) 32x8 LED board:

A detail of the soldering:

Now, the expansion board. It basically holds some 74HCT164 (SIPO registers), some transistors and resistors.

Last, but not least, the control board, which holds the microcontroller (a PIC18F2550), a decoder, and a buffer. The decoder is 4:16, it should be 3:8 but I didn’t have one of them at home (well, I had one but not negative logic). The buffer is actually a quad 2-input OR gate chip, I didn’t have one buffer either, and I needed it to convert voltage levels for the Raspberry Pi. Anyway, using the 4:16 decoder was not a terrible idea because I soldered the 4 inputs to the PIC and I can use the most significant one to turn off and on the screen (I could have used the enable pin, but hey…). The button is just the reset button, and the 4 DIP switches are connected to the PIC, but only the left one is used for now (for switching between UART streaming and automatic mode). The USB is not used for now.

The yellow LED is just a power indicator, the red and green ones are TX/RX indicators, and the other red led is unused for now (it lights if there is a USB cable connected at power up). And yeah, the PIC is in a socket in another socket, just to make it really easy to remove it from the board. :P

And here it is, a video of the display running. I can’t embed the video here.

The software at the PC side is shown in the video, but it is basically a 32x8 matrix you can edit with the mouse and keyboard. You can also type a text and the program will convert it to an animation! There are some things missing, like error checking and sending again the data if the microcontroler says the packet is corrupted. It is coded in C with SDL, using software rendering because the Raspberry Pi version of SDL doesn’t have OpenGL support.

If someone asks I could make schematics and upload them, and the code (in assembly) for the PIC too, but there are a lot of tutorials for making LED Matrix screens so I think it’s not necessary.

Root Locus 0.3

Sun, 30 Sep 2012 13:21:00 +0000

Well, I should have put this here a few months ago, but I’ve been lazy to do so.

Anyway, here is Root Locus 0.3. It now supports discrete systems, and it lets you set a value for ‘k’ (the one of the regulator) manually. You can also ask it for the position of the poles in the current position. Everything is in the manual.

Link to hpcalc: http://www.hpcalc.org/details.php?id=7354

Download (binary + source)

Update (2018-03-23)

This project is now hosted in GitHub.

Update (2026-01-14):

This project is now hosted in Codeberg.

Root Locus 0.2

Sat, 04 Feb 2012 14:28:00 +0000

Hello!

This is a program I’ve been coding for university. It is a library for the HP50g. This program draws the root locus of a given transfer function and lets you add a regulator, as well as change the proportional value of the regulator and see the new position for the poles of the system for that value.

I’ve sent it to www.hpcalc.org, too. There are a lot of great programs there. Anyway, the download link is here:

Download (Binary + Source)

There are instructions on how to install and use it, they should be clear enough for anybody. The source code is included (HP-GCC 2.0 and HP files for packaging the library).

Nitro Engine v0.6.1

Thu, 01 Sep 2011 16:02:00 +0000

Well… I just looked at the code this morning and saw that the code looked horrible… So I just reorganised it a bit (included the code of examples), added a few “static” keywords and fixed a few warnings related to new versions of libnds and devkitARM. Nothing else, though. Everything worked fine, so I didn’t have to do anything else…

Link to web with the download information and those things.

GiiBiiAdvance v0.1.0

Fri, 26 Aug 2011 17:14:00 +0000

Special Scenery Beta 2011 edition.

This is what I’ve been working on since last summer, and I think it is a quite good program right now. It is just another GBA emulator, just like VisualBoyAdvance, and it emulates the same: GB, GBC, SGB and GBA.

I’ve used the GB, GBC and SGB emulation code from GiiBii, so GiiBiiAdvance has the same compatibility (a bit more, I’ve changed a bit of SGB emulation code). GBA emulation is, on the other hand, not really high. I mean, lots of ROMs work, but some of them just show a black screen, or hang when you try to start the game from the menu… Everything of GBA is emulated (except the serial port), but there are bugs I can’t find, I’ll work on it until I get a better compatibility. Of course, it emulates all save chips, but some saves aren’t compatible with other emulators. It will try to guess the save type if it can’t detect it from the ROM. It lets you take screenshots, and GB Printer output is saved as a png image. GB Camera is not emulated yet, though, so if you want to play with that ROM, use GiiBii.

There is also a quite good debugger, with a disassembler, memory viewer, I/O ports viewer, tile viewer, map viewer, palette viewer and sprite viewer. They are different in GBx and GBA mode. If you are playing a SGB game, there is also a SGB things viewer. I have to make it easy to dump/save things, right now it only lets you watch. So… here are some screens:

GBA mode

GBC mode

SGB mode

SGB viewer

And the downloads:

Binary (windows only)

Source

So… that’s it. I hope this program is useful for somebody. About the splash screen… You can close it by clicking it, or just waiting 4 seconds. It is disabled in the source code.

Oh, the last thing. If you want real SGB emulation, try bsnes. It’s an impressive SNES emulator, and lets you load and use a Game Boy ROM with Super Game Boy ROM.

A few more screenshots in GBA mode:

Bye!

GiiBii v0.3

Fri, 27 Aug 2010 16:55:00 +0000

Special Scenery Beta 2010 version!

The most important change is that it now uses OpenGL instead of drawing directly to the framebuffer, which makes it work a bit faster. I’ve also allowed to use 3x zoom because the screen size is no longer a problem.

Changes:

Dissasembler fixes.
Debugger screen now gets focus when reaching a breakpoint.
Changed to OpenGL, allowed 3x zoom. Fullscreen mode is buggy, sometimes it crashes when returning to windowed mode… :S
Rumble “emulated” (screen shakes a bit).
MBC7 fixed (Kirby Tilt ’n’ Tumble).
Mapper code optimized a bit.
Stat bug emulated (Legend of Zerd, Road Rash now work in non-color Game Boy modes).
Game Boy Pocket screen is now white, you can only change the color of the normal Game Boy screen.
Sound emulation code partially optimized. Also, it is more accurate now (and it can save the sound output to a wav file, but the code is disabled this version because it needs testing).
CPU fixes: Zero flag for opcodes RRA / RR A, RCLA / RCL A, etc…
Added a filter to make colors more “realistic”. You can enable it in the menu, and you can also enable or disable the frame mix filter that comes with GiiBii since first version.
Discovered why Alleyway didn’t work: GB Printer was enabled.
Fixed a bug in ICON_EN SGB command that made graphics have serious glitches in some games (DK2, DK3).

Downloads:

Binaries (win32)

Binaries (Linux)

You need SDL and GTK+ (and OpenCV for the GB Camera).

Source

Notes:

Emulation may be more accurate if you put the GB boot roms in the “boot” folder of the emulator (see the readme.txt). They aren’t included with the download.
You can load a ROM by grabbing it to the GiiBii exe file (or using the command line “GiiBii myrom.gb”).
If you want free ROMs, go to PDRoms. If you are looking for commercial games, I can’t help you.
This emulator will be mixed someday with GiiBiiAdvance.

Screenshots:

GiiBiiAdvance - WIP

Wed, 25 Aug 2010 13:06:00 +0000

Hello!

Since GiiBii works really well for what I expected, I wanted to do a GBA emulator. I’ve been working on it since July, and after 2 months of work, here are some results:

“Kirby - Nightmare in Dream Land” and “Need For Speed - Underground 2”.

Obviously, there is still a lot to do, most games are unplayable (in fact, NFS runs very slowly, there is a problem with CPU timing, I guess), have graphic glitches (where is the needle of the speedometer? :P) or just can’t pass from the initial splash screens (if they can show them…).

What is done:

CPU emulation (ARM and THUMB), but it is still buggy.
DMA channels (except special modes).
All BG modes and regular (non-affine) sprites are emulated. No special effects or window effects, though.
VBL, HBL, VCOUNT, DMA and KEYPAD interrupt requests.
Disassembler, I/O register viewer (both aren’t finished) and memory viewer.

A capture of the debugger:

Yeah, that’s a Tonc demo.

PS: A new version of GiiBii is coming in a few days :P.

GiiBii v0.2

Tue, 02 Feb 2010 23:06:00 +0000

New version! This time, GiiBii comes with an interesting new feature… It can emulate the GB Camera with camera features! I’ll explain more about this later, before that:

Changes:

New mappers supported: MMM01 (Taito Variety Pack works, Momotarou Collection 2 doesn’t…), MBC7 (controls need some improvements…).
You can set the screen size to 1x or 2x now.
You can reset the ROM instead of having to exit it and reload the ROM.
Now the console shows more information when loading a ROM (like the licensee name).
You can set customized controls for 4 players (yeah, SGB multiplayer works again ^^).
You can change volume or enable/disable each sound channel.
Stop mode emulated correctly (but I’ve never seen any game using it, I’ve coded it just by testing on my GBC).
Added breakpoint support.
Debugger font size can be changed (take a look at the ini file).
A few little bugfixes and improvements…

Downloads:

Binaries (win32)

Binaries (Linux) – coming soon… :)

Source

Very messy, camera functions in “memory.c” (nothing special, though).

Game Boy Camera:

This version of GiiBii can emulate camera features of GB Camera just by using a webcam. For getting the pictures from it, GiiBii uses OpenCV, which is cross-platform, just like SDL and GTK+. GiiBii will try to use as much information as possible from the webcam, and scale it down to the GB size. This is just the first version with camera support, you can expect some improvements in next versions. For example, brightness is emulated very badly… but hey, it “works”. On the other hand, contrast doesn’t work… What I’m trying to say is that you will have to wait if you want a better support. Just remember that this emulator isn’t as fast as it could be, so don’t expect it running as well as the other emulators you’ve tried. Anyway, take a look at what it can do now :) :

Try taking a picture and “printing” it using GB Printer (which is emulated). :)

Just a note: It may freeze a second or so when loading the GB Camera ROM (because of the webcam being initialized). If you want to enable the webcam window, enable debug messages and it will load when opening the GB Camera ROM.

GB Camera emulated with a webcam!

Tue, 02 Feb 2010 15:29:00 +0000

Uhmmm… yeah… ^_^

PS: I’m using OpenCV for getting the webcam data.

GBT Player v1.1

Sat, 24 Oct 2009 16:06:00 +0000

Hello again!

This time I’m going to show you a music player… for Game Boy. :P It’s very easy to use, and easy to compose music for it. I’ve included source code (100% asm) and templates for RGBDS and GBDK. You have to compose the music in a tracker in the PC using a custom mod file included in the download. Available effects and other instructions to modify it are in a text file in the download. Then, you convert it using a special tool which will export the data to a GBDK C file or a RGBDS asm file. Included templates can be compiled by double clicking the bat files, so you can use them for testing your songs as you compose them (I’d use the RGBDS one). For any other information, look at the readme, or ask me. There is an example there, the rest should be self-explanatory.

Download

PS: Is there anybody who still codes for GB? :P

Update

Some incorrect definitions changed:

Download version 1.1

Pascal Pong v0.1

Sat, 24 Oct 2009 01:31:00 +0000

Well… This is what happens when I’m bored and I feel a bit guilty because I haven’t practised anything with pascal (they make us code with Turbo Pascal in university)… I don’t know exactly why I’ve put v0.1 as there won’t probably be more updates… :P Anyway, download links here, source + win32 binary:

Download

And a screenshot…

GiiBii v0.1

Fri, 02 Oct 2009 12:53:00 +0000

Well, it took me some days more to finish this because of some (sound related) bugs I couldn’t fix, but here it is! GiiBii v0.1, first version of GiiBii for PC. I hope you like it. I think this is the first “official” release of an emulator that supports the GBC boot ROM (not included in the downloads). :)

Features:

Supports MBC1, MBC2, MBC3 (RTC emulated), MBC5, HuC-1.
Sound channels emulated correctly (you can hear “Pikachu!” in Pokemon Yellow, for example).
“Turbo” mode. Not extremely fast, though… This emulator is not meant to be fast, but to be accurate.
Supports boot ROMs (bios). At the moment of writing this only DMG, SGB and CGB have been dumped, but GiiBii is prepared for the other ones as well (they may not work, as they haven’t been tested).
It can generate screenshots in PNG format.
GB Printer emulated, images are saved into the screenshots folder in PNG format, too.
Allows changing the screen palette in GB mode.
Super Game Boy is emulated, though some commands aren’t coded (sound, default palettes…).
Debugger and VRAM viewer (debugger is not complete yet).
Uses SDL and GTK+, cross platform libraries, so it should be very easy to port to Linux, for example (I’ll check it and upload a binary when done).
GiiBii is open source, it is licensed under the GPL v3 so you can modify it but you have to make modifications open source too.

And finally, the downloads:

Binaries

Source

GiiBii... now on PC!

Sat, 19 Sep 2009 10:42:00 +0000

Well, this is the first “real” post. :P

I’ve been working on a port of GiiBii (my Game Boy emulator) to PC for about 3 weeks. It has been a bit difficult, as I used libraries that are only available in Wii (libogc, asndlib…), and I wanted to make the port using only cross-platform libraries (as I want to make Linux binaries).

The first thing I have to decide was the graphics library I could use in PC. I decided that SDL was a good idea because it also gives a low-level sound API, just what I need to improve the audio system of my emulator (yeah, the Wii version uses a really bad system and there are glitches many times). When I managed to get it to compile, I started porting the emulator. I deleted a lot of code and, after commenting a lot of parts like sound, input, Super Game Boy emulation, I managed to get it to compile. Then I started to fix that parts. When I finished with the input and the SGB ones, I decided it was time to begin with the GUI.

I looked for a library to make it. I found out that GTK+ was a good one, and I started to put together GTK+ and SDL. When it was ready, I started to code the GUI. GTK+ is a bit difficult at the beginning, but when you get used to it, you can see that it’s really useful. After a lot of hours of work, I finally made a little menu with almost all options that you can see in the Wii binary and rewrote the debugger.

This is the result:

Cool, isn’t it? :)

I’m rewriting the sound emulation part at the moment. I think that in a week or so I will have finished it (and some parts of the menu) and I will release a beta.

Bye!

Welcome!

Sat, 19 Sep 2009 01:15:00 +0000

Hello everybody!

This is my new blog. I think it’s time to create one, so that I can say when update one of my projects, or just I’ve done something I consider interesting to say. :) I’m not quite good at writing, and my English isn’t great, either, so you can expect a lot of mistakes in my writing. Just let me know where I made any mistake and I’ll correct it.

By the way, this is my other webpage.

Thanks to Dovoto for the hosting of both this blog and the other webpage! :D

Now, time to go back to coding…

Bye!

About me

Mon, 01 Jan 0001 00:00:00 +0000

I’m Antonio Niño Díaz, and this is a short story of my hacking life.

I’m Spanish, born in a city near Madrid. I studied Industrial Engineering in Madrid, and specialized in Electronics and Control. After getting my degree I got a job at Arm in Cambridge, UK, where I’ve lived since January 2016.

Most of what I know about programming is self-taught. I started trying a few simple things in BASIC on my father’s Amstrad CPC. I eventually came across Game Maker and started to program for PC an to understand how games are made, what objects are, that kind of things.

At some point, when I was 15, I discovered that I could also write my own programs for the Nintendo DS. That’s when I started to learn C. Then I realized everything that it could do, and the fact that it can be used to develop for pretty much any device you can think of. It has been my favourite programming language ever since.

I also discovered microcontrollers thanks to the Wii hacking scene, and starting to program a bit in assembly. I find it amazing that I can control things in the real world by just programming a small chip. I’ve played quite a bit with PIC microcontrollers.

I eventually moved to PC and wrote GiiBiiAdvance, my GBC and GBA emulator. And then, as I knew the instruction set of the GBC, I decided to start developing things in assembly for the GBC.

Something else I love are FPGAs. I learned about them at university, and I had to buy one to play with at home. I don’t use it nearly as much as I’d like, though, but it’s one of the things I’m most interested in at the moment.

And this is the end, for now. Just take a look at my projects in this website, and know that I’m always available to answer questions about them!