1. Overview — What This Example Does

The 002_HelloWorld_semihosting project prints “Hello world” to the host computer’s console via ARM semihosting. Unlike ITM/SWV (which uses a dedicated hardware trace path), semihosting uses the debug interface itself (SWD/JTAG) and requires the processor to halt to service each I/O request.

The single key difference from Example 01 is the call to initialise_monitor_handles() before printf(). This function, provided by the rdimon library, sets up the semihosting C library streams (stdin, stdout, stderr) via semihosting file-open calls.

2. Source Code — Annotated Walkthrough

#include <stdio.h>

/* Prototype for the semihosting initialisation function
 * provided by librdimon (-lrdimon linker flag) */
extern void initialise_monitor_handles(void);

int main(void)
{
    /* MUST call this before any printf() when using semihosting.
     * It opens stdin/stdout/stderr via semihosting SYS_OPEN calls.
     * Without it, the C library file descriptors point to null
     * and nothing will appear in the host console. */
    initialise_monitor_handles();

    printf("Hello world\n");

    for(;;);
}

What initialise_monitor_handles() Does

This function, from the rdimon (Remote Debug Interface Monitor) library, issues three semihosting SYS_OPEN calls — one each for stdin, stdout, and stderr. Each call generates a BKPT #0xAB instruction, halting the CPU and transferring control to OpenOCD (or any ARM debug agent), which executes the open call on the host file system and returns file handles back to the MCU’s registers.

/* Simplified pseudocode of what initialise_monitor_handles() does */
void initialise_monitor_handles(void)
{
    /* SYS_OPEN for ":tt" (stdin) — host opens keyboard input */
    __semihosting_call(SYS_OPEN, ":tt", MODE_READ);  /* returns fd=0 */

    /* SYS_OPEN for ":tt" (stdout) — host opens terminal output */
    __semihosting_call(SYS_OPEN, ":tt", MODE_WRITE); /* returns fd=1 */

    /* SYS_OPEN for ":tt" (stderr) — host opens error output */
    __semihosting_call(SYS_OPEN, ":tt", MODE_WRITE); /* returns fd=2 */
}

3. How ARM Semihosting Works

Semihosting is defined in the ARM ABI (Application Binary Interface) specification. It uses a special breakpoint instruction to signal the debug host that a system call is needed.

The BKPT #0xAB Instruction

When the processor executes BKPT #0xAB (opcode 0xBEAB in Thumb), it causes a DebugMonitor exception (or halts if a hardware debugger is connected). The magic value 0xAB is the semihosting magic number recognised by debug agents like OpenOCD, QEMU, and Arm’s Fast Models.

Register Convention for Semihosting Calls

The semihosting call sequence in assembly:

/* Generic semihosting call in ARM Thumb assembly */
semihosting_call:
    PUSH {R0, R1, R2, R3, IP, LR}
    /* R0 = operation number, R1 = parameter block pointer */
    BKPT #0xAB          /* ← This is the magic instruction */
    /* After the debug agent handles the call:
     * R0 contains the return value */
    POP  {R0, R1, R2, R3, IP, PC}

Semihosting Call Flow

Common Semihosting Operation Codes

4. Setup Requirements

Linker Flags

-specs=rdimon.specs -lc -lrdimon

Also: remove syscalls.c from the project. rdimon provides its own _write(), _read() stubs that use semihosting. Having both will cause multiple-definition linker errors.

OpenOCD Configuration

In your debug configuration (GDB script or OpenOCD startup command), add:

# In OpenOCD startup commands (Debug Configuration → Startup)
monitor arm semihosting enable

Without this command, OpenOCD will not intercept the BKPT #0xAB instruction and the MCU will HardFault.

IDE Steps (STM32CubeIDE)

1. Right-click project → Properties → C/C++ Build → Settings → Tool Settings → Linker → Miscellaneous
2. Add -specs=rdimon.specs -lc -lrdimon to “Other linker flags”
3. Remove syscalls.c from the project
4. Debug Configuration → Startup → Run Commands: add monitor arm semihosting enable
5. Run → output appears in the “Console” or “OpenOCD” view

Debug Configuration Startup Script

# Example .cfg / launch startup commands
target extended-remote localhost:3333
monitor reset halt
monitor arm semihosting enable
load
monitor reset halt
continue

5. rdimon Library — What It Provides

rdimon (Remote Debug Interface Monitor) is the semihosting C library provided by arm-none-eabi-gcc. When you link with -specs=rdimon.specs, the linker includes a full set of syscall implementations that route all I/O through BKPT #0xAB.

Writing a Manual Semihosting Call (no library)

/* Direct semihosting call — no rdimon needed */
static inline int __semihosting(int op, void *arg)
{
    int result;
    __asm volatile (
        "MOV R0, %1\n"      /* op number */
        "MOV R1, %2\n"      /* parameter block */
        "BKPT #0xAB\n"      /* trigger semihosting */
        "MOV %0, R0\n"      /* get return value */
        : "=r"(result)
        : "r"(op), "r"(arg)
        : "R0", "R1", "memory"
    );
    return result;
}

/* SYS_WRITE0: print a null-terminated string */
void sh_puts(const char *str)
{
    __semihosting(0x04, (void*)str);
}

/* Usage */
int main(void)
{
    initialise_monitor_handles();
    sh_puts("Direct semihosting: no printf\n");
    for(;;);
}

6. Semihosting vs ITM — Detailed Comparison

7. Extended Examples

Reading Input via Semihosting

#include <stdio.h>
extern void initialise_monitor_handles(void);

int main(void)
{
    initialise_monitor_handles();

    int n;
    printf("Enter a number: ");
    scanf("%d", &n);          /* reads from host keyboard via SYS_READ */
    printf("You entered: %d\n", n);

    for(;;);
}

Writing to a Host File via Semihosting

#include <stdio.h>
extern void initialise_monitor_handles(void);

int main(void)
{
    initialise_monitor_handles();

    /* fopen uses SYS_OPEN semihosting call to open a real file on the host */
    FILE *f = fopen("output.txt", "w");
    if (f)
    {
        fprintf(f, "Log entry from MCU\n");
        fclose(f);
        printf("File written on host!\n");
    }
    for(;;);
}

Semihosting Exit (Used in Testing/CI)

/* Force a clean exit via semihosting — useful for automated testing */
void semihosting_exit(int code)
{
    /* SYS_EXIT = 0x18, ADP_Stopped_ApplicationExit = 0x20026 */
    uint32_t params[2] = { 0x20026, (uint32_t)code };
    __semihosting(0x18, params);
}

8. Interview Questions & Answers

/* SYS_WRITE0 = 0x04: print null-terminated string */
void sh_print(const char *s) {
    __asm volatile (
        "MOV R0, #0x04\n"   /* operation: SYS_WRITE0 */
        "MOV R1, %0\n"      /* R1 = pointer to string */
        "BKPT #0xAB\n"      /* semihosting call */
        : : "r"(s) : "R0","R1"
    );
}