************
Special code
************

Main
====

Execution starts in the ``main.main`` function. This function must have the ``void`` return type
and must not have any arguments.

Interrupt handlers
==================

Interrupt handlers are functions defined in the ``interrupts`` module and start with ``handler_``.
The name following ``handler_`` must be one of the handler names in the table below. Interrupt
handlers must have the ``void`` return type and must not have any arguments.

Defined interrupt handlers create an appropriate interrupt vector. This does not enable the
interrupts; see the hardware documentation for details about this.

To include the ``interrupts`` module for compilation, it is recommended to create an "enable
interrupts" function within the ``interrupts`` module and call this function from another module.

+----------------------+-----------------+----------+
| Interrupt            | Handler name    | Vector   |
+======================+=================+==========+
| IE0                  | ``IE0``         | ``0x03`` |
+----------------------+-----------------+----------+
| TF0                  | ``TF0``         | ``0x0B`` |
+----------------------+-----------------+----------+
| IE1                  | ``IE1``         | ``0x13`` |
+----------------------+-----------------+----------+
| TF1                  | ``TF1``         | ``0x1B`` |
+----------------------+-----------------+----------+
| RI, TI               | ``RI_TI``       | ``0x23`` |
+----------------------+-----------------+----------+
| TF2                  | ``TF2``         | ``0x2B`` |
+----------------------+-----------------+----------+
| IADC                 | ``IADC``        | ``0x43`` |
+----------------------+-----------------+----------+
| IE2                  | ``IE2``         | ``0x4B`` |
+----------------------+-----------------+----------+
| TRF, BCERR           | ``TRF_BCERR``   | ``0x53`` |
+----------------------+-----------------+----------+
| CC2P                 | ``CC2P``        | ``0x5B`` |
+----------------------+-----------------+----------+
| CCnF, CCnR (n=0,1,2) | ``CCnF_CCnR``   | ``0x63`` |
+----------------------+-----------------+----------+
| CT1FP, CT1FC         | ``CT1FP_CT1FC`` | ``0x6B`` |
+----------------------+-----------------+----------+
| Power down interrupt | ``PDI``         | ``0x7B`` |
+----------------------+-----------------+----------+

Special function registers
==========================

The SC compiler predefines the ``sfr`` module with data fields pointing to the special function
registers. In the current version of the SC compiler, this contains all special function registers
found in the Siemens C504. This is a superset of the special function registers found in the Intel
8051, although some are named subtly different.
In a future version, you can specify the specific microcontroller you're compiling for, so that only
that microcontroller's special function registers are available.

If you need to use a special function register not provided by the ``sfr`` module, you can define it
(in another module) like this::

    addr internal mysfr = 0xFF;

Compiler services
=================

The SC compiler defines the ``compilerservices`` module. Normally, this module should never be used.
It provides functions that are easy in assembly code, but impossible to do with normal language
constructs.

``reti()`` is a function that contains one instruction: ``RETI``. This function is *not* needed to
return from interrupt handlers; interrupt handlers always end with a ``RETI`` instruction. This
function is only needed if you abnormally exit an interrupt handler.

``reset()`` is a function that resets program execution while keeping memory contents. When called,
the stack pointer is reset to its initial value, and jumps to the start of ``main.main()``. If used
within an interrupt handler, call ``reti()`` before calling ``reset()``. ``reset()`` could be useful
in 'fast abort' situations, where restarting and reinitializing is faster or simpler than executing
stop actions at every layer in the call stack.

.. vim: tw=100