gcc/m2/target-independent/SYSTEM-iso.texi

   1
   2 @example
   3 DEFINITION MODULE SYSTEM;
   4
   5   (* Gives access to system programming facilities that are probably
   6      non portable. *)
   7
   8   (* The constants and types define underlying properties of storage *)
   9
  10 EXPORT QUALIFIED BITSPERLOC, LOCSPERWORD,
  11                  LOC, BYTE, WORD, ADDRESS, CSIZE_T, CSSIZE_T, (*
  12                  Target specific data types.  *)
  13                  ADDADR, SUBADR, DIFADR, MAKEADR, ADR, ROTATE,
  14                  SHIFT, CAST, TSIZE,
  15
  16                  (* Internal GM2 compiler functions *)
  17                  ShiftVal, ShiftLeft, ShiftRight,
  18                  RotateVal, RotateLeft, RotateRight,
  19                  THROW, TBITSIZE ;
  20
  21 CONST
  22                   (* <implementation-defined constant> ; *)
  23 @findex BITSPERLOC (const)
  24   BITSPERLOC    = __ATTRIBUTE__ __BUILTIN__ ((BITS_PER_UNIT)) ;
  25                   (* <implementation-defined constant> ; *)
  26 @findex LOCSPERWORD (const)
  27   LOCSPERWORD   = __ATTRIBUTE__ __BUILTIN__ ((UNITS_PER_WORD)) ;
  28                   (* <implementation-defined constant> ; *)
  29 @findex LOCSPERBYTE (const)
  30   LOCSPERBYTE = 8 DIV BITSPERLOC ;
  31
  32 (* Note that the full list of system and sized datatypes include:
  33    LOC, WORD, BYTE, ADDRESS,
  34
  35    (and the non language standard target types)
  36
  37    INTEGER8, INTEGER16, INTEGER32, INTEGER64,
  38    CARDINAL8, CARDINAL16, CARDINAL32, CARDINAL64,
  39    WORD16, WORD32, WORD64, BITSET8, BITSET16,
  40    BITSET32, REAL32, REAL64, REAL128, COMPLEX32,
  41    COMPLEX64, COMPLEX128, CSIZE_T, CSSIZE_T.
  42
  43    Also note that the non-standard data types will
  44    move into another module in the future.  *)
  45
  46 (*
  47    All the data types and procedures below are declared internally.
  48    ===============================================================
  49
  50 TYPE
  51    (* Target specific data types.  *)
  52
  53 TYPE
  54   LOC; (* A system basic type. Values are the uninterpreted
  55           contents of the smallest addressable unit of storage *)
  56 @findex ADDRESS (type)
  57   ADDRESS = POINTER TO LOC;
  58 @findex WORD (type)
  59   WORD = ARRAY [0 .. LOCSPERWORD-1] OF LOC;
  60
  61   (* BYTE and LOCSPERBYTE are provided if appropriate for machine *)
  62
  63 TYPE
  64 @findex BYTE (type)
  65   BYTE = ARRAY [0 .. LOCSPERBYTE-1] OF LOC;
  66
  67 @findex ADDADR
  68 PROCEDURE ADDADR (addr: ADDRESS; offset: CARDINAL): ADDRESS;
  69   (* Returns address given by (addr + offset), or may raise
  70      an exception if this address is not valid.
  71   *)
  72
  73 @findex SUBADR
  74 PROCEDURE SUBADR (addr: ADDRESS; offset: CARDINAL): ADDRESS;
  75   (* Returns address given by (addr - offset), or may raise an
  76      exception if this address is not valid.
  77   *)
  78
  79 @findex DIFADR
  80 PROCEDURE DIFADR (addr1, addr2: ADDRESS): INTEGER;
  81   (* Returns the difference between addresses (addr1 - addr2),
  82      or may raise an exception if the arguments are invalid
  83      or address space is non-contiguous.
  84   *)
  85
  86 @findex MAKEADR
  87 PROCEDURE MAKEADR (high: <some type>; ...): ADDRESS;
  88   (* Returns an address constructed from a list of values whose
  89      types are implementation-defined, or may raise an
  90      exception if this address is not valid.
  91
  92      In GNU Modula-2, MAKEADR can take any number of arguments
  93      which are mapped onto the type ADDRESS. The first parameter
  94      maps onto the high address bits and subsequent parameters map
  95      onto lower address bits. For example:
  96
  97      a := MAKEADR(BYTE(0FEH), BYTE(0DCH), BYTE(0BAH), BYTE(098H),
  98                   BYTE(076H), BYTE(054H), BYTE(032H), BYTE(010H)) ;
  99
 100      then the value of, a, on a 64 bit machine is: 0FEDCBA9876543210H
 101
 102      The parameters do not have to be the same type, but constants
 103      _must_ be typed.
 104   *)
 105
 106 @findex ADR
 107 PROCEDURE ADR (VAR v: <anytype>): ADDRESS;
 108   (* Returns the address of variable v. *)
 109
 110 @findex ROTATE
 111 PROCEDURE ROTATE (val: <a packedset type>;
 112                   num: INTEGER): <type of first parameter>;
 113   (* Returns a bit sequence obtained from val by rotating up/right
 114      or down/right by the absolute value of num.  The direction is
 115      down/right if the sign of num is negative, otherwise the direction
 116      is up/left.
 117   *)
 118
 119 @findex SHIFT
 120 PROCEDURE SHIFT (val: <a packedset type>;
 121                  num: INTEGER): <type of first parameter>;
 122   (* Returns a bit sequence obtained from val by shifting up/left
 123      or down/right by the absolute value of num, introducing
 124      zeros as necessary.  The direction is down/right if the sign of
 125      num is negative, otherwise the direction is up/left.
 126   *)
 127
 128 @findex CAST
 129 PROCEDURE CAST (<targettype>; val: <anytype>): <targettype>;
 130   (* CAST is a type transfer function.  Given the expression
 131      denoted by val, it returns a value of the type <targettype>.
 132      An invalid value for the target value or a
 133      physical address alignment problem may raise an exception.
 134   *)
 135
 136 @findex TSIZE
 137 PROCEDURE TSIZE (<type>; ... ): CARDINAL;
 138   (* Returns the number of LOCS used to store a value of the
 139      specified <type>.   The extra parameters, if present,
 140      are used to distinguish variants in a variant record.
 141   *)
 142
 143 @findex THROW
 144 PROCEDURE THROW (i: INTEGER) ;
 145   (*
 146      THROW is a GNU extension and was not part of the PIM or ISO
 147      standards.  It throws an exception which will be caught by the
 148      EXCEPT block (assuming it exists).  This is a compiler builtin
 149      function which interfaces to the GCC exception handling runtime
 150      system.
 151      GCC uses the term throw, hence the naming distinction between
 152      the GCC builtin and the Modula-2 runtime library procedure Raise.
 153      The later library procedure Raise will call SYSTEM.THROW after
 154      performing various housekeeping activities.
 155   *)
 156
 157 @findex TBITSIZE
 158 PROCEDURE TBITSIZE (<type>) : CARDINAL ;
 159   (* Returns the minimum number of bits necessary to represent
 160      <type>.  This procedure function is only useful for determining
 161      the number of bits used for any type field within a packed RECORD.
 162      It is not particularly useful elsewhere since <type> might be
 163      optimized for speed, for example a BOOLEAN could occupy a WORD.
 164   *)
 165 *)
 166
 167
 168 (* The following procedures are invoked by GNU Modula-2 to
 169    shift non word set types. They are not part of ISO Modula-2
 170    but are used to implement the SHIFT procedure defined above. *)
 171
 172 (*
 173    ShiftVal - is a runtime procedure whose job is to implement
 174               the SHIFT procedure of ISO SYSTEM. GNU Modula-2 will
 175               inline a SHIFT of a single WORD sized set and will only
 176               call this routine for larger sets.
 177 *)
 178
 179 @findex ShiftVal
 180 PROCEDURE ShiftVal (VAR s, d: ARRAY OF BITSET;
 181                     SetSizeInBits: CARDINAL;
 182                     ShiftCount: INTEGER) ;
 183
 184
 185 (*
 186    ShiftLeft - performs the shift left for a multi word set.
 187                This procedure might be called by the back end of
 188                GNU Modula-2 depending whether amount is known at
 189                compile time.
 190 *)
 191
 192 @findex ShiftLeft
 193 PROCEDURE ShiftLeft (VAR s, d: ARRAY OF BITSET;
 194                      SetSizeInBits: CARDINAL;
 195                      ShiftCount: CARDINAL) ;
 196
 197 (*
 198    ShiftRight - performs the shift left for a multi word set.
 199                 This procedure might be called by the back end of
 200                 GNU Modula-2 depending whether amount is known at
 201                 compile time.
 202 *)
 203
 204 @findex ShiftRight
 205 PROCEDURE ShiftRight (VAR s, d: ARRAY OF BITSET;
 206                      SetSizeInBits: CARDINAL;
 207                      ShiftCount: CARDINAL) ;
 208
 209
 210 (*
 211    RotateVal - is a runtime procedure whose job is to implement
 212                the ROTATE procedure of ISO SYSTEM. GNU Modula-2 will
 213                inline a ROTATE of a single WORD (or less)
 214                sized set and will only call this routine for larger
 215                sets.
 216 *)
 217
 218 @findex RotateVal
 219 PROCEDURE RotateVal (VAR s, d: ARRAY OF BITSET;
 220                      SetSizeInBits: CARDINAL;
 221                      RotateCount: INTEGER) ;
 222
 223
 224 (*
 225    RotateLeft - performs the rotate left for a multi word set.
 226                 This procedure might be called by the back end of
 227                 GNU Modula-2 depending whether amount is known at
 228                 compile time.
 229 *)
 230
 231 @findex RotateLeft
 232 PROCEDURE RotateLeft (VAR s, d: ARRAY OF BITSET;
 233                       SetSizeInBits: CARDINAL;
 234                       RotateCount: CARDINAL) ;
 235
 236
 237 (*
 238    RotateRight - performs the rotate right for a multi word set.
 239                  This procedure might be called by the back end of
 240                  GNU Modula-2 depending whether amount is known at
 241                  compile time.
 242 *)
 243
 244 @findex RotateRight
 245 PROCEDURE RotateRight (VAR s, d: ARRAY OF BITSET;
 246                        SetSizeInBits: CARDINAL;
 247                        RotateCount: CARDINAL) ;
 248
 249
 250 END SYSTEM.
 251 @end example