------------------------------------------
Developing Ada Applications for DDC-I Deos
------------------------------------------

.. toctree::

This chapter is intended for users already familiar with DDC-I OpenArbor and
GNATbench. Some familiarity with GNAT Pro is also useful. For more information
on *GNAT Pro* and *GNAT Pro for Deos* please refer to the *GNAT Pro User's Guide*
and the *GNAT User’s Guide Supplement for Cross Platforms*,  available on *GNAT
Tracker*.

This chapter contains two tutorials: one for developing Ada applications using
Deos processes and one for developing Ada applications using Deos 653 partitions.

Note: at the moment, GNATbench does not support converting existing Deos
executable projects nor can it import existing Ada project. If you have such
projects, follow the tutorials on how to create a new Ada application and copy
the code and configuration files from your previous project to the new project.
Do note that if you have an existing GPR file, look at the GPR file created by
GNATbench for any modification you may need to apply to your own GPR file.
Please contact AdaCore if you need any help.

.. _installing_gnatbench_into_openarbor:

Installing GNATbench
====================

.. _openarbor_requirements:

Requirements
------------

GNATbench for DDC-I OpenArbor requires DDC-I OpenArbor 10 or later.

Prior to installing GNATbench, first install *GNAT Pro for Deos* and ensure it
binaries are located on your path before starting OpenArbor. On Windows, the
installer will update your environment path to include *GNAT Pro for Deos* if
the option is selected during installation. On Linux, the installer will
provide instructions on how to update ``PATH`` variable at the end of the
install.


..  _downloading_gnatbench_openarbor:

Downloading GNATbench
---------------------

GNATbench is downloadable from GNAT Tracker and can be found on the *Release
Download* page under the *IDE* section. Download the GNATbench ZIP archive
that corresponds to your host platform. Once downloaded, you will install the
plug-in through the Eclipse plug-in installer, so there is no need to expand
the ZIP archive.


.. _openarbor_installation_process:

Installing
----------

GNATbench requires an Eclipse plug-in that is not installed by default in
OpenArbor (``org.eclipse.equinox.p2.iu``). To have OpenArbor install this plug-in
during the GNATbench install, add the appropriate Eclipse release repository
to OpenArbor:

 1. Find the version of Eclipse your copy of OpenArbor is based on. This can
    be done by selecting ``About OpenArbor`` from the ``Help`` and then
    clicking on the red DDC-I logo (the tooltip for the button will read ``DDC-I``).
    In the lower half of the window that opens, look for the line that read
    *This offering is powered by Eclipse <version>-R*, where *<version>* will
    correspond to the Eclipse version in the form *yyyy-mm*. For example,
    OpenArbor 10.4 is based on *2020-12*. You can now close the *About OpenArbor
    Features* and *About OpenArbor* windows.

 2. Open the OpenArbor plug-in installer by selecting ``Install New Software``
    from the ``Help`` menu.

 3. Click the ``Add`` button near the top right of the ``Install`` window to
    open the ``Add Repository`` dialog.

 4. Under ``Name`` enter ``Eclipse <version>`` and then enter as the ``Location``
    ``https://download.eclipse.org/releases/<version>/``. For example, for
    OpenArbor 10.4, you would enter ``Eclipse 2020.12`` and
    ``https://download.eclipse.org/releases/2020-12/`` respectively.

 5. Click ``Add`` to add the Eclipse repository.

Once done, GNATbench can now be installed:

  1. Click the ``Add`` button on the ``Install`` window again.

  2. Select 'Archive' from the resulting ``Add Repository`` dialog and navigate
     to the zip file downloaded from GNAT Tracker. The Location field will then
     reflect the path that file.

  3. The ``Install`` dialog will then list a number of different variants of
     GNATbench to install. Select 'AdaCore Plugins for DDC-I OpenArbor IDE'
     from the list.

  4. Click ``Next`` and follow the installation wizard to completion. During
     the install, a dialog may appear asking you trust the AdaCore certificates.
     Chec
     k the mark next to the GNATbench certificate and press 'OK'.

Once GNATbench is installed and OpenArbor has been restarted, confirm that
GNATbench can find the *GNAT Pro for Deos* toolchain by opening the Eclipse preferences
and selecting the ``Ada/Toolchains`` page. *GNAT Pro for Arm Deos* should
be listed as ``arm-eabi``.

.. _openarbor_documentation:

Documentation
-------------

The *GNATbench for Eclipse User’s Guide* and other AdaCore documentation can be
found in the OpenArbor help system, by selecting "Help Contents" from the
``Help`` menu. Please read the next section on creating an Ada application for
Deos before using the plug-in.



.. _creating-ddci-deos-executable-tutorial:

Creating an Ada Application for Deos Processes
==============================================

This tutorial walks you through the process of creating a new Ada Deos
application for Arm Deos using the ``qemu-arm`` platform.


Create a new DDC-I Executable Project
-------------------------------------

To create an Ada application for Deos, first create a new *DDC-I Executable Project*
by selecting the ``File → New → DDC-I Executable Project`` menu item.

If you do not see the ``DDC-I Executable Project`` menu item, you will need
to switch to the *DDC-I Perspective*. This can be done by selecting the
``Window → Perspective → Open Perspective → Other...`` menu item and selecting
the ``DDC-I (default)`` perspective.

In the *New DDC-I Executable Project* window, enter ``hello_world`` as the
project name and select ``ARM`` as the target. Finally, click the ``Finish``
button to create the ``hello_world`` project.


Convert DDC-I Executable Project
--------------------------------

To use the *GNAT Pro for Deos* toolchain with your new *DDC-I Executable Project*
you first need to convert the project for use with GNATbench. To do this:

 1. Right click on the ``hello_world`` project.
 2. Select the ``New → Other...`` menu item.
 3. From the *Select a wizard* dialog, expand the ``Ada`` folder and select
    ``Convert an empty DDC-I Executable Project to use Ada Language``.
 4. Click the ``Next`` button and confirm the project unit name is correct
    (this is the name GPR file without the extension). For this tutorial we will
    leave the name as ``hello_world``.
 5. Click the ``Finish`` button to perform the conversion.

The converted project will have a new ``code`` folder containing a simple
hello_world procedure called ``hello_world.adb``.


Add Deos Component Dependencies
-------------------------------

*GNAT Pro for Deos* requires *Deos Executable Projects* to include ``ansi``
and ``gnu-language`` components. For this tutorial, we also want to print to
the video console, so we need to also include the ``vfile`` component.

To add these components to our executable project:

  1. Expand the ``hello_world`` project in the *DDC-I Project* window.
  2. Expand ``Deos Component``, right click on ``Dependencies`` and select ``Add Dependency``.
  3. Select ``ansi`` from the drop down menu.
  4. Repeat for the ``gnu-language`` and ``vfile`` components.


Deos Process Developer XML file
-------------------------------

The *Deos Process Developer XML* contain the Deos process settings. To create
the XML file, first create a folder at the top level of your ``hello_world``
project called ``xml`` by right clicking on the ``hello_world`` project and
select ``New → Folder``.

Next, right click on the ``xml`` folder and select ``New → Other...``. In the
*Select a wizard* dialog expand the *DDC-I* folder and select *Deos Process
Developer XML file*. In the resulting dialog, name the process ``hello_world``
and click on the ``Next`` button. On the next page enter ``20`` into the
*How many 4k pages of stack space this thread need* field and click ``Finish``.

Edit the ``hello_world.pd.xml`` by expanding the ``xml`` folder and double click
on ``hello_world.pd.xml``. Perform the following modifications:

 1. Change the ``tlsSpaceInBytes`` attribute to ``128``.
 2. Change ``ramPagesQuota`` to ``100``. If you cannot find ``ramPagesQuota``,
    continue to the next step.
 3. Save ``hello_world.pd.xml`` and rebuild the project by right clicking on
    the ``hello_world`` project and select ``Rebuild Project``.
 4. If you could not find ``ramPagesQuota`` before, expand the ``logicalMemoryPools``
    attribute and the ``pool`` attribute within it. Change the ``pagesNeeded``
    attribute to ``100``.
 5. At the bottom of the ``hello_world.pd.xml`` window, select ``Source``. Add
    the following XML code after ``</logicalMemoryPools>``:

.. code-block:: xml

   <usedFeatureSets>
      <usedFeatureSet
           name = "libansi"
           versionRequirement = "none"
           versionNumber = "none"
           featureSetUndefinedAction = "ignore"
         >
      </usedFeatureSet>
      <usedFeatureSet
           name = "vfile"
           versionRequirement = "none"
           versionNumber = "none"
           featureSetUndefinedAction = "error"
         >
         <usedFeature
              name = "vfile"
            >
            <usedFeatureParameter
                 name = "ProcessInstanceName"
                 value = "hello_world"
            ></usedFeatureParameter>
         </usedFeature>
      </usedFeatureSet>
   </usedFeatureSets>


Save the file.


Build the project
-----------------

Build the executable by right clicking on the ``hello_world`` project and select
``Build Project`` if you do not have automatic builds turned on (``Project →
Build Automatically``).


Create the DDC-I Deos Platform Project
--------------------------------------

With the executable project built, create a new ``DDC-I Platform Project`` and
select ``qemu-arm``. In the project window, expand the ``qemu-arm`` project and
then ``Deos Components``. Right click on ``Dependencies`` and add a new
dependency. In the resulting window, select ``All`` in the registry filter drop
down menu and then select ``hello_world`` as a dependencies.

Next, in the project window expand ``Complete Integration`` and double click
on ``Components``. Expand ``platreg`` in the window that opens and then right
click on ``vfile`` and select ``Debug Variant``. Build the platform project by
right clicking on the project and selecting ``Project``.


Run the Deos project
--------------------

Click on the *Target Manager* window on near the top left corner of the screen
and click the left most button on that window to create a new target. The
tooltip for the button should read *New Remote Target*. Click OK to accept the
defaults and then click the play button.

QEMU will launch and the hello world message will print to the video monitor.

This concludes the tutorial.
.. _creating-ddci-deos_653-executable-tutorial:

Creating an Ada 653 Partition
=============================

This tutorial walks you through the process of creating a new Ada Deos 653
application for Arm Deos using the ``qemu-arm`` platform.


Create a new DDC-I Executable Project
-------------------------------------

To create an Ada application for Deos, first create a new *DDC-I Executable Project*
by selecting the ``File → New → DDC-I Executable Project`` menu item.

If you do not see the ``DDC-I Executable Project`` menu item, you will need
to switch to the *DDC-I Perspective*. This can be done by selecting the
``Window → Perspective → Open Perspective → Other...`` menu item and selecting
the ``DDC-I (default)`` perspective.

In the *New DDC-I Executable Project* window, enter ``hello_653`` as the
project name and select ``ARM`` as the target. Finally, click the ``Finish``
button to create the ``hello_653`` project.

Next, right click the new project and select ``Properties``. On the
*DDC-I Options* page, select the ``Project`` tab. Under ``General`` check the
check box ``Uses thread_local``. Click ``Apply and Close``.


Convert DDC-I Executable Project
--------------------------------

To use the *GNAT Pro for Deos* toolchain with your new *DDC-I Executable Project*
you first need to convert the project for use with GNATbench. To do this:

 1. Right click on the ``hello_653`` project.
 2. Select the ``New → Other...`` menu item.
 3. From the *Select a wizard* dialog, expand the ``Ada`` folder and select
    ``Convert an empty DDC-I Executable Project to use Ada Language``.
 4. Click the ``Next`` button and confirm the project unit name is correct
    (this is the name GPR file without the extension). For this tutorial we will
    leave the name as ``hello_653``.
 5. Click the ``Finish`` button to perform the conversion.

The converted project will have a new ``code`` folder containing a simple
hello_653 procedure called ``hello_653.adb``.


Add Deos Component Dependencies
-------------------------------

*GNAT Pro for Deos* requires Deos 653 partitions to include ``ansi``, ``deos-653-p1``
and ``gnu-language`` components. For this tutorial, we also want to print to
the video console, so we need to also include the ``vfile`` component.

To add these components to our executable project:

  1. Expand the ``hello_653`` project in the *DDC-I Project* window.
  2. Expand ``Deos Component``, right click on ``Dependencies`` and select ``Add Dependency``.
  3. Select ``ansi`` from the drop down menu.
  4. Repeat for the ``gnu-language``, ``deos-653-p1`` and ``vfile`` components.


Deos Feature Provider XML file
------------------------------

Deos 653 auto-generates the *Deos Process Developer XML* for our 653 partition.
To add the required feature sets to the auto-generate *Deos Process Developer XML*
we need to create a *Deos Feature Provider XML file* in our project. To create
this file, first create a folder at the top level of your ``hello_653``
project called ``xml`` by right clicking on the ``hello_653`` project and
select ``New → Folder``.

Next, right click on the ``xml`` folder and select ``New → File``. In the
*Create New File* dialog name the file ``hello_653.fp.xml`` and click
``Finish``.

If the XML file does not open automatically, open it from the *DDC-I Project
Windows*. At the bottom of the ``hello_653.fp.xml`` window, select ``Source``
and add the following XML code:

.. code-block:: xml

  <?xml version = "1.0" encoding="UTF-8"?>
  <featureSet
       name = "hello_653"
       versionNumber = "1.0.0"
       validityKey = "1891889728"
       comment = "653 partition extensions to PD XML"
       toolVersion = "3.61.3"
       xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
       xsi:noNamespaceSchemaLocation = "ddci:/xsd/fp.xsd"
     >
     <feature
          name = "oncePerUsingProcessTemplate"
          description = "usage required by partition"
        >
        <usedFeatureSetAction
             featureSetName = "libansi"
             featureName = "oncePerUsingProcessTemplate"
             featureSetUndefinedAction = "error"
             usingProcessTemplate = ""
        ></usedFeatureSetAction>
        <usedFeatureSetAction
             featureSetName = "vfile"
             featureName = "oncePerUsingProcessTemplate"
             featureSetUndefinedAction = "error"
             usingProcessTemplate = ""
        ></usedFeatureSetAction>
        <usedFeatureSetAction
             featureSetName = "vfile"
             featureName = "vfile"
             featureSetUndefinedAction = "error"
             usingProcessTemplate = ""
           >
           <methodParameter
                parameterName = "ProcessInstanceName"
                value = "hello_653"
           ></methodParameter>
        </usedFeatureSetAction>
     </feature>
  </featureSet>

Save and close the file.


Build the project
-----------------

Build the executable by right clicking on the ``hello_653`` project and select
``Build Project`` if you do not have automatic builds turned on (``Project →
Build Automatically``).


Create the Deos 653 Configuration Project
-----------------------------------------

To create the Deos 653 configuration project for our application, create another
new *DDC-I Executable Project* by selecting the ``File → New → DDC-I Executable
Project`` menu item.

In the *New DDC-I Executable Project* window:

 1. Enter ``tutorial_653_configuration`` as the project name.
 2. Select ``Deos Metadata Project`` as the *Project Type*.
 3. Select ``ARM`` as the target.

Click the ``Finish`` button to create the ``tutorial_653_configuration`` project.


Update the Deos Component Dependencies
--------------------------------------

Right click on the ``tutorial_653_configuration`` project in the *DDC-I
Project* window and select ``Properties``. Click on the *DDC-I Options`` page
and select the *Deos* tab. On the *Dependencies* page, click ``Add`` and select
``hello_653`` from the drop down menu. Click the ``OK`` button to close the dialog
and click ``Apply and Close`` to close the properties dialog.


Create the Deos 653 Configuration File
--------------------------------------

Create a new ``xml`` folder and within it a new file called ``tutorial_config.653.xml``.
With the *Source* view selected at the bottom of the ``tutorial_config.653.xml``
window add the following XML:

.. code-block:: xml

  <?xml version = "1.0" encoding="UTF-8"?>
  <Deos653Config
       name = "Sample-Configuration"
       validityKey = "-1118335824"
       toolVersion = "1.27.1"
       comment = ""
       hmShutdownRegistry = "platreg.bin"
       hmShutdownHyperstartIndex = "2"
       minimumWindowDurationInNs = "100000"
       xmlns = "http://ddci.com/ARINC653"
       xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation = "deos653.xsd"
     >
     <Partitions>
        <Partition
             Name = "hello_653"
             Identifier = "1"
             Period = "12500000"
             Duration = "8000000"
             ExecutableImageName = "hello_653.exe"
             MainProcessStackSizeInPages = "10"
             BreakAtStartup = "false"
             InDebugSet = "false"
             MapConfigurationFileTo = "RAM"
             ExecuteFrom = "RAM"
             PartitionUsesFPU = "true"
             ProcessStackSpaceInPages = "1000"
             MinimumProcessStackSizeInBytes = "1024"
             ProcessQuota = "4"
             BlackboardQuota = "16"
             BlackboardMessageSpaceInBytes = "128"
             BufferQuota = "0"
             BufferMessageSpaceInBytes = "0"
             SemaphoreQuota = "0"
             EventQuota = "0"
             QueuingPortListQuota = "0"
             MaximumPartitionLockLevel = "16"
             MinimumProcessPriority = "1"
             MaximumProcessPriority = "239"
             LoggingFunction = ""
             DeosKernelAttributeAccess = "true"
             ProcessStackGapSizeInDwords = "0"
             ProcessStackTagIntervalInDwords = "0"
             SourcePortSharedMemoryType = "DeosSharedMemory"
             SourcePortPlatformMemoryPool = "0"
             PlatformResourcePhysicalAddress = "0x0"
             PlatformResourceSizeInPages = "0"
             PlatformResourceCachePolicy = "off"
             HealthMonitorEventLogSize = "30"
             EventLoggingEnabled = "true"
             Core = "0"
             Type = "653"
             ProcessSwitchHook = ""
             PartitionModeChangeHook = ""
             SetModuleSchedule = "false"
             LinguisticTLSSpaceInBytes = "1280"
             ScheduleChangeAction = "IGNORE"
             PartitionCapabilities = ""
           >
           <MemoryRegions>
              <MemoryRegion
                   Name = "Initial RAM Pool"
                   Type = "Initial RAM Pool"
                   Address = "0x0"
                   Size = "0x80000"
                   AccessRights = "READ_WRITE"
                   PlatformMemoryPool = "0"
              ></MemoryRegion>
           </MemoryRegions>
        </Partition>
     </Partitions>
     <Schedule
          MinorFrameLength = "Automatic"
          ScheduleName = "default-wat"
          ScheduleID = "1"
          InitialModuleSchedule = "true"
        >
        <PartitionTimeWindow
             PartitionNameRef = "hello_653"
             Duration = "8000000"
             Offset = "0"
             PeriodicProcessingStart = "true"
             RepeatWindowAtNanosecondInterval = "PartitionPeriod"
             MayStartEarly = "false"
             MayFinishEarly = "true"
             MayUseSlack = "false"
        ></PartitionTimeWindow>
     </Schedule>
     <HealthMonitoring>
        <SystemErrors>
           <SystemError
                ErrorIdentifier = "1"
                Description = "processorSpecific"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "2"
                Description = "floatingPoint"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "3"
                Description = "accessViolation"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "4"
                Description = "powerTransient"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "5"
                Description = "platformSpecific"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "6"
                Description = "frameResync"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "7"
                Description = "deadlineMissed"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "8"
                Description = "applicationError"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "9"
                Description = "illegalRequest"
           ></SystemError>
           <SystemError
                ErrorIdentifier = "10"
                Description = "stackOverflow"
           ></SystemError>
        </SystemErrors>
        <MultiPartitionHM
             TableIdentifier = "1"
             TableName = "default MultiPartitionHM"
           >
           <ErrorAction
                ErrorIdentifierRef = "1"
                ErrorLevel = "MODULE"
                ModuleRecoveryAction = "IGNORE"
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "2"
                ErrorLevel = "MODULE"
                ModuleRecoveryAction = "IGNORE"
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "3"
                ErrorLevel = "MODULE"
                ModuleRecoveryAction = "IGNORE"
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "4"
                ErrorLevel = "MODULE"
                ModuleRecoveryAction = "IGNORE"
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "5"
                ErrorLevel = "MODULE"
                ModuleRecoveryAction = "IGNORE"
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "6"
                ErrorLevel = "MODULE"
                ModuleRecoveryAction = "IGNORE"
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "7"
                ErrorLevel = "PARTITION"
                ModuleRecoveryAction = ""
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "8"
                ErrorLevel = "PARTITION"
                ModuleRecoveryAction = ""
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "9"
                ErrorLevel = "MODULE"
                ModuleRecoveryAction = "IGNORE"
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "10"
                ErrorLevel = "MODULE"
                ModuleRecoveryAction = "IGNORE"
           ></ErrorAction>
        </MultiPartitionHM>
        <PartitionHM
             TableIdentifier = "1"
             TableName = "required unique name 1"
             MultiPartitionHMTableNameRef = "default MultiPartitionHM"
           >
           <ErrorAction
                ErrorIdentifierRef = "7"
                ErrorLevel = "PROCESS"
                PartitionRecoveryAction = "WARM_RESTART"
                ErrorCode = "DEADLINE_MISSED"
           ></ErrorAction>
           <ErrorAction
                ErrorIdentifierRef = "8"
                ErrorLevel = "PROCESS"
                PartitionRecoveryAction = "WARM_RESTART"
                ErrorCode = "APPLICATION_ERROR"
           ></ErrorAction>
        </PartitionHM>
     </HealthMonitoring>
  </Deos653Config>



Save and close the file.


Create the DDC-I Deos Platform Project
--------------------------------------

With the executable project built, create a new ``DDC-I Platform Project`` and
select ``qemu-arm``. In the project window, expand the ``qemu-arm`` project and
then ``Deos Components``. Right click on ``Dependencies`` and add a new
dependency. In the resulting window, select ``All`` in the registry filter drop
down menu and then select ``tutorial_653_configuration`` as a dependencies.

Next, in the project window expand ``Complete Integration`` and double click
on ``Components``. Expand ``platreg`` in the window that opens and then right
click on ``vfile`` and select ``Debug Variant``. Build the platform project by
right clicking on the project and selecting ``Project``.


Run the Deos project
--------------------

Click on the *Target Manager* window on near the top left corner of the screen
and click the left most button on that window to create a new target. The
tooltip for the button should read *New Remote Target*. Click OK to accept the
defaults and then click the play button.

QEMU will launch and the hello world message will print to the video monitor.

This concludes the tutorial.