import MdxPreview from ’./assets/MdxPreview’

This is a collection of reusable components that I have created for my blog.

<Age />

This component calculates the age based on the birth date and the current date.

Hello, I am years old.

<ArchivedLink />

This component creates a link to an archived version of a webpage.

My old blog from 2020 is archived on the Wayback Machine.

<Divider />

This component creates a horizontal divider with an icon in the middle.

<ExtraInformation client:load />

This component adds a fold-out panel to add extra information for something without cluttering the main text.

import ExtraInformation from '@/ExtraInformation'

The <ExtraInformation client:load name="USB Device Descriptor">
  The **USB Device Descriptor** is a data structure that provides information about a USB device, such as its vendor ID, product ID, and supported USB version. It is used by the host to identify and configure the device.
</ExtraInformation> is a crucial part of the USB protocol.

import ExtraInformation from ’@/ExtraInformation’

The The USB Device Descriptor is a data structure that provides information about a USB device, such as its vendor ID, product ID, and supported USB version. It is used by the host to identify and configure the device. is a crucial part of the USB protocol.

<Figure />

This component creates a figure with an image and a caption.

import FileTree from '@/FileTree'

<FileTree client:load>
- src
  - components
    - Button.tsx
    - Card.tsx
  - pages
    - index.astro
    - about.astro
</FileTree>

import LocalTime from '@/LocalTime'

`12:00` my time is <LocalTime client:load time24h="12:00" fromTimezone="Europe/Zurich" /> for you.

import Oscilloscope from '@/Oscilloscope'

<Oscilloscope client:load
  signals={[
    { name: 'CLK', color: 'blue' },
    { name: 'DATA', color: 'green' },
    { name: 'EN', color: 'red' },
  ]}
  channelData={[
    [0, 0, 1, 0, 1, 0, 1, 0, 1, 0], // Clock signal
    [0, 0, 0, 1, 0, 1, 0, 1, 1, 0], // Data signal
    [0, 0, 1, 1, 1, 1, 1, 1, 1, 0], // Enable signal
  ]}
/>

import TechnicalTerm from '@/TechnicalTerm'

The <TechnicalTerm client:load term="CPU" description="Central Processing Unit, the brain of the computer" /> is responsible for executing instructions in a computer.

import Terminal from '@/Terminal'

<Terminal client:load initialText={"Welcome to Linux!\r\n$ "}/>

import Video from '@/Video'
import test_video from './assets/video.mp4'

<Video client:load src={test_video} />

import NotePanel from ‘packages/mdx-blog-components/src/NotePanel’;

Compared to languages like Python or Java, C++ does not provide built-in support for stack traces in exceptions. This can make debugging somewhat difficult when all you end up having is a crash log stating what(): bad optional access. With some linker ticks and a bit of code, it is possible though to add cleaner stack traces to C++ exceptions, including standard library ones.

For MSVC, a similar approach can be taken by hooking different functions that are used for exception handling in the MSVC runtime, but the details will be different and are not covered in this post.

The simplest way to get stack traces working for exceptions is to just create a custom exception type that captures the stack trace in the constructor and then we can print that stack trace in the what() method.

#include <exception>
#include <stdexcept>
#include <stacktrace>
#include <print>

class ExceptionWithStackTrace : public std::exception {
public:
  ExceptionWithStackTrace(std::string what) {
    m_what = std::format(
      "what(): {}\n{}", 
      what,
      // Capture the stack trace
      // skipping the current frame which is the constructor itself
      std::stacktrace::current(1)
    );
  }

  auto what() const noexcept -> const char* override {
    return m_what.c_str();
  }

private:
  std::string m_what;
};

auto some_function() -> void {
  throw ExceptionWithStackTrace("Test");
}

auto main() -> int {
  try {
    some_function();
  } catch (const std::exception &e) {
    std::println("{}", e.what());
  }
}

This works great if all you need is stack traces for code you wrote yourself

$ ./custom_exceptions

what(): Test
   0#  someFunction() at main.cpp:20 [0x6520e5502718]
   1#  main at main.cpp:25 [0x6520e5502793]
   2#  <unknown> [0x785ae3c29d8f]
   3#  __libc_start_main [0x785ae3c29e3f]
   4#  _start [0x6520e5502604]

For any exception that is of a different type though, including standard library exceptions, we won’t get a stack trace just like before.

To support stack traces for all exceptions, we need to somehow inject this code into the existing exceptions. However, there are quite a few of them and if libraries add their own, it would need to be added there as well. Luckily, the Itanium C++ ABI provides a simple common entry point for all exceptions that can be used.

Exceptions in the Itanium ABI are implemented using a set of functions that are automatically inserted by the compiler when you throw or catch an exception.

main:
    ; ...
    ; try {
        ; printf("Throwing\n");
        call    puts@PLT
        ; ...
        ; auto exception = std::runtime_error("My exception");
        call    __cxa_allocate_exception@PLT
        call    std::runtime_error::runtime_error(char const*)@PLT
        ; ...
        ; throw exception;
        call    __cxa_throw@PLT
        ; ...
        jmp     .catch_statement
        ; ...
        call    __cxa_free_exception@PLT
    ; }
.catch_statement:
    ; ...
    ; catch (const std::exception& e) {
        call    __cxa_begin_catch@PLT
        ; ...
        ; printf("Caught exception\n");
        call    puts@PLT
        call    __cxa_end_catch@PLT
    ; }
    ; ...
    ret

As you can see, the compiler generates calls to __cxa_allocate_exception and __cxa_throw at the call site of the throw statement and calls __cxa_begin_catch and __cxa_end_catch at the start and end of the catch block respectively. __cxa_throw is the function that actually starts the whole unwinding process so it is the perfect place to inject our stack trace code into. By hooking this function, we can capture the stack trace at the point where the exception is thrown and then we can store that stack trace in a thread-local variable that can be accessed later in the catch block.

Hooking __cxa_throw

To hook __cxa_throw, we can make use of the Linker to redirect all calls made to __cxa_throw to our own function. This can be done by using the -Wl,--wrap=__cxa_throw flag when linking the application.

The linker will then replace all calls to __cxa_throw with calls to __wrap___cxa_throw and it will rename the original __cxa_throw function to __real___cxa_throw.

#include <array>
#include <stacktrace>
#include <typeinfo>
#include <exception>

// Storage to store up to 5 nested stack traces for exceptions
//   should be enough for most cases but can be increased if needed
thread_local std::array<std::stacktrace, 5> s_stacktraces;

// Forward declaration for the original __cxa_throw function
//   that will be called from our wrapper
extern "C" auto __real___cxa_throw(
  void *thrown_object, 
  std::type_info *tinfo, 
  void (*dest)(void *)
) -> void;

// Wrapper function for __cxa_throw that will be called
//   instead of the original one
extern "C" auto __wrap___cxa_throw(
  void *thrown_object, 
  std::type_info *tinfo, 
  void (*dest)(void *)
) -> void {
  // Called when an exception is thrown, at the call site of the `throw`

  // std::uncaught_exceptions() returns the number of currently
  //   active exceptions that have been thrown but not yet caught
  auto exception_count = std::uncaught_exceptions();

  // If there's still some space on the exception stack,
  //   capture a new stacktrace and add it to the stack
  if (exception_count < ssize_t(s_stacktraces.size())) {
    // Add the current stack trace to the end of the
    //   stack trace storage array skipping the current
    //   frame which is the __wrap___cxa_throw function itself
    s_stacktraces[exception_count] = std::stacktrace::current(1);
  }

  // Forward to original __cxa_throw()
  __real___cxa_throw(thrown_object, tinfo, dest);
}

// Simple helper function to print the stack trace
//   of the exception that's currently being caught
auto print_stacktrace() -> void {
  auto exception_count = std::uncaught_exceptions();
  if (exception_count < 0) {
    std::println("No active exception");
    return;
  } else if (exception_count >= s_stacktraces.size()) {
    std::println("Too many active exceptions");
    return;
  }

  std::print("Stacktrace:\n{}", s_stacktraces[exception_count]);
}

Now code like this here will automatically have stack traces for all exceptions, including standard library ones, without needing any further modifications to existing code. The only thing that is needed is to add the -Wl,--wrap=__cxa_throw flag when linking the final executable and all shared libraries that need this functionality.

#include <optional>

auto main() -> int {
  try {
    // A non-existent int
    std::optional<int> nothing;

    // This will throw a std::bad_optional_access exception
    nothing.value();
  } catch (const std::exception &e) {
    // Print the exception what() message
    std::println("Caught exception: {}", e.what());

    // Print the stack trace
    print_stacktrace();
  }
}

$ ./wrapped_exceptions

Caught exception: bad optional access
Stacktrace:
   0#  std::__throw_bad_optional_access() at optional:126 [0x5e5c24b3cf94]
   1#  std::optional<int>::value() & at optional:1279 [0x5e5c24b3ccb2]
   2#  main at main.cpp:9 [0x5e5c24b3c8a4]
   3#  <unknown> [0x7b3a63229d8f]
   4#  __libc_start_main [0x7b3a63229e3f]
   5#  _start [0x5e5c24b3c644]

There’s a few downsides with this approach that I’d like to mention.

The first one is obviously that this is highly implementation defined. It works out of the box on latest GCC and Clang at the time of writing, both using libstdc++ as their C++ standard library.

LLVM’s libc++ also uses the same exception mechanism, however it does currently not support <stacktrace> so something like libbactrace or boost::stacktrace() would need to be used instead.

If your application throws a lot of exceptions that are caught and handled silently, this may add quite a substantial overhead as now every throw has to generate a stack trace, no matter if it’s being used or not. Definitely do some profiling if you’re using this in production code.

Finally, due to the linker magic needed here, this only works for binaries you’re linking yourself. If you rely on external shared libraries that you do not compile yourself, the exceptions there will not generate any stack traces. This includes exceptions thrown from the pre-compiled C++ standard library too. libstdc++ seems to be doing this in a few places to prevent including exception headers in various libraries, libc++ doesn’t do this as often. Exceptions from there may be intercepted as well by using dynamic linker magic like a LD_PRELOAD library that defines the __cxa_throw symbol. For statically linked code, this is not necessary though.

import LinuxEmulator from ’./components/Linux’ import TechnicalTerm from ’@/TechnicalTerm’ import PdfDocument from ’@/PdfDocument’ import Steps from ’@/Steps’ import NotePanel from ’@/NotePanel’ import PencilMarked from ’@/PencilMarked’ import Figure from ’@/Figure’

import riscv_spec from ’./assets/riscv-spec.pdf’ import wd8250_datasheet from ’./assets/WD8250_82C50_16C450.pdf’

Many embedded systems these days run Linux as their operating system. Generally because it’s a great foundation to run anything you like on top of and because many great developers and manufacturers already took care of writing drivers for all kinds of hardware components.

Even though this makes building the finished project much easier, if you’re dealing with custom hardware, you will most likely still have to bring up the Linux kernel on your own initially. This post is about just that: Setting up the bare minimal to get Linux running on a new platform. In this case, the new platform is not a new PCB but a minimal, emulated RISC-V CPU.

Even though Linux is a very complex piece of software, it doesn’t actually have that many requirements to run. The only thing it really needs in terms of hardware is:

• A CPU with an Memory Management Unit
  A piece of hardware on the SoC that handles translating virtual addresses to physical addresses, allowing for isolation between multiple different userspace processes and the Kernel
• Enough RAM to, at least, load the Kernel, a Device Tree and an initramfs.
• A periodically lapsing system clock timer

These things are what I ended up implementing in about 2000 lines of C++ code. For the CPU I implemented the RV32IMA instruction set which has all the things Linux needs to run. For the Hardware, I implemented a simple RAM peripheral, the Supervisor Binary Interface
Basically a syscall-like interface that allows the Kernel to send request to Machine Mode (the CPU itself) to configure built-in functionality for timers and a UART peripheral based on the WD8250 chip which is well supported and is really simple to implement.

Documenting the entire process of writing the emulator is a bit out of scope for this post but the full implementation can be found here: WerWolv/riscv-emulator.

Using this emulator, the final hardware definition looks like this:

struct Hardware {
  Hardware() {
    // Map peripherals into the address space
    cpu.address_space().map(0x0000'0000, &ram);
    cpu.address_space().map(0xF400'0000, &uart8250);

    // Hook up a RISC-V compatible MMU as the address translator
    cpu.address_space().add_address_translator(&riscv_mmu);

    // Configure the UART peripheral to print output to the terminal
    uart8250.output_callback([](std::uint8_t c) {
      putchar(c);
      fflush(stdout);
    });

    // Load the Linux Kernel to the start of the RAM
    ram.write(0x00, LinuxKernel);

    // Load the Device Tree to the end of the RAM
    constexpr static auto DeviceTreeBlobLoadAddress = 512_MiB - 1_MiB;
    ram.write(DeviceTreeBlobLoadAddress, DeviceTreeBlob);
    // Put the device tree address into register a1 to emulate the way
    // the bootloader would do it on a real system
    emulator.cores()[0].a1() = DeviceTreeBlobLoadAddress;

    // Load the Device Tree in front of the device tree
    // but at a fixed address we can use later
    constexpr static auto InitRamFsLoadAddress = 0x1F700000;
    ram.write(InitRamFsLoadAddress, InitRamFs);

    // Start up cpu
    cpu.power_up();
  }

  auto step() -> void {
    cpu.step();
  }

private:
  riscv::Cpu<1> cpu;
  dev::riscv::MMU<std::uint32_t> riscv_mmu;

  dev::Ram ram(512_MiB);
  dev::UART8250 uart8250;
};

This, of course, currently does absolutely nothing since there’s no code for it to execute. To get Linux running, we need to first configure and compile the Linux Kernel for our platform and then populate those LinuxKernel, DeviceTreeBlob and InitRamFs arrays with the correct data.

To compile anything to run on the target, the first thing we need is a toolchain. Compiling it by hand is generally a bit of a pain since you need to get the correct version of various different tools and libraries and then configure and compile them in the correct order (sometimes even multiple times with different configurations!). Luckily for us though, the crosstool-ng Project exists and handles all of that for us. With it we can simply configure the toolchain we need and then let it do all the work.

Since we’re planing on building an application that later on runs on 32-bit RISC-V Linux, we need a toolchain that targets riscv32-unknown-linux-gnu. This will give us a GCC compiler that can compile C code for our target platform as well as glibc as the C standard library implementation to interface with the Kernel.

.
$ ./bootstrap
INFO  :: *** Generating package version descriptions
...
INFO  :: *** Done!


$ make
gmake[1]: Entering directory 'crosstool-ng'
...
GEN      ct-ng



$ ./ct-ng riscv32-unknown-elf
                                                    
...
Now configured for "riscv32-unknown-elf"


$ ./ct-ng menuconfig

This will open a visual configuration menu where we can change various options for the toolchain.

$ make -j    \
  ARCH=riscv \
  CROSS_COMPILE=/path/to/riscv32-unknown-linux-gnu-

#include <stdlib.h>
#include <stdint.h>
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>

int main() {
  // Open /dev/kmsg to write logs directly to the Kernel Log
  int kmsg = open("/dev/kmsg", O_WRONLY);
  if (kmsg == -1) {
    return EXIT_FAILURE;
  }
  
  // Print some message
  dprintf(kmsg, "Hello World from \033[32mLinux Userspace\033[0m!\n");
  
  // Loop forever to prevent the init process from exiting
  while (true) {
    sleep(1);
  }
  
  // Close the file handle
  close(kmsg);

  return EXIT_SUCCESS;
}

$ riscv32-unknown-linux-gnu-gcc -static init.c -o init

.
# /bin
dir /bin 755 0 0
file /bin/init init 755 0 0


# /dev
dir /dev 755 0 0
nod /dev/kmsg 644 0 0 c 1 11
nod /dev/initrd 644 0 0 b 1 250
nod /dev/console 600 0 0 c 5 1
nod /dev/null 666 0 0 c 1 3
nod /dev/ram 644 0 0 b 1 0
nod /dev/root 644 0 0 b 4 0
nod /dev/ttyS0 660 0 0 c 4 64

# /proc
dir /proc 755 0 0

$ gen_init_cpio initramfs.txt -i initramfs.cpio

/dts-v1/;


/ {
  #address-cells = <0x01>;
  #size-cells = <0x01>;

  model = "WerWolv's Emulator";


  cpus {
    #address-cells = <0x01>;
    #size-cells = <0x00>;

    timebase-frequency = <65000000>;


    cpu@0 {
      device_type = "cpu";
      compatible = "riscv";
      reg = <0x00>;
      riscv,isa = "rv32ima";
      mmu-type = "riscv,sv32";


      interrupt_controller: interrupt-controller {
        #interrupt-cells = <0x01>;
        #address-cells = <0x00>;
        compatible = "riscv,cpu-intc";

        interrupt-controller;
      };
    };
  };


  memory@0 {
    device_type = "memory";
    reg = <0x00 (512 * 1024 * 1024)>;
  };
}

/ {
  // ...



  soc@F0000000 {
    #address-cells = <0x01>;
    #size-cells = <0x01>;
    compatible = "simple-bus";
    ranges = <0x00 0xF0000000 0x10000000>;



    serial@4000000 {


      compatible = "ns8250", "ns16550";
      reg = <0x4000000 0x100000>;
      interrupt-parent = <&interrupt_controller>;
      interrupts = <0x01>;
      no-loopback-test;
      clock-frequency = <5000000>;
    };
  };
};

/ {
  // ...


  aliases {
    serial0 = "/soc@F0000000/serial@4000000";
  };


  chosen {
    bootargs = "earlycon console=/dev/ttyS0 rdinit=/bin/init root=/dev/initrd";
    stdout-path = "serial0";
    linux,initrd-start = <0x1F700000>;
    linux,initrd-end = <0x1FEFFFFF>;
  };
};

$ dtc -I dts -O dtb -o riscv-emulator.dtb riscv-emulator.dts

constexpr std::uint8_t LinuxKernel[] = {
    #embed "Image"
};

constexpr std::uint8_t DeviceTreeBlob[] = {
    #embed "device_tree.dtb"
};

constexpr std::uint8_t InitRamFs[] = {
    #embed "initramfs.cpio"
};

$ ./command

[    0.000000] Booting Linux on hartid 0
[    0.000000] Linux version 7.0.0-00166-g0f0013213293 (werwolv@fedora) ...
[    0.000000] Machine model: WerWolv's Emulator
...
[   54.748992] Run /bin/init as init process
[   54.814251] Hello World from Linux Userspace!

import NotePanel from ’@/NotePanel’ import PencilMarked from ’@/PencilMarked’ import PdfDocument from ’@/PdfDocument’

import { Image } from ‘astro’ import device_descriptor_imhex from ’./assets/device_descriptor_imhex.png’; import usb_spec from ’./assets/usb_20.pdf’

Say you’re being handed a USB device and told to write a driver for it. Seems like a daunting task at first, right? Writing drivers means you have to write Kernel code, and writing Kernel code is hard, low level, hard to debug and so on.

None of this is actually true though. Writing a driver for a USB device is actually not much more difficult than writing an application that uses Sockets.

This post aims to be a high level introduction to using USB for people who may not have worked with Hardware too much yet and just want to use the technology. There are amazing resources out there such as USB in a NutShell that go into a lot of detail about how USB precisely works (check them out if you want more information), they are however not really approachable for somebody who has never worked with USB before and doesn’t have a certain background in Hardware. You don’t need to be an Embedded Systems Engineer to use USB the same way you don’t need to be a Network Specialist to use Sockets and the Internet.

The device we’ll be using an Android phone in Bootloader mode. The reason for this is that

• It’s a device you can easily get your hands on
• The protocol it uses is well documented and incredibly simple
• Drivers for it are generally not pre-installed on your system so the OS will not interfere with our experiments

Getting the phone into Bootloader mode is different for every device, but usually involves holding down a combination of buttons while the phone is starting up. In my case it’s holding the volume down button while powering on the phone

Enumeration refers to the process of the host asking the device for information about itself. This happens automatically when you plug in the device and it’s where the OS normally decides which driver to load for the device. For most standard devices, the OS will look at the USB Device Class and loads a driver that supports that class. For vendor specific devices, you generally install a driver made by the manufacturer which will look at the VID (Vendor ID) and PID (Product ID) instead to detect whether or not it should handle the device.

Even without a driver, plugging the phone into your computer will still make it get recognized as a USB device. That’s because the USB specification defines a standard way for devices to identify themselves to the host, more on how that exactly works in a bit though.

On Linux, we can use the handy lsusb tool to see what the device identified itself as:

$ lsusb
...
Bus 008 Device 014: ID 18d1:4ee0 Google Inc. Nexus/Pixel Device (fastboot)
...

Bus and Device are just identifiers for the physical USB port the device is plugged into. They will most likely differ on your system since they depend on which port you plugged the device into. ID is the most interesting part here. The first part 18d1 is the Vendor ID (VID) and the second part 4ee0 is the Product ID (PID). These are identifiers that the device sends to the host to identify itself. The VID is assigned by the USB-IF to companies that pay them a lot of money, in this case Google, and the PID is assigned by the company to a specific product, in this case the Nexus/Pixel Bootloader.

Using the lsusb -t command we can also see the device’s USB class and what driver is currently handling it:

$ lsusb -t
...
/:  Bus 008.Port 001: Dev 001, Class=root_hub, Driver=xhci_hcd/1p, 480M
    |__ Port 001: Dev 002, If 0, Class=Hub, Driver=hub/4p, 480M
        |__ Port 003: Dev 003, If 0, Class=Hub, Driver=hub/4p, 480M
            |__ Port 002: Dev 014, If 0, Class=Vendor Specific Class, Driver=[none], 480M
...

This shows the entire tree of USB devices connected to the system. The bottom most one in this part of the tree is our device (Bus 008, Device 014 as reported in the previous command). The Class=Vendor Specific Class part specifies that the device does not use any of the standard USB classes (e.g HID, Mass Storage or Audio) but instead uses a custom protocol defined by the manufacturer. The Driver=[none] part simply tells us that the OS didn’t load a driver for the device which is good for us since we want to write our own.

We will also go after the VID and PID since they are the only real identifying information we have. The Device Class is not very useful for it here since it’s just Vendor Specific Class which any manufacturer can use for any device. Instead of doing all of this in the Kernel though, we can write a Userspace application that does the same thing. This is much easier to write and debug (and is arguably the correct place for drivers to live anyway but that’s a different topic). To do this, we can use the libusb library which provides a simple API for communicating with USB devices from Userspace. It achieves this by providing a generic driver that can be loaded for any device and then provides a way for Userspace applications to claim the device and talk to it directly.

Enumerating the device with libusb

The same thing we just did manually can also be done in software though. The following program initializes libusb, registers a hotplug event handler for devices matching the 18d1:4ee0 VendorId / ProductId combination and then waits for that device to be plugged into the host.

#include <print>
#include <libusb-1.0/libusb.h>

auto hotplug_callback(
    libusb_context *ctx, 
    libusb_device *device, 
    libusb_hotplug_event event, 
    void *user_data
) -> int {
    std::println("Device plugged in!\n");

    return 0;
}

auto main() -> int {
    // Create a context so we can interact with the libusb driver
    libusb_context *context = nullptr;
    libusb_init(&context);

    // Register a hotplug event handler to wait for our device to be plugged in
    libusb_hotplug_callback_handle hotplug_callback_handle;
    libusb_hotplug_register_callback(
        context,
        LIBUSB_HOTPLUG_EVENT_DEVICE_ARRIVED, // Device plugged in event
        LIBUSB_HOTPLUG_ENUMERATE,  // Fire event for already plugged in devices
        0x18d1, 0x4ee0,            // The VID and PID we found previously
        LIBUSB_HOTPLUG_MATCH_ANY,  // Match any USB Class
        hotplug_callback, nullptr, // The callback to call
        &hotplug_callback_handle
    );

    // Handle the libusb events
    while (true) {
        if (libusb_handle_events(context) < 0)
            break;
    }

    // Clean up
    libusb_hotplug_deregister_callback(context, hotplug_callback_handle);
    libusb_exit(context);
}

If you compile and run this, plugging in the device should result in the following output:

$ ./libusb_enumerate

Device plugged in!

Congrats! You have a program now that can detect your device without ever having to touch any Kernel code at all.

On Windows, things may look different. If you're lucky, the device has a `Microsoft OS Descriptor` that tells Windows to load the `Winusb.sys` driver for your device. In that case, `libusb` can talk to it directly. However if no driver was loaded (the device shows up in the Device Manager with a little ⚠️ icon), you might need to use Zadig to force-replace the driver of the device with `Winusb.sys` or another supported driver. More information can be found here: libusb Wiki

Next step, getting any answer from the device. The easiest way to do that for now is by using the standardized Control endpoint. This endpoint is always on ID 0x00 and has a standardized protocol. This endpoint is also what the OS previously used to identify the device and get its VID:PID.

The way we use this endpoint is with yet another libusb function that’s made specifically to send requests to that endpoint. So we can extend our hotplug event handler using the following code:

// Open the device so we can communicate with it
libusb_device_handle *handle = nullptr;
libusb_open(device, &handle);

std::vector<std::uint8_t> data(0xFF);

// Do a Control transfer
const auto result = libusb_control_transfer(
    handle,
    uint8_t(LIBUSB_ENDPOINT_IN)      | // Ask for data from the device...
        LIBUSB_RECIPIENT_DEVICE      | //   about the device as a whole...
        LIBUSB_REQUEST_TYPE_STANDARD,  //   using a standard request.
    LIBUSB_REQUEST_GET_STATUS,         // Send a GET_STATUS request
    0x00,                              // wValue value of 0x00
    0x00,                              // wIndex value of 0x00
    data.data(), data.size(),          // Buffer to read the data into
    1000                               // 1000ms timeout
);

// Print the data returned by the device if there was no error
if (result >= 0)
    print_bytes(std::span(data).subspan(0, result));

// Close device again
libusb_close(handle);

This code will now send a GET_STATUS request to the device as soon as it’s plugged in and prints out the data it sends back to the console.

$ ./libusb_enumerate
Addr  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F

0000: 01 00 

Those bytes came from the device itself! Decoding them using the USB Specification tells us that the first byte tells us whether or not the device is Self-Powered (1 means it is which makes sense, the device has a battery) and the second byte means it does not support Remote Wakeup (meaning it cannot wake up the host).

There are a few more standardized request types (and some devices even add their own for simple things!) but the main one we (and the OS too) are interested in is the GET_DESCRIPTOR request.

Descriptors are binary structures that are generally hardcoded into the firmware of a USB device. They are what tells the host exactly what the device is, what it’s capable of and what driver it would like the OS to load. So when you plug in a device, the host simply sends multiple GET_DESCRIPTOR requests to the standardized Control Endpoint at ID 0x00 to get back a struct that gives it all the information it needs for enumeration. And the cool thing is, we can do that too!

Instead of a GET_STATUS request, we now send a GET_DESCRIPTOR request:

const auto result = libusb_control_transfer(
    handle,
    uint8_t(LIBUSB_ENDPOINT_IN)      | // Ask for data from the device...
        LIBUSB_RECIPIENT_DEVICE      | //   about the device as a whole...
        LIBUSB_REQUEST_TYPE_STANDARD,  //   using a standard request.
    LIBUSB_REQUEST_GET_DESCRIPTOR,     // Send a GET_DESCRIPTOR request
    (LIBUSB_DT_DEVICE << 8) | 0,       // Request the 0th Device Descriptor
    0x00,                              // Language ID, can be ignored here
    data.data(), data.size(),          // Buffer to read the data into
    1000                               // 1000ms timeout
);

This now instead returns the following data:

$ ./libusb_enumerate
Addr  00 01 02 03 04 05 06 07  08 09 0A 0B 0C 0D 0E 0F

0000: 12 01 00 02 00 00 00 40  D1 18 E0 4E 99 99 01 02 
0010: 00 01 

Now to decode this data, we need to look at the USB specification on Chapter 9.6.1 Device. There we can find that the format looks as follows:

struct DeviceDescriptor {
    u8  bLength;
    u8  bDescriptorType;
    u16 bcdUSB;
    u8  bDeviceClass;
    u8  bDeviceSubClass;
    u8  bDeviceProtocol;
    u8  bMaxPacketSize0;
    u16 idVendor;
    u16 idProduct;
    u8  iManufacturer;
    u8  iProduct;
    u8  iSerialNumber;
    u8  bNumConfigurations;
};

Throwing the data into ImHex and giving its Pattern Language this structure definition yields the following result:

And there we have it! idVendor and idProduct correspond to the values we found previously using lsusb.

There’s more than just the device descriptor though. There’s also Configuration, Interface, Endpoint, String and a couple of other descriptors. These can all be read using the same GET_DESCRIPTOR request on the control endpoint. We could still do this all by hand but luckily for us, lsusb has an option that can do that for us already!

$ lsusb -d 18d1:4ee0 -v

Bus 001 Device 012: ID 18d1:4ee0 Google Inc. Nexus/Pixel Device (fastboot)
Negotiated speed: High Speed (480Mbps)
Device Descriptor:
  bLength                18
  bDescriptorType         1
  bcdUSB               2.00
  bDeviceClass            0 [unknown]
  bDeviceSubClass         0 [unknown]
  bDeviceProtocol         0
  bMaxPacketSize0        64
  idVendor           0x18d1 Google Inc.
  idProduct          0x4ee0 Nexus/Pixel Device (fastboot)
  bcdDevice           99.99
  iManufacturer           1 Synaptics
  iProduct                2 USB download gadget
  iSerial                 0
  bNumConfigurations      1
  Configuration Descriptor:
    bLength                 9
    bDescriptorType         2
    wTotalLength       0x0020
    bNumInterfaces          1
    bConfigurationValue     1
    iConfiguration          2 USB download gadget
    bmAttributes         0xc0
      Self Powered
    MaxPower                2mA
    Interface Descriptor:
      bLength                 9
      bDescriptorType         4
      bInterfaceNumber        0
      bAlternateSetting       0
      bNumEndpoints           2
      bInterfaceClass       255 Vendor Specific Class
      bInterfaceSubClass     66 [unknown]
      bInterfaceProtocol      3
      iInterface              3 Android Fastboot
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x81  EP 1 IN
        bmAttributes            2
          Transfer Type            Bulk
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0200  1x 512 bytes
        bInterval               0
      Endpoint Descriptor:
        bLength                 7
        bDescriptorType         5
        bEndpointAddress     0x02  EP 2 OUT
        bmAttributes            2
          Transfer Type            Bulk
          Synch Type               None
          Usage Type               Data
        wMaxPacketSize     0x0200  1x 512 bytes
        bInterval               0
Device Qualifier (for other device speed):
  bLength                10
  bDescriptorType         6
  bcdUSB               2.00
  bDeviceClass            0 [unknown]
  bDeviceSubClass         0 [unknown]
  bDeviceProtocol         0
  bMaxPacketSize0        64
  bNumConfigurations      1
Device Status:     0x0001
  Self Powered

This output shows us a few more of the descriptors the device has. Specifically, it has a single Configuration Descriptor that contains a Interface Descriptor for the Android Fastboot interface. And that interface now contains two Endpoints. This is where the device tells the host about all the other endpoints, besides the Control endpoint, and these will be the ones we’ll be using in the next step to actually finally send data to the device’s Fastboot interface!

Let’s talk a bit more about endpoints first though. We already learned about the Control endpoint on address 0x00. Endpoints are basically the equivalent to ports that a device on the network opened for us to send data back and fourth. The device specifies in its descriptor which kind of endpoints it has and then services these in its firmware. So we don’t even need to do port scanning or know that SSH just runs on port 22 usually, we have a nice way of finding out what interfaces the device has, what language they speak and how we can speak to them. Looking at the descriptors above, that control descriptor is not there though. Instead, there’s two others with different types.

There’s exactly one per device and it’s always fixed on Endpoint Address 0x00. It’s what is used do initial configuration and request information about the device.

The main purpose of the Control endpoint is to solve the chicken-and-egg problem where you couldn’t communicate with a device without knowing its endpoints but to know its endpoints you’d need to communicate with it. That’s also why it doesn’t even appear in the descriptors. It’s not part of any interface but the device itself. And we know about its existence thanks to the spec, without it having to be advertised.

It’s made for setting simple configuration values or requesting small amounts of data. The function in libusb doesn’t even allow you to set the endpoint address to make a control request to because there’s only ever one control endpoint and it’s always on address 0x00

Bulk Endpoints are what’s used when you want to transfer larger amounts of data. They’re used when you have large amounts of non-time-sensitive data that you just want to send over the wire.
This is what’s used for things like the Mass Storage Class, CDC-ACM (Serial Port over USB) and RNDIS (Ethernet over USB).

One detail: Data sent over Bulk endpoints is high bandwidth but low priority. This means, Bulk data will always just fill up the remaining bandwidth. Any Interrupt and Isochronous transfers (further detail below) have a higher priority so if you’re sending both Bulk and Isochronous data over the same connection, the bandwidth of the Bulk transmission will be lowered until the Isochronous one can transmit its data in the requested timeframe.

Interrupt Endpoints are the opposite of Bulk Endpoints. They allow you to send small amounts of data with very low latency. For example Keyboards and Mice use this transfer type under the HID Class to poll for button presses 1000+ times per second. If no button was pressed, the transfer fails immediately without sending back a full failure message (only a NAK), only when something actually changed you’ll get a description back of what happened.

The important fact here is, even though these are called interrupt endpoints, there’s no interrupts happening. The Device still does not talk to the Host without being asked. The Host just polls so frequently that it acts as if it’s an interrupt.
The functions in libusb that handle interrupt transfers also abstract this behaviour away further. You can start an interrupt transfer and the function will block until the device sends back a full response.

Isochronous Endpoints are somewhat special. They’re used for bigger amounts of data that is really timing critical. They’re mainly used for streaming interfaces such as Audio or Video where any latency or delay will be immediately noticeable through stuttering or desyncs. In libusb, these work asynchronously. You can setup multiple transfers at once and they will be queued and you’ll get back an event once data has arrived so you can process it and queue further requests.
This type is generally not used very often outside of the Audio and Video classes.

Besides the Transfer Type, endpoints also have a direction. Keep in mind, USB is a full master-slave oriented interface. The Host is the only one ever making any requests and the Device will never answer unless addressed by the Host. This means, the device cannot actually send any data directly to the Host. Instead the Host needs to ask the Device to please send the data over.

This is what the direction is for.

• IN endpoints are for when the Host wants to receive some data. It makes a request on an IN endpoint and waits for the device to respond back with the data.
• OUT endpoints are for when the Host wants to transmit some data. It makes a request on an OUT endpoint and then immediately transfers the data it wants to send over. The Device in this case only acknowledges (ACK) that it received the data but won’t send any additional data back.

Contrary to the transfer type, the direction is encoded in the endpoint address instead. If the topmost bit (MSB) is set to 1, it’s an IN endpoint, if it’s set to 0 it’s an OUT endpoint. (If you’re into Hardware, you might recognize this same concept from the I2C interface.)

That means two things:

• You can have a maximum of 27−1=1272^7 - 1 = 12727−1=127 custom endpoints available at once
  • 272^727 because we have 7 bits available for addresses
  • −1-1−1 because we always have the control endpoint that’s on the fixed address 0x00.
• Endpoints are entirely unidirectional. Either you’re using an endpoint to request data or to transmit data, it cannot do both at once
  • That’s also the reason why our Fastboot interface has two Bulk endpoints: one is dedicated to listening to requests the Host sends over and the other one is for responding to those same requests

Now that we have all this information about USB, let’s look into the Fastboot protocol. The best documentation for this is both the u-boot Source Code and as its Documentation.

According to the documentation, the protocol really is incredibly simple. The Host sends a string command and the device responds with a 4 character status code followed by some data.

Host:    "getvar:version"        request version variable

Client:  "OKAY0.4"               return version "0.4"

Host:    "getvar:nonexistant"    request some undefined variable

Client:  "OKAY"                  return value ""

Let’s update our code to do just that then:

// Open the device so we can communicate with it
libusb_device_handle *handle = nullptr;
libusb_open(device, &handle);

// Claim the interface to let libusb know which interface
// we're sending data to
libusb_claim_interface(handle, 0);

// Setup a 64 byte buffer for our request and response
// The documentation specifies 64 bytes for full-speed and
// 512 bytes for high-speed. Since this is a full-speed device,
// we use 64 bytes.
std::vector<uint8_t> bytes(64);

// Copy the command "getvar:version"
// to the start of the buffer
std::ranges::copy(
    "getvar:version", 
    bytes.begin()
);

// Do a Bulk transfer of that data on the OUT Endpoint 0x02
int num_bytes_transferred = 0;
libusb_bulk_transfer(
    handle,                     // Device handle
    LIBUSB_ENDPOINT_OUT | 0x02, // Endpoint OUT 0x02
    bytes.data(), bytes.size(), // Data to send
    &num_bytes_transferred,     // Number of bytes sent
    1000                        // 1000ms timeout
);

// Print the transmitted data data
std::println("Request: {}", 
    std::string_view(
        reinterpret_cast<const char *>(bytes.data()),
        num_bytes_transferred
    )
);

// Clear the buffer
std::ranges::fill(bytes, 0x00);
num_bytes_transferred = 0;

// Do a Bulk transfer on the IN Endpoint 0x01
libusb_bulk_transfer(
    handle,                     // Device handle
    LIBUSB_ENDPOINT_IN | 0x01,  // Endpoint IN 0x81
    bytes.data(), bytes.size(), // Buffer to receive into
    &num_bytes_transferred,     // Number of bytes received
    1000                        // 1000ms timeout
);

// Print the returned characters
std::println("Response: {}", 
    std::string_view(
        reinterpret_cast<const char *>(bytes.data()),
        num_bytes_transferred
    )
);

// Release the interface again
libusb_release_interface(handle, 0);

// Close the device handle
libusb_close(handle);

Plugging the device in now, prints the following message to the terminal:

$ ./libusb_enumerate
Request:  getvar:version
Response: OKAY0.4

That seems to match the documentation!
First 4 bytes are OKAY, specifying that the request was executed successfully The rest of the data after that is 0.4 which corresponds to the implemented Fastboot Version in the Documentation: v0.4

And that’s it! You successfully made your first USB driver from scratch without ever touching the Kernel.

All these same principles apply to all USB drivers out there. The underlying protocol may be significantly more complex than the fastboot protocol (I was pulling my hair out before over the atrocity that the MTP protocol is) but everything around it stays identical. Not much more complex than TCP over sockets, is it? :)

import Figure from ’@/Figure’;

Thermal Printers are amazing for quickly printing out notes and todo lists since all they need is paper and some power. Printing is done by heating up the paper to color it black without needing any sort of ink that can run out. Unfortunately the model I got here only supports Bluetooth and the only official way to talk to it is through the horrible iPrint app.

Two weeks ago I ordered this thermal printer from AliExpress hoping it would be the same as the one a friend got a while ago. Their printer has an STM32 MCU on it as well as a super nicely labeled UART header. Unfortunately for me, mine has some weird ass controller with no information online whatsoever and no UART or USB support. Great.

import Horizontal from ’@/Horizontal’;

LogUtils.m1960e(Integer.valueOf(getEneragy()));
bArr2 = new byte[((i7 * length) + BluetoothOrder.print_text.length + 9 + 10)];
byte[] bArr5 = new byte[10];
bArr5[0] = 81;
bArr5[1] = 120;
bArr5[2] = -81;
bArr5[3] = 0;
bArr5[4] = 2;
bArr5[5] = 0;
bArr5[6] = ConvertUtils.hexString2Bytes(Integer.toHexString(getEneragy()))[1];
bArr5[7] = ConvertUtils.hexString2Bytes(Integer.toHexString(getEneragy()))[0];
bArr5[8] = BluetoothOrder.calcCrc8(bArr5, 6, 2);
bArr5[9] = -1;
System.arraycopy(bArr5, 0, bArr2, 0, bArr5.length);
this.packageLength += 10;

Magic0:         0x51
Magic1:         0x78
CommandID:      0x00 - 0xFF
AlwaysZero0:    0x00
Data Size:      0x00 - 0xFF
AlwaysZero1:    0x00
Data:           [ Array of bytes with the length provided before, Big Endian ]
DataCRC8:       0x00 - 0xFF
Magic4:         0xFF

RetractPaper:     0xA0
FeedPaper:        0xA1
DrawBitmap:       0xA2
SetDrawingMode:   0xBE
SetEnergyLevel:   0xAF
SetQuality:       0xA4

crc8_table = [
    0x00, 0x07, 0x0e, 0x09, ... # Rest of array
]

def crc8(data):
    crc = 0
    for byte in data:
        crc = crc8_table[(crc ^ byte) & 0xFF]
    return crc & 0xFF

def formatMessage(command, data):
    data = [ 0x51, 0x78 ] + [command] + [0x00] + [len(data)] + [0x00] + data + [crc8(data)] + [0xFF]
    return data

PrinterAddress = "93:2A:BB:C4:95:8D"
PrinterCharacteristic = "0000AE01-0000-1000-8000-00805F9B34FB"

FeedPaper = 0xA1
async def feedPaper():
  device = await BleakScanner.find_device_by_address(PrinterAddress, timeout=20.0)
  async with BleakClient(device) as client:
    await client.write_gatt_char(PrinterCharacteristic, formatMessage(FeedPaper, [0x70, 0x00]))

loop = asyncio.get_event_loop()
loop.run_until_complete(feedPaper())

import Figure from ’@/Figure’;

The Surface Book 2 is one of Microsoft’s self made notebooks. What makes it different from other laptops is it’s deep integration of the drawing pen into Windows and the ability to detach the entire screen from it’s base by pressing a button on the keyboard or using their pre-installed SurfaceDTX tool.

Since Windows any many other operating systems run on a ton of different hardware, it’s impossible to bundle support for every device directly into the Kernel, however userspace programs may still want to communicate with hardware installed in the computer. Instead of adding custom system calls for every device ever built, most OSes support loading of kernel extensions at runtime (kernel modules on Linux, device drivers on Windows) together with a unified way to communicate with these extensions, called ioctl.

The reason ioctl and device drivers are necessary in the first place is for security reasons. On startup all hardware devices found on- or connected to the computer’s mainboard are mapped into the kernel’s address space and have to be controlled from there using extensions that live in the kernel’s address space as well. The kernel’s address space cannot be directly accessed by userspace applications so the kernel may allow access to certain devices through syscalls while denying access to others.

The greatness of ioctl comes from its simplicity. A single syscall is used on windows called NtDeviceIoControlFile with its wrapper function DeviceIoControl. It takes the following arguments:

• A HANDLE to the device, usually obtained by using the NtCreateFile syscall
• A control code describing the operation the device driver should execute. These codes consist of several fields:
  • Device type (CD-ROM, mouse, network, printer, etc.) values 0x8000 or greater are vendor specific devices (for example the latch mechanism on the Surface Book 2)
  • Function code describing the command the device driver should execute. These are arbitrary values defined in the individual drivers.
  • Transfer type specifying if the data gets buffered or not
  • Required access for operations, either read-only, write-only or read-write
• A pointer to a in-buffer sent to the device driver
• The size of the in-buffer
• A pointer to a out-buffer which will be filled with data returned from the driver
• The size of the out-buffer
• A pointer to a uint32_t where the received data size will be written to
• A optional pointer to a overlapped struct for async operations

When calling DeviceIoControl a syscall handler in the kernel gets called. That handler uses the passed device handler to find the right device driver to be called. The in-buffer then gets copied from user- into kernel space and the driver’s DEVICE_CONTROL callback gets called containing the control code and pointers to the in- and out-buffers. The control code is used to figure out what operation should be executed, the in-buffer is used for parameters and the out-buffer for possible returned values.

To find out how the latch driver works, there are two possible approaches. Either we reverse engineer the device driver directly and analyze the DEVICE_CONTROL callback or we use the already implemented latch control tool Microsoft built to find the correct driver and control codes.

I decided to go for the latter since the tool was trivial to find (by simply looking at the task manager) and even better, it was written in C# containing full symbol information. To analyze the .NET application, I used JetBrain dotPeek. Simply looking through the different namespaces in dotPeek quickly made me discover a promising class called DriverLatch.cs.

private static readonly Guid g_latchInterfaceId = new Guid("f49e75f6-f869-4346-9eb8-ded248275916");

private static readonly IOControlCode g_latchCommandIoctl = new IOControlCode((ushort) 32768, (ushort) 2065, (IOControlAccessMode) 2, (IOControlBufferingMethod) 0);
private static readonly IOControlCode g_latchChangedIoctl = new IOControlCode((ushort) 32768, (ushort) 2066, (IOControlAccessMode) 1, (IOControlBufferingMethod) 0);
private static readonly IOControlCode g_latchStatusIoctl = new IOControlCode((ushort) 32768, (ushort) 2064, (IOControlAccessMode) 1, (IOControlBufferingMethod) 0);
private static readonly IOControlCode g_detachChangedIoctl = new IOControlCode((ushort) 32768, (ushort) 2067, (IOControlAccessMode) 1, (IOControlBufferingMethod) 0);
private static readonly IOControlCode g_detachStateIoctl = new IOControlCode((ushort) 32768, (ushort) 2068, (IOControlAccessMode) 1, (IOControlBufferingMethod) 0);

private enum LatchCommandType
{
    Invalid,
    Open,
    Close_DEPRECATED,
    ButtonPress,
    Cancel,
    MaximumValue,
}

[StructLayout(LayoutKind.Sequential, Pack = 1)]
private struct LatchCommandInArgs
{
    public DriverLatch.LatchCommandType LatchCommand;
    public uint TimeoutMs;
}

#include <windows.h>
#include <cstdint>

enum class LatchCommandType : std::uint32_t {
    Invalid,
    Open,
    Close_DEPRECATED,
    ButtonPress,
    Cancel,
    MaximumValue
};

struct [[gnu::packed]] LatchCommandInArgs {
    LatchCommandType LatchCommand;
    std::uint32_t TimeoutMs;
};

// Latch command ioctl control code
constexpr DWORD latchCommandIoctl = CTL_CODE(0x8000, 2065, METHOD_BUFFERED, FILE_WRITE_ACCESS);

int main() {
    // Open a handle to the latch device driver
    HANDLE ioctlLatchFile = CreateFileW (
        L"\\\\?\\ACPI#MSHW0133#2&daba3ff&1#{f49e75f6-f869-4346-9eb8-ded248275916}",
        GENERIC_READ | GENERIC_WRITE,
        FILE_SHARE_READ | FILE_SHARE_WRITE,
        nullptr,
        OPEN_EXISTING,
        FILE_ATTRIBUTE_NORMAL,
        nullptr
    );

    // Specify the device driver arguments sent through the in-buffer
    LatchCommandInArgs args = { .LatchCommand = LatchCommandType::ButtonPress, .TimeoutMs = 5000 };
    DWORD readSize = 0;

    // Make the ioctl call, opening the latch
    DeviceIoControl(ioctlLatchFile, latchCommandIoctl, &args, sizeof(LatchCommandInArgs), nullptr, 0, &readSize, nullptr);

    return 0;

}

import Steps from ’@/Steps’; import PdfDocument from ’@/PdfDocument’; import Figure from ’@/Figure’;

The STM32MP157C-DK2 is one of the latest dev boards by ST Microelectronics. It features a STM32MP1 SoC with two ARM A7 cores and one M4 co-processor core. The intended way of using this SoC according to STM is to run their custom, pre-built Linux distribution, toolchain, SDK and proprietary flash tools. Their Wiki does a great job at not telling you a lot of important details because STM’s linux distro “takes care of that”. This post however deals with all the dirty details about how the entire boot process works and how to bring the DK2 board into a state where a custom kernel can be loaded.

import stpmic1_datasheet from ’./assets/stpmic1.pdf’; import board_schematics from ’./assets/p574376-en.MB1272-DK2-C01_Schematic.pdf’;

When the board gets plugged in, the first thing happening is the STPMIC1 power management IC initializing it’s output voltages to the default settings. According to its Datasheet and the Board Schematics, this means the core gets powered with 1.2V, the DDR RAM with 1.1V and the rest of the SoC peripherals with 3.3V.

Once the voltage has stabilized, the Boot ROM starts running and determines where to boot from by reading either the BOOT0 and BOOT1 pin or a value burnt into the OTP eFuses. Possible boot sources are NAND and NOR flash, eMMC, Serial and SD cards. The DK2 uses the SD card by default as no other sources can be found on the board.

The Boot ROM now tries to boot from the SD card. The SD card must contain a GPT containing two partitions named fsbl1 and fsbl2. These are two, hopefully identical, copies of the First Stage bootloader the Boot ROM will later execute.

For the Boot ROM to recognize and load the FSBL (or in fact any binary), a special format is used. It is described as the STM32 header for binary files and consists of a 256 bytes long header followed by the binary data to load.

header = struct.pack("<4sQQQQQQQQIIIIIIIIIIQQQQQQQQ83xb",
  # Header magic
  b"STM\x32",                 
  # ECDSA signature, unsigned here                      
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  # Checksum of payload, sum of all bytes   
  sum(payload),
  # Header version 1.0                                     
  0x00010000,
  # Length of payload                                       
  len(payload),
  # Entrypoint address. SYSRAM + 0x2400 (BROM data) + 0x100 (header)                                     
  0x2FFC0000 + 0x2400 + 0x100,
  # Reserved                      
  0x00,
  # Load address of image, unused                                             
  0x2FFC0000 + 0x2400 + 0x100,
  # Reserved                      
  0x00,
  # Image version                                             
  0x00,
  # Option flags, disable signature verification                                             
  0x01,
  # ECDSA algorithm set to P-256 NIST, unused                                             
  0x01,
  # ECDSA signature, unsigned here                                             
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  # Binary type: U-Boot   
  0x00
)

$ openocd -f $OPENOCD_SCRIPTS/board/stm32mp15x_dk2.cfg -c "gdb_flash_program enable"

// launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Debug",
      "type": "gdb",
      "request": "launch",
      "cwd": "${workspaceRoot}",
      "target": "${workspaceRoot}/fsbl/build/fsbl.elf",
      "gdbpath": "/bin/arm-none-eabi-gdb",
      "preLaunchTask": "build", // Before debugging, build changes
      "autorun": [
        "target remote tcp:localhost:3333", // Connect to OpenOCD's gdb-server
        "load ./fsbl/build/fsbl.elf", // Flash fsbl.elf to target
        "file ./fsbl/build/fsbl.elf", // Load symbols from fsbl.elf
        "b main", // Set a breakpoint at the start of main()
        "j _start" // Jump to _start, the beginning of the crt0
      ]
    }
  ]
}

// tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "type": "shell", // Run a command
      "command": "make", // Run make
      "problemMatcher": []
    }
  ]
}

U-Boot 2020.04 (Jul 03 2020 - 20:11:15 +0200)

CPU: STM32MP157CAC Rev.B
Model: STMicroelectronics STM32MP157C-DK2 Discovery Board
Board: stm32mp1 in basic mode (st,stm32mp157c-dk2)
Board: MB1272 Var2 Rev.C-01
DRAM:  512 MiB
Clocks:
- MPU : 650 MHz
- MCU : 208.878 MHz
- AXI : 266.500 MHz
- PER : 24 MHz
- DDR : 533 MHz
NAND:  0 MiB
MMC:   STM32 SDMMC2: 0
Loading Environment from EXT4... OK
In:    serial
Out:   serial
Err:   serial
****************************************************
*       WARNING 1.5mA power supply detected        *
*     Current too low, use a 3A power supply!      *
****************************************************

Net:   eth0: ethernet@5800a000
Hit any key to stop autoboot:  0
Boot over mmc0!
switch to partitions #0, OK
mmc0 is current device
Scanning mmc 0:4...
Found /boot/extlinux/extlinux.conf
Retrieving file: /boot/extlinux/extlinux.conf
131 bytes read in 22 ms (4.9 KiB/s)
1:      stm32mp157c-dk2-buildroot
Retrieving file: /boot/zImage
4171640 bytes read in 202 ms (19.7 MiB/s)
append: root=/dev/mmcblk0p4 rootwait
Retrieving file: /boot/stm32mp157c-dk2.dtb
49532 bytes read in 24 ms (2 MiB/s)
## Flattened Device Tree blob at c4000000
   Booting using the fdt blob at 0xc4000000
   Loading Device Tree to cfff0000, end cffff17b ... OK

Starting kernel ...

[    0.000000] Booting Linux on physical CPU 0x0
[    0.000000] Linux version 5.7.1 (werwolv@werwolv-vmwarevirtualplatform) (gcc version 10.1.0 (Buildroot 2020.08-git-00490-gf50086e59f), GNU ld (GNU Binutils) 2.33.1) #1 SMP PREEMPT Fri Jul 3 18:44:10 CEST 2020
[    0.000000] CPU: ARMv7 Processor [410fc075] revision 5 (ARMv7), cr=10c5387d
[    0.000000] CPU: div instructions available: patching division code
[    0.000000] CPU: PIPT / VIPT nonaliasing data cache, VIPT aliasing instruction cache
[    0.000000] OF: fdt: Machine model: STMicroelectronics STM32MP157C-DK2 Discovery Board
[    0.000000] Memory policy: Data cache writealloc
[    0.000000] Reserved memory: created DMA memory pool at 0x10000000, size 0 MiB
[    0.000000] OF: reserved mem: initialized node mcuram2@10000000, compatible id shared-dma-pool
[    0.000000] Reserved memory: created DMA memory pool at 0x10040000, size 0 MiB
[    0.000000] OF: reserved mem: initialized node vdev0vring0@10040000, compatible id shared-dma-pool
[    0.000000] Reserved memory: created DMA memory pool at 0x10041000, size 0 MiB
[    0.000000] OF: reserved mem: initialized node vdev0vring1@10041000, compatible id shared-dma-pool
[    0.000000] Reserved memory: created DMA memory pool at 0x10042000, size 0 MiB
[    0.000000] OF: reserved mem: initialized node vdev0buffer@10042000, compatible id shared-dma-pool
[    0.000000] Reserved memory: created DMA memory pool at 0x30000000, size 0 MiB
[    0.000000] OF: reserved mem: initialized node mcuram@30000000, compatible id shared-dma-pool
[    0.000000] Reserved memory: created DMA memory pool at 0x38000000, size 0 MiB
[    0.000000] OF: reserved mem: initialized node retram@38000000, compatible id shared-dma-pool
[    0.000000] cma: Reserved 128 MiB at 0xd8000000
[    0.000000] psci: probing for conduit method from DT.
[    0.000000] psci: PSCIv1.0 detected in firmware.
[    0.000000] psci: Using standard PSCI v0.2 function IDs
[    0.000000] psci: Trusted OS migration not required
[    0.000000] psci: SMC Calling Convention v1.0
[    0.000000] percpu: Embedded 15 pages/cpu s30028 r8192 d23220 u61440
[    0.000000] Built 1 zonelists, mobility grouping on.  Total pages: 113664
[    0.000000] Kernel command line: root=/dev/mmcblk0p4 rootwait
[    0.000000] Dentry cache hash table entries: 65536 (order: 6, 262144 bytes, linear)
[    0.000000] Inode-cache hash table entries: 32768 (order: 5, 131072 bytes, linear)
[    0.000000] mem auto-init: stack:off, heap alloc:off, heap free:off
[    0.000000] Memory: 313508K/458752K available (6144K kernel code, 188K rwdata, 1540K rodata, 1024K init, 171K bss, 14172K reserved, 131072K cma-reserved, 0K highmem)
[    0.000000] SLUB: HWalign=64, Order=0-3, MinObjects=0, CPUs=2, Nodes=1
[    0.000000] rcu: Preemptible hierarchical RCU implementation.
[    0.000000] rcu:     RCU restricting CPUs from NR_CPUS=4 to nr_cpu_ids=2.
[    0.000000]  Tasks RCU enabled.
[    0.000000] rcu: RCU calculated value of scheduler-enlistment delay is 10 jiffies.
[    0.000000] rcu: Adjusting geometry for rcu_fanout_leaf=16, nr_cpu_ids=2
[    0.000000] NR_IRQS: 16, nr_irqs: 16, preallocated irqs: 16
[    0.000000] random: get_random_bytes called from start_kernel+0x320/0x4b0 with crng_init=0
[    0.000000] arch_timer: cp15 timer(s) running at 24.00MHz (virt).
[    0.000000] clocksource: arch_sys_counter: mask: 0xffffffffffffff max_cycles: 0x588fe9dc0, max_idle_ns: 440795202592 ns
[    0.000008] sched_clock: 56 bits at 24MHz, resolution 41ns, wraps every 4398046511097ns
[    0.000024] Switching to timer-based delay loop, resolution 41ns
[    0.000806] Console: colour dummy device 80x30
[    0.001850] printk: console [tty0] enabled
[    0.001905] Calibrating delay loop (skipped), value calculated using timer frequency.. 48.00 BogoMIPS (lpj=240000)
[    0.001954] pid_max: default: 32768 minimum: 301
[    0.002157] Mount-cache hash table entries: 1024 (order: 0, 4096 bytes, linear)
[    0.002202] Mountpoint-cache hash table entries: 1024 (order: 0, 4096 bytes, linear)
[    0.003023] CPU: Testing write buffer coherency: ok
[    0.003373] CPU0: update cpu_capacity 1024
[    0.003412] CPU0: thread -1, cpu 0, socket 0, mpidr 80000000
[    0.004120] Setting up static identity map for 0xc0100000 - 0xc0100060
[    0.004303] rcu: Hierarchical SRCU implementation.
[    0.004743] smp: Bringing up secondary CPUs ...
[    0.005409] CPU1: update cpu_capacity 1024
[    0.005420] CPU1: thread -1, cpu 1, socket 0, mpidr 80000001
[    0.005587] smp: Brought up 1 node, 2 CPUs
[    0.005663] SMP: Total of 2 processors activated (96.00 BogoMIPS).
[    0.005689] CPU: All CPU(s) started in SVC mode.
[    0.006297] devtmpfs: initialized
[    0.022241] VFP support v0.3: implementor 41 architecture 2 part 30 variant 7 rev 5
[    0.022755] clocksource: jiffies: mask: 0xffffffff max_cycles: 0xffffffff, max_idle_ns: 19112604462750000 ns
[    0.022825] futex hash table entries: 512 (order: 3, 32768 bytes, linear)
[    0.028600] pinctrl core: initialized pinctrl subsystem
[    0.029641] NET: Registered protocol family 16
[    0.032494] DMA: preallocated 256 KiB pool for atomic coherent allocations
[    0.039443] /soc/interrupt-controller@5000d000: bank0
[    0.039494] /soc/interrupt-controller@5000d000: bank1
[    0.039524] /soc/interrupt-controller@5000d000: bank2
[    0.043618] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOA bank added
[    0.044033] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOB bank added
[    0.044387] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOC bank added
[    0.044727] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOD bank added
[    0.045067] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOE bank added
[    0.045391] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOF bank added
[    0.045727] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOG bank added
[    0.046052] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOH bank added
[    0.046403] stm32mp157-pinctrl soc:pin-controller@50002000: GPIOI bank added
[    0.046513] stm32mp157-pinctrl soc:pin-controller@50002000: Pinctrl STM32 initialized
[    0.047280] stm32mp157-pinctrl soc:pin-controller-z@54004000: GPIOZ bank added
[    0.047335] stm32mp157-pinctrl soc:pin-controller-z@54004000: Pinctrl STM32 initialized
[    0.058799] usbcore: registered new interface driver usbfs
[    0.058906] usbcore: registered new interface driver hub
[    0.059026] usbcore: registered new device driver usb
[    0.059281] pps_core: LinuxPPS API ver. 1 registered
[    0.059310] pps_core: Software ver. 5.3.6 - Copyright 2005-2007 Rodolfo Giometti <giometti@linux.it>
[    0.059368] PTP clock support registered
[    0.059683] Advanced Linux Sound Architecture Driver Initialized.
[    0.060887] clocksource: Switched to clocksource arch_sys_counter
[    0.071787] NET: Registered protocol family 2
[    0.072549] tcp_listen_portaddr_hash hash table entries: 512 (order: 0, 6144 bytes, linear)
[    0.072626] TCP established hash table entries: 4096 (order: 2, 16384 bytes, linear)
[    0.072718] TCP bind hash table entries: 4096 (order: 3, 32768 bytes, linear)
[    0.072833] TCP: Hash tables configured (established 4096 bind 4096)
[    0.072991] UDP hash table entries: 256 (order: 1, 8192 bytes, linear)
[    0.073057] UDP-Lite hash table entries: 256 (order: 1, 8192 bytes, linear)
[    0.073306] NET: Registered protocol family 1
[    0.074665] workingset: timestamp_bits=30 max_order=17 bucket_order=0
[    0.083817] Block layer SCSI generic (bsg) driver version 0.4 loaded (major 248)
[    0.083875] io scheduler mq-deadline registered
[    0.083900] io scheduler kyber registered
[    0.153081] STM32 USART driver initialized
[    0.153532] stm32-usart 40010000.serial: IRQ index 1 not found
[    0.153638] 40010000.serial: ttySTM0 at MMIO 0x40010000 (irq = 21, base_baud = 4000000) is a stm32-usart
[    0.853240] printk: console [ttySTM0] enabled
[    0.858169] stm32-usart 40010000.serial: rx dma alloc failed
[    0.863329] stm32-usart 40010000.serial: interrupt mode used for rx (no dma)
[    0.870383] stm32-usart 40010000.serial: tx dma alloc failed
[    0.876091] stm32-usart 40010000.serial: interrupt mode used for tx (no dma)
[    0.906704] random: fast init done
[    0.908119] brd: module loaded
[    0.912034] random: crng init done
[    0.922703] loop: module loaded
[    0.925951] libphy: Fixed MDIO Bus: probed
[    0.928672] CAN device driver interface
[    0.933588] stm32-dwmac 5800a000.ethernet: IRQ eth_wake_irq not found
[    0.938970] stm32-dwmac 5800a000.ethernet: IRQ eth_lpi not found
[    0.945195] stm32-dwmac 5800a000.ethernet: PTP uses main clock
[    0.950903] stm32-dwmac 5800a000.ethernet: no reset control found
[    0.960987] stm32-dwmac 5800a000.ethernet: User ID: 0x40, Synopsys ID: 0x42
[    0.966577] stm32-dwmac 5800a000.ethernet:   DWMAC4/5
[    0.971617] stm32-dwmac 5800a000.ethernet: DMA HW capability register supported
[    0.978910] stm32-dwmac 5800a000.ethernet: RX Checksum Offload Engine supported
[    0.986294] stm32-dwmac 5800a000.ethernet: TX Checksum insertion supported
[    0.993201] stm32-dwmac 5800a000.ethernet: Wake-Up On Lan supported
[    0.999541] stm32-dwmac 5800a000.ethernet: TSO supported
[    1.004858] stm32-dwmac 5800a000.ethernet: Enable RX Mitigation via HW Watchdog Timer
[    1.012753] stm32-dwmac 5800a000.ethernet: Enabled Flow TC (entries=2)
[    1.019296] stm32-dwmac 5800a000.ethernet: TSO feature enabled
[    1.025188] stm32-dwmac 5800a000.ethernet: Using 32 bits DMA width
[    1.032121] libphy: stmmac: probed
[    1.037644] ehci_hcd: USB 2.0 'Enhanced' Host Controller (EHCI) Driver
[    1.042821] ehci-platform: EHCI generic platform driver
[    1.048394] ohci_hcd: USB 1.1 'Open' Host Controller (OHCI) Driver
[    1.054322] ohci-platform: OHCI generic platform driver
[    1.061849] stm32_rtc 5c004000.rtc: IRQ index 1 not found
[    1.065839] stm32_rtc 5c004000.rtc: alarm can't wake up the system: -6
[    1.073068] stm32_rtc 5c004000.rtc: registered as rtc0
[    1.077625] stm32_rtc 5c004000.rtc: setting system clock to 2000-01-01T00:00:22 UTC (946684822)
[    1.086648] stm32_rtc 5c004000.rtc: Date/Time must be initialized
[    1.092543] stm32_rtc 5c004000.rtc: registered rev:1.2
[    1.097792] i2c /dev entries driver
[    1.121614] stm32f7-i2c 40012000.i2c: can't use DMA
[    1.129085] i2c i2c-0: Added multiplexed i2c bus 1
[    1.133191] edt_ft5x06 0-0038: supply vcc not found, using dummy regulator
[    1.145478] input: generic ft5x06 (11) as /devices/platform/soc/40012000.i2c/i2c-0/0-0038/input/input0
[    1.153880] stm32f7-i2c 40012000.i2c: STM32F7 I2C-0 bus adapter
[    1.182290] stm32f7-i2c 5c002000.i2c: can't use DMA
[    1.186728] stpmic1 2-0033: PMIC Chip Version: 0x10
[    1.192618] BUCK1: supplied by regulator-dummy
[    1.198691] BUCK2: supplied by regulator-dummy
[    1.204581] BUCK3: supplied by regulator-dummy
[    1.210553] BUCK4: supplied by regulator-dummy
[    1.216397] LDO1: supplied by v3v3
[    1.221977] LDO2: supplied by regulator-dummy
[    1.227973] LDO3: supplied by vdd_ddr
[    1.233149] LDO4: supplied by regulator-dummy
[    1.236660] LDO5: supplied by regulator-dummy
[    1.243498] LDO6: supplied by v3v3
[    1.248521] VREF_DDR: supplied by regulator-dummy
[    1.254543] BOOST: supplied by regulator-dummy
[    1.258117] VBUS_OTG: supplied by bst_out
[    1.262218] SW_OUT: supplied by bst_out
[    1.267892] input: pmic_onkey as /devices/platform/soc/5c002000.i2c/i2c-2/2-0033/5c002000.i2c:stpmic@33:onkey/input/input1
[    1.278222] stm32f7-i2c 5c002000.i2c: STM32F7 I2C-2 bus adapter
[    1.286594] mmci-pl18x 58005000.sdmmc: Got CD GPIO
[    1.290542] mmci-pl18x 58005000.sdmmc: mmc0: PL180 manf 53 rev1 at 0x58005000 irq 46,0 (pio)
[    1.325558] sdhci: Secure Digital Host Controller Interface driver
[    1.330375] sdhci: Copyright(c) Pierre Ossman
[    1.335820] Synopsys Designware Multimedia Card Interface Driver
[    1.341056] sdhci-pltfm: SDHCI platform and OF driver helper
[    1.348863] usbcore: registered new interface driver usbhid
[    1.353093] usbhid: USB HID core driver
[    1.357656] stm32-ipcc 4c001000.mailbox: ipcc rev:1.0 enabled, 6 chans, proc 0
[    1.364638] OF: Can't handle multiple dma-ranges with different offsets on node(/ahb)
[    1.373179] OF: Can't handle multiple dma-ranges with different offsets on node(/ahb)
[    1.380360] stm32-rproc 10000000.m4: wdg irq registered
[    1.385339] stm32-rproc 10000000.m4: failed to get pdds
[    1.390643] remoteproc remoteproc0: m4 is available
[    1.398481] NET: Registered protocol family 10
[    1.402931] Segment Routing with IPv6
[    1.405275] sit: IPv6, IPv4 and MPLS over IPv4 tunneling driver
[    1.412137] NET: Registered protocol family 17
[    1.415651] can: controller area network core (rev 20170425 abi 9)
[    1.422004] NET: Registered protocol family 29
[    1.426323] can: raw protocol (rev 20170425)
[    1.430606] can: broadcast manager protocol (rev 20170425 t)
[    1.436392] can: netlink gateway (rev 20190810) max_hops=1
[    1.442153] ThumbEE CPU extension supported.
[    1.446136] Registering SWP/SWPB emulation handler
[    1.452705] stm32-dma 48000000.dma-controller: STM32 DMA driver registered
[    1.459654] stm32-dma 48001000.dma-controller: STM32 DMA driver registered
[    1.466288] mmc0: new high speed SDHC card at address 0007
[    1.468382] stm32-mdma 58000000.dma-controller: STM32 MDMA driver registered
[    1.478263] mmcblk0: mmc0:0007 SD8GB 7.42 GiB
[    1.478435] reg11: supplied by vdd
[    1.485844] reg18: supplied by vdd
[    1.489331] stm32-usbphyc 5a006000.usbphyc: registered rev:1.0
[    1.500002] [drm] Supports vblank timestamp caching Rev 2 (21.10.2013).
[    1.506266] [drm] Initialized stm 1.0.0 20170330 for 5a001000.display-controller on minor 0
[    1.514711] GPT:Primary header thinks Alt. header is not at the end of the disk.
[    1.521174] GPT:247694 != 15564799
[    1.524492] GPT:Alternate GPT header not at the end of the disk.
[    1.530542] GPT:247694 != 15564799
[    1.533981] GPT: Use GNU Parted to correct GPT errors.
[    1.539199]  mmcblk0: p1 p2 p3 p4
[    1.993335] Console: switching to colour frame buffer device 60x50
[    2.018194] stm32-display 5a001000.display-controller: fb0: stmdrmfb frame buffer device
[    2.026848] dwc2 49000000.usb-otg: supply vusb_d not found, using dummy regulator
[    2.034054] dwc2 49000000.usb-otg: supply vusb_a not found, using dummy regulator
[    2.042060] dwc2 49000000.usb-otg: Configuration mismatch. dr_mode forced to host
[    2.055120] usb33: supplied by vdd_usb
[    2.058079] dwc2 49000000.usb-otg: DWC OTG Controller
[    2.062719] dwc2 49000000.usb-otg: new USB bus registered, assigned bus number 1
[    2.070208] dwc2 49000000.usb-otg: irq 42, io mem 0x49000000
[    2.076920] hub 1-0:1.0: USB hub found
[    2.079557] hub 1-0:1.0: 1 port detected
[    2.084452] ehci-platform 5800d000.usbh-ehci: EHCI Host Controller
[    2.089839] ehci-platform 5800d000.usbh-ehci: new USB bus registered, assigned bus number 2
[    2.105114] ehci-platform 5800d000.usbh-ehci: irq 48, io mem 0x5800d000
[    2.140919] ehci-platform 5800d000.usbh-ehci: USB 2.0 started, EHCI 1.00
[    2.154036] hub 2-0:1.0: USB hub found
[    2.159806] hub 2-0:1.0: 2 ports detected
[    2.167463] ALSA device list:
[    2.172483]   No soundcards found.
[    2.182411] EXT4-fs (mmcblk0p4): INFO: recovery required on readonly filesystem
[    2.195322] EXT4-fs (mmcblk0p4): write access will be enabled during recovery
[    2.496866] EXT4-fs (mmcblk0p4): recovery complete
[    2.508272] EXT4-fs (mmcblk0p4): mounted filesystem with ordered data mode. Opts: (null)
[    2.522013] VFS: Mounted root (ext4 filesystem) readonly on device 179:4.
[    2.534466] usb 2-1: new high-speed USB device number 2 using ehci-platform
[    2.548092] devtmpfs: mounted
[    2.555314] Freeing unused kernel memory: 1024K
[    2.562151] Run /sbin/init as init process
[    2.691199] EXT4-fs (mmcblk0p4): re-mounted. Opts: (null)
[    2.742529] hub 2-1:1.0: USB hub found
[    2.748854] hub 2-1:1.0: 4 ports detected

import Figure from ’@/Figure’;

The GCW0 as well as the RG350 are small handheld retro emulation and homebrew devices running the OpenDingux operating system. Although the RG350 was released 6 years after the GCW0, they both use the exact same Ingenic JZ4770 SoC. This post focuses on how the RG350’s system image is structured, how the JZ4770 loads data from it and how it ultimately jumps to the OpenDingux Linux kernel.

The layout of the system image looks as follows:

When the JZ4770 is powered up, it first start executing it’s Boot ROM. The Boot ROM reads the boot select pins and determines on the RG350 that it’s supposed to boot from an MMC device, here an SD card.

The Boot ROM proceeds by copying the first 0x2000 bytes on the SD card into the SoCs dcache and deinitializing the MMC interface again. To validate if the read data is correct, the Boot ROM skips past the MBR, right to the first stage bootloader, and checks for the magic value MSPL. If valid, the 0x2000 bytes previously loaded into dcache are copied into icache where the Boot ROM jumps into. This is possible due to the unique fact that the JZ4770s cache is mapped into the address space at address 0x8000'0000.

The data found in the icache now is the MBR immediately followed by the first stage bootloader and the Program Counter now points to address 0x8000'0000. This is the start of the MBR which looks as follows in memory.

import NotePanel from ’@/NotePanel’ import Steps from ’@/Steps’ import Figure from ’@/Figure’

I started this project mainly because I wanted a proper XP tracker I didn’t have to pay extra for since the price felt really unjustifiable to me.

This page aims to explain how I used Visual C++ to write a DLL injector tool for RuneScape’s new NXT Client as well as a DLL that hooks into RuneScape’s OpenGL draw calls to render a full Dear ImGui overlay on top of it.

std::uint32_t pid = 0;

// Loop infinitely till RuneScape is launched
while (pid == 0) {
    pid = getPID(L"rs2client.exe");
    Sleep(1000);
}

#include <Windows.h>
#include <TlHelp32.h>
#include <cstdint>
#include <string>

std::uint32_t getPID(const std::wstring &processName) {
    std:uint32_t pid = 0;

    // Create snapshot
    HANDLE hSnap = CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0);

    // Check if the snapshot is valid, otherwise bail out
    if (hSnap == INVALID_HANDLE_VALUE)
        return 0;

    PROCESSENTRY32 procEntry{};
    procEntry.dwSize = sizeof(PROCESSENTRY32);

    // Iterate over all processes in the snapshot
    if (Process32First(hSnap, &procEntry)) {
        do {
            // Check if current process name is the same
            // as the passed in process name
            if (_wcsicmp(procEntry.szExeFile, processName.c_str()) == 0) {
                pid = procEntry.th32ProcessID;
                break;
            }
        } while (Process32Next(hSnap, &procEntry));
    }

    // Cleanup
    CloseHandle(hSnap);

    return pid;
}

HANDLE hProc = OpenProcess(PROCESS_ALL_ACCESS, FALSE, pid);

// Allocate memory in the remote process
void *injectDllPathRemote = VirtualAllocEx(hProc, 0x00,
    MAX_PATH, MEM_COMMIT | MEM_RESERVE, PAGE_READWRITE);

// If allocation failed, bail out
if (injectDllPathRemote == nullptr)
    return 1;

// Write DLL path to the memory we just allocated
constexpr auto DllPath = "C:\\path\\to\\inject.dll";
WriteProcessMemory(hProc, injectDllPathRemote, DllPath, strlen(DllPath) + 1, 0);

// Create a thread in the RuneScape process which
// runs LoadLibraryA("C:\\path\\to\\inject.dll")
HANDLE hRemoteThread = CreateRemoteThread(hProc, nullptr, 0,
    (LPTHREAD_START_ROUTINE)LoadLibraryA, injectDllPathRemote, 0, nullptr);

// Check if we succeeded
if (hRemoteThread != nullptr && hRemoteThread != INVALID_HANDLE_VALUE)
    CloseHandle(hRemoteThread);
else
    printf("[*] Error starting thread! Error Code: %x\n", GetLastError());

BOOL APIENTRY DllMain(HMODULE hModule, DWORD ul_reason_for_call, LPVOID lpReserved) {
    switch (ul_reason_for_call) {
    case DLL_PROCESS_ATTACH: {
        HANDLE hThread = CreateThread(nullptr, 0,
            (LPTHREAD_START_ROUTINE)patcherThread, hModule, 0, 0);
        if (hThread != nullptr)
            CloseHandle(hThread);
        break;
    }
    case DLL_THREAD_ATTACH:
    case DLL_THREAD_DETACH:
    case DLL_PROCESS_DETACH:
        break;
    }

    return TRUE;
}

AllocConsole();                             // Open a new console window
FILE *f = new FILE();
freopen_s(&f, "CONOUT$", "w", stdout);      // Redirect stdout to CONOUT$, the
                                            // current console window.

printf("[*] Running under RuneScape!\n");   // Console works!

PUBLIC wglSwapBuffersTrampoline

wglSwapBuffersTrampoline PROC
	mov [rsp + 20], rsi         ; Execute the instruction that
                                ; was overwritten by our hook patch.

	push rax                    ; Save the current context.
	push rbx                    ; Pushing all the registers is probably
	push rcx                    ; overkill but better safe than sorry.
	push rdx
	push rsi
	push rdi
	push rbp
	push rsp
	push r8
	push r9
	push r10
	push r11
	push r12
	push r13
	push r14
	push r15

	call wglSwapBuffers_hook;    ; Call our hook

	pop r15                     ; Restore the context in reverse order
	pop r14                     ; as a Stack is a FILO buffer (First in last out)
	pop r13
	pop r12
	pop r11
	pop r10
	pop r9
	pop r8
	pop rsp
	pop rbp
	pop rdi
	pop rsi
	pop rdx
	pop rcx
	pop rbx
	pop rax

	jmp wglSwapBuffers_return   ; Jump back to the original function.
                                ; This is the address of where our jmp
                                ; instruction was inserted + 5, so immediately
                                ; after it.

wglSwapBuffersTrampoline ENDP

namespace mem {

    template<typename T>
    T read(DWORD64 addr) {
        return *((T *)addr);
    }

    template<typename T>
    void write(DWORD64 addr, T value) {
        *((T *)addr) = value;
    }

    template<typename T>
    DWORD64 protect(DWORD64 addr, DWORD protection) {
        DWORD oldProtection;
        VirtualProtect((LPVOID)addr, sizeof(T), protection, &oldProtection);

        return oldProtection;
    }

    DWORD64 hookFunction(DWORD64 hookAt, DWORD64 newFunc, unsigned int size) {
        // -5 since the jump is relative to the next instruction
        DWORD64 newOffset = newFunc - hookAt - 5;

        auto oldProtection = mem::protect<DWORD[3]>(hookAt + 1, PAGE_EXECUTE_READWRITE);

        // Opcode of the jmp instruction
        mem::write<BYTE>(hookAt, 0xE9);
        mem::write<DWORD>(hookAt + 1, newOffset);

        // nop extra bytes to avoid corrupting the overwritten opcode
        for (unsigned int i = 5; i < size; i++)
            mem::write<BYTE>(hookAt + i, 0x90);

        mem::protect<DWORD[3]>(hookAt + 1, oldProtection);

        return hookAt + 5;
    }
}

using wglSwapBuffers_t = void(*)(_In_ HDC hDc);
extern "C" wglSwapBuffers_t wglSwapBuffers_return = nullptr;
extern "C" void wglSwapBuffersTrampoline();

// ...

// Get a handle to the opengl32.dll
HMODULE hOpengl32 = GetModuleHandle(L"opengl32.dll");

if (hOpengl32 != nullptr) {
    // Get the address of wglSwapBuffers
    DWORD64 wglSwapBuffersHookAddr = (DWORD64)GetProcAddress(
        hOpengl32,
        "wglSwapBuffers"
    );

    // Insert a hook to our trampoline at the start of wglSwapBuffers,
    // returns the address to return to
    wglSwapBuffers_return = (glSwapBuffers_t) mem::hookFunction(
        wglSwapBuffersHookAddr, 
        (DWORD64)wglSwapBuffersTrampoline, 
        5
    );
}

HWND hGameWindow;
WNDPROC hGameWindowProc;
bool menuShown = true;

LRESULT CALLBACK windowProc_hook(HWND hWnd, UINT uMsg, WPARAM wParam, LPARAM lParam) {
    // Toggle the overlay using the delete key
    if (uMsg == WM_KEYDOWN && wParam == VK_DELETE) {
        menuShown = !menuShown;
        return false;
    }

    // If the overlay is shown, direct input to the overlay only
    if (menuShown) {
        CallWindowProc(ImGui_ImplWin32_WndProcHandler, hWnd, uMsg, wParam, lParam);
        return true;
    }

    // Otherwise call the game's wndProc function
    return CallWindowProc(hGameWindowProc, hWnd, uMsg, wParam, lParam);
}

void glSwapBuffers_hook(HDC hDc) {
    // Initialize GLEW and ImGui but only once
    static bool imGuiInitialized = false;
    if (!imGuiInitialized) {
        imGuiInitialized = true;

        // Get the game's window from it's handle
        hGameWindow = WindowFromDC(hDc);

        // Overwrite the game's wndProc function
        hGameWindowProc = (WNDPROC)SetWindowLongPtr(hGameWindow,
            GWLP_WNDPROC, (LONG_PTR)windowProc_hook);

        // Init GLEW, create ImGui context, init ImGui
        glewInit();
        ImGui::CreateContext();
        ImGui_ImplWin32_Init(hGameWindow);
        ImGui_ImplOpenGL3_Init();
        ImGui::StyleColorsDark();
        ImGui::GetStyle().AntiAliasedFill = false;
        ImGui::GetStyle().AntiAliasedLines = false;
        ImGui::CaptureMouseFromApp();
        ImGui::GetStyle().WindowTitleAlign = ImVec2(0.5f, 0.5f);
    }

    // If the menu is shown, start a new frame and draw the demo window
    if (menuShown) {
        ImGui_ImplOpenGL3_NewFrame();
        ImGui_ImplWin32_NewFrame();
        ImGui::NewFrame();
        ImGui::ShowDemoWindow();
        ImGui::Render();

        // Draw the overlay
        ImGui_ImplOpenGL3_RenderDrawData(ImGui::GetDrawData());
    }
}