

***************
Getting started
***************

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

.. index:: C language

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*.

.. index:: cross compiler

Cross compiler
--------------

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

.. index:: supported devices, devices; supported

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.


File extensions
===============

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

.. index:: file extensions

.. _FileExtensions:

.. table:: File extensions
 :widths: 1 5
 :column-dividers: none single none
 :column-alignment: right left

 +----------------+---------------------------------------------------+
 |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                          |
 +----------------+---------------------------------------------------+

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.

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.

.. index:: code model
.. _code-model:

Code model
----------

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

.. index:: data model
.. _data-model:

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.

.. index:: data model; small, small; data model

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.

.. index:: data model; large, large; data model

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.


.. index:: data model; far-only, far-only; data model

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:: Data models
 :widths: 1 2 2
 :column-dividers: none single single none
 :column-alignment: left left left

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

.. index:: floating point; types, floating point; setting,
.. index:: size; of float, size; of double

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.

.. index:: optimizer

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.

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.

.. index:: intrinsics

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.


