doc/m2ref.doc

   1 .\" $Id: m2ref.doc,v 2.14 1994/06/24 10:02:03 ceriel Exp $
   2 .\" troff -ms m2ref.doc
   3 .TL
   4 The ACK Modula-2 Compiler
   5 .AU
   6 Ceriel J.H. Jacobs
   7 .AI
   8 Department of Mathematics and Computer Science
   9 Vrije Universiteit
  10 Amsterdam
  11 The Netherlands
  12 .AB no
  13 .AE
  14 .NH
  15 Introduction
  16 .PP
  17 This document describes the implementation-specific features of the
  18 ACK Modula-2 compiler.
  19 It is not intended to teach Modula-2 programming.
  20 For a description of the Modula-2 language,
  21 the reader is referred to [1].
  22 .PP
  23 The ACK Modula-2 compiler is currently available for use with the VAX,
  24 Motorola MC68020,
  25 Motorola MC68000,
  26 PDP-11,
  27 and Intel 8086 code-generators.
  28 For the 8086,
  29 MC68000,
  30 and MC68020,
  31 floating point emulation is used.
  32 This is made available with the \fI-fp\fP
  33 option,
  34 which must be passed to \fIack\fP[4,5].
  35 .NH
  36 The language implemented
  37 .PP
  38 This section discusses the deviations from the Modula-2 language as described
  39 in the "Report on The Programming Language Modula-2",
  40 as it appeared in [1],
  41 from now on referred to as "the Report".
  42 Also,
  43 the Report sometimes leaves room for interpretation.
  44 The section numbers
  45 mentioned are the section numbers of the Report.
  46 .NH 2
  47 Syntax (section 2)
  48 .PP
  49 The syntax recognized is that of the Report,
  50 with some extensions to
  51 also recognize the syntax of an earlier definition,
  52 given in [2].
  53 Only one compilation unit per file is accepted.
  54 .NH 2
  55 Vocabulary and Representation (section 3)
  56 .PP
  57 The input "\f(CW10..\fP" is parsed as two tokens: "\f(CW10\fP" and "\f(CW..\fP".
  58 .PP
  59 The empty string \f(CW""\fP has type
  60 .DS
  61 .ft CW
  62 ARRAY [0 .. 0] OF CHAR
  63 .ft P
  64 .DE
  65 and contains one character: \f(CW0C\fP.
  66 .PP
  67 When the text of a comment starts with a '\f(CW$\fP',
  68 it may be a pragma.
  69 Currently,
  70 the following pragmas exist:
  71 .DS
  72 .ft CW
  73 (*$F      (F stands for Foreign) *)
  74 (*$R[+|-] (Runtime checks, on or off, default on) *)
  75 (*$A[+|-] (Array bound checks, on or off, default off) *)
  76 (*$U      (Allow for underscores within identifiers) *)
  77 .ft P
  78 .DE
  79 The Foreign pragma is only meaningful in a \f(CWDEFINITION MODULE\fP,
  80 and indicates that this
  81 \f(CWDEFINITION MODULE\fP describes an interface to a module written in another
  82 language (for instance C,
  83 Pascal,
  84 or EM).
  85 Runtime checks that can be disabled are:
  86 range checks,
  87 \f(CWCARDINAL\fP overflow checks,
  88 checks when assigning a \f(CWCARDINAL\fP to an \f(CWINTEGER\fP and vice versa,
  89 and checks that \f(CWFOR\fP-loop control-variables are not changed
  90 in the body of the loop.
  91 Array bound checks can be enabled,
  92 because many EM implementations do not
  93 implement the array bound checking of the EM array instructions.
  94 When enabled,
  95 the compiler generates a check before generating an
  96 EM array instruction.
  97 Even when underscores are enabled,
  98 they still may not start an identifier.
  99 .PP
 100 Constants of type \f(CWLONGINT\fP are integers with a suffix letter \f(CWD\fP
 101 (for instance \f(CW1987D\fP).
 102 Constants of type \f(CWLONGREAL\fP have suffix \f(CWD\fP if a scale factor is missing,
 103 or have \f(CWD\fP in place of \f(CWE\fP in the scale factor (f.i. \f(CW1.0D\fP,
 104 \f(CW0.314D1\fP).
 105 This addition was made,
 106 because there was no way to indicate long constants,
 107 and also because the addition was made in Wirth's newest Modula-2 compiler.
 108 .NH 2
 109 Declarations and scope rules (section 4)
 110 .PP
 111 Standard identifiers are considered to be predeclared,
 112 and valid in all
 113 parts of a program.
 114 They are called \fIpervasive\fP.
 115 Unfortunately,
 116 the Report does not state how this pervasiveness is accomplished.
 117 However,
 118 page 87 of [1] states: "Standard identifiers are automatically
 119 imported into all modules".
 120 Our implementation therefore allows
 121 redeclarations of standard identifiers within procedures,
 122 but not within
 123 modules.
 124 .NH 2
 125 Constant expressions (section 5)
 126 .PP
 127 Each operand of a constant expression must be a constant:
 128 a string,
 129 a number,
 130 a set,
 131 an enumeration literal,
 132 a qualifier denoting a
 133 constant expression,
 134 a type transfer with a constant argument,
 135 or one of the standard procedures
 136 \f(CWABS\fP,
 137 \f(CWCAP\fP,
 138 \f(CWCHR\fP,
 139 \f(CWLONG\fP,
 140 \f(CWMAX\fP,
 141 \f(CWMIN\fP,
 142 \f(CWODD\fP,
 143 \f(CWORD\fP,
 144 \f(CWSIZE\fP,
 145 \f(CWSHORT\fP,
 146 \f(CWTSIZE\fP,
 147 or \f(CWVAL\fP,
 148 with constant argument(s);
 149 \f(CWTSIZE\fP and \f(CWSIZE\fP may also have a variable as argument.
 150 .PP
 151 Floating point expressions are never evaluated compile time,
 152 because the compiler basically functions as a cross-compiler,
 153 and thus cannot
 154 use the floating point instructions of the machine on which it runs.
 155 Also,
 156 \f(CWMAX(REAL)\fP and \f(CWMIN(REAL)\fP are not allowed.
 157 .NH 2
 158 Type declarations (section 6)
 159 .NH 3
 160 Basic types (section 6.1)
 161 .PP
 162 The type \f(CWCHAR\fP includes the ASCII character set as a subset.
 163 Values range from
 164 \f(CW0C\fP to \f(CW377C\fP,
 165 not from \f(CW0C\fP to \f(CW177C\fP.
 166 .NH 3
 167 Enumerations (section 6.2)
 168 .PP
 169 The maximum number of enumeration literals in any one enumeration type
 170 is \f(CWMAX(INTEGER)\fP.
 171 .NH 3
 172 Record types (section 6.5)
 173 .PP
 174 The syntax of variant sections in [1] is different from the one in [2].
 175 Our implementation recognizes both,
 176 giving a warning for the older one.
 177 However,
 178 see section 3.
 179 .NH 3
 180 Set types (section 6.6)
 181 .PP
 182 The only limitation imposed by the compiler is that the base type of the
 183 set must be a subrange type,
 184 an enumeration type,
 185 \f(CWCHAR\fP,
 186 or \f(CWBOOLEAN\fP.
 187 So,
 188 the lower bound may be negative.
 189 However,
 190 if a negative lower bound is used,
 191 the compiler gives a warning of the \fIrestricted\fP class (see the manual
 192 page of the compiler).
 193 .PP
 194 The standard type \f(CWBITSET\fP is defined as
 195 .DS
 196 .ft CW
 197 TYPE BITSET = SET OF [0 .. 8*SIZE(INTEGER)-1];
 198 .ft P
 199 .DE
 200 .NH 2
 201 Expressions (section 8)
 202 .NH 3
 203 Operators (section 8.2)
 204 .NH 4
 205 Arithmetic operators (section 8.2.1)
 206 .PP
 207 The Report does not specify the priority of the unary
 208 operators \f(CW+\fP or \f(CW-\fP:
 209 It does not specify whether
 210 .DS
 211 .ft CW
 212 - 1 + 1
 213 .ft P
 214 .DE
 215 means
 216 .DS
 217 .ft CW
 218 - (1 + 1)
 219 .ft P
 220 .DE
 221 or
 222 .DS
 223 .ft CW
 224 (-1) + 1
 225 .ft P
 226 .DE
 227 I have seen some compilers that implement the first alternative,
 228 and others that implement the second.
 229 Our compiler implements the second,
 230 which is suggested by the fact that their priority is not specified,
 231 which might indicate that it is the same as that of their binary counterparts.
 232 And then the rule about left to right decides for the second.
 233 On the other hand one might argue that,
 234 since the grammar only allows for one unary operator in a simple expression,
 235 it must apply to the whole simple expression,
 236 not just the first term.
 237 .NH 2
 238 Statements (section 9)
 239 .NH 3
 240 Assignments (section 9.1)
 241 .PP
 242 The Report does not define the evaluation order in an assignment.
 243 Our compiler certainly chooses an evaluation order,
 244 but it is explicitly left undefined.
 245 Therefore,
 246 programs that depend on it may cease to work later.
 247 .PP
 248 The types \f(CWINTEGER\fP and \f(CWCARDINAL\fP are assignment-compatible with
 249 \f(CWLONGINT\fP,
 250 and \f(CWREAL\fP is assignment-compatible with \f(CWLONGREAL\fP.
 251 .NH 3
 252 Case statements (section 9.5)
 253 .PP
 254 The size of the type of the case-expression must be less than or equal to
 255 the word-size.
 256 .PP
 257 The Report does not specify what happens if the value of the case-expression
 258 does not occur as a label of any case,
 259 and there is no \f(CWELSE\fP-part.
 260 In our implementation,
 261 this results in a runtime error.
 262 .NH 3
 263 For statements (section 9.8)
 264 .PP
 265 The Report does not specify the legal types for a control variable.
 266 Our implementation allows the basic types (except \f(CWREAL\fP),
 267 enumeration types,
 268 and subranges.
 269 A runtime warning is generated when the value of the control variable
 270 is changed by the statement sequence that forms the body of the loop,
 271 unless runtime checking is disabled.
 272 .NH 3
 273 Return and exit statements (section 9.11)
 274 .PP
 275 The Report does not specify which result-types are legal.
 276 Our implementation allows any result type.
 277 .NH 2
 278 Procedure declarations (section 10)
 279 .PP
 280 Function procedures must exit through a RETURN statement,
 281 or a runtime error occurs.
 282 .NH 3
 283 Standard procedures (section 10.2)
 284 .PP
 285 Our implementation supports \f(CWNEW\fP and \f(CWDISPOSE\fP
 286 for backwards compatibility,
 287 but issues warnings for their use.
 288 However,
 289 see section 3.
 290 .PP
 291 Also,
 292 some new standard procedures were added,
 293 similar to the new standard procedures in Wirth's newest compiler:
 294 .IP \-
 295 \f(CWLONG\fP converts an argument of type \f(CWINTEGER\fP or \f(CWREAL\fP to the
 296 types \f(CWLONGINT\fP or \f(CWLONGREAL\fP.
 297 .IP \-
 298 \f(CWSHORT\fP performs the inverse transformation,
 299 without range checks.
 300 .IP \-
 301 \f(CWFLOATD\fP is analogous to \f(CWFLOAT\fP,
 302 but yields a result of type
 303 \f(CWLONGREAL\fP.
 304 .IP \-
 305 \f(CWTRUNCD\fP is analogous to \f(CWTRUNC\fP,
 306 but yields a result of type
 307 \f(CWLONGINT\fP.
 308 .NH 2
 309 System-dependent facilities (section 12)
 310 .PP
 311 The type \f(CWBYTE\fP is added to the \f(CWSYSTEM\fP module.
 312 It occupies a storage unit of 8 bits.
 313 \f(CWARRAY OF BYTE\fP has a similar effect to \f(CWARRAY OF WORD\fP,
 314 but is safer.
 315 In some obscure cases the \f(CWARRAY OF WORD\fP mechanism does not quite
 316 work properly.
 317 .PP
 318 The procedure \f(CWIOTRANSFER\fP is not implemented.
 319 .NH 1
 320 Backwards compatibility
 321 .PP
 322 Besides recognizing the language as described in [1],
 323 the compiler recognizes most of the language described in [2],
 324 for backwards compatibility.
 325 It warns the user for old-fashioned
 326 constructions (constructions that [1] does not allow).
 327 If the \fI-Rm2-3\fP option (see [6]) is passed to \fIack\fP,
 328 this backwards compatibility feature is disabled.
 329 Also,
 330 it may not be present on some
 331 smaller machines,
 332 like the PDP-11.
 333 .NH 1
 334 Compile time errors
 335 .PP
 336 The compile time error messages are intended to be self-explanatory,
 337 and not listed here.
 338 The compiler also sometimes issues warnings,
 339 recognizable by a warning-classification between parentheses.
 340 Currently,
 341 there are 3 classifications:
 342 .IP "(old-fashioned use)"
 343 .br
 344 These warnings are given on constructions that are not allowed by [1],
 345 but are allowed by [2].
 346 .IP (strict)
 347 .br
 348 These warnings are given on constructions that are supported by the
 349 ACK Modula-2 compiler,
 350 but might not be supported by others.
 351 Examples: functions returning structured types,
 352 SET types of subranges with
 353 negative lower bound.
 354 .IP (warning)
 355 .br
 356 The other warnings,
 357 such as warnings about variables that are never assigned,
 358 never used,
 359 etc.
 360 .NH 1
 361 Runtime errors
 362 .PP
 363 The ACK Modula-2 compiler produces code for an EM machine as defined in [3].
 364 Therefore,
 365 it depends on the implementation
 366 of the EM machine for detection some of the runtime errors that could occur.
 367 .PP
 368 The \fITraps\fP module enables the user to install his own runtime
 369 error handler.
 370 The default one just displays what happened and exits.
 371 Basically,
 372 a trap handler is just a procedure that takes an INTEGER as
 373 parameter.
 374 The INTEGER is the trap number.
 375 This INTEGER can be one of the
 376 EM trap numbers,
 377 listed in [3],
 378 or one of the numbers listed in the
 379 \fITraps\fP definition module.
 380 .PP
 381 The following runtime errors may occur:
 382 .IP "array bound error"
 383 .br
 384 The detection of this error depends on the EM implementation.
 385 .IP "range bound error"
 386 .br
 387 Range bound errors are always detected,
 388 unless runtime checks are disabled.
 389 .IP "set bound error"
 390 .br
 391 The detection of this error depends on the EM implementation.
 392 The current implementations detect this error.
 393 .IP "integer overflow"
 394 .br
 395 The detection of this error depends on the EM implementation.
 396 .IP "cardinal overflow"
 397 .br
 398 This error is detected,
 399 unless runtime checks are disabled.
 400 .IP "cardinal underflow"
 401 .br
 402 This error is detected,
 403 unless runtime checks are disabled.
 404 .IP "real overflow"
 405 .br
 406 The detection of this error depends on the EM implementation.
 407 .IP "real underflow"
 408 .br
 409 The detection of this error depends on the EM implementation.
 410 .IP "divide by 0"
 411 .br
 412 The detection of this error depends on the EM implementation.
 413 .IP "divide by 0.0"
 414 .br
 415 The detection of this error depends on the EM implementation.
 416 .IP "undefined integer"
 417 .br
 418 The detection of this error depends on the EM implementation.
 419 .IP "undefined real"
 420 .br
 421 The detection of this error depends on the EM implementation.
 422 .IP "conversion error"
 423 .br
 424 This error occurs when assigning a negative value of type INTEGER to a
 425 variable of type CARDINAL,
 426 or when assigning a value of CARDINAL that is > MAX(INTEGER),
 427 to a variable of type INTEGER.
 428 It is detected,
 429 unless runtime checking is disabled.
 430 .IP "stack overflow"
 431 .br
 432 The detection of this error depends on the EM implementation.
 433 .IP "heap overflow"
 434 .br
 435 The detection of this error depends on the EM implementation.
 436 Might happen when ALLOCATE fails.
 437 .IP "case error"
 438 .br
 439 This error occurs when non of the cases in a CASE statement are selected,
 440 and the CASE statement has no ELSE part.
 441 The detection of this error depends on the EM implementation.
 442 All current EM implementations detect this error.
 443 .IP "stack size of process too large"
 444 .br
 445 This is most likely to happen if the reserved space for a coroutine stack
 446 is too small.
 447 In this case,
 448 increase the size of the area given to
 449 \f(CWNEWPROCESS\fP.
 450 It can also happen if the stack needed for the main
 451 process is too large and there are coroutines.
 452 In this case,
 453 the only fix is to reduce the stack size needed by the main process,
 454 f.i. by avoiding local arrays.
 455 .IP "too many nested traps + handlers"
 456 .br
 457 This error can only occur when the user has installed his own trap handler.
 458 It means that during execution of the trap handler another trap has occurred,
 459 and that several times.
 460 In some cases,
 461 this is an error because of overflow of some internal tables.
 462 .IP "no RETURN from function procedure"
 463 .br
 464 This error occurs when a function procedure does not return properly
 465 ("falls" through).
 466 .IP "illegal instruction"
 467 .br
 468 This error might occur when floating point operations are used on an
 469 implementation that does not have floating point.
 470 .PP
 471 In addition,
 472 some of the library modules may give error messages.
 473 The \fBTraps\fP-module has a suitable mechanism for this.
 474 .NH 1
 475 Calling the compiler
 476 .PP
 477 See [4,5,6] for a detailed explanation.
 478 .PP
 479 The compiler itself has no version checking mechanism.
 480 A special linker
 481 would be needed to do that.
 482 Therefore,
 483 a makefile generator is included [7].
 484 .NH 1
 485 The procedure call interface
 486 .PP
 487 Parameters are pushed on the stack in reversed order,
 488 so that the EM AB
 489 (argument base) register indicates the first parameter.
 490 For VAR parameters,
 491 its address is passed,
 492 for value parameters its value.
 493 The only exception to this rule is with conformant arrays.
 494 For conformant arrays,
 495 the address is passed,
 496 and an array descriptor is
 497 passed.
 498 The descriptor is an EM array descriptor.
 499 It consists of three
 500 fields: the lower bound (always 0),
 501 upper bound - lower bound,
 502 and the size of the elements.
 503 The descriptor is pushed first.
 504 If the parameter is a value parameter,
 505 the called routine must make sure
 506 that its value is never changed,
 507 for instance by making its own copy
 508 of the array.
 509 The Modula-2 compiler does exactly this.
 510 .PP
 511 When the size of the return value of a function procedure is larger than
 512 the maximum of \f(CWSIZE(LONGREAL)\fP and twice the pointer-size,
 513 the caller reserves this space on the stack,
 514 above the parameters.
 515 Callee then stores
 516 its result there,
 517 and returns no other value.
 518 .NH 1
 519 References
 520 .IP [1]
 521 Niklaus Wirth,
 522 .I
 523 Programming in Modula-2, third, corrected edition,
 524 .R
 525 Springer-Verlag, Berlin (1985)
 526 .IP [2]
 527 Niklaus Wirth,
 528 .I
 529 Programming in Modula-2,
 530 .R
 531 Stringer-Verlag, Berlin (1983)
 532 .IP [3]
 533 A.S.Tanenbaum, J.W.Stevenson, Hans van Staveren, E.G.Keizer,
 534 .I
 535 Description of a machine architecture for use with block structured languages,
 536 .R
 537 Informatica rapport IR-81, Vrije Universiteit, Amsterdam
 538 .IP [4]
 539 UNIX manual \fIack\fP(1)
 540 .IP [5]
 541 UNIX manual \fImodula-2\fP(1)
 542 .IP [6]
 543 UNIX manual \fIem_m2\fP(6)
 544 .IP [7]
 545 UNIX manual \fIm2mm\fP(1)