MARK Runtime Support

This chapter describes the MARK runtime environment and support. It contains the following sections:

• Subsystem Description
• MARK Programs
• Storage Management (storage_mangement.ss)
• Exceptions (exceptions.ss)
• Profiling

---

Subsystem Description

The MARK runtime environment can logically be broken into three groups of subsystems.

• Runtime Subsystems
• Predefined Subsystems
• Board Subsystems

Runtime Subsystems

Runtime Common Subsystems

runtimes.ss	Front end assist procedures
lower_runtimes	Units that are required by both predefined.ss and runtimes.ss
lower_rts.ss	Code generator assist procedures

Runtime No Tasking Subsystems

ada_tasking.ss	Ada tasking semantics.
ada_kernel.ss	Binding layer from ada_tasking onto microkernel
exceptions.ss	Exception handling
mark.ss	MARK specific
microkernel.ss	Microkernel for Rational Exec
storage_management.ss	Memory allocation/free

Runtime No Kernel Subsystem

no_kernel.ss

No kernel runtime replacement

Predefined Subsystems

lrm	Language Reference Manual
lower_runtimes	Units that are required by both predefined.ss and runtimes.ss
numerics	Numerics annex
predefined	Predefined Ada libraries, text_io, ...
rts_interface	Low level runtime interfaces
rts_vads_exec	Rational's vads_exec interfaces
target_defs	Target specific predefined support
vads	A few minor dependencies on original VADS sources.

Board Subsystems

The board specific subsystems are described more fully in other places in the documentation. Below each of the subsystems are listed and the other documentation is referenced.

board_common, krn_conf, no_krn_conf

An overview of these subsystems can be found in the Embedded Programming Guide.

Additional details are documented in the Configuring Rational Exec

real_time_systems, systems_programming,

Defined by the Ada LRM. These are board-specific since they have board specific configuration information.

mark_examples, models

These subsystems are described in MARK Examples: mark_examples.ss, ada_examples.ss, duo_examples.ss

---

MARK Programs

MARK applications support the full Ada LRM with the exception of the tasking related features. Delay statements are supported. Interrupt handling via Protected objects and rts_vads_exec.ss are supported. Storage management and exception handling are supported but can be selectively stubbed.

The following Runtime Subsystems are required:

runtimes.ss
lower_runtimes.ss
lower_rts.ss
mark.ss
ada_tasking.ss
ada_kernel.ss
microkernel.ss
exceptions.ss
storage_management.ss

---

Storage Management (storage_mangement.ss)

There are three different memory management implementations in the MARK environment. They are all subsets of the STANDARD environment.

The names of these implementations are smN, where N indicates the amount of memory management support. As N gets smaller, support gets smaller and smaller.

sm4	Full user implementation, not supported in MARK
sm3	MARK with full memory management support missing: automatic selection of storage pools fat heap
sm2	MARK with minimal memory management support missing: automatic selection of storage pools fat heap multiple collections - access types are not automatically cleaned up when the access type goes out of scope.
sm1	Kernel, not supported in MARK missing: automatic selection of storage pools fat heap multiple collections - access types are not automatically cleaned up when the access type goes out of scope. collections - all collections are removed slim heap alloc only No collection code at all
sm0	MARK with no memory management support missing: all support for storage pools, collections and allocators. Support for runtime memory allocation (no free) is supported.

sm4 Description

This is not part of the MARK implementation. The sm4 is used to identify the non-MARK, fully functional storage management facilities.

Each access type is allocated it's own collection. When the access type goes out of scope, all of the memory allocated to the collection is automatically reclaimed. For example:

declare
 type Foo ....;
 type Access_Foo is access Foo;
 The_Access_Foo : Access_Foo;
begin
 The_Access_Foo := new Foo;
 ...
end;
-- All memory associated with Access_Foo will be
-- deallocated implicitly.

All of the memory associated with Access_Foo is normally freed when the declare block is complete. In the sm2 implementation, only one collection and one pool will ever be available and the runtime call that is made to deallocate the collection has a null body.

sm3 Description

Missing:

• automatic allocation of storage pools.
• fat heap

The fat heap is a memory intensive but higher performance memory manager. It is not included in the MARK release.

The sm3 view is the most functional MARK view. It is the default view (that is, it is referenced in the Board Model).

Sm3 is simpler then the STANDARD model in that automatic storage pool allocation is never performed. Only one storage_pool is used in the runtime and that is the kernel_pool. The pool is a Heterogenous_Bounded_Pool that is normally given all of the heap memory during initialization. All dynamic allocations, from the runtime and the application, are made from this pool.

There is no tasking protection on any of the sm3 pools since MARK is a non-tasking environment.

The external_pool, default_pool and null_pool are aliases for the kernel_pool. This is set up in the V_Usr_Conf package in usr_conf.ss.

This view supports full Ada95 storage management with storage pools. User defined storage pools are supported and access types to controlled types get finalized when the access types go out of scope.

The "for access_type'storage_size use N" clause correctly limits the amount of storage but does not preallocate the storage. Preallocating storage can be done by explicitly creating a storage pool and associating it with an access type.

The default storage pool is a Heterogenuous_Bounded pool that is initialized with all of the heap space available to the target as configured in the Heap_Top, Heap_Bottom in krn_conf.ss/V_Krn_Conf.Configuration_Table. Normally this is all of the storage space available to the target. This pool layers on top of the Slim_Heap memory management scheme. Alternatively a Alloc_Only pool can be configured to replace the Heterogenuous_Bounded pool.

sm2 Description

The sm2 storage_management view is simpler then sm3. It only supports a single collection. Collections are required for the reasons enumerated below. If the desired application has no need for multiple collections then this simpler view can then be used. Like sm3, the sm2 view only supports one default storage pool and it is a Alloc_Only_Storage_Pool. This can be altered by the user as described below.

1 . In sm2, data can be tracked by the application and explicitly freed using Unchecked_Deallocation to reclaim the space if the underlying storage pool supports deallocation. The Alloc_Only pool does not support deallocation (see below).

This simplification is turned on by the Use_The_Default_Collection flag in the body of storage_management.collections (in the collection directory) which is set to True by default in the sm2 view. This makes some of the code dead in the package. This code will be eliminated by the compiler.

2 . The clause: for access_type'Storage_Size use N is not supported. In sm3 the data would not be preallocated, however the limit would be checked. Since only one collection is used this feature is not supported in sm2.

3 . Access to types that have controlled components are not finalized correctly when the access type goes out of scope. In the following example:

declare
 type Foo is record
  member: A_Controlled_Type;
  -- ...
 end record;
 type Access_Foo is access Foo;
 The_Access_Foo : Access_Foo;
begin
 The_Access_Foo := new Foo;
 ...
end;

In sm3 and sm4, when the access type goes out of scope each of the allocated elements finalize the controlled subcomponents of the elements.

4 . Non default storage pools are not supported. All cells are allocated from collections. Since there is only one collection, it must be attached to the default storage pool and can not be attached to a locally defined storage pool.

5 . Default pool is the Alloc_Only_Bounded_Pool. This can be changed to the Heterogeneous_Bounded_Pool by changing the file:

kernel/storage_management.storage_pools.rational.storage_pools.kernel.2.ada

Change the following two lines of code from:

-- Select either the Alloc_Only_Bounded_Pool or Heterogeneous_Bounded_Pool
Alloc_Only_Bounded_Pool

To:

Heterogeneous_Bounded_Pool

Change these two lines from:

-- Reclaimable is not supported for the Alloc_Only_Bounded_Pool
Reclaimable_Supported : constant Boolean := False;

To:

Reclaimable_Supported : constant Boolean := True;

The code for the Heterogeneous_Bounded_Pool will need to be extracted from the sm3 version of the storage management view.

The Alloc_Only pool does not allow deallocations of any kind. Memory from this pool is simply allocated and aligned correctly. For many safety critical applications this pool allows the use of limited memory management during initialization.

The Alloc_Only pool has the additional procedure Allocations_Complete. After Allocations_Complete is invoked, allocations raise storage_error. This is typically used to allow library level unit elaboration memory allocation and then a call to Allocations_Complete on the pool to disallow any further memory allocation.

6 . Pragma Collection is not supported.

7 . Pragma Main (Heap_Size => ...) and pragma Main (Heap_Extend => ...) are not supported. There is only one storage pool and it is configured via the Heap_Top, Heap_Bottom in krn_conf.ss/V_Krn_Conf.Configuration_Table.

sm0 Description

No storage pools, collections, or Ada memory allocators are supported by sm0. A minimum amount of storage management is allowed to support C type memory allocation.

It is possible to explicitly call the memory complete function to insure that no further memory allocations will be performed at any point in the application. Normally this will be done early in the main subprogram.

It is possible to use the simple memory allocation scheme provided by sm0 within the application as well. This might be useful for applications that need a fixed amount of dynamic memory allocated during program elaboration or initialization but not during normal execution. This mechanism should be used judiciously since the normal Ada protections are not in place.

The program sm0_alloc.2.ada in the mark_examples.ss subsystem duplicated below provides an example. Always check the product release views for the most recent copy of files in mark_examples.ss

with System;
with System.Storage_Elements;
with Storage_Management;
with Unchecked_Conversion;
with All_Contribution;

procedure Sm0_Alloc is
    type Access_Integer is access Integer;
 -- Setting 'Storage_Size to 0 indicates no memory allocator
 -- can be used for the Access_Integer and therefor no
 -- collection is required.
    for Access_Integer'Storage_Size use 0;
    function To_Access_Integer is new Unchecked_Conversion
               (System.Address, Access_Integer);A1, A2, A3 : Access_Integer;
begin
    -- The number of storage elements for an integer is
    -- Integer'size/Storage_Unit
    A1 := To_Access_Integer (Storage_Management.Aa_Support.Aa_Global_New
               (System.Storage_Elements.Storage_Offset
               (Integer'Size / System.Storage_Unit)));
    A1.all := 1;
    A2 := To_Access_Integer (Storage_Management.Aa_Support.Aa_Global_New
               (System.Storage_Elements.Storage_Offset
               (Integer'Size / System.Storage_Unit)));
    A2.all := A1.all;
    Storage_Management.Storage_Mangement_Allocations_Complete;

    -- No further memory allocations are allowed.
    -- This allocation will raise an exception.  In the debugger
    -- try Debug => Catch All to catch the exception raised when
    -- the memory allocation is attempted below.

    A3 := To_Access_Integer (Storage_Management.Aa_Support.Aa_Global_New
                            (System.Storage_Elements.Storage_Offset
                            (Integer'Size / System.Storage_Unit)));
end Sm0_Alloc;

Storage Management Basics

The architecture of the storage management system is described in the "Memory Management" chapter in the Using the Ada Runtime Guide.

The initialization of storage management is called during the elaboration of V_Krn_Conf.V_Start_Program when V_Krn_Conf_I.V_Boot is called.

At this time, the Debug_Block.Kernel_Pool_Address is initialized with the kernel storage pool returned from Storage_Management.Kernel.Krn_Conf_Pool_Initialize in storage_management.ss.

By default, this kernel pool is given all of the heap storage as defined by V_Krn_Conf.Configuration_Table.Heap_Stack_Bottom/Heap_Stack_Top Normally Heap_Stack_Bottom is determined dynamically by looking through the group tables of the MARK application. See V_Krn_Conf.Auto_Config_Heap_Stack_Bottom for more details.

sm0 Implementation.

The implementation of the kernel pool for sm0 is quite limited. The state of the runtime heap is kept in the package level variable The_Runtime_Heap which includes the fields:

Bottom	Bottom of heap, constant.
Top	One past the top of the heap, constant.
Free_Bottom	Location of the next block to allocate
Allocations_Complete	Set to true when allocations are to be disallowed

Memory is allocated from the Free_Bottom. Memory is never freed.

The kernel pool supplies the directly callable routines that are advertised through external names.

Krn_Conf_Pool_Initialize	Initialize pool
Krn_Conf_Pool_Size	Return the original size of pool
Krn_Conf_Allocate	Allocate from the pool
Krn_Conf_Deallocate	Deallocate - not supported

The small amount of dynamically allocated memory required by the microkernel.ss uses Krn_Conf_Allocate.

The rest of the subsystems allocate memory from Storage_Managemen.Aa_Support:

Aa_No_Exception_Global_New	allocate from heap
Aa_Global_New	allocate from heap raise exception on failure
Aa_Global_Free	noop, deallocation not supported

Storage_Management.Aa_Support errors:

All of the following subprograms are mapped to Storage_Management.Storage_Management_Error:

Aa_Aligned_New

Aa_Local_New

Aa_Local_Free

Extend_Intr_Heap

Get_Intr_Heap_Size

Storage_Managemen.Storage_Management_Configuration has a single procedure, Storage_Management_Error which IS called when storage management has detected an unrecoverable error.

Normally an exception is raised at this point, but application specific code could be provided.

---

Exceptions (exceptions.ss)

There are two exception views ex1 and ex0. Ex1 is a full exception unwinding implementation. The ex1 is the Default view. It is referenced in the Board Model

Ex0 does not support exceptions. Any exceptions cause the program to terminate abnormally. It is still possible to use the debugger catch all command to stop a program when an exception is raised.

---

Profiling

Standard Profiling

For the STANDARD product, profiling is implemented by setting the 'PROFILING: prof' context switch in a view. This causes the prelinker to insert the additional elaboration table entry: "__START_PROFILING".

To enable profiling, both the user program and the kernel must be built with this switch. The V_Krn_Conf.Start_Profiling call does any required initialization for the kernel. Similarly the application program when elaborated invokes __START_PROFILING located in the profiling archive library.

Power PC Specifics

The Power PC board support packages provided by Rational use the Decrementer for alarm management and profiling. Kernel initialization for profiling never initializes the Decrementer with a value larger than the profiling interval. Large alarm times are implemented using multiple increments of the profiling interval. The profiling library code linked with the application attaches an interrupt handler to the Decrementer interrupt to increment the histogram array and also call the initial interrupt handler.

i386 Specifics

MARK requires no special profiling support for the example i386_pc. The profiling supplied by the STANDARD kernel configuration works without changes.