============
Introduction
============

.. _RTEMS: https://www.rtems.org
.. _VME: https://en.wikipedia.org/wiki/VMEbus
.. _EPICS: https://epics-controls.org

This project creates an RTEMS_ image that is used to run on VME_ CPU cards 
with EPICS_.

When used with RTEMS_ 4.9, the program also uses the
`cexp shell <https://github.com/till-s/cexpsh>`_  and 
`GeSys <https://github.com/epicsdeb/rtems-gesys>`_ 
to create a boot image that can execute a startup script, dynamically load
object files and has an interactive shell.

Configuration files
-------------------

The configuration files for specific versions of RTEMS_ are named
"CONFIG-RTEMS-NN" where "NN" is the RTEMS_ version number and an optional
suffix. Here is the current list of configuration files:

- CONFIG-RTEMS-4.9 : RTEMS 4.9
- CONFIG-RTEMS-4.10 : RTEMS 4.10
- CONFIG-RTEMS-4.11 : RTEMS 4.11
- CONFIG-RTEMS-5 : RTEMS 5 

There is also a configuration file with common configuration settings, here you
may change things to configure the program for your needs:

- CONFIG.COMMON

Here is a list of :doc:`configuration variables <configuration>`.

Compiling multiple versions of RTEMS
------------------------------------

Although you can create a bootable image for multiple versions of RTEMS_, you cannot do this only once in a working copy of rtems-build-tool. If you have build a kernel for a certain RTEMS_ version and you want now build a kernel for another kernel, you have to run the script ``cleanup.sh`` first.

Scripts
-------

All scripts are in the top directory. Here is a list of scripts

- build-tool.sh : build the RTEMS bootable image
- cleanup.sh : removes all downloaded and generated files
- mvme2100-exe2boot.sh : helper to create bootable images for the mvme2100 CPU
- mvme2500-exe2boot.sh : helper to create bootable images for the mvme2500 CPU

The scripts are explained in detail in :doc:`Scripts <scripts>`.

Makefile
--------

For convenience there is a makefile that builds creates a bootable image from
fron configuration file "CONFIG". Youcan use this by creating this file and
then calling make like in::

  cp CONFIG-RTEMS-4.9 CONFIG
  make