Getting Started

The following topics are covered in this section:

• File > New > New Source Release
• MARK Examples: mark_examples.ss, ada_examples.ss, duo_examples.ss
• Ada I/O
• Application Pragmas
• Debugging

---

File > New > New Source Release

The File > New > New Source Release command is used to create a set of working views to be used for Minimal Ada Runtime Kernel (MARK) development.

In order to modify a set of MARK views you must copy the views that comprise a MARK release and work in those views. The MARK product consists of multiple views per subsystem making the use of view configurations difficult. Using the File > New > New Source Release dialog simplifies the process of creating the views.

New Source Release Views Dialog Box Fields

Source Ada Model

Enter the fully qualified path name to one of the models views that is part of the MARK area you want to copy. You can specify any model with ".mark" in the view name. The model is used to identify the base location for the subsystems containing the MARK views, and the version number for the MARK views. All "mark" views in the same base location, and with the same version number will be copied. For example, for the PowerPC product, if you specify /tools/rational/base/ada/model.ss/power.rx_ppc.issim.src.ada95.mark.4.0.0.rel as the Source Ada Model, the set of views that will be copied are /tools/rational/base/ada/*.ss/power.rx_ppc*mark.4.0.0.rel.

Destination Base

If you need to keep the new MARK views in the same subsystems as the source MARK views, leave this field blank. If you wish to create new subsystems elsewhere, enter the fully qualified path to the subsystem parent directory. For example, entering /usr/bob/my_mark will create /usr/bob/my_mark/model.ss, /usr/bob/my_mark/lrm.ss, etc.

Destination View ID

View names include a string between ada95 and the .rel or .wrk extension. This string is the View ID. In the views that were shipped with your Apex release, the view ID is a sequence of numbers (for example, 4.0.0). If you enter a value here, it will replace the original View ID in your destination MARK views. If you do not enter a value, the original View ID will be used.

Note: You must enter a value for Destination Base and/or Destination View ID. Leaving both fields blank is tantamount to asking Apex to overwrite the original MARK views, which is an error.

Destination Ada Model

This section of the dialog shows a Subsystem and View. These values are computed dynamically as you change the fields above. The purpose of this section is to help you understand the exact subsystem and view structure you will create with this dialog.

Code Destination Views

Selecting this toggle will result in code being run in each of the destination MARK views (except views in model.ss and key.ss). The default is True.

Overwrite Destination Views if they Exist

The default is False.

Verbose

Selecting this toggle will show extra information during creation/editing of views. For example, changes to Policy/Switches files in the destination views are shown.

Copy All BSPs

The default behavior is to copy the BSP specified in the Source Ada Model and all the non-BSP-specific MARK views (for example, lrm.ss views, etc). If you wish to copy other MARK BSP views as well, select this toggle.

Effort Only

Setting this to True will result in a list of the destination MARK views being printed to the message window. No views will be created.

The default is False.

Who should see new models in the Model Navigator?

The set of views you will create using this dialog includes new models. The Who should see new models in the Model Navigator section of the dialog effects the visibility of the models you are about to create when using the Model Navigator dialog.

Select one of the three radio buttons described below depending on the level of visibility you wish to give the new models.

Note: If the new models you create reside under $APEX_BASE/ada/model.ss and $APEX_BASE/c++/model.ss, they will be visible to all users no matter which radio button you choose.

Note: Your choice does not effect the "usability" of the models. It only effects who will see them when using the Model Navigator.

• Nobody

  Select this radio button if you no not expect that you or anyone else will use the Model Navigator to look for the new models.

• Just Me

  Select this radio button if you expect to look for the new models using the Model Navigator, but don't intend on sharing the models with other users. In this case, the models will be stored in an Apex project file relative to your home directory: ~/.Rational/user_models.just_me.apexprj.

• Everyone

  Select this radio button if you expect that others will look for the new models using the Model Navigator. In this case, the models will be stored in an Apex project file relative to $APEX_LOCAL_DIR:

  $APEX_LOCAL_DIR/editor_files/user_models.everyone.apexprj. 
  

  Selecting Everyone will fail if the environment variable APEX_LOCAL_DIR is not correctly defined. To set this variable, follow the directions in the "Establishing a Group Wide Environment".

Note: Models added to either project file will only be visible to a user after they re-load their project files. This is done by pressing the Apply button on the Setup dialog. This dialog is available via the Setup... button on the Main dialog, or via the directory viewer's File > Setup menu.

Storage for Destination Subsystems

If you are creating new subsystems, you have the option of specifying a storage location for them. This location should exist before running File > New > New Source Release.

The storage location will hold the new subsystems and (unless you specify a value for Storage for Destination Views) the new views as well.

An explicitly specified storage location will override the APEX_STORAGE environment variable if it is set. In addition, explicitly specifying "" (two double quotes) or NO_STORAGE as the storage location will result in the views being stored in place, overriding APEX_STORAGE.

Storage for Destination Views

The storage location specified here will hold the new views. If no location is specified the views will be stored in the same location used to create the subsystems.

An explicitly specified storage location will override the APEX_STORAGE environment variable if it is set. Explicitly specifying "" (two double quotes) or NO_STORAGE as the storage location will result in the views being stored in place, again overriding APEX_STORAGE.

---

MARK Examples: mark_examples.ss, ada_examples.ss, duo_examples.ss

There are a number of test views provided for MARK in the mark_examples.ss. The views contain Ada code examples which can be used to test and demo various features of MARK on a release after it has been installed. Each subdirectory in the view contains a different example or a group of closely related examples. Additionally, each subdirectory contains a README file which describes the example(s) present and any special steps needed to build and run them.

The standard ada_examples subsystem has mark views. In addition, there are the following mark_examples variants for each Board:

.sm?.ex?

The test views using the various variations of storage_management.ss and exceptions.ss. See Storage Management (storage_mangement.ss) and Exceptions (exceptions.ss) for more details about the variation.

Each example subprogram is a normal Ada subprogram with the addition of the line:

with All_Contribution;

The All_Contribution package specification captures the difference between a typical MARK program and a STANDARD program. STANDARD programs get runtime archives and board support program units implicitly contributed to the program closure during the link phase. A MARK program explicitly "with"s all of the program units in the board support package and the runtime.

An example All_Contribution will look something like this:

-- The name is Foo_Contribution where Foo is the name of the subsystem
-- of the runtimes

-- All programs can use the following subsystems
with Lower_Runtimes_Contribution;
with Runtimes_Contribution;
...

As the comments indicate, the program units in the "with" are the name of subsystem with the contribution suffix. In each of the corresponding subsystem views, this package will exist with all of the program units that the subsystem contributes to the closure.

For example if the imports are examined for the mark_example there will be a lower_runtimes.ss view in the import closure (try the show_imports command). This view will contain a program unit lower_runtimes_contribution.1.ada which will in turn with all of the units contributed by this view.

---

Ada I/O

The default MARK environment supports the complete Ada IO system as defined in the LRM and implemented by packages in the predefined.ss subsystem. This has been made available for debugging and testing applications. It is not intended for Ada I/O to be supported in the deployed MARK application. There are a number of reasons that Ada I/O is not desirable in a deployed application:

1 . Host debug environment is required. The I/O helper process and the file system are executing on the host.

2 . The size of Ada I/O is substantial. Text_Io, Sequential_Io, ... and the forms handling are large general purpose implementations.

3 . The performance of Ada I/O is not sufficient for embedded applications. The Ada I/O system is polled. All messages sent from the Target to the Host are acknowledged and while waiting for the acknowledgment the processor is spinning with interrupts disabled within TDM.

Ada I/O Requirements

Ada I/O requires exception handling. This implies that a .ex1. view from exceptions.ss must be on the closure.

Ada I/O requires memory management. This implies that .sm2. or .sm3. view from storage_mangement.ss must be on the closure.

Simple_Io

The Simple_Io package allows messages to be displayed on standard output when apex_execute or apex_debug are used to run an executable. Simple_Io requires no memory management or exception handling so it is available in all environments.

---

Application Pragmas

A pragma.1.ada file with the following contents can be added to all MARK views:

pragma Restrictions (No_Abort_Statements);
pragma Restrictions (Max_Asynchronous_Select_Nesting => 0);

Aborts and Asynchronous Transfer of Control only apply to tasking applications. The compiler, however, can not determine that the unit being compiled will be included only in a non-tasking environment (or more specifically an environment which does not require aborts or Asynchronous Task Control). These pragmas instruct the compiler that these constructs are not required.

The compiler can also check for compiler generated implicit memory allocation. This can be done using:

pragma Restrictions (No_Implicit_Heap_Allocations);

The .sm0 view does not support memory allocation. It should include the following restriction pragma:

pragma Restrictions (No_Allocators);

---

Debugging

Debugging MARK applications requires no special knowledge. There are, however, a few places where the debugging experience requires some explanation.

Could only read x out of x bytes from 03fffe0

The stack for a MARK program is normally set to the top of the real memory provided by the board. Often times when debugging a MARK program the stack pointer is very close to the top of the stack and therefore very close to the top of the available memory. Because of this, the debugger will display a harmless warning that might look something like:

 === Could only read 0 out of 4 bytes from 03fffe0

The way to remove this error message is to let the debugger know where available memory is located via the set memory debugger command. If the board only has RAM available from 0..03ffffff the following debugger command could be entered:

:set memory 0..0ffffffff rw
:set memory 0400000..0ffffffff --

The first set memory indicates all memory is readable or writable. The second command indicates that memory addressed 0400000 and larger is not available for reading or writing.

cannot obtain value for KERNEL_VOX from Switch file

In non-MARK environments, the debugger optionally reads the symbols from the kernel object to improve debugging. The MARK application does not have a separate kernel since the non-tasking portion of the microkernel is included in the link closure of the MARK program. This message can be ignored or a KERNEL_VOX Context Switch (Policy/Switch) can be added:

 KERNEL_VOX: NO_KERNEL