.. _the-iso-system-module: The ISO system module ********************* .. code-block:: modula2 DEFINITION MODULE SYSTEM; (* Gives access to system programming facilities that are probably non portable. *) (* The constants and types define underlying properties of storage *) EXPORT QUALIFIED BITSPERLOC, LOCSPERWORD, LOC, ADDRESS, BYTE, WORD, INTEGER8, INTEGER16, INTEGER32, INTEGER64, CARDINAL8, CARDINAL16, CARDINAL32, CARDINAL64, WORD16, WORD32, WORD64, BITSET8, BITSET16, BITSET32, REAL32, REAL64, REAL128, COMPLEX32, COMPLEX64, COMPLEX128, CSIZE_T, CSSIZE_T, ADDADR, SUBADR, DIFADR, MAKEADR, ADR, ROTATE, SHIFT, CAST, TSIZE, (* Internal GM2 compiler functions *) ShiftVal, ShiftLeft, ShiftRight, RotateVal, RotateLeft, RotateRight, THROW, TBITSIZE ; CONST (* ; *) BITSPERLOC (const) BITSPERLOC = __ATTRIBUTE__ __BUILTIN__ ((BITS_PER_UNIT)) ; (* ; *) LOCSPERWORD (const) LOCSPERWORD = __ATTRIBUTE__ __BUILTIN__ ((UNITS_PER_WORD)) ; (* ; *) LOCSPERBYTE (const) LOCSPERBYTE = 8 DIV BITSPERLOC ; (* all the objects below are declared internally to gm2 ==================================================== TYPE LOC (type) LOC ; ADDRESS (type) ADDRESS ; BYTE (type) BYTE ; WORD (type) WORD ; INTEGER8 (type) INTEGER8 ; INTEGER16 (type) INTEGER16 ; INTEGER32 (type) INTEGER32 ; INTEGER64 (type) INTEGER64 ; CARDINAL8 (type) CARDINAL8 ; CARDINAL16 (type) CARDINAL16 ; CARDINAL32 (type) CARDINAL32 ; CARDINAL64 (type) CARDINAL64 ; WORD16 (type) WORD16 ; WORD32 (type) WORD32 ; WORD64 (type) WORD64 ; BITSET8 (type) BITSET8 ; BITSET16 (type) BITSET16 ; BITSET32 (type) BITSET32 ; REAL32 (type) REAL32 ; REAL64 (type) REAL64 ; REAL128 (type) REAL128 ; COMPLEX32 (type) COMPLEX32 ; COMPLEX64 (type) COMPLEX64 ; COMPLEX128 (type) COMPLEX128 ; CSIZE_T (type) CSIZE_T ; CSSIZE_T (type) CSSIZE_T ; TYPE LOC; (* A system basic type. Values are the uninterpreted contents of the smallest addressable unit of storage *) ADDRESS (type) ADDRESS = POINTER TO LOC; WORD (type) WORD = ARRAY [0 .. LOCSPERWORD-1] OF LOC; (* BYTE and LOCSPERBYTE are provided if appropriate for machine *) TYPE BYTE (type) BYTE = ARRAY [0 .. LOCSPERBYTE-1] OF LOC; ADDADR PROCEDURE ADDADR (addr: ADDRESS; offset: CARDINAL): ADDRESS; (* Returns address given by (addr + offset), or may raise an exception if this address is not valid. *) SUBADR PROCEDURE SUBADR (addr: ADDRESS; offset: CARDINAL): ADDRESS; (* Returns address given by (addr - offset), or may raise an exception if this address is not valid. *) DIFADR PROCEDURE DIFADR (addr1, addr2: ADDRESS): INTEGER; (* Returns the difference between addresses (addr1 - addr2), or may raise an exception if the arguments are invalid or address space is non-contiguous. *) MAKEADR PROCEDURE MAKEADR (high: ; ...): ADDRESS; (* Returns an address constructed from a list of values whose types are implementation-defined, or may raise an exception if this address is not valid. In GNU Modula-2, MAKEADR can take any number of arguments which are mapped onto the type ADDRESS. The first parameter maps onto the high address bits and subsequent parameters map onto lower address bits. For example: a := MAKEADR(BYTE(0FEH), BYTE(0DCH), BYTE(0BAH), BYTE(098H), BYTE(076H), BYTE(054H), BYTE(032H), BYTE(010H)) ; then the value of, a, on a 64 bit machine is: 0FEDCBA9876543210H The parameters do not have to be the same type, but constants _must_ be typed. *) ADR PROCEDURE ADR (VAR v: ): ADDRESS; (* Returns the address of variable v. *) ROTATE PROCEDURE ROTATE (val: ; num: INTEGER): ; (* Returns a bit sequence obtained from val by rotating up/right or down/right by the absolute value of num. The direction is down/right if the sign of num is negative, otherwise the direction is up/left. *) SHIFT PROCEDURE SHIFT (val: ; num: INTEGER): ; (* Returns a bit sequence obtained from val by shifting up/left or down/right by the absolute value of num, introducing zeros as necessary. The direction is down/right if the sign of num is negative, otherwise the direction is up/left. *) CAST PROCEDURE CAST (; val: ): ; (* CAST is a type transfer function. Given the expression denoted by val, it returns a value of the type . An invalid value for the target value or a physical address alignment problem may raise an exception. *) TSIZE PROCEDURE TSIZE (; ... ): CARDINAL; (* Returns the number of LOCS used to store a value of the specified . The extra parameters, if present, are used to distinguish variants in a variant record. *) THROW PROCEDURE THROW (i: INTEGER) ; (* THROW is a GNU extension and was not part of the PIM or ISO standards. It throws an exception which will be caught by the EXCEPT block (assuming it exists). This is a compiler builtin function which interfaces to the GCC exception handling runtime system. GCC uses the term throw, hence the naming distinction between the GCC builtin and the Modula-2 runtime library procedure Raise. The later library procedure Raise will call SYSTEM.THROW after performing various housekeeping activities. *) TBITSIZE PROCEDURE TBITSIZE () : CARDINAL ; (* Returns the minimum number of bits necessary to represent . This procedure function is only useful for determining the number of bits used for any type field within a packed RECORD. It is not particularly useful elsewhere since might be optimized for speed, for example a BOOLEAN could occupy a WORD. *) *) (* The following procedures are invoked by GNU Modula-2 to shift non word set types. They are not part of ISO Modula-2 but are used by GNU Modula-2 to implement the SHIFT procedure defined above. *) (* ShiftVal - is a runtime procedure whose job is to implement the SHIFT procedure of ISO SYSTEM. GNU Modula-2 will inline a SHIFT of a single WORD sized set and will only call this routine for larger sets. *) ShiftVal PROCEDURE ShiftVal (VAR s, d: ARRAY OF BITSET; SetSizeInBits: CARDINAL; ShiftCount: INTEGER) ; (* ShiftLeft - performs the shift left for a multi word set. This procedure might be called by the back end of GNU Modula-2 depending whether amount is known at compile time. *) ShiftLeft PROCEDURE ShiftLeft (VAR s, d: ARRAY OF BITSET; SetSizeInBits: CARDINAL; ShiftCount: CARDINAL) ; (* ShiftRight - performs the shift left for a multi word set. This procedure might be called by the back end of GNU Modula-2 depending whether amount is known at compile time. *) ShiftRight PROCEDURE ShiftRight (VAR s, d: ARRAY OF BITSET; SetSizeInBits: CARDINAL; ShiftCount: CARDINAL) ; (* RotateVal - is a runtime procedure whose job is to implement the ROTATE procedure of ISO SYSTEM. GNU Modula-2 will inline a ROTATE of a single WORD (or less) sized set and will only call this routine for larger sets. *) RotateVal PROCEDURE RotateVal (VAR s, d: ARRAY OF BITSET; SetSizeInBits: CARDINAL; RotateCount: INTEGER) ; (* RotateLeft - performs the rotate left for a multi word set. This procedure might be called by the back end of GNU Modula-2 depending whether amount is known at compile time. *) RotateLeft PROCEDURE RotateLeft (VAR s, d: ARRAY OF BITSET; SetSizeInBits: CARDINAL; RotateCount: CARDINAL) ; (* RotateRight - performs the rotate right for a multi word set. This procedure might be called by the back end of GNU Modula-2 depending whether amount is known at compile time. *) RotateRight PROCEDURE RotateRight (VAR s, d: ARRAY OF BITSET; SetSizeInBits: CARDINAL; RotateCount: CARDINAL) ; END SYSTEM. The data types ``CSIZE_T`` and ``CSSIZE_T`` are also exported from the ``SYSTEM`` module. The type ``CSIZE_T`` is unsigned and is mapped onto the target C data type ``size_t`` whereas the type ``CSSIZE_T`` is mapped onto the signed C data type ``ssize_t``. It is anticipated that these should only be used to provide cross platform definition modules for C libraries. There are also a variety of fixed sized ``INTEGER`` and ``CARDINAL`` types. The variety of the fixed sized types will depend upon the target architecture.