.. role:: switch(samp) .. index:: PikeOS Topics .. _PikeOS_Topics: ============= PikeOS Topics ============= This appendix describes topics that are specific to the GNAT for PikeOS, a cross-development ARINC-653 system provided by SYSGO. .. _Kernel_Configuration_for_PikeOS: Kernel Configuration for PikeOS =============================== There are two possible ways to configure a PikeOS kernel: * SYSGO's set of command-line tools: *pikeos-cloneproject*, *pikeos-configure*, etc. * CODEO, a visually-oriented Integrated Development Environment based on the Eclipse framework. In the following sections, we will explain how to use these tools to build a PikeOS kernel so that Ada applications can be run on it. The procedures will mostly use CODEO; to know more about PikeOS kernel configuration, refers to the PikeOS user manual :title:`Installing and Using PikeOS`. In order to debug any application on target, a partition should run a tool called ``muxa``. ``muxa`` provides several development services, such as a target console, and some debug channels that can be connected to AdaCore's debugger. This will be illustrated by a simple scenario. The following instructions should help you build a simple kernel integration project in which Ada application can be run. .. _Creating_a_PikeOS_kernel_integration_project: Creating a PikeOS kernel integration project -------------------------------------------- To setup your PikeOS kernel project, please consult the PikeOS User Manual section 8 : ``Basic Steps of the PikeOS Build Process``. Be sure to pick the template ``devel-pikeos-native`` as it contains a project pre-configured with the major development features. .. _PikeOS_maximum_priority_setting: PikeOS maximum priority setting ------------------------------- You should now have a basic integration project; you can then configure it for Ada Ravenscar applications. In order to run Ada tasking applications on a PikeOS process, you should make sure that this process can handle 240 priority levels. To do so, in the ``Project Explorer``, double-click on :file:`vmit.xml`. This will open the ``Topology View``. In this ``Topology View``, in ``PartitionTable``, expand ``Partition`` => ``pikeos`` => ``ProcessList``, then click on ``ProcessEntry`` => ``Proc_pikeos``. In its attribute, change ``MaxPrio`` to 240. Then click on ``Partition`` => ``pikeos``. CODEO warns you about the fact that the process ``Proc_pikeos`` has a greater priority than its partitions; so upgrade the maximum priority for the partition as well. Set ``MaxPrio`` to 242. Then save your modifications. PikeOS interrupts ----------------- Please read comments in ``p4ext-cert-app.c`` runtime file for guidance on using interrupts. .. _PikeOS_Native_Personality_Extensions: PikeOS Native Personality Extensions ------------------------------------ Please note that with PikeOS 4.2 and up, GNAT Pro now relies on the PikeOS Native Personality extensions (p4ext) library shipped by SYSGO. For more information on it, you can consult the file ``pikeos-native-api-extensions.pdf`` that you can find in your PikeOS installation. .. _PikeOS_muxa_configuration: PikeOS muxa configuration ------------------------- As explained earlier, console and debugging functionalities are provided by a component called ``muxa`` that comes in two parts: one running on target, one running on host. This section will focus on how to configure your kernel integration project in order to include this component on target. How to run the host part will be explained latter in this chapter (in section :ref:`Debugging_an_Ada_application_on_PikeOS`). In the previously-created integration project in CODEO, double-click on :file:`project.xml.conf` in the ``Project Explorer``, to open the ``PikeOS Project Configuration``. Expand ``pikeos`` => ``service`` and click on ``muxa``. This will open a panel ``Configuration Options: muxa``. Change the settings to match your host/target configuration. In our case, as we are building a kernel for QEMU, the following values will do: * *mode:* networkfp * *Device:* eth0:/0 * *HostIP:* IP address of your host; * *HostPort:* port used by the host ``muxa``; say, 1501; * *TargetIP:* IP of the target as seen from target; say, 10.0.2.1 for QEMU; * *TargetPort:* Port on which the target ``muxa`` is listening; say, 1500; * *GatewayIP:* IP of the gateway from target; say, 10.0.2.2 for QEMU; * *ConfigPort:* Port of ``muxa``'s back office; say, 1550. You can also change these settings from the command line, with the command :: $ pikeos-configure --editor In order to have debug support for your particular user application, you will also need to make sure that it has access to the whole file system of the ``muxa`` partition. This is handled in the ``Topology View``. To access to it, click on :file:`vmit.xml` in the ``Project Explorer``. Then, expand ``Root->Default`` => ``PartitionTable`` and go your user partition: in this example, it is named ``Partition -> pikeos``. Expand this node, then the node ``FileAccessList`` and check that a node ``muxa:/*`` has all access rights (Stat, Read. Write, Read-Write). If not, you may add it by right-clicking on ``FileAccessList`` and selecting ``Add``. Your kernel integration project is now properly configured to host an Ada application. The following section will tell you how to build such an application and how to link it to the kernel. .. _Building_an_Ada_application_on_PikeOS: Building an Ada application on PikeOS ===================================== This section will give a basic example to illustrate how an Ada application targeting PikeOS can be built. Consider the following Ada program, to be copied in a file named :file:`hello.adb`: .. code-block:: ada with GNAT.IO; use GNAT.IO; procedure Hello is begin Put_Line ("Hello from Ada!"); end Hello; On ARM PikeOS, you can then build the Ada program and link it against this global handler with this command: :: $ gprbuild --target=arm-sysgo-pikeos --RTS=embedded -g hello.adb A similar command would be used on other CPUs; only the target and the prefix of tools would change (e.g. powerpc-sysgo-pikeos-gcc). In the rest of this tutorial, we will use arm-sysgo-pikeos; adapting it to your platform is just a matter of changing the prefix. This will generate a file :file:`hello`. You should then add this executable to your kernel integration project. Using the project created in the previous section :ref:`Kernel_Configuration_for_PikeOS`, here is how you would do: you would copy :file:`hello` into the directory :file:`target/`, rename it to :file:`pikeos` (as it is the name of the user application as specified in this project) and use ``make boot`` to link all pieces together: :: $ cp hello **/target/pikeos $ cd ** $ source ./PikeOS.sh $ make boot A file will be created: :file:`boot/pikeos-devel-native-qemu-arm-v7hf-qemu`; this is a PikeOS kernel running your simple Ada application. How to run it on QEMU will be explained in the next section. .. _Running_an_Ada_application_on_PikeOS: Running an Ada application on PikeOS ==================================== PikeOS and CODEO are integrated with a simulator called QEMU. This can be a simple way to run and test a PikeOS application. In the previous sections, we have seen how to create a PikeOS kernel targeted to this simulator, embedding a simple Ada application. `make boot` should give the proper command to run QEMU. .. _Debugging_an_Ada_application_on_PikeOS: Debugging an Ada application on PikeOS ====================================== Any application that should be debugged on PikeOS should call a routine named ``init_gdbstub`` at the early stages of its execution. To do so with GNAT, the simplest way will be to recompile the entry code of your Ada application. This entry point is a file named :file:`p4ext-cert-app.c` in the GNAT run-time library; the path to the GNAT run-time library is given by *arm-sysgo-pikeos-gnatls -v*. After copying it in your source directory, you can recompile it with the following command: :: $ arm-sysgo-pikeos-gcc -c -DDEBUG p4ext-cert-app.c -I$PIKEOS_TARGET_FILES/include/ Note the presence of an option :switch:`-DDEBUG`; it enables the gdbstub hook. After compiling it, you can link it to your application; in the case of our ``hello`` example, this build command would be: :: $ gprbuild --target=arm-sysgo-pikeos --RTS=embedded -f -g hello.adb \ -largs p4ext-cert-app.o -lgdbstub -ldebug Note that you should also link against :file:`libgdbstub.a` and :file:`libdebug.a` using the options :switch:`-lgdbstub -ldebug`. You can then recopy it in the integration project that we created in the previous sections and relink the kernel: :: $ cp hello /target/pikeos $ cd $ source ./PikeOS.sh $ make boot To run this on QEMU, specify several options to configure the network support properly, using the option ``-net`` and ``-redir``; these options are documented in the usage message of QEMU that you can get by doing ``qemu --help``. In our example, the proper set of options would be: :: -net nic -net user -redir udp:1500:10.0.2.1:1500 The next step is to launch the host ``muxa``. Run it in your kernel integration project (replacing ** by the actual name of your host machine): :: $ muxa --type eth --host :1550 --eth-host 0.0.0.0:1501 \ --eth-target :1500 You can then connect to it at :1550 and configure your console and debug channels. For example, to get a console: :: $ telnet 1550 Ok: Connected to server. muxa> lsn Ok: Channel list, target supports 16 channels. 0 pikeos/Proc_pikeos/dbg Host:free Port:0 Target:open (Uid:0x000,0x0016,0x0000) 4 Monitor Host:free Port:0 Target:open (Uid:0x000,0x0004,0x0000) 5 mon_con Host:free Port:0 Target:open (Uid:0x000,0x0004,0x0008) 6 traceserver Host:free Port:0 Target:open (Uid:0x000,0x0005,0x0000) muxa> connect mon_con Ok: connected help PikeOS Monitor Command Shell v1.0 Available commands: help Help on command sysinfo Info on system lsp List partition names pinfo Info on a Partition lsc List channels cinfo Info on a channel lsq List Queuing ports of a partition qinfo Info on a queuing port lss List sampling ports of a partition sinfo Info on a sampling port lse List processes of a partition einfo Info on a process lsm List memory requirements of a partition minfo Info on a memory requirement preboot Reboot a Partition phalt Halts a Partition treset Resets the target with the specified mode. kinfo Info on kernel structures ps Show Tasks/Threads Type ``help name`` to find out more about the command ``name``. :: PikeOS# lsp id name partd fctid lctid mprio mode 1 service 1.5 2 21 102 COLD_START 2 pikeos 1.6 22 22 242 COLD_START PikeOS# pinfo pikeos operating mode: COLD_START num_kpages: 8 free_kpages: 3 flags: 0 max prio: 242 part daemon: 1.6 first child task: 22 last child task: 22 proc count: 1 queuing port count: 0 sampling port count: 0 max. open files: 32 open files: 1 cookie: 0 To connect the application gdbstub to an host port, in order to debug your application: :: $ telnet 1550 Ok: Connected to server. muxa> lsn Ok: Channel list, target supports 16 channels. 0 pikeos/Proc_pikeos/dbg Host:free Port:0 Target:open (Uid:0x000,0x0016,0x0000) 4 Monitor Host:free Port:0 Target:open (Uid:0x000,0x0004,0x0000) 5 mon_con Host:connected Port:1550 Target:open (Uid:0x000,0x0004,0x0008) 6 traceserver Host:free Port:0 Target:open (Uid:0x000,0x0005,0x0000) muxa> connect 1551 pikeos/Proc_pikeos/dbg Ok: Connected channel You can then connect the debugger to :1551 using GDB's remote protocol, either from GNAT Studio or from the command line: :: (gdb) file hello (gdb) target remote :1551 Remote debugging using :1551 0x08011d84 in gdbarch_breakpoint () (gdb) l hello.adb:2 1 with GNAT.IO; use GNAT.IO; 2 3 procedure Hello is 4 begin 5 Put_Line ("Hello from Ada!"); 6 end; (gdb) b 5 Breakpoint 1 at 0x80101da: file hello.adb, line 5. (gdb) c Continuing. Breakpoint 1, hello () at hello.adb:5 5 Put_Line ("Hello from Ada!"); For further information about debugging with GNAT, refer to the :title:`GNAT User's Guide for Native Platforms` and to the :title:`GDB User's Manual`.