6 The Modula-2 Run-Time System

The Modula-2 run-time system is contained in the library "$(M2LIB)libm2lib.a" (tools) or "$(M2LIB)libm2libcarbon.a" (carbon applications). It contains a number of program-launch initializations and auxiliary procedures as well as run-time routines for processes, termination and exception handling. The arithmetic routines for the type "BCD" are also part of the runtime system. In addition, the library contains the standard library and the p1 enhancements.

The debugger is incorporated into the library "$(M2LIB)libm2dlib.a" / "$(M2LIB)libm2dlibcarbon.a".

6.1 Initialization Process

Before a Modula-2 program is executed the runtime kernel has to be initialized. This initialization procedure sets up some global data structures (e.g. the process descriptor for the main process, termination chain, exception handler chain with default exception handler), allocates software traps, and finally executes the main module.

The manual call of this procedure (e. g. for standalone code or language mixing) is described in section 4.4.2.2.

The main entry point ("_main")—the address where program execution starts—for each Modula-2 program is the initialization procedure of the runtime kernel. After some global initializations (see above) the module body of the main module ("M2_MAIN_MODULE") is executed.

To be able to conform to the rules laid down by the standard the initialization sequence is finally established at run time. For this purpose the compiler places a call to the module body of each imported module at the beginning of the initialization part of every module.

During the initialization a linked list of the module descriptors of all the initialized modules is built up. This list is used internally by the Modula-2 debugger.

6.2 Run-Time Errors

The run-time system allocates software traps (PPC) resp. calls to the runtime system (Intel) for the handling and reporting of run-time errors. The module "M2SysTrap", which is automatically linked into every program, informs the program every time a software or hardware trap is handled, so that this can be dealt with in accordance with the standard (cf. 6.2.1 / 6.2.2).

Not only those error conditions which the standard demands be detected, but also all others (like address error, bus error etc.) are intercepted and set up for processing by the program. All the various error conditions are described in detail in sections 2.11.3 (Predefined Exception Conditions) and in the "Library" part of the manual (SysExceptions).

6.2.1 Details for Command Line Tools

When a run-time error occurs, the run-time system differentiates three possible situations:
  1. The debugger is present
  2. The debugger is not present but a private exception handler has been installed (cf. 2.7)
  3. Neither debugger nor exception hander are present
In case (a) the debugger is activated (cf. Part 3 "Utilities", section 1.3).

In case (b) the tools continues with the according exception handler.

In case (c) the tools is terminated with with exit code 1 unless the user specified an other exit code by a call to SYSTEM.SETEXITCODE (cf. 4.1.4).

6.2.2 Details for Applications

When a run-time error occurs, the run-time system differentiates three possible situations:
  1. The debugger is present
  2. The debugger is not present but a private exception handler has been installed (cf. 2.7)
  3. Neither debugger nor exception hander are present

In cases (a) and (c) a window of the following form normally appears (cf. Part 3 "Utilities", section 1.3):


Error dialog

Besides the error text, the name of the Modula-2 module, the procedure number and the program counter (PC) relative to the start of the procedure are shown in this dialog. The buttons "up" and "down" can be used to inspect the entire hierarchy of calls. The module name "????" signifies a departure from the Modula-2 environment.

Depending on the type of error and its circumstances not all buttons are always enabled. If "BREAK" is called, or a break point has been reached, the "Handler" button is disabled because no exception condition prevails. In cases of serious errors the "Resume" button cannot be used. The "M2 Debugger" button is only enabled if the debugger is actually present.

Calls to routines from SysExceptions (cf. "Library", section 2.3.4) can be used to control whether or not the dialog should appear in cases (b) and (c). A special debugger dialog (cf. "Utilities", section 1.5.4) controls whether or not it should appear in case (a).

6.2.3 Handling of KILL Signals

For tools (restriction in V8.1), signals issued for "kill -term " and "kill -int " are caught.

6.3 Global Data Structures

6.3.1 Procedure Stack

6.3.1.1 Ppc Runtime

The following diagram illustrates the structure of the stack as seen from the point of view of a procedure. SP0 and SP signify various values of the stack pointer.
SP0:immediately before the procedure is called
SP:before executing the first statement of the procedure

In all the following diagrams memory addresses increase towards the top.

            |                                   |
            |-----------------------------------|<-*--------------*
            |                                   |                   \
                                                                     \
            |         Parameter area            |                     \
                                                                       \
            |                                   |                       \
            |-----------------------------------|<-*                     \
            |            reserved               |   \                     \
            |-----------------------------------|    \                     \
            |            reserved               |     \                     Caller
            |-----------------------------------|      \                   /
            |            reserved               |       \                 /
            |-----------------------------------|        Linkage area    /
            |            Saved LR               |       /               /
            |-----------------------------------|      /               /
            |            Saved CR               |     /               /
            |-----------------------------------|    /               /
            |            Saved SP               |   /               /
SP0 ->      |-----------------------------------|<-*--------------*
            |        Saved static link          |    Only if used
            |--------- -------------------------|
            |                                   |
                    
            |        saved registers            |    procedures with exception handler: all
                    
            |                                   |
            |-----------------------------------|
            |                                   |
                    
            | copies of reference parameters    |
                    
            |                                   |
            |-----------------------------------|
            |                                   |
                    
            |        local variables            |
                    
            |                                   |
            |-----------------------------------|<-*
            | entry point termination procedure |   \
            |-----------------------------------|    only global modules with "FINAL"-part
            |        termination link           |   /
            |-----------------------------------|<-*
            | return-addr for exception part.   |   \
            |-----------------------------------|    only modules with exception handling
            | retry-addr for exception part.    |   /
            |-----------------------------------|<-*
            | actMessage                        |   \
            |-----------------------------------|    \
            | actNumber                         |     \
            |-----------------------------------|      \
            | actSource                         |       \
            |-----------------------------------|        \
            | saveInfo                          |         only if exception handler present
            |-----------------------------------|        /
            | SP                                |       /
            |-----------------------------------|      /
            | entry point exception handler     |     /
            |-----------------------------------|    /
            | exception link                    |   /
            |-----------------------------------|<-*
            |                                   |
                    
            |    space for auxiliary variables  |
                    
            |                                   |
            |                                   |
            |-----------------------------------|<-*--------------*
            |                                   |                  \
                                                                    \
            |         Parameter area            |                    \
                                                                      \
            |                                   |                      \
            |-----------------------------------|<-*                    \
            |            reserved               |   \                    \
            |-----------------------------------|    \                    \
            |            reserved               |     \                    Callee
            |-----------------------------------|      \                  /
            |            reserved               |       \                /
            |-----------------------------------|        Linkage area   /
            |            Saved LR               |       /              /
            |-----------------------------------|      /              /
            |            Saved CR               |     /              /
            |-----------------------------------|    /              /
            |            Saved SP               |   /              /
SP ---->    |-----------------------------------|<-*--------------*

6.3.1.2 Intel 32-Bit Runtime

The following diagram illustrates the structure of the stack as seen from the point of view of a procedure. FP and SP signify values of the frame pointer and the stack pointer.
FP:frame pointer after the procedure prolog is executed
SP:stack pointer before the call to another procedure

In all the following diagrams memory addresses increase towards the top.

                    |                                   |
                    |-----------------------------------|<-*--------------*
                    |                                   |                  \
                                                                            \
                    |        Parameter area             |                    \
                                                                              \
                                                                               Caller
                    | -  -  -  -  -  -  -  -  -  -  -  -|                     /
                    |           (SELF)                  |                    /
                    | -  -  -  -  -  -  -  -  -  -  -  -|                   /
                    |         (memory result address)   |                  /
                    |-----------------------------------|<-*--------------*     <- 16-byte-boundary
                    |           Saved ret adr           |
                    |-----------------------------------|
                    |           Saved FP (%ebp)         |
FP ------------>    |-----------------------------------|
                    |           Saved SL (%esi)         |
                    |-----------------------------------|
                    |           Saved GP (%edi)         |
                    |-----------------------------------|
                    |           Saved PB (%ebx)         |
                    |-----------------------------------|
                    |                                   |
                    
                    |        local variables            |
                    
                    |                                   |
                    |-----------------------------------|<-*
                    | entry point termination procedure |   \
                    |-----------------------------------|    Only global modules with "FINAL"-part
                    |         termination link          |   /
                    |-----------------------------------|<-*
                    | return-addr for Exception-Part.   |   \
                    |-----------------------------------|    Only modules with exception handling
                    | retry-addr for Exception-Part.    |   /
                    |-----------------------------------|<-*
                    | saveFP                            |   \
                    |-----------------------------------|    \
                    | saveBP                            |     \
                    |-----------------------------------|      \
                    | actMessage                        |       \
                    |-----------------------------------|        \
                    | actNumber                         |         \
                    |-----------------------------------|          \
                    | actSource                         |           Only with exception handler
                    |-----------------------------------|          /
                    | saveInfo                          |         /
                    |-----------------------------------|        /
                    | SP                                |       /
                    |-----------------------------------|      /
                    | entry point exception handler     |     /
                    |-----------------------------------|    /
                    | exception link                    |   /
                    |-----------------------------------|<-*      <- 16-byte-boundary
                    |                                   |
                    
                    | copies of reference parameters    |
                    
                    |                                   |
                    |-----------------------------------|
                    |                                   |
                    
                    |        intermediate results       |
                    
                    |                                   |
                    |                                   |
                    |-----------------------------------|<-*--------------*
                    |                                   |                  \
                                                                            \
                    |       Parameter area              |                    Callee
                                                                            /
                    |                                   |                  /
SP ------------->   |-----------------------------------|<-*--------------*         <- 16-byte-boundary

6.3.1.3 Intel 64-Bit Runtime

The following diagram illustrates the structure of the stack as seen from the point of view of a procedure. FP and SP signify values of the frame pointer and the stack pointer.
FP:frame pointer after the procedure prolog is executed
SP:stack pointer before the call to another procedure

In all the following diagrams memory addresses increase towards the top.

                    |                                   |
                    |-----------------------------------|<-*--------------*
                    |                                   |                  \
                                                                            \
                    |        Parameter area             |                    Caller
                                                                            /
                                                                           /     
                    |-----------------------------------|<-*--------------*     <- 16-byte-boundary
                    |           Saved ret adr           |
                    |-----------------------------------|
                    |           Saved FP (%ebp)         |
FP ------------>    |-----------------------------------|
                    |           Saved GP (%r15)         |
                    |-----------------------------------|
                    |           Saved SE (%r14)         |
                    |-----------------------------------|
                    |           Saved SL (%r13)         |
                    |-----------------------------------|
                    |           Saved %r12              |
                    |-----------------------------------|
                    |           Saved PB (%ebx)         |
                    |-----------------------------------|
                    |           Saved outer SL          |   Only for nested procedures
                    |-----------------------------------|
                    |                                   |
                    
                    |        local variables            |   Including parameters passed in registers
                    
                    |                                   |
                    |-----------------------------------|<-*
                    | entry point termination procedure |   \
                    |-----------------------------------|    Only global modules with "FINAL"-part
                    |         termination link          |   /
                    |-----------------------------------|<-*
                    | return-addr for Exception-Part.   |   \
                    |-----------------------------------|    Only modules with exception handling
                    | retry-addr for Exception-Part.    |   /
                    |-----------------------------------|<-*
                    | saveFP                            |   \
                    |-----------------------------------|    \
                    | saveBP                            |     \
                    |-----------------------------------|      \
                    | actMessage                        |       \
                    |-----------------------------------|        \
                    | actNumber                         |         \
                    |-----------------------------------|          \
                    | actSource                         |           Only with exception handler
                    |-----------------------------------|          /
                    | saveInfo                          |         /
                    |-----------------------------------|        /
                    | SP                                |       /
                    |-----------------------------------|      /
                    | entry point exception handler     |     /
                    |-----------------------------------|    /
                    | exception link                    |   /
                    |-----------------------------------|<-*      <- 16-byte-boundary
                    |                                   |
                    
                    | copies of reference parameters    |
                    
                    |                                   |
                    |-----------------------------------|
                    |                                   |
                    
                    |        intermediate results       |
                    
                    |                                   |
                    |                                   |
                    |-----------------------------------|<-*--------------*
                    |                                   |                  \
                                                                            \
                    |       Parameter area              |                    Callee
                                                                            /
                    |                                   |                  /
SP ------------->   |-----------------------------------|<-*--------------*         <- 16-byte-boundary

6.3.2 Global Variables

All global variables of a Modula-2 module are logically viewed as one single record. Access to this area is optimized by holding the address in a special register, the so-called "global pointer" (GP). Register r31/edi/r15 is used as "GP".

The "GP" is loaded by every procedure that is callable from outside the module. Procedures which are exported explicitly or used in an expression (e.g. passed as an actual parameter or assigned to a variable) are considered callable from outside.

If global variables are not used in a procedure (including its local procedures) and only procedures which load the GP themselves are called, or if a module does not have any global variables, the GP is not loaded. r31 is then available for other use; edi/r15 may be used locally.

The module descriptor which the compiler creates for each module is also accessible via the GP. The following diagram depicts the structure of a module descriptor.

  32-bit                           64-bit
            +---------------------+
    -16     |  constant area      | -28             addresse of constants table
            +---------------------+
    -12     |    module chain     | -20
            +---------------------+
     -8     |     data size       | -12             size of global variables
            +---------------------+
     -4     |   compiler version  |  -4             version number in hexadecimal
            |      number         |                 (0910H for V9.1)
            +---------------------+
     -2     | initialization flag |  -2             0 = not yet initialized
            +---------------------+<--------------- global linker symbol
      0     |  global variables   |
For every module descriptor the compiler generates a global linker symbol to permit access to the descriptor by other modules. For the program module this symbol always has the name "M2_MAIN_MODULE", while every other module's symbol name is made up from the module's name and the module key. As the module descriptor is referenced by all importing modules, version incompatibilities lead to linker errors (see also 1.6). Within a global data area the individual global variables are found at positive offsets to the area's base address (GP).

Note:
The exported variables of a foreign module are referenced via their names as in other languages.

6.3.3 Process Descriptor

The process descriptor for the main program is allocated statically in the run-time kernel. If a Modula-2 process is created using "NEWCOROUTINE", its descriptor is constructed at the upper end of its respective workspace.
  32-bit                           64-bit
            +---------------------+
            |                     |                address of the run-time system's
     24     +-  defaultHandler   -+ 50             default exception handler
            |                     |
            +---------------------+
     22     |   actProtection     | 42             protection level
     21     +-  isTerm           -+ 41             process is terminating
     20     |   hasHaltet         | 40             HALT ahs been called
            +---------------------+
            |                     |
     16     +-    actHandler     -+ 32             active exception handler
            |                     |
            +---------------------+
            |                     |
     12     +-     nextTerm      -+ 24             next termination routine
            |                     |
            +---------------------+
            |                     |
      8     +-    nextHandler    -+  16            next exception handler
            |                     |
            +---------------------+
            |                     |
      4     +-     stackLow      -+  8             lower limit for stack check
            |                     |
            +---------------------+
            |                     |                when a process switch occurs the
      0     +-      savePtr      -+  0             stack pointer (pointing to the
            |                     |                saved registers) is written here
            +---------------------+
A global variable points to the process descriptor of the active process at all times. Another holds a copy of the stack's lower limit from the current process descriptor.

6.3.4 Object Organization

Object variables contain a pointer to the object. Each object is stored in a contiguous part of memory. The first entry is a pointer to the method dispatch table. It is followed by the storage for the attributes declared in the definition part. Attributes declared in the declaration part are accessed by a pointer located at the end of the global attributes. The following example shows the memory layout:
UNSAFEGUARDED DEFINITION MODULE Mod;

CLASS Class1;
VAR
    attrib11, attrib12: CARDINAL;
END Class1;

CLASS Class2;
INHERIT Class1;
VAR
    attrib21, attrib22: CARDINAL;
END Class2;

END Mod.


UNSAFEGUARDED IMPLEMENTATION MODULE Mod;

CLASS Class1;
VAR
    attrib13, attrib14: CARDINAL;
END Class1;

CLASS Class2;
VAR
    attrib23, attrib24: CARDINAL;
END Class2;

END Mod.
The object looks like:
Ref ->      |-----------------------------------|
            |            MethTabRef             |
            |-----------------------------------|
            |            attrib11               |
            |-----------------------------------|
            |            attrib12               |
            |-----------------------------------|
            |            Offs1                  | ---------+
            |-----------------------------------|          |
            |            attrib21               |          |
            |-----------------------------------|          |
            |            attrib22               |          |
            |-----------------------------------|          |
            |            Offs2                  | ---+     |
                                                     |     |
            |                                   |    |     |
                                                     |     |
            |-----------------------------------|    |     |
            |            attrib23               | <--+     |
            |-----------------------------------|          |
            |            attrib24               |          |
            |-----------------------------------|          |
            |            attrib13               | <--------+
            |-----------------------------------|
            |            attrib14               |
            |-----------------------------------|
The method dispatch table starts with a pointer to the table of the father class (or "0"). The second entry specifies the size of an object of this class (statically this variable is set to "0", as the size cannot be determined until runtime). Next follow the method references, local methods (declared in the declaration part only) are dispatched by auxiliary tables.

6.3.5 Organization of Dynamic Arrays

Pointers to dynamic arrays reference a data structure description followed by the array data. The first 32-bit/64-bit value contains the total size of the dynamic array (including the structure description), it is followed by the high indices of each dimension (from left to right) and the array data. The size s is 4 for ppc and i386 and 8 for x86_64:
            +---------------------+
            |                     |
      0     +-    total size     -+
            |                     |
            +---------------------+
            |                     |
      s     +-    high 1         -+            high index of 1st dimension
            |                     |
            +---------------------+
            |                     |

            |                     |
            +---------------------+
            |                     |
   n * s    +-    high n         -+            high index of n-th dimension
            |                     |
            +---------------------+
            |                     |
 n * s + s  +-     data          -+            arrays data
            |                     |

chapter 5 (compiler) start page appendix (compiler)