Topspeed_JPI/TS/DOC/SRCKIT.DOC

Core Library and startup files         Documentation version 3.10
==============================         ==========================

Introduction
------------

Why a read-me file?

There are two major reasons why printed documentation was
not produced for the TopSpeed SourceKits:

*  Internal revision. Only the public interface of the 
   run-time libraries can remain fixed. TopSpeed's policy 
   of continual improvement means that the actual 
   implementation of products may be changed between  
   minor releases.

*  User feedback. This documentation will be augmented in 
   response to user requests for information where 
   possible.


What is the core library?
-------------------------

The standard library for a TopSpeed language comprises
two major components, the language specific part and the 
language independent core. 

The core provides startup and termination code, plus
integrated I/O, memory management, text windowing,
graphics, and other services. This arrangement reduces
redundancy and ensures that the major system features are
compatible between languages.


Core library naming

In normal use, the correct core library is linked automatically
by the project system. However, if manual selection is required,
the following naming convention must be used:

   %O%%M%%C%COM.LIB

Where the macros %O%, %M% and %C% are expanded as follows:

  %O%    Operating system:
  R      Real mode (MSDOS).
  W      Windows.
  P      Protected mode (OS2).
  %M%    Memory model:
  S      Small model.
  C      Compact model.
  M      Medium model.
  L      Large model.
  X      XLarge model.
  T      Mthread model.
  O      Overlay model (MSDOS only).
  D      Dynalink model.
  %C%    Calling convention:
  _      JPI.
  F      Stack frame.

For example, the large model, MSDOS, JPI calling
convention core library is named:

   RL_COM.LIB


The core library Interface
---------------------------

For reasons of compatibility, the core library interface 
remains fixed between major releases. However, you should 
avoid using functions, procedures and data objects
declared in the core library interface for future
portability.


The core library Implementation
-------------------------------

Why assembler?

Assembly language code is not straightforward to maintain 
or easy to understand. In a traditional implementation, 
some of the routines could have been implemented in a 
high level language. However, TopSpeed's approach has the 
following advantages:

*  Efficiency. Many of the library functions, such as 
   string handling, are highly optimized, giving a 
   significant improvement in performance over other
   products.
*  Multi language environment. To allow the user to 
   remake and customize the run-time libraries, the 
   complete language implementation must either be 
   written in the host language or assembly language.
*  Low level requirements. While 'tricks' can often be
   employed to implement low-level features, assembly 
   language is often the most elegant and efficient way 
   to implement operating system and machine specific 
   code.


Conditional compilation
-----------------------

The assembly language files produce code for all TopSpeed 
memory models, operating systems and calling conventions. 
This is achieved by conditional compilation.

The following boolean flags are used to reflect the 
various possibilities:

  NearPtr  When true, data pointers are 16 bit. When
           false, data pointers are 32 bit.
           Small and Medium models use NearPtr = true. 
           All other models use NearPtr = false.

  NearCall When true, calls and return are near, and
           procedure variables are 16 bit. When false,
           calls and return are far, and procedure
           variables are 32 bit.
           Small and Compact models use NearCall = true.
           All other models use NearCall = false.

  SameDS   When true, DS is not assumed to be fixed, i.e. 
           pointing to DGROUP, the default data segment.
           XLarge, Mthread, Overlay and Dynalink models
           use SameDS = false. All other models use
           NearCall = true.

  RegParam When using the jpi calling convention, passing
           parameters in registers, RegParam is true.
           When using the standard stack frame calling
           convention, RegParam is false.

  MThread  In memory models that support multi-thread
           operation, MThread is true.
           Mthread, overlay and dynalink models support
           multiple threads. Code to support this mode of
           operation is include in these models.

  _OS2     When true OS2 specific code is generated. When
           false MSDOS and some Windows code is generated

  _WINDOWS When true, Windows specific code is generated.

  _DLLOVL  When true, code required for the TopSpeed 
           overlay manager is generated. This required
           for Overlay model and the Dynalink model under
           MSDOS.

  _DLL     When true, code specific to DLLs is generated.

  ProtMode When true, protected mode features are enabled 
           for either OS2 or Windows.

  _WINDLL  When true, code specific to Windows DLLs is 
           generated.startup files five main EXE file
           startup files are used by TopSpeed:
                initexe.a
                initnew.a
                initpm.a
                initwin.a
                initmwin.a
           Plus two DLL initialization files:
                initdll.a
                initwdll.a
           The selection of the correct startup code
           removes the need for more library variants and
           allows greater flexibility of run-time
           segmentation.

Each file performs two main functions:

*  Declaration of segmentation. 
*  The segment and group declarations at the top the file
   determine the ordering and groups recognized by the
   linker. If a new segment class needs to be added, it
   must be declared in the first section of the startup
   file.
·  The db definitions at the bottom of the file determine 
   the ordering of segments within DGROUP. These must not
   be changed.
·  Initial startup code. Information stored in registers
   at program startup is saved, and a call is made to low
   level initialization code to insert any initialization 
   blocks in to a list which will be processed later. 

Initialization may either be created by hand to 
initialize assembly language modules, or by the C++ 
compiler to construct static objects. See Advanced 
Programmer's guide.


initexe.a
This is the default startup file for an OS2 or DOS exe 
file.

The __initx record has the following structure:

  far ptr:   Address of program entry sequence.
  word:      Size of near heap.
  word:      Size of stack.
  byte:      Stack location. Non-zero in dgroup.

In the code section, the stack size and location are
saved, the near heap, if present, is located, and the 
program entry point determined.

Finally the initialization blocks associated with the 
program are added to the list, and a far jump made into
the library startup code.


initnew.a
This startup is identical to initexe apart from its 
segment ordering. It is used by Modula-2 and Pascal 
programs in XLarge models to reduce DOS exe file size. 
Since static data is not required to be initialized to 
zero, it may be placed at the end of the file.


initpm.a
This startup is identical to initexe apart from its stack 
location. It is used by Presentation manager programs 
which require a stack segment fixed in DGROUP.


initwin.a
This startup file provides both initial startup code for 
C and C++ Windows programs, and a dummy main procedure 
that calls the program entry point WinMain.


initmwin.a
This startup file provides both initial startup code for 
Modula-2 and Pascal Windows programs, and a dummy 
procedure that calls the program entry point WinMain.


initdll.a
This file adds any initialization blocks associated with 
the DLL to the list associated with the process. The file 
is used for both DOS and OS2 DLLs.


initwdll.a
The file is used for Windows DLLs. It adds any
initialization blocks associated with the DLL to the 
list, and calls the DLLs startup sequence.


Floating point files
--------------------


Support files

Three floating point support files are used by TopSpeed:

   noemul.a
   nofloat.a
   r_emul.a
   p_emul.a
   winfloat.a

These files resolve calls to helper functions and perform 
the floating point initialization.

  nofloat   This is used when no floating point is 
            required by the program.
  noemul    This is used when no emulation is required in 
            program that used floating point.
r_emul      This is used by MSDOS programs that require  
            floating point emulation.
p_emul      This is used by OS2 programs that require    
            floating point emulation.
winfloat    This is used by Windows programs that require 
            floating point emulation.


Emulation strategies

Under MSDOS, the standard Microsoft software interrupts 
are used to invoke the emulator. If a chip is present at 
run-time, interrupt instructions are back patched to 
floating point instructions.

Under OS2, the emulator is invoked via the invalid op-
code exception.

Under Windows, special OS fixups are used. These are 
fixed up by the Windows loader to either interrupts or 
floating point instructions depending on the run-time 
environment. Not that Windows emulator is used instead of 
the TopSpeed emulator in Windows programs


Emulator data 

In order to achieve re-entrancy, the TopSpeed emulator 
uses a data area at the bottom of each thread's stack 
segment. In all memory models, This area is reserved.


MKLIB.PI
--------

Overview

MKLIB.PI is included by the project file mklib.pr. It
defines all the TopSpeed libraries, and the commands 
necessary to make them. The macro setting s necessary to 
make a specific group of libraries are described in the 
relevant language library reference. The core library is 
re-made automatically when any language library is re-
made.

Library structure

Core library comprises following files:
  coremain.a      Library startup and termination code.
  coresig.a       Exception and error handling.
  coremath.a      Floating point math and conversions.
  3rdparty.a      Helper functions for third party code.
  corefile.a      File I/O data definitions.
  corertl.a       Helper functions and compiler run-time   
                  support.
  coreio.a        Low level input and output functions.
  corepmd.a       Low level post mortem dump support.
  corewind.a      Low level text window functions.
  coremem.a       Memory management.
  coreemul.a      Operating system independent floating 
                  point emulation code.
  coreproc.a      Low level multi thread functions.
  coregrap.a      Low level, hardware dependent, graphics 
                  functions. MSDOS only.

The system header file is included by each file:

  corelib.inc     System constant definitions.


Interface files
---------------

Interface files for each language are provided. They used 
internally by the high level library modules and should 
not be used by the user unless directed by the Language
documentation.


Replacing or redefining modules
-------------------------------

Certain of the core library modules may be replaced by 
user defined ones. For example, CoreMem could be replaced 
by an another memory manager, as long as the interface 
required by the high level language library and startup 
code is preserved. 
More precise details are provided in the documentation 
for the individual module.


The core library EXP file
-------------------------
The MSDOS and OS2 DLL versions of the core library have 
corresponding EXP files, declaring the exported 
identifiers:
  RD_COM.EXP      Real mode.
  PD_COM.EXP      Protected mode.

If a public definition is added or removed from a  core 
module, EXP must be altered to reflect the change, if the 
DLL version is to be made.

Similarly, a cut-down version of the core library DLL may 
be made by commenting out any unused identifiers. Smart 
linking will take care of removing the unwanted code from 
the DLL when it is remade.


Windows DLL core library
------------------------

The DLL versions of the windows libraries are not DLLs 
themselves; they link statically with a user created DLL. 
Versions exists in all supported models, and have the 
name COMD instead of COM.

The library initialization is called from the initwdll
file.


Core Library modules
--------------------


corelib.inc

The constants defined in this file may not be changed unless
specifically documented as such.
The model and calling convention constants are defined:

   NearCall
   SameDS
   NearPtr
   MThread
   RegParam

Two constants that determine the pointer sizes in Modula-
2 and Pascal initialization records are defined:

near_init_code = NearCall
near_init_data = SameDS

The constant StackChecks is defined to be non-zero. This 
enables stack checking in certain functions that use
large local variables. A small reduction in program size 
may achieved at the cost of safety by setting this 
variable to 0.

All process spawning functions and the C function write
perform a stack check by default.

Three constants are defined to specify the offset of
parameters on a standard BP stack frame.

  frame     Default for current memory model.
  lframe    Far call.
  sframe    Near Call

Three constants are defined to specify the offset of parameters
on an optimized BX stack frame. e.g.

  mov bx, sp
  mov ax, ss:[bx][var]

  bxframe      Default for current memory model.
  lbxframe      Far call.
  sbxframe      Near Call

Code and data pointer sizes are defined for the model 
default, plus near and far variants.

   CodePtrSize
   FarCodePtrSize
   NearCodePtrSize 

   DataPtrSize
   FarDataPtrSize
   NearDataPtrSize 

The FILE structure is defined for near and far data
pointer models. This is used directly by C stdio input 
and output functions, and as a global stream descriptor 
by all languages.

A subset of the error codes defined in errno.h are 
defined for use by the assembler parts of the library.

   ENOENT
   ENOPATH
   EACCESS
   EBADF
   E2BIG
   ENOMEM
   ENOSPC
   EINVAL
   EDOM 
   ERANGE

Similarly a subset of the I/O flags are defined. These 
are documented by comments.

The next section is a subset of the OS2 API type 
definitions required by the assembler library.

THREADTABLESIZE is the size of the thread information 
record. An array of these records is maintained by the 
library for internal static data. The constant MAXTHREAD 
is of interest because this controls the maximum number 
of threads supported. See Advanced Programmer's Guide. 

The following constants are constants private to the 
implementation. Of interest are STACK_GUARD, which is 
used to terminate the BP chain in overlay and DOS DLL
models, plus the error codes generated by the overlay 
loader, LOADER_ERROR_*.


coremain.a
----------

Overview

Coremain contains functions, variables and procedures for
program startup and termination.

Variables

__argbuf         Command line buffer
__hugeshift      Huge pointer shift value.
__osmajor        major OS version number
__osminor        minor OS version number
__osmode         flag, true if protected mode

Functions
Pointers passed to at/onexit are pushed onto the stack and
called LIFO on program termination:
__exit_stk       at/onexit function stack.
__exit_ptr       atexit stack pointer
__exit_top       atexit stack top
__exit_list_done atexit stack flag. True if executed.

The low level C library and C++ static object
initialization code is called from a record entry. The
records, gathered from the main program and any DLLs
used, are stored as a linked list of arrays. These are
traversed once for each priority level, and any code of 
that priority is called. The called code calls InitLoop 
to process the next record. 

At the end of this process the main module is called. 

When that returns or the program terminated, the code 
sections execute any termination code and return, 
ensuring that destructors are called in reverse order.

InitCalled      Running total of low-level initialization 
                procedures called.
@InitGrandTotal Total of low-level initialization
                procedures to be called.
@InitCurrent    Current record being processed.
@InitRecPointer Pointer to current record.
@InitPointer    Pointer to current control record.
@InitPriority   Current priority being processed.

If the process is ended by a call to HALT or exit, the 
stack context is restored to ensure that the termination 
chain is executed.

@StackContextBP      BP value
@StackContextSS      SS value
@StackContextSP      SP value

Variables used in program termination.

@ExitCode      program termination code.      
__exit_io      procedure variable for io termination.
__exit_file    procedure variable for file handling 
               termination.
__exit_tmp     procedure variable for temporary file
               clean up.
__exit_proc    procedure variable for process module   
               termination
__exitbreak    procedure variable for deinstalling break 
               handler.
__exitsig      procedure variable for deinstalling signal 
               handlers.
__exitgraph    procedure variable for graph module 
               termination.

Modula-2 and Pascal use a chain of procedures for their 
termination code, as used by Lib.Terminate.

__Term2              exit label for Terminate chain
standard@haltChain   pointer to beginning of chain.

Two procedure variables are used to install real number 
conversion in printf and scanf. This is used to prevent 
these functions dragging floating point unnecessarily

__real_in      procedure variable for formatted input of
               real numbers
__real_out     procedure variable for formatted output of 
               real numbers

General variables
__CmdLine             command line storage used by
                      windows DLL.
__farstack            flag, true if stack in far
                      segment.
__sp_temp             used for restoring SP.
__ss_temp             used for restoring SS
DOSHUGESHIFT          Huge shift constant
_x_initx              pointer to startup vector.
_x_bss_end            end of BSS segment
_x_bss_start          start of BSS segment.
__sigsetup            flag, true if signal handling
                      setup.
__psp                 Program segment prefix.
__env                 Environment segment.
__heap_base           base of far heap.
__env_init            flag, true if environment
                      initialized.
__arg_init            flag, true command processed.
STKHQQ                stack length.
__stklen              stack length.
__SSisDS              flag, true if SS in dgroup
__far_ss              far stack segment
__x_near_stack_start  start of near stack
__heap_size           heap size, used by windows
                      DLLs.
_x_main               points to main module
__stk_base            base of stack.
__nmemsetup           flag, true if near heap setup.                           
__fmodmemsetup        flag, true if Modula-2 far heap 
                      setup.
__fmemsetup           flag, true if near heap setup. 
__res_mem             procedure variable for restoring
                      heap after spawn.
__fix_mem             procedure variable for fixing far 
                      heap before spawn.
__shr_mem             procedure variable for shrinking
                      far heap before spawn.
__argv                array of pointers to command line 
                      arguments.
__env_var             array of pointers to environment
                      strings
__osversion           OS version


Procedures and routines

Public interface library procedures are not normally 
mentioned here since they are documented fully in the 
appropriate language library reference.

_exit
This the C and C++ exit function. It is also called 
indirectly by Modula-2 and Pascal.

__InitLoop
This procedure is called by C and C++ initialization 
code. It chains all the initialization and termination 
code.

__InitLink
This procedure is called from process and DLL startup to 
add an array of initialization records to the list.

__InitSetup
Preprocesses list of initialization record arrays .

__cleanup
Calls termination procedure variables.

__setenv
Initializes program environment variable table.

exit_handler, __set_exit_handler
Install an exit handler for OS2. This will be called if 
the program terminates will a segment overrun for 
example.

__main_args2
calls _main with 2 arguments.

__main_args3

calls _main with 3 arguments

__libmain_args

Calls windows DLL libmain function.

__set_machine_id
sets machine id information.

__env_copy
copies environment strings to local buffer.

__init0, __init2, __init3
vectors for calling main module.

__initWDLL
entry point for Windows DLL.

__getheapbase
returns base of far heap.

do_initargc
Initialization code to process command line arguments.

__setargv
Initializes command line variables.      

__real_pdef, __real_sdef
Default procedure that is called if an attempt is made to 
format an integer floating point number by either printf 
or scanf.

__exit
Low level, operating system specific termination 
procedure. It all ends here.

__startup
The library entry point.

$Stage2
The second initialization stage, called after low level 
and C++ initialization.

__call_main
calls _main 

__fp_1
Tells library that floating point is present.

__fp_0
Tells library that floating point is absent.


Replacing module 

In normal circumstances this module may not be replaced.


Embedded systems

embedded systems programmers are unlikely to be using the 
low level library initialization. In this case the 
program main module will be called directly from 
initesys, so coremain becomes redundant. However, some 
functions or variables may be referenced. It is safe to 
include coremain, as no OS or machine specific code will 
be dragged in as long as __startup is not used.


Initialization
The initialization code contained in this module concerns 
command line arguments and environment strings. The 
procedures __setargv and __setenv mentioned above perform 
the actual initialization.


coresig.a
---------

Overview

Coresig provides error, signal and exception handling.
variables

__sigTrans
Table for translating signal numbers

__raiseTrans
Table for translating signal numbers

CoreSig@CnsHandler
procedure variable for handling run-time errors such as
 nil pointer dereference etc.

__sigTable
signal vector table

__vec0,__vec2,__vec4,__vec16,__vec23,__vec24
Storage for interrupt vectors to be restored on program 
termination.

@RecursiveExit
Flag, set true at first call to terminate process. A 
subsequent fatal error will cause immediate termination.

_errno 
The C global error variable.

@InProgramFlag 
Flag, when true process not executing in operating system 
(MSDOS).

@StopProgramFlag 
Flag, when true signals that process has received a 
terminate signal. (MSDOS)

@MachineId 
Indicates if machine is an AT.

__pmd_stub
procedure variable for invoking post mortem dump.

Procedures and functions

Public interface library procedures are not normally
mentioned here since they are documented fully in the 
appropriate language library reference.

__seterrno 
Used to set error variable _errno.

__errno__ 
called in multi-thread models to access _errno. 

__ioerr 
Used to set dos error variable.

@ReloadCache
Dummy procedure in far segment to force cache flushing on 
some machines.

__sysmsg
System error message output procedure.

__FatalErrorPos
Returns current IP:CS

__FatalError
Invokes program termination and creates ERRORINF.$$$ 
file. If post mortem dump is included the debug file will 
also be produced.

@DosInterrupt
Executes DOS Int21H. Checks for re-entering DOS.

__SigInit 
Initializes signal handling system

do_initsig
Initialization block for signal system. Calls __SigInit.

__do_exitsig
Clean up for signal handling.

__initsig
Minimal signal handling initialization called if main 
signal system not used.

__sigDefault
Default procedure for handling signal. Terminates 
program.

__sig23
Handler for int23.

__sigFp_AT, __sig_Fp
Handler for floating point exceptions.


Initialization

The initialization code contained in this module relates 
to the signal handling mechanism. The actual 
initialization is done by __SigInit.


Replacing module

It is not really practicable to replace this module if it 
features are required. The signal and exception handling 
are complex and highly implementation specific.


Embedded systems

This module may be omitted, since the startup code in 
initesys will not use the signal handling mechanisms. 
However, using run-time checks or floating point will 
require the use of coresig.


coremath.a
----------

Coremath implements the assembler floating point math 
library. The file is in two sections, one for stack frame 
and one for JPI calling conventions.


3rdparty.a
----------

This module implements compiler support functions called 
by code generated by other vendors products.


corefile.a
----------

Corefile contains the data definitions for the file I/O
descriptor arrays.

OPEN_MAX      Sets maximum number of open files.
__open_max    Variable used by high level languages to
              get file maximum.
__iob         C FILE array.
__openfd      C file handle descriptor array.
_BufInf       Modula-2 buffered file descriptor array.
__tmpfiles    Temporary file name array.
__tmpfptrs    Temporary file FILE structure array.


corertl.a
---------

corertl contains compiler helper functions, run-time 
error handlers and Modula-2/Pascal module initialization 
code.

All helper functions have far, near and IO privilege
versions. The names used below omit the prefixes F, N and 
I.

All the helper functions use a stack based calling
convention, and return values in dx:ax.

$UnsMol
Multiplies two unsigned long integers with modulus 
wraparound on overflow.

$SgnMol
Multiplies two signed long integers with modulus 
wraparound on overflow.

$SgnDiv
Divides two signed long integers.

$UnsDiv
Divides two unsigned long integers.

$UnsRem
Calculates the remainder of two unsigned long integers.

$SgnRem
Calculates remainder of two signed long integers.

$UnsMul
Multiplies two unsigned long integers.

$SgnMul
Multiplies two signed long integers.

$SgnMod
Calculates modulus of two signed long integers.

$LngShl
Shifts left signed long integer.

$LngShr
Shifts right signed long integer.

$ULngShr
Shifts right unsigned long integer.

$PushByt
Pushes bytes onto stack.

$PopByt
Pops bytes from stack.

$SetOr
Computes bitwise OR of two sets.

$SetDif
Computes bitwise difference of two sets.

$SetXor
Computes bitwise XOR of two sets.

$SetAnd
Computes bitwise AND of two sets.

$DupByt
Copies bytes.

$EquByte
Compares two blocks of bytes. Returns result in flags and
non-zero in AX if equal.

$NotEquByte
Compares two blocks of bytes. Returns result in flags and 
non-zero in AX if not equal.

$HugeSub
Subtracts two huge pointers.

$LngRol
Rotates left a signed long integer.

$StkChk
Performs stack check. Called on entry to procedure.

$CnsStk
Called if stack overflow occurs. Invokes error handling 
mechanism.

$CnsPtr
Called if nil pointer dereference occurs. Invokes error
handling mechanism.

$CnsIdx
Called if array index error occurs. Invokes error handling
mechanism.

$CnsOvr
Called if overflow occurs. Invokes error handling
mechanism.

$CnsRng
Called if range error occurs. Invokes error handling 
mechanism.

$CnsRet
Called if illegal return occurs. Invokes error handling 
mechanism.

$CnsCase
Called if case error occurs. Invokes error handling 
mechanism.

$CnsDiv
Called if divide by zero occurs. Invokes error handling 
mechanism.

$CnsPVC
Called if pure virtual function called. Invokes error 
handling mechanism.

__initm
Calls modula2/Pascal initialization, followed by the main 
module. If this module returns then _exit is called.

$initm
Calls each of the module initialization routines. The 
bottom of the stack segment is used for working space. A 
stack of 16k gives enough storage for about 1000 modules 
which should be ample. There are logically three arrays, 
a fixed size hash table, an array of graph nodes, and an 
array of lists used for sorting. The latter two are of 
dynamic size and are interleaved, and allocated together. 
Once the order has been determined, the addresses are 
pushed onto the stack, and a return instruction is 
executed.


Embedded systems

This module must be included, unless no compiler
generated calls exist in your code..


coreio.a
--------

Coreio provides low level file and console I/O 
facilities, plus a DOS timer delay function.

Variables

__fmode 
default file open mode.

__fmask
default permission mask.

__ungotchar
character put back by ungetch.

__DelayFactor, __Iter, __Count
calibration information for timer delay.

__upperHex
Hex format case.

__zero_code, __scanwaiting
variables for handling extended key codes.

__kbdhandle
OS2 keyboard handle.

__i_putch
putch function vector.

__i_cgets
cgets function vector.

__p_init
console initialization flag.

__doserrno      dos error variable.


Procedures and functions

Public interface library procedures are not normally 
mentioned here since they are documented fully in the 
appropriate language library reference.

__d_putch
Default putch function. The graph, JPI window and 
clipping window modules install their own versions of 
putch.

__d_cgets
Default cgets function. The graph, JPI window and 
clipping window modules install their own versions of 
cgets.

__iosetup
Flag, true if file I/O initialized.

do_initio
Initialization block for file I/O.

do_initTimer
Initialization block for delay timer.

__pascreate, __pasopen
Internal file open functions for pascal library.

__exists
low level function to check for a file's existence.


Initialization

The timer and file I/O systems are initialized in coreio.


Embedded systems

Unless I/O is actually used, the module is not required. 
The very low level I/O functions such as __read, __write 
etc require no initialization.


corepmd.a
---------

Corepmd contains the initialization and low level code
for the post mortem dump facility. It is not used unless 
PMD is enabled.


corewind.a
----------

CoreWind provides initialization and low level functions 
for the JPI window module.

__initwin_vector   vector used for DLL initialization.
__fullscreen       The default window handle.
__uselist          List of windows to be used.
__windowstack      Stack of active windows.
__cursorstack      Cursor stack.
__multip           Flag, true if multi-thread process.
__winsetup         Flag, true if window module 
                   initialized.
__cursorlines      Number of raster lines in the cursor.
__ScrnAddr         Address of screen memory.
__ActPag           Active display page.
__IsColor          Flag, true if color display.
__IsSnow           Flag, true if CGA snow checking
                   enabled.
__ScreenSel        OS2 display memory selector.
__Config, __BufInf, __Status
                   OS2 screen configuration.

All the procedures in this module are called from the 
high level wdinow modules.

__bufferwrite
Writes character directly to window buffer.

__getscreendepth
Returns depth in rows of screen.

__palxlat
Translate palette colors.

__buffertoscreen
Updates screen from window buffer.

__screentobuffer
Updates window buffer from screen.

__setvideopage
Selects active display page.

__activepage
Returns active display page.

__initscreentype
Determines display mode and parameters.

do_initconio
Initialization block for window module. __initwin does 
the actual initialization.

__set_initwin_vector 
Initializes vector for DLL.


Embedded systems

The window module uses BIOS calls and code segment variables,
so it not suitable for embedded systems programming.


coremem.a
---------

Coremem implements the run-time memory management of both
near and far heaps. Note that in Modula-2 only programs 
all the far heap is allocated to the Storage module, and 
sub-allocated.


Near heap structure
-------------------

The near heap is a single contiguous block of memory 
located in DGROUP. Free blocks form a linked list. The 
list is terminated by a nil value.

The header structure is as follows:

  Block size                     word
  offset of next free block      word

When a block is allocated and removed from the free list,  
only the block size part of the header is preserved, a
pointer to the second word of the header is returned.


DOS far heap structure  
----------------------

The far heap is a single contiguous block of memory 
located above the stack segment. Free blocks form a 
linked list. The list is terminated by a nil segment 
value.

The header structure is as follows:

  Block size                      word
  segment of next free block      word

When a block is allocated and removed from the free list, 
only the block size part of the header is preserved, a 
pointer to the second word of the header is returned.

All blocks are paragraph aligned. The heap expands 
upwards into free memory. If the heap contracts, surplus 
memory is returned to DOS.


OS2 far heap structure  
----------------------

The OS2 far heap is a linked list of short heaps. Each 
heap has a header of the following structure:

selector of previous heap       word
selector of next heap           word
offset of first free block      word
Heap status                     word

The first block begins after the header at offset 8. The
heap status word can have two values:

  1      Heap allocated and active.
  0      Heap free and unused.

If a request is made to allocate a huge block or one 
greater than 64K - 8, a segment is allocate from the 
Operating system.

When a heap becomes full, a new segment is allocated and 
added to the list. When a heap becomes empty, it is 
returned to the operating system. However, in xlarge, 
mthread and dynalink models, the heap segment is shrunk 
to its header size and marked as free. This means that 
any selectors referring to dynamic memory still on the 
stack may still be popped safely. When a new heap segment 
is required, the first free heaps will be re-used.

__memtype        OS2 segment allocation attribute
__fheapstart     segment value of bottom of far heap
__fheaptop       segment value of top of far heap
__firstfree      segment of first free block in far heap
__fheapsem       process control semaphore
__nheapstart     offset of beginning of near heap
__nfirstfree     offset of first free *block in near heap
__nheaptop       offset of end of near heap
__firstheap      first heap of OS2 far heaps


Procedures and functions

Public interface library procedures are not normally
mentioned here since they are documented fully in the 
appropriate language library reference.

__nheap_merge
Merges two near heap blocks if they are adjacent.

do_initfmem
Initializatin block for far heap.

do_initnmem
Initializatin block for near heap.

__shrink_mem
Shrinks far heap to minimum size and returns rest of 
memory to DOS. Used when spawning a process.

__heap_align
Normalizes block request to far heap allocation function. 
Two bytes are added for header overhead, and the size is 
then rounded up to the nearest paragraph.

__heap_free
Returns any surplus memory to DOS if far heap contracts.

__heap_merge
Merges two far heap blocks if they are adjacent.

__get_heapstate, _set_heapstate
In overlay or dynalink model under DOS, the far heap is 
managed by the overlay manager. Any library functions 
that access the heap must call __get_heapstate to get the
current state of the heap before access it, and call 
set_heapstate to update the overlay manager.

__newheap
Creates new OS2 far heap.

__newheapr
Creates or reinitializes an OS2 far heap in xlarge, 
mthread or dynalink  model.

__osalloc
Allocates memory from OS2.

__osfree
Disposes of an empty OS2 far heap.

__osfreer
Disposes of an empty OS2 far heap. If in xlarge, mthread 
or dynalink model, the heap is shrunk to its header size 
and not freed. This is to ensure that any selector values 
subsequently popped from the stack are still valid.


Initialization

The far and near heaps are initialized in this module.


coreemul.a
----------

Coreemul implements the floating point emulator. If 
floating point is used and emulation is required, either 
R_EMUL (DOS), or P_EMUL (OS2), will be linked, causing 
the emulator to be initialized. Note that Windows3 
programs use the windows emulator.


coreproc.a
----------

Coreproc implements low level thread handling functions
as well as the Modula-2 system procedures NEWPROCESS etc.

__threadTable      Table of thread control structures.
__threadTotal      Total number of active threads.
__cp               currently active task + ready queue
__dq               queue of delayed tasks 
__wq               queue of tasks that have reached their 
                   delay time but haven't been placed on  
                   the ready queue.
__SchedProc        Pointer to scheduler.
__Started          Flag, true if scheduler started.
__Continue         Procedure variable used by closedown 
                   procedure.
__Stop             Signal to stop scheduler.
__LockNestMonster  Lock count.
__SchedTime        Time value for scheduler.
__NextThread       Next thread number to be started.
__proc_init        Flag, true if process module 
                   initialized.
__initmt_vector    Vector used to initialize DLL.
__ProcIds          Process Id array.
__LockSem          OS2 Lock procedure semaphore.
__LockCount        OS2 lock count.      
__LockedThread     Number of locked thread.
@CurrentProcess    Current DOS thread.
__core_lock        procedure variable for language 
                   independent lock.
__core_unlock      procedure variable for language 
                   independent unlock.
__core_delay       procedure variable for language 
                   independent delay.


Major functions

Public interface library procedures are not normally 
mentioned here since they are documented fully in the 
appropriate language library reference.

__set_initmt_vector
Instigates DLL initialization.

_new_priority
Compiler generated call to change priority.

CoreProc$initprocess, SYSTEM$initprocess
Basic low level initialization for SYSTEM.

do_initproc
Initialization block for process module.


Initialization

The initialization block for the process module is 
contained in coreproc, but the actual code is implemented 
in a high level language.


coregrap.a
----------

Coregraph implements the hardware specific and
performance critical areas of the JPI graph module. 


Variables

__active_page        Active display page.
__bkcolor            Background color.
__clip_br            Bottom right corner of clip region.
__clip_tl            TopLeft corner of clip region.
__current_graph      Current position of graphics cursor.
__current_mask       pointer to current fill mask.
__current_text       Current position of text cursor.
__current_video      Current video configuration.
__cursor_lock        Cursor lock count.
__cursor_state       Current cursor state.
__depth              Depth in pixels of screen.
__display_state      Current display mode.
__EGA_table          EGA color translation table.
__EGA64K             Flag, true if 64K EGA card present.
__EGAPlaneShift      EGA plane shift value.
__EGAScreen          Address of EGA screen.
__EGAStartPlane      Starting EGA plane.
__EGAtranslate       Flag, true if translation of EGA 
                     color value required.
__fgcolor            Current foreground color.
__fill_mask          Current fill mask.
__current_linestyle  Current line style.
__fstart             Start of fill when filling pie.
__g_charout          procedure variable for outputting 
                     character to screen.
__g_strin            procedure variable for reading 
                     string from keyboard.
__get                procedure variable for getting bit 
                     image of screen.
__hline              procedure variable for drawing 
                     horizontal line.
__hscan              procedure variable for scanning  a 
                     line of pixels. Used by floodfill.
__initgraph_vector   vector for initialization of DLL.
__lastmode           Previous display mode.
__line               procedure variable for drawing line.
__mode_changed       Flag, true if program has changed 
                     display mode.
__origin             Origin of viewport.
__page_size          Size of graphics display page.
__plot               procedure variable for setting 
                     pixel.
__point              procedure variable for getting pixel
                     value.
__put                procedure variable for copying bit 
                     image to screen.
__scr_attr           Text mode character attribute.
__text_br            Bottom right corner of text window.
__text_tl            Top left corner of text window.
__txcolor            Current text color.
__visual_page        Current visual display page.
__width              Screen width.
__wrap_state         State of text wrap.


Procedures and functions.

All the following routines a called from the high level 
cgraph.c and graph.mod modules.

$OutWord
Word output to port. This is done in single bytes for 
portability. However, coregraph may be recompiled with 
FastIO true, which causes output by an out dx 
instruction. 

__CGA320Get
Captures bit image of CGA 320*200 graphics screen.

__CGA320HLine
Draws horizontal line in CGA 320*200 graphics mode.

__CGA640HLine
Draws horizontal line in CGA 640*200 graphics mode.

__CGA320leftscan
Scans pixel line to the left in CGA 320*200 graphics 
mode. Used by floodfill.

__CGA320Line
Draws line in CGA 320*200 graphics mode.

__CGA320Put
Copies bit image to CGA 320*200 graphics screen.

__CGA320rightscan
Scans pixel line to the right in CGA 320*200 graphics 
mode. Used by floodfill.

__CGA640Get
Captures bit image of CGA 640*200 graphics screen.

__CGA640leftscan
Scans pixel line to the left in CGA 640*200 graphics 
mode. Used by floodfill.

__CGA640Line
Draws line in CGA 640*200 graphics mode.

__CGA640Put
Copies bit image to CGA 640*200 graphics screen.

__CGA640rightscan
Scans pixel line to the right in CGA 640*200 graphics 
mode. Used by floodfill.

__change_screen_background
Updates graphics screen background.

__clear_Herc
Clears hercules graphics screen.

__EGA2HLine
Draws horizontal line in EGA 2 color graphics mode.

__EGA2Line
Draws line in EGA 2 color graphics mode.

__EGA2Plot
Sets pixel in EGA 2 color graphics mode.

__EGA2Point
Gets pixel in EGA 2 color graphics mode.

__EGAGet
Captures bit image of EGA native mode graphics screen.

__EGAHLine
Draws horizontal line in native EGA graphics mode.

__EGAleftscan
Scans pixel line to the left in EGA graphics mode. Used 
by floodfill.

__EGALine
Draws line in native EGA graphics mode.

__EGAPlot
Sets pixel in native EGA graphics mode.

__EGAPoint
Gets pixel in native EGA graphics mode.

__EGAPut
Copies bit image to EGA graphics screen.

__EGArexlat, __EGAxlat
Translation procedures used for 64K EGA.

__EGArightscan
Scans pixel line to the right in EGA graphics mode. Used 
by floodfill.

__gcur
Draws graphics cursor.

__getmemory
Returns display adapter memory size.

__hclip
Clips horizontal line.

__HercGet
Captures bit image of hercules mode graphics screen.

__HercHLine
Draws horizontal line in hercules graphics mode.

__HercLine
Draws line in hercules graphics mode.

__HercPut
Copies bit image to hercules graphics screen.

__lclip
Clips line.

__pixeladdr320x200
Calculates pixel address and shift count in CGA 320*200
graphics mode.

__pixeladdr640x200
Calculates pixel address and shift count in CGA 640*200
graphics mode.

__pixeladdrEGA
Calculates pixel address and shift count in native EGA 
graphics mode.

__pixeladdrEGA2
Calculates pixel address and shift count in EGA 2 color 
graphics mode.

__pixeladdrHerc
Calculates pixel address and shift count in hercules 
graphics mode.

__resetEGA
Resets EGA/VGA adapter.

__restore_mode
Cleanup function top restore display mode on termination.

__setbiosmode
Sets display mode using BIOS call.

__txt_out
Outputs text to screen.

__VGAGet
Captures bit image of VGA 256 color graphics screen.

__VGAHLine
Draws horizontal line in VGA 256 color graphics mode.

__VGALine
Draws line in VGA 256 color graphics mode.

__VGAleftscan
Scans pixel line to the left in VGA 256 color graphics 
mode. Used by floodfill.

__VGAPoint
Gets pixel in VGA 256 color graphics mode.

__VGAPut
Copies bit image to VGA 256 graphics screen.

__VGArightscan
Scans pixel line to the right in VGA 256 color graphics 
mode. Used by floodfill.

do_initgraph 
Initialization block for graphics module.


Initialization

The initialization block for graphics is contained in 
this module, but the actual initialization code is in a 
high level language.