

*****************
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
.. index:: znear; section, near; section
.. index:: switch; section
.. index:: zfar; section, far; section, cfar; section
.. index:: data_init_table; section

.. index:: section; code
.. index:: section; znear, section; near
.. index:: section; switch
.. index:: section; zfar, section; far, section; cfar
.. index:: section; data_init_table

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

 +----------------------+------------+------------------+---------------------------------+
 |Section name          |Type        |Memory kind       |Description                      |
 +======================+============+==================+=================================+
 | ``code``             |text        |ROM               |Executable code                  |
 +----------------------+------------+------------------+---------------------------------+
 | ``nearcode``         |text        |ROM               |Executable near code             |
 +----------------------+------------+------------------+---------------------------------+
 | ``znear``            |bss         |RAM               |bss (zero initialized) near data |
 +----------------------+------------+------------------+---------------------------------+
 | ``near``             |data        |RAM               |Initialized near data            |
 +----------------------+------------+------------------+---------------------------------+
 | ``zfar``             |bss         |RAM               |bss (zero initialized) far data  |
 +----------------------+------------+------------------+---------------------------------+
 | ``far``              |data        |RAM               |Initialized far data             |
 +----------------------+------------+------------------+---------------------------------+
 | ``cfar``             |rodata      |ROM               |Constant far data                |
 +----------------------+------------+------------------+---------------------------------+
 | ``switch``           |rodata      |ROM               |Switch tables                    |
 +----------------------+------------+------------------+---------------------------------+
 | ``inear``            |rodata      |ROM               |Near data initializers           |
 +----------------------+------------+------------------+---------------------------------+
 | ``ifar``             |rodata      |ROM               |Far data initializers            |
 +----------------------+------------+------------------+---------------------------------+
 | ``data_init_table``  |rodata      |ROM               |Data initializer table           |
 +----------------------+------------+------------------+---------------------------------+
 | ``reset``            |text        |ROM               |Reset vector, when used          |
 +----------------------+------------+------------------+---------------------------------+
 | ``heap``             |noinit      |RAM               |Heap memory, for ``malloc()``    |
 +----------------------+------------+------------------+---------------------------------+
 | ``stack``            |noinit      |RAM               |User stack                       |
 +----------------------+------------+------------------+---------------------------------+
 | ``sstack``           |noinit      |RAM               |Supervisor stack                 |
 +----------------------+------------+------------------+---------------------------------+

The sections ``inear``, ``ifar`` and ``data_init_table`` in
the table above are linker generated.

.. note::

   It is assumed that there are no ROM or flash in either the Near area.
   Constants placed in either of those are placed in a
   normal writable section and the ``const`` attribute only affects the
   type of the object.

.. 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_0x00000000``. 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, address range ``0x00000000-0xffffffff``. This
section is intended to be placed in a flash or ROM memory.

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

``nearcode``
^^^^^^^^^^^^

Holds program code, address range ``0x00000000-0xffffffff`` but
limited to about 32K. Code in this section treats function calls as
being reachable with the ``BSR`` instruction that takes a signed 16
bit offset, which means all calls are assumed to be reachable.

.. index:: znear; section, section; znear

``znear``
^^^^^^^^^

Holds zero initialized (bss) data reachable using
base relative from register ``A4``, up to 64K in total.

.. index:: near; section, section; near

``near``
^^^^^^^^

Holds initialized data reachable using
base relative from register ``A4``, up to 64K in total.

.. index:: zfar; section, section; zfar

``zfar``
^^^^^^^^

Holds zero initialized (bss) data in the main memory, address range
``0x00000000-0xffffffff``.

.. index:: far; section, section; far

``far``
^^^^^^^

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

.. index:: cfar; section, section; cfar

``cfar``
^^^^^^^^

Holds initialized constant data in the main memory, address range
``0x00000000-0xffffffff``. This section is intended to be placed in a
flash or ROM memory.

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

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

Holds switch tables in the main memory, address range
``0x00000000-0xffffffff``. This section is intended to be placed in a
flash or ROM memory.

.. index:: inear; section, section; inear

``inear``
^^^^^^^^^

Holds initializers for the ``near`` section. This section is created
by the linker by cloning the ``near`` section provided by the
compiler. This section is placed in the main memory, address
range ``0x00000000-0xffffffff`` and needs to be placed in a flash or
ROM. This section is not used when linking for a hosted system.

.. index:: ifar; section, section; ifar

``ifar``
^^^^^^^^

Holds initializers for the ``far`` section. This section is created
by the linker by cloning the ``far`` section provided by the
compiler. This section is placed in the main memory, address
range ``0x00000000-0xffffffff`` and needs to be placed in a 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``
^^^^^^^^^^^^^^^^^^^

This section is created by the linker and filled in with information
to the C startup code on how to copy and clear memory regions to
properly initialize the data object before giving control to
``main()``. This section is placed in the main memory, address
range ``0x00000000-0xffffffff`` and needs to be placed in
read-only memory, such as flash or ROM.
