Workbench/VxWorks 653 Topics
****************************

Integration of the Simulation Environment in Workbench
======================================================

Building a System
------------------

A **VxWorks 653** system can be configured and built in the usual way, either
from the command line or from within Workbench. See the **VxWorks 653** user
manuals for general instructions, or the **GNATbench** tutorial available in
**Workbench** via :guilabel:`Help --> Help Contents --> GNATbench Ada
Development User Guide --> Tutorial: Creating a VxWorks 653 Integration Project`.
If using the latter, follow the instructions given for a **QEMU** BSP.

Creating a ROM Image
--------------------

The **VxWorks 653** build system generates separate image files for each
component. These images have to be gathered into a single ROM image in
order to be executed by **GNATemulator**. To simplify this unification
procedure, we provide the :command:`powerpc-wrs-vxworksae-romgen` tool. It 
automatically extracts the list of partitions and their respective
locations from the :file:`configRecord.xml` file and uses this data to
automatically build the final ROM image.

To use generate a ROM image from a **VxWorks 653** system under **Workbench**,
add a build target, e.g. :file:`qemu_system.flash` to the integration project.
Let's call this build target ``KERNEL_IMAGE`` in further discussion.

In the :file:`Makefile` for the integration project, append ``KERNEL_IMAGE`` to
the prerequites of the :command:`all` target, e.g.

.. code-block:: console

   all: <other targets> KERNEL_IMAGE

Then add a target for the image:

.. code-block:: console

   KERNEL_IMAGE: rom
   	powerpc-wrs-vxworksae-romgen -o KERNEL_IMAGE

Note that the second line starts with a <tab> character, not spaces.

If using a :file:`Makefile` for the integration project from the command line,
you can omit the step of adding the build target, and still make the changes to
the :file:`Makefile`.

Running the System
------------------

The simulator can easily be run from the **Workbench** interface. To do so:

#. Click on :guilabel:`External Tools Configuration...` in the menu entry
   :menuselection:`Run --> External Tools`.

#. Select :guilabel:`Program` and click on the :guilabel:`New` button.

#. In :guilabel:`Location` enter :command:`powerpc-wrs-vxworksae-gnatemu` with
   its full path (e.g.
   :file:`%GNATEMULATOR_INSTALL_DIR%\\bin\\powerpc-wrs-vxworksae-gnatemu.exe`).

#. In the :guilabel:`Working Directory` browse to the directory containing
   `KERNEL_IMAGE` and select it.

#. In the :guilabel:`Arguments` section enter the arguments to pass to
   :command:`powerpc-wrs-vxworksae-gnatemu`. See :ref:`using-gnatemulator`
   for the available options.  You should add  :option:`--wdb` to
   enable target server connections.

#. Under the :guilabel:`Build` tab, uncheck
   :guilabel:`Build before launch` in order to avoid systematic recompilation
   when you start the simulation environment.

Clicking on :guilabel:`Run` will save the configuration and run the
system. The simulation platform can then be easily accessed from the
**Workbench** toolbar in the Advanced Development perspective via the green
:guilabel:`External Tools` icon.

Creating a Target Server
------------------------

The Wind River Debug Server (DFW) can connect to **GNATemulator** for VxWorks
653 using the ``wdbrpc`` backend that will use the ethernet connection
available in **GNATemulator**.

To create a new target server for **GNATemulator** for VxWorks 653:

#. Click on :guilabel:`New Connection...` in the :guilabel:`Target` menu of
   Workbench.

#. Select :guilabel:`Wind River VxWorks 653 Target Server Connection` as the
   system type.

#. In the :guilabel:`Target Server Options` page, select :guilabel:`wdbrpc` as
   the Backend, set the IP address to ``127.0.0.1`` and the port to
   ``17185``.

#. Set the Kernel image using the :file:`boot.txt` file.

#. To complete the setup of the target server you can keep the other fields
to their default values.

Adapting QEMU for VxWorks 653 to other Contexts
===============================================

Starting QEMU for VxWorks Manually
----------------------------------

You can start manually :command:`powerpc-wrs-vxworksae-gnatemu` using these
following options:

.. code-block:: console

   $ powerpc-wrs-vxworksae-gnatemu [--wdb] KERNEL_IMAGE

Where ``KERNEL_IMAGE`` is the path to your kernel image.


Limitations
===========

The following elements should be taken into account when using **GNAT Emulator** for
VxWorks 653:

#. The time reported to the guest operating system (here VxWorks 653) is
   based on the host OS time. The host OS is a time sharing OS (and not a
   real-time OS), which can lead to situations where QEMU is rescheduled or
   preempted by another host process, which in turn makes the VxWorks 653
   OS miss certain deadlines. That may trigger error handlers in VxWorks
   653. This means that you should avoid loading your host machine when
   running QEMU.

   See in :ref:`health_monitor_configuration` an example of health monitor
   configuration that avoid unexpected simulator halts.

#. **GNAT Emulator** is translating and executing instructions as fast as 
   possible and thus won't be cycle accurate. This means for example that
   within a frame defined by the active VxWorks 653 schedule, processing
   can be faster than on the final target.

#. When **GNAT Emulator** is executing the VxWorks 653 operating system 
   it will preempt all CPU available and allowed by its priority. The
   rest of the Windows system may become hardly usable because of a lack
   of CPU resources allocated to the rest of the system. This is particularly
   true on monocore host machines.

   If you don't have a multicore system, it is advised to start **GNAT Emulator**
   with the following command:

   .. code-block:: console

      > start /LOW powerpc-wrs-vxworksae-gnatemu


.. _health_monitor_configuration:

Health Monitor Configuration
============================

Here is an example of health monitor configuration that can be used to
avoid a simulator stop in case of tick loss:

.. code-block:: xml

  <HealthMonitor>
    <SystemHMTable Name="systemHm">
      <SystemState SystemState="HM_PARTITION_MODE">
        <ErrorIDLevel ErrorIdentifier="HME_DEFAULT"
                      ErrorLevel="HM_MODULE_LVL"/>
      </SystemState>
      <SystemState SystemState="HM_MODULE_MODE">
        <ErrorIDLevel ErrorIdentifier="HME_DEFAULT"
                      ErrorLevel="HM_MODULE_LVL"/>
      </SystemState>
      <SystemState SystemState="HM_PROCESS_MODE">
        <ErrorIDLevel ErrorIdentifier="HME_APPLICATION_ERROR"
                      ErrorLevel="HM_MODULE_LVL"/>
      </SystemState>
    </SystemHMTable>
    <ModuleHMTable Name="moduleHm">
      <SystemState>
        <ErrorIDAction ErrorIdentifier="HME_DEFAULT"
                       ErrorAction="hmDbg_DH_EventShow"/>
      </SystemState>
      <SystemState>
        <ErrorIDAction ErrorIdentifier="HME_APPLICATION_ERROR"
                       ErrorAction="hmDbg_DH_EventShow"/>
      </SystemState>
      <SystemState>
        <ErrorIDAction ErrorIdentifier="HME_LOST_TICKS"
                       ErrorAction=""/>
      </SystemState>
      <Settings stackSize="0x0400" maxQueueDepth="2" />
    </ModuleHMTable>
    <PartitionHMTable Name="helloHm">
      <SystemState>
        <ErrorIDAction ErrorIdentifier="HME_DEFAULT" ErrorAction=""/>
      </SystemState>
      <Settings stackSize="0x0400" maxQueueDepth="2" />
    </PartitionHMTable>
  </HealthMonitor>


