13. Developing Ada Applications for DDC-I Deos

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.

13.1. Installing GNATbench

13.1.1. 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.

13.1.2. 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.

13.1.3. 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:

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.

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

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

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.

Click Add to add the Eclipse repository.

Once done, GNATbench can now be installed:

Click the Add button on the Install window again.

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.

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.

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.

13.1.4. 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.

13.2. 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.

13.2.1. 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.

13.2.2. 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:

Right click on the hello_world project.

Select the New → Other... menu item.

From the Select a wizard dialog, expand the Ada folder and select Convert an empty DDC-I Executable Project to use Ada Language.

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.

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.

13.2.3. 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:

Expand the hello_world project in the DDC-I Project window.

Expand Deos Component, right click on Dependencies and select Add Dependency.

Select ansi from the drop down menu.

Repeat for the gnu-language and vfile components.

13.2.4. 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:

Change the tlsSpaceInBytes attribute to 128.

Change ramPagesQuota to 100. If you cannot find ramPagesQuota, continue to the next step.

Save hello_world.pd.xml and rebuild the project by right clicking on the hello_world project and select Rebuild Project.

If you could not find ramPagesQuota before, expand the logicalMemoryPools attribute and the pool attribute within it. Change the pagesNeeded attribute to 100.

At the bottom of the hello_world.pd.xml window, select Source. Add the following XML code after </logicalMemoryPools>:

<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.

13.2.5. 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).

13.2.6. 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.

13.2.7. 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:

13.3. 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.

13.3.1. 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.

13.3.2. 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:

Right click on the hello_653 project.

Select the New → Other... menu item.

From the Select a wizard dialog, expand the Ada folder and select Convert an empty DDC-I Executable Project to use Ada Language.

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.

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.

13.3.3. 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:

Expand the hello_653 project in the DDC-I Project window.

Expand Deos Component, right click on Dependencies and select Add Dependency.

Select ansi from the drop down menu.

Repeat for the gnu-language, deos-653-p1 and vfile components.

13.3.4. 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:

<?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.

13.3.5. 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).

13.3.6. 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:

Enter tutorial_653_configuration as the project name.

Select Deos Metadata Project as the Project Type.

Select ARM as the target.

Click the Finish button to create the tutorial_653_configuration project.

13.3.7. 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.

13.3.8. 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:

<?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.

13.3.9. 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.

13.3.10. 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.