

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


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``       | Commodore 64 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 ``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.

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.





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

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))``.

.. index:: intrinsics

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.

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 :ref:`sec-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
<https://github.com/hth313/Calypsi-6502-Commodore.git>`_
and a `hello project
<https://github.com/hth313/Calypsi-6502-hello-world.git>`_
which makes use of it.
