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 standard MOS Technology 6502, the Sunplus 65B02, the Western Design Center 65C02 (with and without Rockwell extensions) and the 45GS02 in the MEGA65 8-bit computer. There have been other 6502 derivatives produced which can also be used by selecting one that matches its instruction set. As they all tend to have the base 6502 in common, the 6502 can be used a lowest common denominator.

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`	Commodore 64 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 cc6502, and assembly source files use as6502.

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 ln6502 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:

$ cc6502 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:

$ as6502 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:

$ ln6502 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
Commodore program files are similar to RAW but prefixed by a load address
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 toolchain supports various 6502 variants, including the original 6502, Sunplus 65B02, WDC 65C02 (with or without Rockwell extensions), and the MEGA65 45GS02 cores.

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¶

The 6502 features a zero page short address area, offering more efficient access than arbitrary memory addresses.

You can specify zero page allocation using extension keywords like __zpage or __attribute__((zpage)).

Intrinsics¶

Intrinsics functions appear as ordinary calls but are special compiler constructs, emitting specific instruction sequences. To enable them, include the calypsi/intrinsics6502.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.

4.6. Example projects¶

You can find some simple example projects in the examples sub-directory of the installation directory. For more information about the installation, see the Installation chapter.

There are a couple of “hello world” projects using different approaches, the printf() function typically adds quite a bit of overhead. There is also a minimal application to demonstrate that it is possible to get very small applications. The expression example is mainly intended to make it easy to play with variables in the debugger.

On Github you can find a work in progress board support package for the Commodore 64 and a hello project which makes use of it.