MPC8641 Runtimes
================

Runtimes Supported
------------------

* ZFP
* Ravenscar-SFP
* Ravenscar-Full

Targets Supported
-----------------

NXP MPC8641 Single-Core and MPC8641D Dual-Core Power Architecture e600

System Clocks
-------------

See package System.BB.Board_Parameters (`s-bbbopa.ads`) in the gnat
directory for the clock frequency declaration.

Startup Code
------------

There are two assembly language files for the startup code, one each for
executing from RAM or ROM. These are `start-ram.S` and `start-rom.S`
respectively.

The startup code selection is controlled by a scenario variable named
"Loader". This scenario variable is declared in an xml file
(`runtime.xml`) read by gprbuild automatically and used to define linker
switches. These switches specify the startup code corresponding to the
scenario value, as follows:

* ROM  : `start-rom.S`
* RAM  : `start-ram.S`

The default is ROM.

There is a third assembly file, `setup.S`, that defines branchpoints used
by both `start-ram.S` and `start-rom.S`. In the former case, the branchpoint
clears the segments (sbss2, sbss, and bss). In the latter case, the
branchpoint configures the floating-point unit.

The file `start-rom.S` initializes and starts CPU0. Note that the
declaration of package System.BB.Parameters (`gnat/s-bbpara.ads`) contains
a constant indicating one processor is available.

For the ZFP runtime the `handler.S` file is used to initialize the vector
table. For the ravenscar-* runtimes, the code in package
System.BB.CPU_Primitives (`s-bbcppr.adb`) then installs GNAT-specific
handlers that raise exceptions for the traps.

Note that context switching is implemented by a combination of Ada code
in the body of package System.BB.CPU_Primitives (`s-bbcppr.adb`) and
assembly code in `context_switch.S`.

Interrupts
----------

The package Ada.Interrupts.Names is located in the gnat directory
(gnat/a-intnam.ads).

See the package body for System.BB.Board_Support (`s-bbbosu.adb`) in
the gnat directory for board configuration for interrupts.

See package System.BB.Parameters (`gnat/s-bbpara.ads`) for the number of
interrupts defined. The runtime supports at most 128 interrupts external
interrupts and 8 non external. If you have more interrupts, you need to
change the values used in the declaration of subtype Interrupt_Range in
that package.

Memory Layout
-------------

The memory layout is controlled by linker scripts selected by the
scenario variable named "Loader" described above. This scenario variable
is declared in an xml file (`runtime.xml`) read by gprbuild automatically
and used to define linker switches. These switches specify the linker
scripts corresponding to the scenario value, as follows:

* ROM  : `qemu-rom.ld`
* RAM  : `ram.ld`

Resources Used
--------------

The Ravenscar runtime libraries use the time base and decrementer core
registers to implement Ada semantics for time, i.e., delay statements
and package Ada.Real_Time. See the package body for
System.BB.Board_Support in the file `gnat/s-bbsuti.adb`. Note that these
registers are 32-bits wide, so although the underlying time base value
is 64-bits, the value must be read in two separate instructions, that
is, non-atomically, and then combined. This results in the possibility
of a race condition in which the upper half changes after being read,
apart from when the lower half is read. To deal with that race condition
a loop is used, but note that this requires multiple reads of the two
registers. See function Read_Clock in that package for the loop.

The runtime libraries provide a minimal version of package Ada.Text_IO
supporting character- and string-based input and output routines. The
bodies of the Ada.Text_IO routines call through to a device-specific I/O
package named System.Text_IO. See the package body in the file
`s-textio.adb` in the gnat directory. The default console is available via
UART0, with line configuration (baud rate etc.) set by the boot-loader.
