

.. _target-specifics:

****************
Target specifics
****************

This chapter describes the built-in target-specific support.

The support is enabled using the ``--target`` option which has the
following effects:

* Select a suitable default ``--core``.

* Enable preprocessor macros to identify the target and core used.
  This can be used for conditional compilation, in both the compiler
  and the assembler.

* Additional target specific header files can be included using
  ``#include <file.h>``.

* Enable certain language extensions to suit the target, if applicable.
  This will also affect certain aspects of the code generator to take
  advantage of extensions and capabilities of the target.

* When using ``--target`` the linker will assume a RAM based system
  where a program is loaded into memory and data sections are
  initialized by loading the data in place. This is a sensible
  default, but can be controlled using the
  ``--rom-code`` and ``--copy-initialize`` options.

The installation comes with header files, pre-built target specific
board support link libraries and linker control files.

.. index:: board support; enabling, enabling; board support

Board support
=============

Enabling board support in the linker requires two conditions:
First, specify the appropriate ``--target`` option. Second, use a supplied
linker control file whose name corresponds to the board support.

For example, this means that to select to link with a Foenix C256U
board support you need to specify:

.. code-block:: sh

   $ ln65816  --target=c256  c256-u-plain.scm  [object-files]

.. note::

   If you need to alter the supplied linker rules file or create your
   own, name it with the same prefix name as the board support one.
   The linker will first look in the current directory for the
   ``.scm`` file, then in the installation directory.

The following table gives an overview of the board support definition.

.. table:: Board support definitions
 :widths: 2 3 2 2
 :column-dividers: none single single single
 :column-alignment: left left left left

 +--------------+---------------+-------------+-------------------+
 | ``--target`` | name          |  kernel/OS  |  ``.scm`` prefix  |
 +==============+===============+=============+===================+
 | Foenix       | C256U/FMX     | Kernel      | ``c256-``	  |
 +--------------+---------------+-------------+-------------------+

.. index:: Foenix C256, C256

Foenix C256
===========

The C256 family includes the FMX, U, and U+ new retro-style computers
with a 65816.

Board support
-------------

The board support package is for the standard C256 kernel.

The board support includes C header files, a link library  and linker
control files from the
`Foenix C256 support <https://github.com/hth313/Calypsi-65816-Foenix>`_
project. The current variant is built from commit hash
``b3713b3c0fa27aac0640d7bd2f45ee7941d24e4a``.

Header files
------------

The supplied header files are:

.. table:: Foenix C256 header files
 :widths: 2 3
 :column-dividers: none single single none
 :column-alignment: left left

 +-----------------------------------+------------------------------------------+
 | include path                      |  description                             |
 +===================================+==========================================+
 | ``#include <foenix/gavin.h>``     | Gavin chip                               |
 +-----------------------------------+------------------------------------------+
 | ``#include <foenix/vicky.h>``     | Vicky graphics chip                      |
 +-----------------------------------+------------------------------------------+
 | ``#include <foenix/dma.h>``       | DMA controller                           |
 +-----------------------------------+------------------------------------------+
 | ``#include <foenix/interrupt.h>`` | Interrupt controller                     |
 +-----------------------------------+------------------------------------------+
 | ``#include <foenix/network.h>``   | Network interface                        |
 +-----------------------------------+------------------------------------------+
 | ``#include <foenix/system.h>``    | C256 system control registers            |
 +-----------------------------------+------------------------------------------+
 | ``#include <foenix/timer.h>``     | Timer definitions                        |
 +-----------------------------------+------------------------------------------+

The C256 library, which includes startup code, exit handling, and I/O
adaption between the C library and the C256 kernel, comes pre-built. Your
application will automatically be linked with it if you specify
``--target=c256`` and use a linker rules file starting with the ``c256-``
prefix:

.. code-block:: sh

   $ ln65816  --target=c256  c256-u-plain.scm  [object-files]

The installation provides several library variants to accommodate different
compiler settings, such as ``double`` size. The linker automatically selects a
compatible variant for your application.

Linker rules
------------

Linker rules use the ``c256-`` prefix. Naming your custom linker rules file
with this prefix, or specifying ``--target=c256``, ensures automatic linking with
the supplied pre-built C256 kernel library.

``c256-u-plain.scm``
^^^^^^^^^^^^^^^^^^^^

Suitable for use with the C256U.

.. code-block:: hex

    ;;; Example linker rules for the for the C256 Foenix U
    
    (define memories
      '((memory Banks (address (#x10000 . #x1fffff)) (type ANY))
        (memory LoMem (address (#x2100 . #x7fff)) (type ANY))
        (memory Vector (address (#xffe4 . #xffff)))
    
        (memory palettes (address (#xaf2000 . #xaf3fff))
    	    (section (palette0 #xaf2000) (palette1 #xaf2400))
    	    (section (palette2 #xaf2800) (palette3 #xaf2c00))
    	    (section (palette4 #xaf3000) (palette5 #xaf3400))
    	    (section (palette6 #xaf3800) (palette7 #xaf3c00)))
        (memory vram (address (#xb00000 . #xcfffff))
                (section vram))
        ))


``c256-u_-plain.scm``
^^^^^^^^^^^^^^^^^^^^^

Suitable for use with the C256U+. This variant has 4MB system RAM compared to
2MB in the C256U. If your application does not need the extra memory,
consider using the ``c256-u-plain.scm`` variant to run on both C256U and C256U+.

.. code-block:: hex

    ;;; Example linker rules for the for the C256 Foenix U+
    
    (define memories
      '((memory Banks (address (#x10000 . #x2fffff)) (type ANY))
        (memory LoMem (address (#x2100 . #x7fff)) (type ANY))
        (memory Vector (address (#xffe4 . #xffff)))
    
        (memory palettes (address (#xaf2000 . #xaf3fff))
    	    (section (palette0 #xaf2000) (palette1 #xaf2400))
    	    (section (palette2 #xaf2800) (palette3 #xaf2c00))
    	    (section (palette4 #xaf3000) (palette5 #xaf3400))
    	    (section (palette6 #xaf3800) (palette7 #xaf3c00)))
        (memory vram (address (#xb00000 . #xcfffff))
                (section vram))
        ))


``c256-fmx-plain.scm``
^^^^^^^^^^^^^^^^^^^^^^^

Suitable for use with the C256-FMX.

.. code-block:: hex

    ;;; Example linker rules for the for the C256 Foenix FMX
    
    (define memories
      '((memory Banks (address (#x10000 . #x2fffff)) (type ANY))
        (memory LoMem (address (#x2100 . #x7fff)) (type ANY))
        (memory Vector (address (#xffe4 . #xffff)))
    
        (memory palettes (address (#xaf2000 . #xaf3fff))
    	    (section (palette0 #xaf2000) (palette1 #xaf2400))
    	    (section (palette2 #xaf2800) (palette3 #xaf2c00))
    	    (section (palette4 #xaf3000) (palette5 #xaf3400))
    	    (section (palette6 #xaf3800) (palette7 #xaf3c00)))
        (memory vram (address (#xb00000 . #xefffff))
                (section vram))
        ))


.. index:: Foenix F256, F256

Foenix F256
===========

The F256 family includes the F256 and F256K.

Board support
-------------

The board support package provides a flat memory load for the 65816 on
the F256 series computers.

The board support includes C header files, a link library  and linker
control files from the
`F256 support <https://github.com/hth313/Calypsi-65816-F256>`_
project. The current variant is built from commit hash
``8b4cec98c8281e2988c97481209502a03a7044d4``.

Header files
------------

The supplied header files are:

.. table:: Foenix F256 header files
 :widths: 2 3
 :column-dividers: none single single none
 :column-alignment: left left

 +-----------------------------------+------------------------------------------+
 | include path                      |  description                             |
 +===================================+==========================================+
 | ``#include <f256.h>``             | Main header to include all F256 header   |
 |                                   | files                                    |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/dma.h>``         | DMA controller                           |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/interrupt.h>``   | Interrupt controller                     |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/rts.h>``         | Real time clock                          |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/sdc.h>``         | SD card                                  |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/sid.h>``         | SID                                      |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/system.h>``      | F256 system control registers            |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/uart.h>``        | UART, serial port                        |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/via.h>``         | 6522 VIA                                 |
 +-----------------------------------+------------------------------------------+
 | ``#include <f256/vicky.h>``       | Vicky graphics chip                      |
 +-----------------------------------+------------------------------------------+

The F256 library includes startup code; other specifics are absent due to the
current lack of a ready kernel.
Your application will automatically be linked with it if you specify
``--target=f256`` or use a linker rules file starting with the ``f256-``
prefix:

.. code-block:: sh

   $ ln65816  --target=f256  f256-plain.scm  [object-files]

The installation provides several library variants to accommodate different
compiler settings, such as ``double`` size. The linker automatically selects a
compatible variant for your application.

Linker rules
------------

Linker rules use the ``f256-`` prefix. Naming your custom linker rules file
with this prefix, or specifying ``--target=f256``, ensures automatic linking with
the supplied pre-built F256 board support library.

``f256-plain.scm``
^^^^^^^^^^^^^^^^^^

This file defines the basic flat memory map.

I/O and Near addressing
-----------------------

The 65816 can address 64K using shorter 16-bit addressing. In the Small data
model, bank 0 is set up as the Near addressing area. In the Medium data
model, a single bank is set aside for this purpose. However, in the Large
data model, the Near bank is set to point to the I/O bank. The C startup
module in this board support configures this.
