4. Getting started

This chapter provides an overview of using the compiler and its related tools.

4.1. C language

C is a widely used programming language. It is well-suited for hardware-level programming and also functions as a powerful, generic high-level language. It offers powerful abstractions over target machines, enabling efficient application development and precise control.

This implementation uses the ISO/IEC 9899:1999 standard, commonly known as C99. In this guide, it is referred to as Standard C.

Cross compiler

The compiler is a cross-compiler, running on a modern workstation but producing applications for more constrained target machines.

Supported devices

This Calypsi C compiler tool chain supports the Motorola 68000, 68010, 68020, 68030, 68040 and 68060. Additionally, some support is provided for the APOLLO 68080 core.

4.2. File extensions

The following table shows the file extensions normally used with the Calypsi C compiler tool chain.

Table 4.1 File extensions

Extension	Purpose
.c	C source
.h	C header source
.s	Assembler source
.o	ELF/DWARF object file
.a	Library (collection of object files)
.lst	List file
.scm	Linker rules
.elf	ELF/DWARF output (executable file)
.hex	Intel-hex output
.srec	Motorola S-record output
.s19	Motorola S-record output, 16-bit address records
.s28	Motorola S-record output, 24-bit address records
.s37	Motorola S-record output, 32-bit address records
.raw	Raw output
.pgz	Foenix binary format
.prg	TOS binary format
.hunk	Amiga Hunk binary format

4.3. Building applications

Applications can be built from source files and libraries. Source files, written in C or assembly language, are compiled into object files: C source files use cc68k, and assembly source files use as68k.

A library is a collection of object files produced by the nlib tool, combining them with an index into a single file. The C runtime library is provided as an example; third-party libraries are also supported.

The ln68k takes object files, libraries, and placement rules as input to construct the executable application.

Compiler

The compiler command-line interface processes a single source file to produce an object file:

$ cc68k source.c

The object file produced will have the same base name as the input but with a .o file extension.

Note

You typically need command-line options to select the CPU core, runtime models, and other settings.

Assembler

C projects do not require knowledge of assembly language. C simplifies programming and enables portability across architectures.

However, for highly specific target code, deep-level control, or critical routines, the assembler is indispensable.

The assembler command-line interface is similar to the compiler, with the main difference being the file extension:

$ as68k source.s

The produced object file has the same .o extension as the compiler.

Note

You may need to provide a --core option for the assembler to recognize the target exact machine instructions.

Linker

The linker combines object files and libraries to create an executable application.

A rules file is required by the linker to describe the memory system, including placement rules for code and data. Stack and heap sizes can also be specified in this file.

You can run the linker from the command line as:

$ ln68k myfile1.o myfile2.o rules.scm

This simplified command produces aout.elf, an ELF binary.

There are many ways to tailor the output:

• Using hex output, in either Intel HEX or Motorola S-record file format

• RAW output, which is just plain binary output of a single memory area

• Foenix program files, which are segmented binary files with start address

• Amiga Hunk relocatable format

• TOS which is the binary format used by the Atari ST platform

• The --debug option includes DWARF debugging information in the ELF executable.

The linker can produce a list file with cross-reference information, showing memory usage, placement, and why certain library contents were included.

4.4. Configuring

Tune compiler code generation using various command-line options.

The most basic settings to consider are:

• The CPU core (--core) in use. This controls the exact instruction set.

• The data model, which affects how data are placed and accessed in memory.

• The size of the double floating point type.

• Optimization settings.

Core

The Calypsi C compiler tool chain currently supports the 68000, 68020, 68030, 68040, 68060 and the APOLLO 68080 cores.

Code model

The code model controls which instruction is used to make a function call.

Data model

The data model controls where global data is located by default.

The available data models are Small, Large and Far-only. If not specified the compiler uses the Small data model by default.

All data models are capable of addressing the entire 32 bits address space. The difference between the data models is in whether register A4 is used as a base pointer.

Small

In the Small data model register A4 is used as a base pointer to a 64K area where static and global variables are allocated. This typically saves two bytes for each each instruction that access such variable directly.

You can still allocate larger objects outside this area by using the Far attribute.

Large

In the Large data model variables can be allocated anywhere in the address space and the compiler will use 32 bits absolute addressing which typically results in large code compared to the Small data model.

The base register A4 is still regarded as a base pointer, but is left unused. This is intended to allow writing library code that can be called from other applications that use A4 as its base register.

Far-Only

The Far-Only data model is similar to the Large data model, but it treats register A4 as a general purpose register that can be used as any other address register.

Table 4.2 Data models

Data model	Default pointer size	Default size limit
Small	32 bits	64K bytes
Large	32 bits	4G bytes
Far-Only	32 bits	4G bytes

Size of double

The double floating-point type uses IEEE 754 format and can be set to either 32 or 64 bits using --32bit-doubles or --64bit-doubles. It defaults to 32 bits if not specified.

The float type is always 32 bits, and the long double type is always 64 bits.

Optimization

Select the optimization level using the -O command-line option, which accepts a numeric argument of 1 or 2.

The compiler applies a number of techniques to reduce the width of expressions, select efficient code sequences and dead code elimination, regardless of optimization settings.

The -O option enables further optimization to reduce the code memory footprint and typically increase execution speed.

4.5. Low level control

This section provides a brief overview of controlling access to specific memory and built-in functions, also known as intrinsics.

Extended keywords

Memory attribute keywords are provided for __near and, __far memory. The __near keyword is for register A4 base relative addressing. The __far keyword is full 32 bits addressing which can be useful for larger static data objects when using the Small data model.

You can specify an attribute such as Near in two ways, either as a __near or __attribute__((near)).

Function attributes includes __saveds and __farfunc. The __saveds attribute is useful in the Small data model. It makes a function callable from outside your application. Such call context will not share the same register A4 base address as your application. The compiler will generate code to preserve the old register A4 value and initialize it with the base address context used in your application.

Intrinsics

Intrinsics functions appear as ordinary calls but are special compiler constructs, emitting specific instruction sequences. To enable them, include the calypsi/intrinsics68000.h header file.

Assembly code

You can write functions in assembly language by following the C calling convention. These functions can be called from C in the same way as any C function.