

*****************
Section reference
*****************

Compiler-generated code and data objects are organized into sections
within the object file. Understanding these sections is crucial for
writing linker placement files and interpreting compiler and linker
list files.

Section overview
================

Code and data objects occupy space in target memory, either as
*program-bits* (actual data written to memory) or *no-bits* (sections
represented only by their size in the ELF object file).

The Calypsi C compiler tool chain has adapted names that trace back to the origins to the
early days of computing. These may not always be the best possible
names, but they are widely known and familiar to many.

.. index:: section; text, section; data, section; bss
.. index:: text section, data section, bss section

Sections are broadly categorized into three groups: *text*, *data*, and
*bss*. Text sections are read-only *program-bits*. Data sections are
read-write *program-bits*. BSS sections are read-write *no-bits*.

.. note::

   If you ever wondered about what bss section stands for, it
   originally is *block started by symbol*, a pseudo operation
   in an assembler for IBM 704 from the mid fifties. Some people suggest
   it is easier to remember as *better save space*, as it is a way to
   save space in the output file by just storing the size of the section
   without any explicit data bits.

Section names
-------------

Each section has a name, and multiple section fragments can share
the same name. Section names serve two purposes:

*   To provide a descriptive identifier for the section.
*   To control memory placement through rules that reference these names.

.. index:: section; types, rodata section, read-only; section
.. index:: section; read-only, section; no-init, no-init; section

Section types
-------------

Each section has a type: *text*, *data*, or *bss*. For embedded systems,
*rodata* (read-only data) and *no-init* sections are also available.
Read-only data sections are similar to text sections but identify data
rather than executable code. No-init sections resemble bss but lack
the memory-clearing mechanism.

.. index:: section; data, data section; initialization
.. index:: initialization; of data

Data sections
-------------

From the compiler's perspective, data sections are read-write
*program-bits* sections, meaning they have initializer values
that reside in memory. In a hosted environment, such sections
are loaded into memory before program execution. This approach
is unsuitable for programs stored in flash memory where execution
is expected to begin immediately upon power-on.

To address this, the linker clones data sections. The initializers for
the original data section are moved and placed in the clone. The clone
has a section name with an "``i``" prepended (e.g., ``idata`` for
``data``) and is intended for flash (read-only) memory.

To initialize data sections on power-on, a copy routine is inserted
before the ``main()`` function. This routine copies initializers from
flash to RAM, initializing data memory and clearing bss sections.

.. index:: data_init_table; section, section; data_init_table

The linker generates a ``data-init_table`` describing data to be copied and cleared.

.. note::

   For some targets, the Calypsi C compiler tool chain can cross-compile executables for OS loading.
   The ``--hosted`` option prevents data section cloning, avoiding duplication.
   However, the table-driven initializer is still needed for BSS sections in
   such environments.


Sections used by the compiler
=============================

The following sections are sections used by the Calypsi C compiler tool chain.

.. index:: code; section, zdata; section, data; section, cdata; section
.. index:: zzpage; section, zpage; section, switch; section
.. index:: idata; section
.. index:: data_init_table; section

.. index:: section; code, section; zdata, section; data, section; cdata
.. index:: section; zzpage, section; zpage, section; switch
.. index:: section; idata
.. index:: section; data_init_table

.. table:: Sections
 :widths: 2 1 1 5
 :column-dividers: none single single single none
 :column-alignment: left left left left

 +----------------------+------------+------------------+----------------------------+
 |Section name          |Type        |Memory kind       |Description                 |
 +======================+============+==================+============================+
 | ``code``             |text        |ROM               |Executable code             |
 +----------------------+------------+------------------+----------------------------+
 | ``zdata``            |bss         |RAM               |Zero-initialized (bss) data |
 +----------------------+------------+------------------+----------------------------+
 | ``data``             |data        |RAM               |Initialized data            |
 +----------------------+------------+------------------+----------------------------+
 | ``cdata``            |rodata      |ROM               |Constant data               |
 +----------------------+------------+------------------+----------------------------+
 | ``zzpage``           |bss         |RAM               |Zero-initialized (bss) zero |
 |                      |            |                  |page data                   |
 +----------------------+------------+------------------+----------------------------+
 | ``zpage``            |data        |RAM               |Initialized zero page data  |
 +----------------------+------------+------------------+----------------------------+
 | ``switch``           |rodata      |ROM               |Switch tables               |
 +----------------------+------------+------------------+----------------------------+
 | ``izpage``           |rodata      |ROM               |Data initializers for       |
 |                      |            |                  |``zpage`` section           |
 +----------------------+------------+------------------+----------------------------+
 | ``idata``            |rodata      |ROM               |Data initializers for       |
 |                      |            |                  |``data`` section            |
 +----------------------+------------+------------------+----------------------------+
 | ``data_init_table``  |rodata      |ROM               |Data initializer table      |
 +----------------------+------------+------------------+----------------------------+
 | ``registers``        |noinit      |RAM               |Pseudo registers in zero    |
 |                      |            |                  |page                        |
 +----------------------+------------+------------------+----------------------------+
 | ``reset``            |text        |ROM               |Reset vector, when used     |
 +----------------------+------------+------------------+----------------------------+
 | ``heap``             |noinit      |RAM               |Heap memory, for            |
 |                      |            |                  |``malloc()``                |
 +----------------------+------------+------------------+----------------------------+
 | ``stack``            |noinit      |RAM               |CPU stack, always in page   |
 |                      |            |                  |1 on the 6502               |
 +----------------------+------------+------------------+----------------------------+
 | ``cstack``           |noinit      |RAM               |C stack, simulated stack,   |
 |                      |            |                  |anywhere in memory          |
 +----------------------+------------+------------------+----------------------------+
 | ``zpsave``           |noinit      |RAM               |Commodore targets, save     |
 |                      |            |                  |area for ``registers``      |
 |                      |            |                  |section                     |
 +----------------------+------------+------------------+----------------------------+
 | ``zfar``             |bss         |RAM               |Zero-initialized (bss)      |
 |                      |            |                  |far data, MEGA65 only       |
 +----------------------+------------+------------------+----------------------------+
 | ``far``              |data        |RAM               |Initialized far data,       |
 |                      |            |                  |and MEGA65 only             |
 +----------------------+------------+------------------+----------------------------+
 | ``cfar``             |rodata      |ROM               |Constant far data,          |
 |                      |            |                  |MEGA65 only                 |
 +----------------------+------------+------------------+----------------------------+
 | ``ifar``             |rodata      |ROM               |Data initializers for       |
 |                      |            |                  |``far`` section,            |
 |                      |            |                  |MEGA65 only                 |
 +----------------------+------------+------------------+----------------------------+
 | ``zhuge``            |bss         |RAM               |Zero-initialized (bss)      |
 |                      |            |                  |huge data, MEGA65 only      |
 +----------------------+------------+------------------+----------------------------+
 | ``huge``             |data        |RAM               |Initialized huge data,      |
 |                      |            |                  |MEGA65 only                 |
 +----------------------+------------+------------------+----------------------------+
 | ``chuge``            |rodata      |ROM               |Constant huge data,         |
 |                      |            |                  |MEGA65 only                 |
 +----------------------+------------+------------------+----------------------------+
 | ``ihuge``            |rodata      |ROM               |Data initializers for       |
 |                      |            |                  |``huge`` section,           |
 |                      |            |                  |MEGA65 only                 |
 +----------------------+------------+------------------+----------------------------+

The sections ``izpage``, ``idata``, ``ifar``, ``ihuge``, and ``data_init_table``
in the table above are linker generated.

.. note::

   It is assumed that no ROM exists in the zero page. Consequently,
   constants placed in the zero page are placed in ``zpage`` (the normal
   RAM initialized zero page section), and the ``const`` attribute only
   affects the object type.

.. note::

   The table assigns sections to ROM and RAM for ROM-based applications
   that start on power-up. For hosted systems loading from storage to
   RAM, this distinction is not applicable. Always consider ROM-marked
   sections as read-only.

.. index interrupt; vectors

The vector section
------------------

An interrupt function will have an associated vector. This is a
specially named section for the purpose of holding a single vector.
The name looks something like ``$$interruptVector_0xfffe``. The intended
address of the vector is encoded in the section name and the linker
recognizes these and will place the vector at the address
specified. This is handled without the help of any section placement
rules.

Section reference
------------------

The following goes through the available sections in detail.

.. index:: code; section, section; code

``code``
^^^^^^^^

Holds program code for the address range ``0x0000-0xffff``. This section
is intended for placement in flash or ROM memory.

.. index:: zdata; section, section; zdata

``zdata``
^^^^^^^^^

Holds zero-initialized (bss) data in main memory, address range
``0x0000-0xffff``.

.. index:: data; section, section; data

``data``
^^^^^^^^

Holds non-zero initialized data in the main memory, address range
``0x0000-0xffff``.

.. index:: cdata; section, section; cdata

``cdata``
^^^^^^^^^

Holds initialized constant data in main memory, address range
``0x0000-0xffff``. This section is intended for placement in flash or
ROM memory.

.. index:: zzpage; section, section; zzpage

``zzpage``
^^^^^^^^^^

Holds zero-initialized (bss) data in the zero page, address range
``0x00-0xff``.

.. index:: zpage; section, section; zpage

``zpage``
^^^^^^^^^

Holds non-zero initialized data in the zero page memory,
address range ``0x00-0xff``.

.. index:: switch; section, section; switch

``switch``
^^^^^^^^^^

Holds switch tables in main memory, address range
``0x0000-0xffff``. This section is intended for placement in flash or
ROM memory.

.. index:: izpage; section, section; izpage

``izpage``
^^^^^^^^^^

Holds initializers for the ``zpage`` section. The linker creates this
section by cloning the ``zpage`` section provided by the compiler. It is
placed in main memory, address range ``0x0000-0xffff``, and must be placed
in flash or ROM. This section is not used when linking for a hosted
system.

``idata``
^^^^^^^^^

Holds initializers for the ``data`` section. The linker creates this
section by cloning the ``data`` section provided by the compiler. It is
placed in main memory, address range ``0x0000-0xffff``, and must be placed
in flash or ROM. This section is not used when linking for a hosted
system.

.. index:: data_init_table; section, section; data_init_table

``data_init_table``
^^^^^^^^^^^^^^^^^^^

The linker creates this section and populates it with information for
the C startup code, detailing how to copy and clear memory regions to
properly initialize data objects before transferring control to
``main()``. It is placed in main memory, address range ``0x0000-0xffff``,
and must reside in read-only memory, such as flash or ROM.
