gcc/m2/gm2-libs-coroutines/SYSTEM.def

   1 (* SYSTEM.def provides access to COROUTINE primitives and underlying system.
   2
   3 Copyright (C) 2002-2023 Free Software Foundation, Inc.
   4 Contributed by Gaius Mulley <gaius.mulley@southwales.ac.uk>.
   5
   6 This file is part of GNU Modula-2.
   7
   8 GNU Modula-2 is free software; you can redistribute it and/or modify
   9 it under the terms of the GNU General Public License as published by
  10 the Free Software Foundation; either version 3, or (at your option)
  11 any later version.
  12
  13 GNU Modula-2 is distributed in the hope that it will be useful, but
  14 WITHOUT ANY WARRANTY; without even the implied warranty of
  15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16 General Public License for more details.
  17
  18 Under Section 7 of GPL version 3, you are granted additional
  19 permissions described in the GCC Runtime Library Exception, version
  20 3.1, as published by the Free Software Foundation.
  21
  22 You should have received a copy of the GNU General Public License and
  23 a copy of the GCC Runtime Library Exception along with this program;
  24 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  25 <http://www.gnu.org/licenses/>.  *)
  26
  27 DEFINITION MODULE SYSTEM ;
  28
  29 (* This module is designed to be used on a native operating system
  30    rather than an embedded system as it implements the coroutine
  31    primitives TRANSFER, IOTRANSFER and
  32    NEWPROCESS through the GNU Pthread library.  *)
  33
  34 FROM COROUTINES IMPORT PROTECTION ;
  35
  36 EXPORT QUALIFIED (* the following are built into the compiler: *)
  37                  ADDRESS, WORD, BYTE, CSIZE_T, CSSIZE_T, (* @SYSTEM_DATATYPES@ *)
  38                  ADR, TSIZE, ROTATE, SHIFT, THROW, TBITSIZE,
  39                  (* SIZE is exported depending upon -fpim2 and
  40                     -fpedantic.  *)
  41                  (* The rest are implemented in SYSTEM.mod.  *)
  42                  PROCESS, TRANSFER, NEWPROCESS, IOTRANSFER,
  43                  LISTEN,
  44                  ListenLoop, TurnInterrupts,
  45                  (* Internal GM2 compiler functions.  *)
  46                  ShiftVal, ShiftLeft, ShiftRight,
  47                  RotateVal, RotateLeft, RotateRight ;
  48
  49
  50 TYPE
  51    PROCESS  = RECORD
  52                  context: INTEGER ;
  53               END ;
  54
  55 (* Note that the full list of system and sized datatypes include:
  56    LOC, WORD, BYTE, ADDRESS,
  57
  58    (and the non language standard target types)
  59
  60    INTEGER8, INTEGER16, INTEGER32, INTEGER64,
  61    CARDINAL8, CARDINAL16, CARDINAL32, CARDINAL64,
  62    WORD16, WORD32, WORD64, BITSET8, BITSET16,
  63    BITSET32, REAL32, REAL64, REAL128, COMPLEX32,
  64    COMPLEX64, COMPLEX128, CSIZE_T, CSSIZE_T.
  65
  66    Also note that the non-standard data types will
  67    move into another module in the future.  *)
  68
  69 (* The following types are supported on this target:
  70    @SYSTEM_TYPES@
  71 *)
  72
  73
  74 (*
  75    TRANSFER - save the current volatile environment into, p1.
  76               Restore the volatile environment from, p2.
  77 *)
  78
  79 PROCEDURE TRANSFER (VAR p1: PROCESS; p2: PROCESS) ;
  80
  81
  82 (*
  83    NEWPROCESS - p is a parameterless procedure, a, is the origin of
  84                 the workspace used for the process stack and containing
  85                 the volatile environment of the process.  StackSize, is
  86                 the maximum size of the stack in bytes which can be used
  87                 by this process.  new, is the new process.
  88 *)
  89
  90 PROCEDURE NEWPROCESS (p: PROC; a: ADDRESS; StackSize: CARDINAL; VAR new: PROCESS) ;
  91
  92
  93 (*
  94    IOTRANSFER - saves the current volatile environment into, First,
  95                 and restores volatile environment, Second.
  96                 When an interrupt, InterruptNo, is encountered then
  97                 the reverse takes place.  (The then current volatile
  98                 environment is shelved onto Second and First is resumed).
  99
 100                 NOTE: that upon interrupt the Second might not be the
 101                       same process as that before the original call to
 102                       IOTRANSFER.
 103 *)
 104
 105 PROCEDURE IOTRANSFER (VAR First, Second: PROCESS; InterruptNo: CARDINAL) ;
 106
 107
 108 (*
 109    LISTEN - briefly listen for any interrupts.
 110 *)
 111
 112 PROCEDURE LISTEN ;
 113
 114
 115 (*
 116    ListenLoop - should be called instead of users writing:
 117
 118                 LOOP
 119                    LISTEN
 120                 END
 121
 122                 It performs the same function but yields
 123                 control back to the underlying operating system
 124                 via a call to pth_select.
 125                 It also checks for deadlock.
 126                 This function returns when an interrupt occurs ie
 127                 a file descriptor becomes ready or a time event
 128                 expires.  See the module RTint.
 129 *)
 130
 131 PROCEDURE ListenLoop ;
 132
 133
 134 (*
 135    TurnInterrupts - switches processor interrupts to the protection
 136                     level, to.  It returns the old value.
 137 *)
 138
 139 PROCEDURE TurnInterrupts (to: PROTECTION) : PROTECTION ;
 140
 141
 142 (*
 143    all the functions below are declared internally to gm2
 144    ====================================================
 145
 146 PROCEDURE ADR (VAR v: <anytype>): ADDRESS;
 147   (* Returns the address of variable v. *)
 148
 149 PROCEDURE SIZE (v: <type>) : ZType;
 150   (* Returns the number of BYTES used to store a v of
 151      any specified <type>.  Only available if -fpim2 is used.
 152   *)
 153
 154 PROCEDURE TSIZE (<type>) : CARDINAL;
 155   (* Returns the number of BYTES used to store a value of the
 156      specified <type>.
 157   *)
 158
 159 PROCEDURE ROTATE (val: <a set type>;
 160                   num: INTEGER): <type of first parameter>;
 161   (* Returns a bit sequence obtained from val by rotating up or down
 162      (left or right) by the absolute value of num.  The direction is
 163      down if the sign of num is negative, otherwise the direction is up.
 164   *)
 165
 166 PROCEDURE SHIFT (val: <a set type>;
 167                  num: INTEGER): <type of first parameter>;
 168   (* Returns a bit sequence obtained from val by shifting up or down
 169      (left or right) by the absolute value of num, introducing
 170      zeros as necessary.  The direction is down if the sign of
 171      num is negative, otherwise the direction is up.
 172   *)
 173
 174 PROCEDURE THROW (i: INTEGER) ;
 175   (*
 176      THROW is a GNU extension and was not part of the PIM or ISO
 177      standards.  It throws an exception which will be caught by the EXCEPT
 178      block (assuming it exists).  This is a compiler builtin function which
 179      interfaces to the GCC exception handling runtime system.
 180      GCC uses the term throw, hence the naming distinction between
 181      the GCC builtin and the Modula-2 runtime library procedure Raise.
 182      The later library procedure Raise will call SYSTEM.THROW after
 183      performing various housekeeping activities.
 184   *)
 185
 186 PROCEDURE TBITSIZE (<type>) : CARDINAL ;
 187   (* Returns the minimum number of bits necessary to represent
 188      <type>.  This procedure function is only useful for determining
 189      the number of bits used for any type field within a packed RECORD.
 190      It is not particularly useful elsewhere since <type> might be
 191      optimized for speed, for example a BOOLEAN could occupy a WORD.
 192   *)
 193 *)
 194
 195 (* The following procedures are invoked by GNU Modula-2 to
 196    shift non word sized set types.  They are not strictly part
 197    of the core PIM Modula-2, however they are used
 198    to implement the SHIFT procedure defined above,
 199    which are in turn used by the Logitech compatible libraries.
 200
 201    Users will access these procedures by using the procedure
 202    SHIFT above and GNU Modula-2 will map SHIFT onto one of
 203    the following procedures.
 204 *)
 205
 206 (*
 207    ShiftVal - is a runtime procedure whose job is to implement
 208               the SHIFT procedure of ISO SYSTEM. GNU Modula-2 will
 209               inline a SHIFT of a single WORD sized set and will
 210               only call this routine for larger sets.
 211 *)
 212
 213 PROCEDURE ShiftVal (VAR s, d: ARRAY OF BITSET;
 214                     SetSizeInBits: CARDINAL;
 215                     ShiftCount: INTEGER) ;
 216
 217
 218 (*
 219    ShiftLeft - performs the shift left for a multi word set.
 220                This procedure might be called by the back end of
 221                GNU Modula-2 depending whether amount is known at
 222                compile time.
 223 *)
 224
 225 PROCEDURE ShiftLeft (VAR s, d: ARRAY OF BITSET;
 226                      SetSizeInBits: CARDINAL;
 227                      ShiftCount: CARDINAL) ;
 228
 229 (*
 230    ShiftRight - performs the shift left for a multi word set.
 231                 This procedure might be called by the back end of
 232                 GNU Modula-2 depending whether amount is known at
 233                 compile time.
 234 *)
 235
 236 PROCEDURE ShiftRight (VAR s, d: ARRAY OF BITSET;
 237                      SetSizeInBits: CARDINAL;
 238                      ShiftCount: CARDINAL) ;
 239
 240
 241 (*
 242    RotateVal - is a runtime procedure whose job is to implement
 243                the ROTATE procedure of ISO SYSTEM.  GNU Modula-2 will
 244                inline a ROTATE of a single WORD (or less)
 245                sized set and will only call this routine for
 246                larger sets.
 247 *)
 248
 249 PROCEDURE RotateVal (VAR s, d: ARRAY OF BITSET;
 250                      SetSizeInBits: CARDINAL;
 251                      RotateCount: INTEGER) ;
 252
 253
 254 (*
 255    RotateLeft - performs the rotate left for a multi word set.
 256                 This procedure might be called by the back end of
 257                 GNU Modula-2 depending whether amount is known
 258                 at compile time.
 259 *)
 260
 261 PROCEDURE RotateLeft (VAR s, d: ARRAY OF BITSET;
 262                       SetSizeInBits: CARDINAL;
 263                       RotateCount: CARDINAL) ;
 264
 265
 266 (*
 267    RotateRight - performs the rotate right for a multi word set.
 268                  This procedure might be called by the back end of
 269                  GNU Modula-2 depending whether amount is known at
 270                  compile time.
 271 *)
 272
 273 PROCEDURE RotateRight (VAR s, d: ARRAY OF BITSET;
 274                        SetSizeInBits: CARDINAL;
 275                        RotateCount: CARDINAL) ;
 276
 277
 278 END SYSTEM.