3. Tutorial

This chapter shows how to build and run a simple “Hello World” application on different targets.

The command line examples offer a clear understanding of the process. Tools can also be used with an IDE, but setup varies.

Beyond the Calypsi C compiler tool chain, you will need Make to control builds and Git to obtain projects. An internet connection is also required to download example projects.

3.1. Simulator

The db68k contains a simulator mode which is enabled by default. It mimics the 68000 architecture and allows the application to run on your host machine.

From a terminal or command line, copy the example project from the internet using:

$ git clone https://github.com/hth313/Calypsi-m68k-hello-world.git

Change to the newly cloned project directory:

$ cd Calypsi-m68k-hello-world

Build the project with:

$ make
cc68k --core=68000 --code-model=large --data-model=small --debug --list-file=obj/main-debug.lst -o obj/main-debug.o src/main.c
ln68k --debug -o hello.elf obj/main-debug.o module/Calypsi-m68k-Foenix/linker-files/a2560u-simplified.scm clib-68000-lc-sd.a --list-file=hello-debug.lst --cross-reference --rtattr printf=reduced --semi-hosted --target=Foenix --stack-size=2000 --sstack-size=800

This will create an output file hello.elf. To run the application you can load it into the debugger using:

$ db68k hello.elf
Calypsi debugger for 68000
(db68k)

By default, the debugger enters interactive command mode. Run the application using the run command:

(db68k) run
running
Hello World!
program exited normally
(db68k)

When you are done with the debugger, you can leave it using the quit command:

(db68k) quit
$

You can also run the program directly from the command prompt, without entering interactive mode. You need to provide the debugger with additional command-line options to run and terminate automatically:

$ db68k hello.elf -e run --terminate-on-program-exit
Calypsi debugger for 68000
run
running
Hello World!
program exited normally
$

This tells the debugger to execute the command run and that termination of the application also means termination of the debugger.

3.2. Amiga

This section describes how to build a “Hello World” application for the Amiga.

For the Amiga we need to generate Hunk output and the output can either be executed on an emulator such as FS-UAE or WinUAE.

First you need to Git clone the Amiga Hello World example, you can do so using:

$ git clone https://github.com/hth313/Calypsi-Amiga-hello-world

Change directory to the just cloned project and build the project:

$ cd Calypsi-Amiga-hello-world
$ make

This will generate an hello.hunk output file. You need to copy this file to your emulator. Consult the documentation of the emulator you are using. For the FS-UAE it will probably use a directory on the host computer as the Amiga hard drive, copy hello.hunk to a suitable location on it and start the emulator. You may want to rename the file to be without .hunk while doing the copy.

Start the emulator, open a shell and run the program. It should print “Hello World!” and then exit:

3.3. A2560 Foenix

This section shows how to build the “Hello World” application for a A2560 Foenix and run it on hardware.

This means you need to have access the actual hardware, but it is possible to use an A2560 emulator as well, such as Morfe.

The the Calypsi C compiler tool chain generates ELF/DWARF by default, but you may prefer to use the native PGZ format instead. It is also possible to load an Intel-hex file over the debug port on the A2560. The provided Makefile already has a target to build a PGZ executable.

If you have not previously cloned the project, you can do so using:

$ git clone https://github.com/hth313/Calypsi-m68k-hello-world.git

Change directory to the just cloned project:

$ cd Calypsi-m68k-hello-world

When you are standing in the project folder, you can build the application for the A2560 Foenix using:

$ make hello.pgz

This will result in a program file hello.pgz. In order to run it you need to put it on the removable SD card storage media you have with your A2560 Foenix.

Once you have the hardware or emulator set up you can load and run the hello.pgz by typing the filename at the prompt.

Downloading an executable to a real A2560 can also be done using the USB debug port and the C256 Manager tool. In this case you will need to generate an S-record output file.

3.4. The Morfe emulator

It is also possible to download the program into Morfe, the emulator. Currently this need to be done by a Intel-hex file which can be generated using:

$ make hello.hex

The Morfe emulator can be found at https://github.com/aniou/morfe and need to be built according to instructions found there. Morfe can be launched emulating the A2560 K:

$ ./morfe-m68k conf/a2560k.ini

Once started, hit function key 9 to enter its TUI environment. Here you can load the Intel-hex file using load hex hello.hex. Then you may need to set the PC register manually using set pc. In this case you may need to look up the address in the generated hello-Foenix.lst file and look for the address of __program_start in it.

Once entered, you can press quit to resume the emulator at the start of the program. The result should be: