How to Write and Build Programs

This guide explains how to write, compile, and build programs for rosco_m68k in a bare-metal environment.

This page assumes that you already have a working toolchain installed. A separate guide covers toolchain installation and setup.

Prerequisites

Before you start, make sure you have:

Installed the m68k toolchain
SD card formatted as FAT32

Toolchain setup guide

Execution Environment

Programs for rosco_m68k run in a bare-metal environment. This means:

No operating system by default
Direct access to hardware
Program execution starts at kmain

It is possible to run an operating system (for example, one targeting Motorola 68010), but this guide focuses only on bare-metal development.

Supported Languages

rosco_m68k supports development in:

Assembly (vasm)
C

For C programs, the project provides an adapted standard library suitable for bare-metal environments.

Examples:

printf() outputs text to the serial (UART) console
No host OS is required

For Assembly, there is also an adapted library with similar functions.

Quick Start

The easiest way to get started is to download our starter template:

Download starter template: rosco_start.zip

This archive contains:

rosco_start/
├── starter_c/          # C project template
│   ├── kmain.c         # Example C program
│   ├── Makefile
│   └── libs/           # Standard libraries (need to be built)
│
└── starter_asm/        # Assembly project template
    ├── kmain.asm       # Example Assembly program
    ├── Makefile
    └── libs/           # Standard libraries (need to be built)

Getting Started Steps:

Download and extract the archive
Build the standard libraries first:

   cd rosco_start/starter_c/libs/    # or starter_asm/libs/
   make install
   cd ..

Choose your language:
- For C: navigate to starter_c/
- For Assembly: navigate to starter_asm/
Build your program:

   make clean all

Deploy to SD card:
- Copy the generated .bin file to your FAT32-formatted SD card
- Rename it to ROSCODE1.bin
- Insert the SD card into your ROSCO M68K
- Power on and connect via UART to see the output

Important: You must compile the standard libraries with make install before building your first program. This step only needs to be done once.

Project Structure

Both C and Assembly skeletons follow the same minimal structure:

project/
├── kmain.c          # or kmain.asm (your main program)
├── Makefile         # Build configuration
└── libs/            # rosco_m68k standard libraries

Key Files:

kmain.c / kmain.asm — Your program's entry point. Execution starts here.
Makefile — Defines how to compile and link your program.
libs/ — Contains the standard libraries for bare-metal development (must be compiled first).

Compiling the Standard Libraries

Before building your first program, you need to compile the standard libraries.

Navigate to the libs/ directory and run:

cd libs/
make install
cd ..

This will build all necessary library files that your programs will link against. You only need to do this once after downloading the starter template.

Writing Your Program

C Development

When writing C programs:

Use #include <stdio.h> for functions like printf()
The printf() function outputs to UART (serial console)
Your program starts at the kmain() function
Returning from kmain() will reboot the machine

Example structure:

#include <stdio.h>

void kmain() {
    // Your code here
    printf("Hello from ROSCO!\r\n");

    // Returning will cause a reboot
}

Assembly Development

When writing Assembly programs:

Use the machine library functions like mcPrintln
Always clean up the stack after function calls
Entry point is the kmain:: label
Returning from kmain will reboot the machine

Example structure:

    section .text

kmain::
    ; Your code here
    lea.l   MESSAGE,A0
    move.l  A0,-(A7)
    jsr     mcPrintln
    addq.l  #4,A7
    rts

MESSAGE:
    dc.b    "Hello from ROSCO!", 0

Building Your Program

From your project directory (either starter_c/ or starter_asm/), run:

make clean all

This will:

Clean previous build artifacts
Compile your program
Link it with the standard libraries
Generate the executable (.bin file)

Deploying to ROSCO M68K

After building your program, you need to copy it to an SD card:

Format your SD card as FAT32 (if not already formatted)
Copy the generated .bin file to the SD card
Rename it to ROSCODE1.bin — this is the filename the bootloader looks for
Insert the SD card into your ROSCO M68K
Connect via UART to see the output (38400 baud)
Power on the board

Successful Boot Example

When everything works correctly, you should see output similar to this via UART:

Makefile Overview

Both skeletons use a similar Makefile:

ROSCO_M68K_DEFAULT_DIR=./

ifndef ROSCO_M68K_DIR
$(info NOTE: ROSCO_M68K_DIR not set, using libs: ./libs)
ROSCO_M68K_DIR=$(ROSCO_M68K_DEFAULT_DIR)
else
$(info NOTE: Using ROSCO_M68K_DIR libs in: $(ROSCO_M68K_DIR))
endif

-include $(ROSCO_M68K_DIR)/code/software/software.mk

EXTRA_CFLAGS=
EXTRA_LIBS=

What it does:

Sets up the library path (ROSCO_M68K_DIR)
Includes build rules from software.mk
Allows customization via EXTRA_CFLAGS and EXTRA_LIBS

Notes and Common Pitfalls

Standard libraries must be built first — run make install in the libs/ directory before building your program
SD card must be FAT32 formatted — other filesystems won't work
Binary file must be named ROSCODE1.bin — the bootloader looks for this specific filename
Returning from kmain reboots the machine — if you want your program to keep running, use an infinite loop instead
In Assembly, always clean up the stack after function calls (e.g., addq.l #4,A7)
Make sure libraries are in libs/ — the starter template includes them
An incorrect ROSCO_M68K_DIR path will cause build errors

Advanced: Building Libraries from Source

If you need to rebuild the standard libraries or want to get the latest version:

Library sources: Available on GitHub.

Download the sources, navigate to the libs/ directory and run:

make install

This will rebuild all library files.

Cart